Parakeet 的自定义词汇表¶

状态： 研究，2026-10-22。工作量数字是我的估算。来自厂商自身基准测试或第三方文章的声明会照实标注。更新 2026-10-28： 词汇表增强现已实现为解码后的重新评分，而不是解码循环中的加分；参见 vocabulary-boost-results.md。

问题（Kit）： 用户想要语音替换和词汇表，而 Hex 的默认模型 Parakeet 没有提示（hints）。我们能否自己构建一些东西，包括训练或修改模型？

简短回答： 可以，而且其中大部分比训练更便宜。

• 模型不是障碍。Hex 的 Parakeet 解码循环在宿主 CPU 上运行，一次一个 token，基于一个普通的 logits 数组（参见 为什么 Parakeet 可以被施加偏置）。增加词汇表增强是对该循环的一个小改动。它不是模型改动。
• 如今的替换功能无法修复 Kit 真正错漏的地方。"Hanks" 和 "Capuchin" 是真实存在的词。盲目替换会破坏所有合法使用场景。
• 按用户微调并不划算。在中央位置针对开发者词汇语料库进行一次训练，是将来更合理的赌注。

1. 用户的诉求¶

Hex 自己的议题¶

两个仓库都在 2026-10-22 通读了完整 issue 列表。kitlangton/Hex 是旧版 Swift 应用；anomalyco/hex 是本仓库。

我找到的内容没有任何一条要求训练。每一条请求都是"把我的词识别正确"，而且报告者都假设用的是术语列表。

竞品¶

以下所有声明均来自各产品自己的文档，除非另有说明。

我没有找到专门讨论 Hex 和词汇表的 Reddit 或 X 帖子。 我使用的搜索工具几乎没有返回结果。上述用户信号来自 问题跟踪器。

市场最终达成的共识¶

1. 一份简短的精选列表。 每个供应商都表示，它不是常见单词的堆砌。
2. 两层结构： 一层是发送给识别器的提示，另一层是之后应用的字面 替换。Superwhisper 和 Flow 都在 UI 中将这两者分开。
3. 从用户的编辑中学习，并带确认和撤销功能。 Flow 和 TypeWhisper 都这样做。
4. 屏幕或应用上下文 作为术语的来源。Flow 和 Aqua 都宣传了这一点。

2. Parakeet 的技术选项¶

为什么 Parakeet 能够被偏置¶

我阅读了固定的 transcribe-cpp-sys 0.2.4 源码（Hex 使用的版本）以及 上游仓库的最新版本（handy-computer/transcribe.cpp，2026-10-22， 0.4.1 版本）。

• 每个 Parakeet 头（TDT、RNN-T、CTC）都在宿主机上解码。 src/arch/parakeet/decoder.h 说“解码器完全以 ggml 图的形式运行在 一个共享的、每次解码独立的 CPU 线程池上”，即使编码器在 GPU 上也是如此。
• 在 decoder.cpp 中，decode_tdt_greedy 和 decode_rnnt_greedy（以及 流式 RNN-T 变体）都会调用 joint_step，后者将联合 输出复制到宿主机 std::vector<float> logits 中并应用 log-softmax。 下一个 token 随后是 argmax_range(token_logits, n_token_cls)。 Blank 是 blank_id = vocab，因此它位于同一个切片中。
• 因此，在 argmax 之前向选定的 token logits 添加偏置，只需在 一个已存在的循环中写几行代码。每个 token 的置信度已经计算出来了 （token_confidence，基于熵），公共 API 将其作为 Token::p 返回，以及词和 token 的时间戳。Hex 已经调用了 transcribe_segments 并读取了 transcript.words；目前它没有读取 tokens 或 p。
• 上游的 docs/prompting.md 定义了通用的 vocabulary 和 prompt 字段及功能位。表格列出了 Whisper、Qwen3-ASR、Granite、 Fun-ASR-Nano 和 MOSS。Parakeet 未被列出。 它的 vocabulary 槽位 是空的。
• transcribe_tokenize 对 Parakeet 返回 INT_MIN（“SentencePiece； 目前返回 INT_MIN”）。因此，将用户术语编码为 token 尚未实现。GGUF 带有 SentencePiece 词汇表（根据 NVIDIA 的模型卡，英语模型为 1,024 个片段），所以必须有人来编写该 编码器。
• transcribe.cpp 中没有任何 LoRA 或适配器加载功能。搜索 src/ 和 docs/ 没有发现任何相关内容，除了 Moonshine Streaming 中一个无关的“适配器”层。
• 默认模型 Parakeet Unified English 0.6B 是 RNN-T，GGUF 中没有 CTC 头。 混合模型 parakeet-tdt_ctc-110m 端口在转换时明确丢弃了其 CTC 头。

按单位努力所获得的质量排序的选项¶

A. 词汇表提供给已有功能（确定性，约 1 周）¶

一个词汇表，由所有模式共享（模型不需要支持 提示）。它提供给：

1. Whisper 的提示，以及 Qwen3-ASR 在 transcribe-cpp 从 0.2.4 升级到 0.4.x 之后的提示。 #129 描述了这一变化。报告者遇到的唯一 API 破坏是 Model::capabilities() 现在返回 Result。
2. OpenCode 重写提示：“这些术语存在；当一个词听起来像其中一个时， 优先使用这些拼写”。这是能修复 “Hanks”和“Capuchin”的最廉价选项，因为 LLM 能看到整个句子。它会带来 延迟，并且可按模式选择是否启用。
3. 替换： 作为确定性层保留，先进行批量导入和 #139 与 #177 的修复。

限制：LLM 可能过度纠正并增加延迟，提示也可能诱发 Whisper 幻觉。Hex 已经有关于 Whisper 在静音时编造文本的报告 （anomalyco/hex #193 和 #108，kitlangton/Hex #206）。Superwhisper 自己的文档也提到 了长词汇表有同样的问题。保持提示列表简短并设置上限。

B. 置信度门控的语音近似修正（约 1 到 2 周）¶

识别后的一次纯 Rust 处理。对于转录文本中每一个 1-3 个词的片段， 将其与每个词汇术语进行语音比较（使用字素到音素的 编辑距离或 Double Metaphone 键，并以字母相似性检查作为 第二信号）。当匹配接近且该片段不是高置信度的 常见词时进行替换，使用 Hex 已有的 Token::p 和词时间戳。

• 它适用于所有模型，且不需要修改模型。
• “Hex”和“Hanks”在发音上很接近（hɛks 和 hæŋks），“Cappuccino”和 “Capuchin”也是如此。弱点在于第二种情况：Parakeet 很可能对 “Capuchin”非常自信，因为它是一个常见词。置信度 门控随后会跳过 Kit 报告的那个确切错误。我尚未对此进行测量。 将门控视为误报限制器，而不是召回率驱动力。
• FluidAudio 的重打分器具有相同形式的防护，它是一份有用的 参考清单：最小相似度、对短词更严格的阈值（四个或更少字符为 80%）、 当片段包含停用词时更严格的阈值 （85%），以及随词汇表大小提高的阈值。
• 学到的“听起来像”别名（见 D）会使其效果好得多。它们 实际上是一个针对每个用户的混淆表。

C. transcribe.cpp 内的解码时短语增强（质量最佳，约 1 周 spike，3 到 5 周发布）¶

NVIDIA 的 GPU-PB 正是这个思路：“仅在浅融合模式的解码步骤中应用”，它“在 token 级别用提升树重新调整 ASR 模型分数”，无需重新训练，并支持 CTC、RNN-T/TDT 和 Canary 的贪心解码。论文（arXiv 2508.07014）称其“即使有大量关键短语（最多 20K 项），也不会出现明显的速度下降”。sherpa-onnx 用相同的思路实现了 Aho-Corasick 自动机，作用于分词后的热词，提升每个匹配的前缀 token，并在路径无法完成时取消提升。

对于 Hex：

1. 为 Parakeet 实现 SentencePiece 编码。Parakeet 输出区分大小写的文本，而 NeMo 的文档说明关键短语必须预先大写，因此每个术语使用多种大小写形式。
2. 在解码循环中构建一个 trie 或 Aho-Corasick 图。在 joint_step 之后，将 boost 加到那些扩展了当前实时部分匹配的 token 的 logits 上。当路径失败时移除该 boost。
3. 为它加上门控，使 boost 不会劫持普通语音：仅当被提升的 token 与最佳 token 的差距在某个范围内时才应用它，并对每个术语的总 boost 设置上限。
4. 将其作为 Parakeet 尚未实现的 vocabulary 运行选项暴露出来，并向上游提交，或者维护一个 fork（分支）。Hex 将 transcribe-cpp 固定为 0.2.4，而上游目前是 0.4.1。

在承诺之前，我会用 spike（技术验证）来解决的未知问题：

• 贪婪提升的质量。 Chirp 的设计说明提到 sherpa-onnx 只在 modified_beam_search 中支持热词，并引用了上游关于 TDT 束搜索中约 20% 幻觉率的问题（二手信息；我未验证）。带边际门控的贪婪循环可以绕过束搜索，但 NVIDIA 的论文是贪婪提升效果良好的唯一证据，而且它是在 NeMo 中运行的，不是在这里。
• 规模。 NVIDIA 的 NIM 文档建议对 RNN-T 和 TDT 模型进行动态提升时，“最多约 500 个词”，更大的列表则静态构建。
• 流式路径。 流式解码器是独立的，因此它需要同样的 hook。听写流式功能尚属推测性，并且会回退到整段音频，因此整段路径可以先发布。
• 上游是否接受 不在我们的控制范围内。

D. 从用户显式编辑中学习术语（约 2 周，取决于 A 或 B）¶

Wispr 和 TypeWhisper 都这样做，anomalyco/hex #15 规定了一个谨慎的版本（与 Hex 输出相关的、反复出现且数量有限的证据；确认机制；无键盘记录）。它被关闭为“未计划”，因此这是一个需要重新讨论的产品决策。输入是原始文本、最终文本，以及粘贴后的用户编辑。Hex 的 History 存储原始文本和最终文本，但不存储用户的编辑。辅助功能适配器可以读取聚焦的字段，但这是一个隐私敏感面，需要与 #15 相同的限制。输出是一个词汇术语加上一个“被听成”的别名。

更便宜的第一步，且不新增隐私敏感面：让用户从 History 中添加一个听错的例子（“Hex 被听成了 Hanks”），只需一次点击，即可创建一个术语和别名。

E. CTC 词检测与重新打分（已由他人验证，对 Hex 而言工作量大得多）¶

这是 NVIDIA 的 CTC-WS（arXiv 2406.07096），由 FluidAudio 发布。一个独立的 CTC 模型根据上下文图对音频进行评分，其检测结果会在声学证据更强的地方替换 transducer 的词。这是唯一在 Parakeet 上有独立测量的方法：

MacParakeet 的 Phase 0 笔记（第三方，使用 macOS say 生成的合成音频，50 个术语，FluidAudio 0.15.4）：

同一份笔记还发现吞吐量从 103 RTFx 下降到 31 RTFx，并且发现 Unified 模型不受支持：CTC sidecar 检测到了术语，但库中没有 hook 来应用它们，因此召回率停留在 13/50。对 Hex 而言有两点很重要：门控阈值决定一切（错误替换会严重损害 WER），而 Hex 的默认模型是 Unified。

在 Hex 中需要的东西：一个来自 transcribe.cpp 的 CTC log-prob API，该 API 目前不存在（公共头文件只暴露了 token 的 p）；通过 CTC 模型进行第二次编码器传递；以及 DP 和重新打分代码。相比 C 方案，工作量更大，但结果类似。如果解码器 spike 的结果不理想，就将其视为后备方案。

F. 使用词汇表的 LLM 纠正¶

已在 A.2 中涵盖。Apple 的 FoundationModels 是 OpenCode 的一个可行本地替代方案。sayline.app 的 Show HN 帖子报告称，在听写重写场景中，Apple 模型的内容过滤器“阻止了几乎每一个有用的请求”（轶事，来自一位作者）。anomalyco/hex #167 已经跟踪 Voice Action 的 Foundation Model 支持。

G. 个性化与训练（不建议按用户实施）¶

• 数据量。 NVIDIA 自己的指南（NIM 定制文档）说：“我们建议仅在数据充足的情况下微调 ASR 模型，即需要数百小时的语音。如果没有这样的数据，更有效的做法是在领域内文本语料库上调整 LM。”单个用户保留的听写内容只有几分钟到几小时，且主要是其正常语音。这会有遗忘的风险，而且对十几个重要术语提供的信号很少。
• 将编辑作为训练对。 Hex 的 History 存储原始文本和最终文本对，并且只能在 HEX_RETAIN_DICTATION_AUDIO 下保留 WAV（显式、有界、仅限所有者）。这些配对有助于挖掘术语和别名（D），也可作为私有评估集。但数量太少、噪声太大，不适合训练。
• 纯文本适配是存在的。 NeMo 有一个混合 ASR-TTS 模型，可以通过将文本送入一个冻结的 FastPitch 文本转 mel 生成器，仅用文本就能微调 ASR 模型，这样可以让纯文本数据与音频混合。它支持 CTC 和 RNN-T BPE 模型。针对罕见术语的合成语音是另一条路线，Hex 的 dictation-corpus 分支已经在使用 macOS say 和 ElevenLabs 生成合成片段。
• 没有 Mac 路径，也没有适配器路径。 NeMo 是一个基于 PyTorch 和 CUDA 的工具包，我没有找到支持 Mac 的训练方案（未验证）。transcribe.cpp 不支持加载适配器，因此用户特定的结果只能作为完全合并的 GGUF 发布（约 0.6 到 2.5 GB）。这对每个用户来说都不现实。
• 中央模型是一个真正的后续选项。 Aqua 的 Avalon 就是一个存在的证明：针对 AI 和编码词汇训练的模型确实会改变结果（供应商报告：在其自身基准上，关键术语准确率为 97.4%，而基线为 51.5% 到 65.1%）。基于 Unified English 基础模型进行 Anomaly 训练的“面向开发者的 Parakeet”微调，使用针对工具、产品和人物名称的合成 TTS 数据加上真实数据，通过现有的 transcribe.cpp 转换路径转换为 GGUF，这需要几周时间和 GPU 预算，并存在降低通用 WER 的风险。请先检查 NVIDIA Open Model License 关于衍生作品再分发的条款。该模型自己的文档列出了这一许可证；我没有阅读其衍生条款。

3. 建议¶

先进行构建（总共约 2 到 3 周）¶

1. 每个 Hex 一个词汇表，支持导入/导出。 术语、可选的“听到为”别名、可选的按模式作用域。修复 #139 和 #177。添加 CSV 或文本批量导入（kitlangton/Hex #160）。一键“从历史记录添加”。
2. 将词汇表接入现有组件： Whisper 提示（限制列表长度）、OpenCode 重写提示（针对已开启重写的模式）、以及针对别名的确定性替换。将 transcribe-cpp 升级到 0.4.x 以支持 Qwen3-ASR 提示（#129），作为单独步骤，因为它会更改固定的依赖项。
3. 置信度门控的语音吸附（选项 B），默认关闭，并带有 FluidAudio 风格的防护措施。将其置于与步骤 4 相同的基准门控之后进行发布。
4. 在所有这些功能发布之前先进行评估。 参见下一节。先做这一步，因为错误替换率决定了 B、C 或 E 中任何一个是否可接受。

更大的赌注：解码器端增强（选项 C）¶

在 transcribe.cpp 的检出中进行为期一周的预研：在 decode_rnnt_greedy 和 decode_tdt_greedy 中通过环境变量硬编码一个增强列表，并带有边际门控，然后在术语语料库上针对 Parakeet Unified 和 v2 运行它。成功标准是召回率达到或超过 70%，错误替换率接近零，且 WER 变化低于 0.3 个百分点（MacParakeet 使用了相同的门控）。如果通过，则编写 SentencePiece 编码器，并将其作为 Parakeet 的 vocabulary 提交到上游。如果未通过，则回退到 E。

这是唯一能修复模型从未作为候选词生成的术语的方案，而且它不需要第二个模型。

不值得做¶

• 针对每位用户的 LoRA 或微调，以及在用户编辑上的训练。数据太少，没有 Mac 路径，而且 transcribe.cpp 中没有适配器格式。
• 仅为了词汇而将默认模型热切换到不同的 Parakeet 变体。不同变体在速度和准确性上存在差异，而且没有一个在 GGUF 中包含 CTC 头。
• 作为第一步，将屏幕 OCR 获取上下文（kitlangton/Hex #187）纳入方案。权限成本很高，而且 Parakeet 无论如何也无法接受提示。当增强列表存在时再重新考虑，因为屏幕上的术语只是一个动态词汇表。
• 对真实单词的盲目替换。“Hanks to Hex” 和 “Capuchin to Cappuccino” 会破坏合法用法。将它们置于某个模式、某个上下文或仅在置信度较高的语音匹配后才出现的别名之后。

4. 如何衡量¶

Hex 已经具备大部分组件：

• hex benchmark-transcription <manifest.json> 通过生产环境的 transcribe.cpp 路径运行一个由 {id, audio, expected} 片段组成的语料库，并报告 WER 和 RTF。这记录在 docs/research/transcription-benchmark.md 中。
• test/dictation-corpus 分支有一个语料库测试框架（scripts/dictation-corpus.sh、src/dictation_corpus_tests.rs），它读取 synthetic/say_manifest.json 和 synthetic/elevenlabs_manifest.json，以及真实片段。

新增：

1. 术语语料库。 一开始仅文本：大约 100 个句子，每个句子包含一个或多个目标术语（OpenCode、Rune、Scrawl、Effect、Anomaly、Cappuccino、Hex，以及真实姓名）。使用多种 say 声音、至少一种 ElevenLabs 声音以及 Kit 自己录制的一小批音频进行渲染，包括出现 “Hanks” 和 “Capuchin” 的会议片段。真实片段比合成片段更重要：MacParakeet 的说明本身也指出，合成的 say 音频无法替代口音和麦克风。
2. 两个指标，而不是一个。
   • 术语召回率： 预期术语精确出现在输出中（大小写和间距已规范化）。
   • 错误替换率： 在参考文本没有这些术语的地方插入了术语，使用无术语语料库（LibriSpeech test-clean，加上 Kit 自己录制的没有目标术语的录音）进行测量。仅靠 WER 会掩盖这一点。
3. 一个门控： 在无术语语料库上 WER 变化至多 0.3 个百分点，如 MacParakeet 的说明所述；对于 10 秒片段，p95 新增延迟低于约 100 毫秒（我的数字）。将基线、A、B 和预研实验作为单独的列运行。
4. 真实漏报的固定测试集。 将 Hanks 和 Capuchin 保留为永久回归片段。

使用 expected_terms 扩展 manifest，并为 benchmark-transcription 添加一个 --vocabulary <file> 选项，以便每种方法都通过同一个测试框架运行。

来源¶

• Hex：src/parakeet.rs（提示仅限 Whisper）、src/transcription_models.rs（supports_recognition_hints）、src/dictation/text_replacements.rs、src/dictation_processor.rs、src/history.rs，以及上述问题。
• transcribe.cpp：handy-computer/transcribe.cpp 位于提交 4d7c1cc（docs/prompting.md、include/transcribe.h、src/arch/parakeet/decoder.cpp、decoder.h、docs/models/parakeet-tdt_ctc-110m.md），以及 Hex 随附的 transcribe-cpp-sys 0.2.4。
• NVIDIA NeMo：Word Boosting（docs.nvidia.com/nemo-framework/.../asr_customization/word_boosting.html）；GPU-PB，arXiv 2508.07014；CTC-WS，arXiv 2406.07096；NIM 定制文档中关于 500 个单词和数百小时指导的内容；NeMo 模型页面中的 ASR-TTS 混合模型部分。
• sherpa-onnx 热词文档（k2-fsa.github.io/sherpa/onnx/hotwords）。
• FluidAudio Documentation/ASR/CustomVocabulary.md；MacParakeet docs/research/2026-07-04-custom-vocab-phase0.md；Chirp docs/superpowers/specs/2026-03-30-vocabulary-hotwords-design.md。
• Superwhisper、Wispr Flow、MacWhisper、TypeWhisper 和 Aqua Voice 的文档和博客页面，以及 Apple 的 AnalysisContext 文档。