分词词典加载失败?先检查空行与重复键
准备好自己的词典,程序却在模型推理前就报错?先别调整模型参数。对使用 CharTokenizer 分词词典的流程,一行空白、重复键或文件开头的隐藏字符,就足以让加载或映射结果偏离预期。把文件结构检查从识别任务中拆出来,问题更容易复现,也不必先启动 GPU。
例如,hello h e l l o 表示键 hello 对应后面的分词单元。若文件后面再出现 hello hh,当前加载实现会由后一条覆盖前一条;只有一个 hello 而没有后续单元,则得到空映射。这些情况与“识别器是否认识 hello”不是同一个问题。
本文针对 FunASR 的 CharTokenizer 及其 seg_dict/seg_dict_file 路径,不是所有模型通用的词表或热词接口。检查器只读取本地 UTF-8 文本,使用 Python 标准库,不导入 FunASR、不加载权重、不联网、不改文件。示例数据是人工构造的文本,不构成语音准确率、训练效果或生产服务验收。
1. 先确认文件确实是这类词典
在固定提交的 CharTokenizer 实现中,加载函数按空白拆分每行:第一项是键,其余项连接成映射。制表符和多个空格可以作为分隔符。这里没有注释语法:以 # 开头的非空行仍会被当成词典条目。
分词路径会将待匹配词转为小写,但加载函数不会自动把词典键转为小写。因此,大写键值得核对。不要直接批量转换整个文件:输出单元还需要与目标模型的 token 表一致,盲目改写可能制造另一种错配。本文示例也不是可以直接替换任意模型词典的推荐词表。
2. 用只读检查器定位可疑行
把下面示例作为独立的 inspect_dictionary.py 运行,传入有权检查的词典文件。报告保留 1 起始行号;它记录空白行、无映射的键、重复键、键中的 BOM 字符及含大写字符的键。UTF-8 解码失败会直接报错,不用替换字符掩盖损坏。
import json
import sys
def inspect_seg_dict(path):
report = {
"entries": 0,
"blank_lines": [],
"empty_values": [],
"duplicate_keys": [],
"bom_lines": [],
"uppercase_keys": [],
}
seen = {}
with open(path, "r", encoding="utf-8") as source:
for number, line in enumerate(source, 1):
fields = line.strip().split()
if not fields:
report["blank_lines"].append(number)
continue
key = fields[0]
if len(fields) == 1:
report["empty_values"].append(number)
if "\ufeff" in key:
report["bom_lines"].append(number)
if key != key.lower():
report["uppercase_keys"].append(number)
if key in seen:
report["duplicate_keys"].append({
"key": key,
"previous_line": seen[key],
"line": number,
})
seen[key] = number
report["entries"] = len(seen)
return report
if __name__ == "__main__":
print(json.dumps(inspect_seg_dict(sys.argv[1]),
ensure_ascii=False, indent=2))
python inspect_dictionary.py /path/to/seg_dict.txt
entries 是按原始键计算的唯一条目数,不是模型词表大小。previous_line 指最近一次同键出现的行号:三次重复会分别报告第二次和第三次覆盖。空文件返回 0 条;“没有发现可疑行”不代表词典可用。检查器不会验证输出单元是否在模型词表中,也不会模拟完整的未知词回退。
3. 按问题类型处理,而不是直接重写
- 空白行:先确认安装代码是否包含对应修复;需要兼容旧环境时,人工审阅后在另一份文件中去除意外空行,保留原文件和差异。
- 重复键或空映射:核对词典来源和生成流程,明确哪条才是期望映射。不要让“最后一条生效”悄悄替代业务规则。
- BOM 或编码错误:确认文件编码和导出工具,在保留原件的前提下做明确的编码转换;不要用忽略解码错误的方式继续加载。
- 大写键:结合实际输入和模型 token 表检查大小写策略。结构检查不能确认输出单元的语义正确。
4. 主线修复与安装版本要分开核对
#3905 的词典空行修复集成保留了原作者 #3903 的实现与测试,并把回归测试接入现有 CI。修复对空白拆分结果先做检查,再取首项,避免空行造成索引错误。相关 CPU 回归、原生 CUDA CTC 输入链路和两套 NumPy CI 已按实际测试范围验收;这不是预训练 ASR 准确率评测。
截至 2026-11-15 本次维护验收,修复已在 main,已验收的根包仍是 FunASR 1.4.26,不能宣称旧 wheel 已包含这项新修复。本文检查器不依赖该修复。升级前应核对目标发行说明、实际安装版本和最小复现,避免仅凭“仓库已合并”判断本机行为。
随文测试实际执行中英文源码页和构建页中的代码,覆盖空白与 CRLF、制表符、中文键、重复覆盖、空映射、BOM、大写键、空文件、非法 UTF-8、普通 # 条目和命令行入口,并确认输入文件字节不变。它不是对任意恶意或超大文件的安全审计。
词典结构通过后,再在隔离环境验证 token 映射及有权使用的真实样本。报告问题时提供脱敏的最小词典、版本和错误栈;词典可能包含内部实体或术语,不要直接公开完整文件。
若你要调整的是识别请求里的热词,而非分词映射,请继续阅读热词传递链路与安装包边界。