wehub-resource-sync
5.9 KiB
热词功能如何使用
什么是热词
热词功能用于修正语音识别结果中的特定词汇。比如你 "CapsWriter" 是一个非常见词，可能被识别成 "Caps rider"，就可以通过热词进行修正。
CapsWriter-Offline 提供了三种热词机制，分别用于不同场景。
一、客户端强制热词（hot.txt）
作用
基于音素匹配的强制替换。只要识别文本的音素与热词足够相似（超过阈值），一定会被替换。适用于人名、专业术语、英文品牌等识别不准的词。
文件位置
项目根目录的 hot.txt，修改后自动热重载，无需重启。
格式
- 每行一个热词
#开头的行为注释- 用
|分隔多个别名（写法不同，音素相似，都替换为第一个词） - 在
~~~后面添加黑名单
# 这是注释
Claude | Cloud | 克劳德 | 克劳得 ~~~ Weather | Sky
CapsWriter | Caps Rider |
我家鸽鸽
上例中，如果说 "cloud" 或 "克劳德"，都会被替换为 "Claude"，但当周围有 weather 或 sky 时，就不会替换。
自定义短语
热词的第一个词不一定是"纠正目标"，也可以是你希望输入的内容，后面跟触发别名。这样就可以用作"自定义短语"，用语音快速输入长文本，而不必逐字念：
18200006666 | 我的手机号 | input my phone
上海市浦东新区张江高科技园区 | input my address
hello@example.com | 我的邮箱 | input my email
上例中，说"我的手机号"或"input my phone"，都会自动上屏 "18200006666"，不需要一个个数字念。
如何添加热词
方法一：直接编辑 hot.txt，保存后自动生效。
方法二：右键系统托盘图标 → 添加热词 → 在弹出的对话框中输入热词（每行一个）→ 确认。
配置项
在 `config_client.py 中：
hot = True # 总开关，是否启用音素热词替换
hot_thresh = 0.85 # 替换阈值（越高越精准，越低越容易触发）
hot_similar = 0.6 # 相似阈值（低于 hot_thresh 但高于此值的，只作为 LLM 参考）
二、规则替换（hot-rule.txt）
作用
基于正则表达式的精确替换。适用于单位转换、符号修正等固定模式替换。（正则语法可参考 Python 正则表达式）
文件位置
项目根目录的 hot-rule.txt，修改后自动热重载。
格式
查找模式 = 替换文本
=两边必须有空格- 查找模式是正则表达式，支持捕获组
#开头的行为注释- 替换侧可用
\s表示空格
示例
毫安时 = mAh
赫兹 = Hz
(艾特)\s*(QQ)\s*点\s* = @qq.
(艾特)\s*(\w+)\s*(点)\s*(\w+) = @\2.\4
欧拉玛 = Ollama
\/sil =
\[breath\] =
(^逗号[，。]?)|([，。]?逗号$) = ，
(^句号[，。]?)|([，。]?句号$) = 。
(^问号[，。]?)|([，。]?问号$) = ？
配置项
hot_rule = True # 是否启用规则替换
三、服务端热词（hot-server.txt）
作用
部分模型自带热词功能，会用这个文件中的热词，用作语境增强。
具体原理是：
- Fun-ASR-Nano 有两个解码器，CTC Decoder 和 LLM Decoder。
- CTC Decoder 会输出一个较粗糙的结果，可通过音素检索出全部热词中发音最相近的几个
- 发音最相近的热词被放入 LLM Decoder 的上下文，辅助精确识别。但上下文提示仅具建议性，LLM Decoder 会根据语境决定是否采纳。
- SenseVoice 的解码器是 CTC Decoder，每帧音频会依概率转为文字，设计了一种扫描算法，当 CTC 的连续概率空间内出现热词时，强制输出热词。不建议添加长度太短的英文热词，否则容易误换。
事实上，客户端热词（加上别名功能后）就已经完全够用，仅是因为有模型支持这个特性，于是加上了这个功能。
文件位置
项目根目录的 hot-server.txt，服务端暂无热重载。
格式
每行一个热词，# 开头为注释：
# ========== 中文热词 ==========
机器学习
深度学习
自然语言处理
# ========== 英文热词 ==========
Transformer
PyTorch
TensorFlow
四、客户端热词工作流程
语音识别结果
↓
音素 RAG 匹配（hot.txt）
├─ 相似度 ≥ hot_thresh → 周围没有黑名单词 → 强制替换
└─ hot_similar ≤ 相似度 < hot_thresh → 记作"潜在热词"，可传入角色上下文，用于润色
↓
正则规则替换（hot-rule.txt）
↓
（可选）角色功能润色
↓
输出
其实，Qwen3-ASR 已经非常强大，加上热词功能，已经完全不需要 LLM 润色功能。只是 Typeless 有润色，LLM 又这么火，总会有朋友想试试。
五、实用技巧
1. 英文热词
直接英文单词专用术语，辅助正确的大小写拼写：
PyTorch
TensorRT
DirectML
2. 用别名覆盖多种口音
Claude | Cloud | 克劳德 | 克劳得
六、常见问题
Q: 修改热词文件后需要重启吗？
客户端会自动检测热词文件变化，修改的 3 秒后自动重载。
Q: 热词为什么没生效？
检查以下几点：
config_client.py中hot = True是否开启hot_thresh是否过高- 热词是否添加到了正确的文件（服务端热词放到
hot.txt而不是hot-server.txt） - 日志中是否有匹配记录（查看
logs/client_latest.log）
Q: hot.txt 和 hot-server.txt 有什么区别？
hot.txt 是客户端强制替换，匹配了一定会改；hot-server.txt 是服务端功能，仅支持的模型可用，且不具备强制性
Q: 规则替换的正则语法是什么？
Python 标准 re 模块语法，支持 \1、\2 等反向引用。