Karukan KV cache管理全解析：llama.cpp序列上限与Beam的工程边界-平芜编程栈

Karukan KV cache管理全解析：llama.cpp序列上限与Beam的工程边界

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

Karukan 是一款面向 Linux 和 macOS 的日语输入法系统，核心亮点是用 llama.cpp 运行小型神经网络模型做かな漢字変換（假名汉字转换）。本文带你深入它的引擎层，看 Karukan 的 KV cache 管理如何在 llama.cpp 的序列上限（LLAMA_MAX_SEQ）内，为 beam search（束搜索）候选生成划出一道精确的工程边界。

先看看 Karukan 在实际输入中是什么样子：输入罗马字，候选列表即时弹出神经网络生成的汉字组合。

为什么输入法引擎要操心KV cache？

传统输入法靠词典查表，而 Karukan 把假名转汉字交给一个小语言模型（默认是 Qwen3 109M 的 jinen-v2-small，见 karukan-engine/models.toml）。模型推理时，每个 token 的注意力中间结果都会写进 KV cache——这是推理引擎最重要的状态资源。

对输入法场景来说，有两类典型用法：

贪心解码（greedy）：只要 1 个候选，一条序列跑到底；
Beam search（束搜索）：要 3 个以上候选时，同时养 N 条"存活束"，每步淘汰低分、保留高分，天然需要 N 份 KV 状态。

模型注册表与变体定义在 karukan-engine/src/kanji/model_config.rs，推理实现则集中在 karukan-engine/src/kanji/llamacpp.rs——下面所有工程边界都出自这一个文件。

工程边界的第一道墙：LLAMA_MAX_SEQ = 256

llama.cpp 底层对单个上下文能承载的序列槽数有硬上限（LLAMA_MAX_SEQ，256）。超限不是返回错误，而是抛出 C++ 异常并跨越 FFI 边界直接中止进程——对输入法来说，这意味着整个输入服务崩溃。

Karukan 的对策是一个刻意的常数钳制（llamacpp.rs#L41-L49）：

/// Beam ceiling: live + scratch slots must stay within llama.cpp's /// LLAMA_MAX_SEQ (256), which throws a C++ exception that aborts across FFI. const MAX_BEAM_SIZE: usize = 128;

为什么是 128 而不是 256？因为 beam search 的槽位布局是n_seq = beam_size * 2：前beam_size个是存活束（live beams），后beam_size个是暂存槽（scratch slots），用于安全地搬移 KV 前缀。128 × 2 = 256，正好贴住上限而绝不越界。单元测试里专门验证了这一点：传入beam_size = 200的请求会被钳制而不是让进程暴毙（llamacpp.rs#L1060-L1067）。

💡 用户侧完全感知不到这道墙——候选数由设置控制，引擎在后台悄悄守住边界。

在 fcitx5 环境下安装 Karukan 的效果如下，模型在后台线程加载，加载失败也不会拖垮输入法本体。

KV cache复用的核心：提示词只解码一次

朴素做法是每个束都重新跑一遍完整提示词（re-prefill），成本随束宽线性放大。Karukan 的 generate_beam_search 采用共享提示词 + 缓存拷贝的策略：

提示词只解码一次：整段 jinen 格式提示词（左上下文 + 片假名输入）解码进槽位 0；
一次拷贝广播：copy_kv_cache_seq(0, slot)把槽位 0 的 KV 前缀拷贝给每个存活束（llamacpp.rs#L484-L488），此后每个束只持有"提示词 + 自己生成的 token"；
每步只解码 N 个新 token：一条束一个 token，批量提交给ctx.decode，绝不重复计算提示词部分。

暂存槽：避免"边拷贝边踩雷"

选束时会有棘手的搬移问题：多个新束可能来自同一个父束，而父束自己的槽位又恰好是拷贝目的地——直接原地改写会破坏还没用完的前缀。解法就是前面说的 scratch 槽位，permute_beam_kv 的三步走：

① 每个幸存束：清空 scratch 槽 → 从父槽拷贝前缀进 scratch ② 清空全部 live 槽（顺带回收已结束束的 KV 单元） ③ 把 scratch 里排好序的前缀搬回 live 槽，再清空 scratch

这是一次精心编排的"置换"，保证任何时刻被读取的前缀都不会被半路覆盖。

三道常数：headroom 怎么算的

上下文要分配多大的 KV 池？Karukan 用三个常数精确核算（llamacpp.rs#L41-L49）：

常数	值	作用
`MAX_BEAM_SIZE`	128	束宽钳制，保 2×128 ≤ 256 序列上限
`KV_HEADROOM_CELLS`	64	提示词+生成行之外的冗余 KV 单元
`BATCH_HEADROOM`	8	冗余 batch 槽，同时覆盖`n_seq`的输出缓冲区

KV 池大小的计算公式（llamacpp.rs#L459-L466）：

let n_cells = input_len + 2 * beam_size * (max_new_tokens + 1) + KV_HEADROOM_CELLS;

2 ×的系数覆盖了"后端可能以物化拷贝而非共享单元格实现"的最坏情况。默认max_new_tokens为 50（见 ConversionConfig::default），所以即使束宽拉满，池子大小也是可预测的定值——不会中途扩容，也不会悄悄超限。

贪心路径则更抠门：batch 尺寸按提示词长度动态设定（input_len + 8），刻意不继承 llama.cpp 默认的 2048/512，省掉每次转换都多分配一个数量级的临时内存（llamacpp.rs#L798-L810）。

复用与清理：NllScorer 的单上下文策略

创建LlamaContext是昂贵的。用于候选 NLL 打分的 NllScorer 只建一个上下文常驻，每次打分前调用clear_kv_cache()把 KV 池清零复用（llamacpp.rs#L880-L894）。配合"每线程一个 scorer"的并行策略，既摊薄了上下文创建成本，又让 KV 生命周期完全可预测：每次调用之间是干净的。

等价性测试：让优化"只是变快"

复用 KV cache 的 beam search 是否和朴素实现选出一模一样的候选？Karukan 保留了一个故意低效的参考实现 generate_beam_search_full_eval（每束每步在全新上下文里 re-prefill），并用测试 matches_full_eval_reference 逐束宽、逐用例断言两者输出完全一致。这个测试就是那道护栏：如果槽位分配、父束置换或位置计算有任何差错，束会"注意到错误的前缀"并立即在这里暴露。

延迟侧的实测脚本见 karukan-engine/examples/beam_bench.rs：对 21 字假名串扫描线程数，对比 beam-3 与贪心的中位延迟——这正是把 KV cache 管理做好之后，"多个候选"与"单个候选"之间的真实代价。