企业官网建设流程全解析

Karukan候选构建机制全解：6类候选源的合并、去重与排序

【免费下载链接】karukanJapanese Input Method System for Linux, macOS, Neural Kana-Kanji Conversion Engine项目地址: https://gitcode.com/GitHub_Trending/ka/karukan

Karukan 是一款面向 Linux 和 macOS 的日语输入法系统，内置神经网络假名汉字转换引擎。它的核心难题在于：按下空格后，候选窗口里的一行行汉字并非来自单一来源——AI 模型、学习缓存、用户词典、系统词典、假名回退、规则改写器等6 类候选源会同时产出结果。本文完整拆解 Karukan 候选构建机制：这些候选如何按优先级合并、如何去重、又如何排序后呈现给你。

一、候选从哪里来？先看整体流水线

在 Karukan 中，你键入罗马字 → 引擎转成平假名（reading）→ 按空格触发转换。此时 start_conversion() 启动一条固定的构建流水线：

1. 查询学习缓存（你历史上选过的转换）
2. 查询词典（用户词典 + 系统词典）
3. 模型推理（神经网络假名汉字转换，结果带缓存）
4. 补上回退项与改写项（假名、半角片假名、符号、日期变体）
5. 统一去重并回填注释，交给候选窗口分页展示

其中模型推理由 run_kana_kanji_conversion() 调度，策略选择（主模型 / 轻量模型 / 并行束搜索）逻辑在 strategy.rs 中——机器慢时自动降级到轻量模型，保证候选不卡顿。

二、6类候选源逐一点名：谁产出了哪行候选

每个候选都携带一个 CandidateSource 标签，标记它的出身。界面辅助栏会显示对应图标：

另有特殊的 📅日期候选（Date）：键入[date]类短语时由时钟实时渲染，因"明天就过期"所以不会被写入学习记录（见 is_learnable()）。

💡 词典候选的查找顺序也讲究：用户词典一定排在系统词典前面；每个词典内部又是"精确匹配优先，前缀预测在后"。相关优先级说明见官方文档 docs/dictionary.md。

三、合并与去重：先到先得，学习缓存"强制置顶"

多源合并的核心是 CandidateBuilder 结构体，内部维护一个"已见文本"集合，提供两条写入路径：

• push()（普通写入）：文本已出现过就丢弃——先来的候选源"占坑"，后来的重复项直接消失；
• push_force()（强制写入）：无条件插入，并把文本标记为已见。

唯一使用强制写入的是学习缓存：你教给输入法的答案，即使后面词典或模型再产出同样文本，也必须排在最前面、保持你选择的顺序（见 build_conversion_candidates()）。

去重之外还有两处"隐形合并"：

• 模型内部合并：并行束搜索时，主模型与轻量模型的结果用 merge_candidates_dedup() 先合并去重再进入总流水线；
• 词典双源去重：用户词典与系统词典共享同一个"已见"集合，同一条词面只显示一次，但保留它来自哪本"书"的标签。

四、排序机制：为什么你选的词总是排第一

最终列表的顺序完全由候选源的注入顺序决定——没有复杂的重排打分，规则简单可预期：

学习缓存 → 用户词典 → AI 模型 → 系统词典 → 假名回退 → 日期/改写器

再叠加三条细节规则：

1. 词典内部：精确匹配在前，前缀预测在后；预测项最多 3 条，且需至少输入 2 个字符才触发（防止单个按键刷爆列表）；
2. 悬尾约束：输入末尾还有未完成的罗马字时（如わsed中的d），精确匹配暂停，预测项会被收窄到"这个尾巴还能变成的假名"范围；
3. 注释回填：合并完成后统一补注——符号候选标注名称（如「金 = 部首」，仅限回退源），纯假名候选标注宽度（[全]ひらがな/[全]カタカナ）。

最后 CandidateList 接手：每页 9 条、支持循环翻页，空格/Tab 下一条，Shift+Tab 上一条，数字键 1-9 直达提交。

五、进阶技巧：用 Ctrl+R / Ctrl+T 单独查看每个候选源

混合列表按最高优先级源去重，某些文本可能在其他源里"被吃掉"。为此 Karukan 提供了来源过滤视图：Ctrl+T/Ctrl+R按 固定循环 在 📝学习 → 📚词典 → 🤖模型 → 🔄改写 四个视图间切换，Ctrl+I直达 AI 视图。

关键设计：每个视图不是过滤混合列表，而是直接重新查询对应来源——否则去重逻辑会把共享文本折叠进最高优先级源，低优先级视图就看不全了。空源会显示「候補なし」而非跳过，位置永远可预测。

在 Linux 上，Karukan 以 fcitx5 插件形式运行，上述候选行为在 fcitx5 环境中完整生效（安装步骤见 karukan-im/fcitx5/README.md）。

六、小结：一套简单可预期的候选流水线

想深入阅读？推荐按顺序查看：转换构建源码 conversion.rs、来源过滤源码 filter.rs、模型调度源码 model.rs，以及官方文档 docs/dictionary.md 与 docs/key-bindings.md。理解了这套"优先级注入 + 文本去重"的机制，你就能完全预测并掌控 Karukan 候选窗口里的每一行输出。

【免费下载链接】karukanJapanese Input Method System for Linux, macOS, Neural Kana-Kanji Conversion Engine项目地址: https://gitcode.com/GitHub_Trending/ka/karukan