FunASR热词定制教程：FST算法实现精准关键词识别

【免费下载链接】FunASR A Fundamental End-to-End Speech Recognition Toolkit and Open Source SOTA Pretrained Models, Supporting Speech Recognition, Voice Activity Detection, Text Post-processing etc. 项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR

引言：语音识别中的关键词识别痛点

在语音识别（Automatic Speech Recognition, ASR）应用中，通用模型往往难以满足特定领域的关键词识别需求。例如：

• 专业术语（如"通义实验室"）被误识别为"同一实验室"
• 品牌名称（如"阿里巴巴"）被拆分为"阿里 巴巴"
• 人名/产品名识别准确率低，影响业务流程

FST（有限状态转换器）算法通过构建关键词的有向图模型，能将识别准确率提升30%以上，同时保持实时性。本教程将详解如何在FunASR中使用FST实现热词定制，解决上述痛点。

读完本文你将掌握：

• FST热词模型的工作原理与优势
• 从热词文件到FST图的完整编译流程
• 服务端配置与多场景客户端调用
• 权重调优与性能优化技巧

FST算法原理：关键词识别的数学基础

FST基本概念

FST是一种有向图结构，由状态（State）和边（Arc）组成，每条边包含：

• 输入符号（热词字符）
• 输出符号（识别结果）
• 权重（Weight，控制识别优先级）

FunASR中的FST工作流

热词定制全流程

1. 准备热词文件

创建hotwords.txt，格式为关键词 权重（权重范围1-100，建议20-50）：

阿里巴巴 30
通义实验室 40
FunASR 50
语音识别 25

权重选择指南：

• 高优先级（40-50）：核心品牌词、不可替换术语
• 中优先级（20-30）：行业术语、产品名称
• 低优先级（10-15）：常用词汇的个性化偏好

2. 编译FST热词模型

2.1 生成词典与令牌文件

cd FunASR/runtime/tools/fst
bash compile_dict_token.sh \
  --dict-src-dir ./hotword_data \
  --tmp-dir ./tmp \
  --lang-dir ./lang

关键输出文件：

• lang/tokens.txt：令牌符号表
• lang/L.fst：词典有限状态机
• lang/words.txt：词汇索引表

2.2 构建解码图

bash make_decode_graph.sh \
  --lm-dir ./lm \
  --tgt-lang ./lang

生成最终解码图lang/TLG.fst，包含：

• T.fst：令牌转换
• L.fst：词典规则
• G.fst：语言模型

3. 服务端配置与启动

3.1 基础启动命令

cd FunASR/runtime
nohup bash run_server.sh \
  --download-model-dir /workspace/models \
  --model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-onnx \
  --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
  --punc-dir damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx \
  --lm-dir ./tools/fst/lang \  # 指定FST热词模型路径
  --hotword /workspace/models/hotwords.txt \  # 热词文件
  --decoder-thread-num 8 \  # 解码线程数
  --model-thread-num 2 > log.txt 2>&1 &

3.2 关键参数调优

参数	含义	推荐值
--lm-dir	FST模型目录	编译生成的lang目录
--hotword	热词文件路径	绝对路径，确保容器内可访问
--decoder-thread-num	并发线程数	CPU核心数的1/2~2/3
--model-thread-num	单模型线程数	1-2（平衡延迟与吞吐量）

客户端调用示例

1. Python客户端

import websockets
import asyncio
import json

async def test_hotword():
    uri = "ws://127.0.0.1:10095"
    async with websockets.connect(uri) as websocket:
        # 1. 发送配置信息
        config = {
            "mode": "offline",
            "wav_name": "test_hotword",
            "wav_format": "wav",
            "is_speaking": True,
            "hotwords": '{"阿里巴巴":30,"通义实验室":40}',  # 动态热词
            "itn": True
        }
        await websocket.send(json.dumps(config))
        
        # 2. 发送音频数据
        with open("asr_example.wav", "rb") as f:
            audio_data = f.read()
            await websocket.send(audio_data)
        
        # 3. 发送结束标志
        await websocket.send(json.dumps({"is_speaking": False}))
        
        # 4. 获取结果
        result = await websocket.recv()
        print(json.loads(result)["text"])

asyncio.run(test_hotword())

2. 命令行客户端

python3 funasr_wss_client.py \
  --host "127.0.0.1" \
  --port 10095 \
  --mode offline \
  --audio_in "asr_example.wav" \
  --hotword "hotwords.txt" \
  --output_dir "./results"

3. 热词生效验证

输入音频内容：

"阿里巴巴通义实验室发布了FunASR语音识别工具包"

识别结果对比： | 配置 | 识别结果 | 关键词准确率 | |------|----------|--------------| | 无热词 | "阿里 巴巴 同一 实验室 发布了 Fun ASR 语音识别 工具包" | 2/4 (50%) | | FST热词 | "阿里巴巴 通义实验室 发布了 FunASR 语音识别 工具包" | 4/4 (100%) |

高级配置与性能优化

1. 热词冲突解决

当多个热词存在包含关系（如"阿里"和"阿里巴巴"），可通过make_decode_graph.sh的--minimal参数生成最小化FST：

bash make_decode_graph.sh --minimal true --lm-dir ./lm --tgt-lang ./lang

2. 动态热词更新

无需重启服务，通过WebSocket协议实时更新：

{
  "mode": "update_hotword",
  "hotwords": '{"新热词":35}',
  "update_type": "append"  // append/overwrite
}

3. 性能监控指标

指标	优化目标	测量方法
RTF（实时率）	<0.1	识别耗时/音频时长
内存占用	<500MB	nvidia-smi/top
关键词召回率	>95%	测试集命中率统计

常见问题与解决方案

问题	原因	解决方案
热词不生效	1. 路径错误 2. 权重设置过低	1. 检查--hotword参数路径 2. 权重提高至30+
识别延迟增加	FST图过大	1. 热词数量控制在1k以内 2. 使用--minimal编译选项
服务启动失败	TLG.fst缺失	重新执行make_decode_graph.sh

总结与展望

通过FST算法实现热词定制，FunASR能为特定领域提供高精度关键词识别能力。本文详细介绍了从热词文件准备、FST图编译、服务端配置到客户端调用的全流程，并提供了权重调优和性能优化的实用技巧。

未来展望：

• 多语言热词支持（当前v4.5版本已支持中英混合）
• 基于上下文的动态权重调整
• Web界面化热词管理工具

建议收藏本文，关注FunASR官方仓库获取最新更新。如有疑问，欢迎在GitHub Issues中提交反馈。

行动清单：

1. 克隆仓库：git clone https://gitcode.com/GitHub_Trending/fun/FunASR
2. 按照教程配置热词文件
3. 使用提供的测试脚本验证效果
4. 集成到你的ASR应用中提升关键词识别准确率

【免费下载链接】FunASR A Fundamental End-to-End Speech Recognition Toolkit and Open Source SOTA Pretrained Models, Supporting Speech Recognition, Voice Activity Detection, Text Post-processing etc. 项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR