人名、术语总说错？Vocalinux自定义词典完全指南：术语偏置+纠错双管齐下

Vocalinux 是一款 100% 离线、免费的 Linux 语音听写工具，通过 whisper.cpp、Whisper、Faster Whisper、VOSK 等引擎把语音实时转成文字。而它的自定义词典功能可以帮你解决听写时最头疼的问题：人名、产品名、专业术语总被识别错。本文将带你用"术语偏置 + 转写纠错"两招，一次搞定。

一、两个功能，先分清

自定义词典包含两个独立的能力（在同一个设置页里，但不能互相替代）：

简单说：偏置是让模型"想"得对，纠错是把结果"改"得对。双管齐下，准确率更高。🎯

二、一键开启：设置页操作步骤

打开Settings → Custom Dictionary，页面分为两个标签页：

1. Custom terms 标签页

   • 打开 "Use custom terms" 开关，启用术语偏置；
   • 在输入框中逐条添加术语（如同事姓名、内部产品名），点Add term保存；
   • 默认词典文件为~/.config/vocalinux/dictionary.txt，UTF-8 格式、每行一个词，空行和#开头的注释都会被忽略；
   • 也可以点Choose Terms File指向你自己的术语文件。

2. Corrections 标签页

   • 在 "Heard as" 输入听错的词（如super base）；
   • 在 "Replace with" 输入正确写法（如Supabase）；
   • 点Add correction，转写完成后会自动替换。

💡 小提示：术语文件会在每次转写前重新读取，你在应用外直接编辑文件，下一句话立即生效，无需重启。

设置页源码见 settings_dialog.py，完整行为设计文档可阅读 docs/CUSTOM_DICTIONARY_DESIGN.md。

三、术语偏置的生效规则（新手必看）

• 每次转写，最多取前 200 个有效术语、2000 个字符注入提示词，所以把最常用的词放前面；
• 术语偏置只覆盖 Whisper 系引擎；如果你在用 VOSK 或 Parakeet，请依赖纠错功能补位；
• 纠错规则匹配时不区分大小写，但替换后的写法会原样保留（大写、连字符都按你写的来）；
• 长词组优先于短词组匹配，避免 "super" 抢跑 "super base" 这类冲突。

四、实战：给术语表加人名，给纠错表加产品名

举个真实场景：

• 你的项目里有个叫VocaLinux的组件、一位叫PyG的同事，术语总被听成vo calink、py gee；
• 把VocaLinux、PyG加进Custom terms，Whisper 系引擎会显著倾向识别出正确拼写；
• 再把vo calink→VocaLinux加进Corrections，即使偏置偶尔失效，转写结果也会被兜底修正。

两条规则配合，基本告别"每次都要手动改字"的尴尬。✍️

五、高级用法：单次会话临时词典

临时会议只关心一组术语？可以用命令行参数为当前会话指定一个术语文件，不改动已保存的设置：

vocalinux --dictionary-file /path/to/dictionary.txt

该参数定义于 main.py。会话期间设置页的术语编辑会被禁用，但转写纠错依然照常生效；退出后一切恢复原样。

六、常见问题（FAQ）

Q1：加了术语为什么没效果？确认你用的引擎是 Whisper、whisper.cpp 或 Faster Whisper；VOSK、Parakeet 和 Remote API 不支持偏置，只能用纠错。

Q2：纠错会误伤词内包含的部分吗？不会。只有当听错短语前后不是英文字母等"词字符"时才会匹配，例如supersize不会被super规则改写。

Q3：纠错和语音命令会不会打架？纠错在语音命令之前执行，可以救回一个"长得像命令"的误识别。但反过来注意：别把替换文本写成new line、period这类命令词，否则会触发命令而不是插入文字。

Q4：文件写坏了怎么办？格式非法的 JSON 或损坏的术语文件会被安全忽略，听写继续进行；设置页会给出状态提示，旧的设置不会被覆盖删除。

总结

Vocalinux 自定义词典的核心思路很简单：识别前给提示，识别后做兜底。配置一次，之后所有听写自动受益——而且全程离线，你的术语表不会离开本机。🔒

更多引擎与模型说明见 docs/USER_GUIDE.md 中的Custom Dictionary Support章节，词典模块核心实现位于 custom_dictionary.py。