今天在 GitHub Trending 上看到一个有意思的项目：Karukan，这是一个面向 Linux 和 macOS 的现代日语输入法系统，采用神经网络驱动的下一代假名汉字转换引擎，值得深入了解其技术架构与设计思路。

一、项目概述

Karukan 是一个基于神经网络的日语输入法系统，支持 Linux（通过 fcitx5）和 macOS（通过 InputMethodKit）两大平台。与传统日语输入法依赖统计模型不同，Karukan 采用 GPT-2 架构 的神经网络模型，通过 llama.cpp 进行高效推理，实现了更精准的假名汉字转换。

项目采用 Rust 语言编写，整体架构模块化设计，核心分为四大组件：

组件说明
karukan-engine核心库——罗马字→平假名转换 + 基于 llama.cpp 的神经网络假名汉字转换
karukan-im共享 IME 引擎——状态机、罗马字转换、karukan-imserver（macOS 的 JSON-RPC 服务器）
karukan-fcitx5Linux 前端——fcitx5 插件 + C FFI
karukan-macosmacOS 前端——Swift/InputMethodKit 实现

核心特性

  • 神经网络假名汉字转换：基于 GPT-2 的模型通过 llama.cpp 推理，实现高质量日语转换
  • 实时转换（Live Conversion）：输入同时实时显示转换结果，无需按 Space 键转换（Ctrl+Shift+L 切换开关）
  • 上下文感知：考虑周边文本上下文，提升转换准确率
  • 转换学习：记忆用户选择的转换结果，优先显示学习后的候选；支持预测转换（前缀匹配）
  • 系统字典：基于 SudachiDict 构建系统字典
  • 候选重写器（移植自 Mozc）：自动生成半角片假名、英文字母大小写、符号关联候选、数字各种表记（汉字数字、大字、罗马数字等）
  • 表情符号输入：支持假名读音（ぴえん → 🥺）和 Slack 风格 :trigger 查询（:smile → 😄）

二、技术原理

2.1 神经网络转换引擎

Karukan 的核心创新在于使用 GPT-2 架构 的神经网络模型进行假名汉字转换，而非传统的 N-gram 或 CRF 模型。模型通过 llama.cpp 进行推理，这是一个用 C/C++ 编写的高性能推理框架，支持量化模型，能够在 CPU 上高效运行。

转换流程如下：

用户罗马字输入 → 罗马字→平假名转换 → 神经网络模型推理 → 假名汉字转换结果 → 候选列表展示

神经网络模型的优势在于：

  1. 长距离依赖建模：能够捕捉长距离的上下文依赖关系，提升转换准确率
  2. 端到端学习：无需手工设计特征，模型自动学习最优表示
  3. 泛化能力强：对于未见过的词汇和用法，仍能生成合理的转换结果

2.2 实时转换机制

传统日语输入法需要用户按 Space 键触发转换，而 Karukan 支持 实时转换（Live Conversion），在用户输入的同时持续进行转换推理。这一特性通过以下机制实现：

  • 增量推理：每次用户输入新字符时，基于已有上下文增量更新转换结果
  • 异步推理：神经网络推理在后台线程进行，避免阻塞用户输入
  • 结果缓存：推理结果被缓存，避免重复计算

用户可以通过 Ctrl+Shift+L 快捷键切换实时转换的开关状态。

2.3 上下文感知与学习

Karukan 支持 上下文感知，在转换时考虑周边文本信息。这一特性对于日语尤为重要，因为日语的汉字转换高度依赖于上下文语境（如「は」可读作「は」或「わ」，「を」通常读作「を」但输入时为「wo」）。

此外，Karukan 实现了 转换学习 功能：

  • 记忆用户选择的转换结果
  • 下次遇到相同输入时，优先显示学习后的候选
  • 支持预测转换（前缀匹配），在用户输入中途即可提示学习过的候选

这一功能通过本地存储的用户字典实现，数据格式为 JSON，便于迁移和备份。

2.4 系统字典构建

Karukan 的系统字典基于 SudachiDict 构建，这是日本国立信息学研究所（NII）开发的日语词典数据。SudachiDict 包含丰富的词汇、词性和语法信息，为 Karukan 提供高质量的词典支持。

字典构建流程：

  1. 下载 SudachiDict 原始数据
  2. 解析并转换为 Karukan 内部格式
  3. 构建索引以加速查询

2.5 候选重写器

Karukan 移植了 Google Mozc 的 候选重写器（Candidate Rewriter），自动为候选生成关联变体：

  • 半角片假名：全角片假名 → 半角片假名
  • 英文字母大小写：自动生成大写、小写、首字母大写等变体
  • 数字表记转换：阿拉伯数字 → 汉字数字、大字、罗马数字、丸数字、16/8/2 进制等
  • 符号关联：自动生成相关符号候选

每个候选都带有 Mozc 来源的注釈（如「半角カタカナ」「16進数」等），帮助用户快速识别候选类型。

三、安装与快速开始

3.1 Linux (fcitx5) 安装

Karukan 提供基于 fcitx5 的 Linux 输入法前端，安装步骤如下：

# 安装依赖
sudo apt install fcitx5 fcitx5-mozc  # Debian/Ubuntu
sudo dnf install fcitx5 fcitx5-mozc  # Fedora

# 从 release 页面下载预编译二进制
wget https://github.com/togatoga/karukan/releases/latest/download/karukan-fcitx5.tar.gz
tar -xzf karukan-fcitx5.tar.gz
cd karukan-fcitx5
sudo ./install.sh

# 配置 fcitx5，添加 Karukan 输入法
fcitx5-configtool

详细安装说明请参考 karukan-fcitx5 的 README。

3.2 macOS 安装

macOS 版本通过 InputMethodKit 实现，安装步骤如下：

# 从 release 页面下载 Karukan.app
wget https://github.com/togatoga/karukan/releases/latest/download/Karukan.app.zip
unzip Karukan.app.zip

# 移动到应用程序文件夹
mv Karukan.app /Applications/

# 在"系统设置 → 键盘 → 输入法"中添加 Karukan

首次启动时，Karukan 会从 Hugging Face 下载神经网络模型，需要保持网络连接。模型下载完成后，后续启动将直接使用本地模型，无需重复下载。

详细安装说明请参考 karukan-macos 的 README。

3.3 最简运行示例

安装完成后，在输入法切换菜单中选择 Karukan，即可开始使用：

  1. 打开任意文本编辑器
  2. 切换到 Karukan 输入法
  3. 输入罗马字，如「konnichiha」，将实时转换为「こんにちは」
  4. 按 Space 键或等待实时转换，将「こんにちは」转换为「今日は」
  5. 按 Enter 键确认输入

四、使用方法与实战

4.1 基础用法

  • 罗马字输入：输入罗马字，自动转换为平假名
  • 汉字转换：输入完成后，按 Space 键（或启用实时转换）将平假名转换为汉字
  • 候选选择：按 Space 键循环切换候选，按数字键直接选择对应候选
  • 表情符号输入：输入假名读音（如「ぴえん」）或 Slack 风格触发词（如「:smile」）输入表情符号

4.2 进阶用法

实时转换开关

按 Ctrl+Shift+L 切换实时转换的开关状态。启用后，输入同时即进行转换推理，无需按 Space 键。

转换学习

当用户选择某个转换结果后，Karukan 会记忆这一选择。下次遇到相同输入时，将优先显示学习后的候选。

例如：

  1. 输入「こうぎょう」，默认转换为「工業」
  2. 用户按 Space 键切换为「興業」并选择
  3. 下次输入「こうぎょう」时，「興業」将作为首选候选显示

预测转换

Karukan 支持预测转换（前缀匹配）。当用户输入中途时，若已学习过相同前缀的转换结果，将自动提示。

例如：

  1. 用户学习了「こうぎょう」→「興業」
  2. 下次输入「こう」时，「興業」将作为预测候选提示

4.3 实际项目示例

示例 1：编写日语文档

# 今日は、世界！

こんにちは、世界！

通过 Karukan 输入：

  • 输入「konnichiha」，转换为「今日は」
  • 输入「sekai」，转换为「世界」

示例 2：输入表情符号

  • 输入「ぴえん」，候选列表显示 🥺
  • 输入「:smile」，候选列表显示 😄

4.4 CLI 工具与服务器

Karukan 提供 karukan-cli 命令行工具，支持以下功能：

  • 字典构建：从 SudachiDict 构建系统字典
  • 字典查看器：浏览和查询系统字典
  • AJIMEE-Bench：基准测试工具，评估转换准确率
  • HTTP 服务器：提供 HTTP API，供其他应用调用 Karukan 转换服务

启动 HTTP 服务器：

karukan-cli server --port 8080

调用转换 API：

curl -X POST http://localhost:8080/convert \
  -H "Content-Type: application/json" \
  -d '{"input": "konnichiha"}'

五、常见问题与解决方案

5.1 安装失败

问题：Linux 下安装后 fcitx5 无法识别 Karukan 输入法。

解决方案：

  1. 确认 fcitx5 已正确安装并运行
  2. 检查 /usr/lib/x86_64-linux-gnu/fcitx5/ 目录下是否存在 karukan.so
  3. 运行 fcitx5-configtool，手动添加 Karukan 输入法
  4. 重启 fcitx5：fcitx5 -r

5.2 模型下载失败

问题：首次启动时，神经网络模型下载失败，无法开始转换。

解决方案：

  1. 确认网络连接正常，能够访问 Hugging Face
  2. 手动下载模型文件，放置到 ~/.local/share/karukan/model/
  3. 设置环境变量 KARUKAN_MODEL_PATH，指定模型文件路径

5.3 转换速度慢

问题：启用实时转换后，输入有延迟，转换速度慢。

解决方案：

  1. 确认 CPU 支持 AVX2 等指令集，llama.cpp 能够利用这些指令集加速推理
  2. 使用量化模型（如 Q4_K_M），减小模型大小，提升推理速度
  3. 关闭实时转换，改为手动按 Space 键触发转换

5.4 兼容性问题

问题：某些应用程序中，Karukan 无法正常输入。

解决方案：

  1. 确认应用程序支持输入法（如终端模拟器可能需要额外配置）
  2. 在 fcitx5 配置中，将 Karukan 设置为首选输入法
  3. 对于 macOS，确认应用程序已获得输入法访问权限

5.5 字典构建失败

问题：运行 karukan-cli dict build 时，字典构建失败。

解决方案：

  1. 确认已安装 SudachiDict 依赖
  2. 检查磁盘空间是否充足（字典文件较大）
  3. 查看日志输出，定位具体错误原因

六、总结

Karukan 是一个技术前瞻、架构清晰的现代日语输入法项目。其采用神经网络模型进行假名汉字转换，相比传统统计模型具有更高的准确率和泛化能力。项目采用 Rust 语言编写，模块化设计，支持 Linux 和 macOS 两大平台，具备实时转换、上下文感知、转换学习等先进特性。

对于日语输入法的开发者和研究者，Karukan 提供了一个优秀的开源参考实现。其神经网络转换引擎、实时转换机制、上下文感知等技术方案，值得深入学习与借鉴。

未来，随着神经网络模型的持续优化和量化技术的进步，Karukan 有望在转换准确率和推理速度上取得更大突破，成为日语输入法领域的重要开源项目。

项目链接：

相关参考文献：

  • llama.cpp - 高性能 LLM 推理框架
  • SudachiDict - 日语词典数据
  • Mozc - Google 日语输入法（候选重写器来源）