# 热词功能如何使用

## 什么是热词

热词功能用于修正语音识别结果中的特定词汇。比如你 "CapsWriter" 是一个非常见词，可能被识别成 "Caps rider"，就可以通过热词进行修正。

CapsWriter-Offline 提供了**三种热词机制**，分别用于不同场景。

---

## 一、客户端强制热词（hot.txt）

### 作用

基于**音素匹配**的强制替换。只要识别文本的音素与热词足够相似（超过阈值），**一定会被替换**。适用于人名、专业术语、英文品牌等识别不准的词。

### 文件位置

项目根目录的 `hot.txt`，修改后**自动热重载**，无需重启。

### 格式

- 每行一个热词
- `#` 开头的行为注释
- 用 `|` 分隔多个别名（写法不同，音素相似，都替换为第一个词）
- 在 `~~~` 后面添加黑名单

```text
# 这是注释
Claude | Cloud | 克劳德 | 克劳得 ~~~ Weather | Sky
CapsWriter | Caps Rider | 
我家鸽鸽
```

上例中，如果说 "cloud" 或 "克劳德"，都会被替换为 "Claude"，但当周围有 weather 或 sky 时，就不会替换。

### 自定义短语

热词的第一个词不一定是"纠正目标"，也可以是**你希望输入的内容**，后面跟触发别名。这样就可以用作"自定义短语"，用语音快速输入长文本，而不必逐字念：

```text
18200006666 | 我的手机号 | input my phone
上海市浦东新区张江高科技园区 | input my address
hello@example.com | 我的邮箱 | input my email
```

上例中，说"我的手机号"或"input my phone"，都会自动上屏 "18200006666"，不需要一个个数字念。

### 如何添加热词

**方法一**：直接编辑 `hot.txt`，保存后自动生效。

**方法二**：右键系统托盘图标 → **添加热词** → 在弹出的对话框中输入热词（每行一个）→ 确认。

### 配置项

在 [`config_client.py](../config_client.py) 中：

```python
hot = True          # 总开关，是否启用音素热词替换
hot_thresh = 0.85   # 替换阈值（越高越精准，越低越容易触发）
hot_similar = 0.6   # 相似阈值（低于 hot_thresh 但高于此值的，只作为 LLM 参考）
```

---

## 二、规则替换（hot-rule.txt）

### 作用

基于**正则表达式**的精确替换。适用于单位转换、符号修正等固定模式替换。（正则语法可参考 [Python 正则表达式](Python%20正则表达式.md)）

### 文件位置

项目根目录的 `hot-rule.txt`，修改后**自动热重载**。

### 格式

```
查找模式 = 替换文本
```

- `=` 两边必须有空格
- 查找模式是正则表达式，支持捕获组
- `#` 开头的行为注释
- 替换侧可用 `\s` 表示空格

### 示例

```text
毫安时     =      mAh
赫兹      =      Hz
(艾特)\s*(QQ)\s*点\s*            =     @qq.
(艾特)\s*(\w+)\s*(点)\s*(\w+)    =     @\2.\4
欧拉玛   =  Ollama
\/sil   =   
\[breath\]  =    
(^逗号[，。]?)|([，。]?逗号$)       =    ，
(^句号[，。]?)|([，。]?句号$)       =    。
(^问号[，。]?)|([，。]?问号$)       =    ？
```

### 配置项

```python
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`，服务端暂无热重载。

### 格式

每行一个热词，`#` 开头为注释：

```text
# ========== 中文热词 ==========
机器学习
深度学习
自然语言处理

# ========== 英文热词 ==========
Transformer
PyTorch
TensorFlow
```


---

## 四、客户端热词工作流程

```
语音识别结果
    ↓
音素 RAG 匹配（hot.txt）
    ├─ 相似度 ≥ hot_thresh → 周围没有黑名单词 → 强制替换
    └─ hot_similar ≤ 相似度 < hot_thresh → 记作"潜在热词"，可传入角色上下文，用于润色
    ↓
正则规则替换（hot-rule.txt）
    ↓
（可选）角色功能润色
    ↓
输出
```

其实，Qwen3-ASR 已经非常强大，加上热词功能，已经完全不需要 LLM 润色功能。只是 Typeless 有润色，LLM 又这么火，总会有朋友想试试。

---

## 五、实用技巧

### 1. 英文热词

直接英文单词专用术语，辅助正确的大小写拼写：

```text
PyTorch
TensorRT
DirectML
```

### 2. 用别名覆盖多种口音

```text
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` 等反向引用。