FunASR Python SDK 实战指南基于 AutoModel 的语音识别、VAD、标点与说话人分离【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASRFunASR 是开源的语音识别工具包funasr.AutoModel是其 Python SDK 的核心统一入口一次构造即可完成模型下载、组件装配与推理调用覆盖离线识别、VAD 语音活动检测、标点恢复、句子时间戳、批量转录、热词偏置乃至说话人分离等常见语音任务。本文以仓库 examples/README.md 为主线结合 AutoModel 源码 与各示例程序从第一个转录开始逐步深入读完你将掌握 AutoModel 的完整参数语义、VAD/标点/说话人分离管线的正确用法、批量输入与热词纠正的实战细节并能独立完成训练、导出与自定义模型的注册与排查。适用范围说明本文讲解的是funasr.AutoModel工具包路径。若你只需要 Fun-ASR-Nano 的原生转录能力可参考 Transformers 5.17.0 原生集成指南它直接加载独立的-hf权重而无需 FunASR 工具包。两条路径的依赖、参数与输出契约各不相同不要混用。模型选择、语言支持、依赖与模型卡信息请以 Model Zoo 为准而不是一份通用的能力清单尚未配置本地环境的读者可先跑 Colab 快速开始。1. 环境准备与第一个转录FunASR 使用 MIT 许可但每个模型权重拥有独立的许可协议请记录完整的模型 ID 与 revision并遵守对应模型卡。仅当模型卡明确链接到 FunASR 模型许可协议 时才适用该协议。第三方集成仍属于第三方模型例如 MOSS-Transcribe-Diarize 来自 OpenMOSS并非 FunASR 训练的权重。安装 SDK 并准备好匹配的 PyTorch/torchaudio 环境后先阅读 安装与环境验证然后运行下面的 Python 代码块。首次运行需要联网以下载模型和示例 WAV并需要足够的磁盘与内存空间。以下代码基于仓库的 Paraformer 示例 改写from funasr import AutoModel audio https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav model AutoModel( modelparaformer-zh, hubms, devicecpu, ncpu4, disable_updateTrue, trust_remote_codeFalse, ) results model.generate(inputaudio) for item in results: print(item.get(key), item.get(text, )) print(Model directory:, model.model_path)要转录你自己的录音把audio替换为本地 WAV 路径即可。建议从短的单声道录音开始采样率与所选模型匹配本例为 16 kHz。文件解码依赖已安装的音频后端一个可读的 WAV 比任意媒体容器更适合作为第一步验证。若输入是 NumPy 波形数组由于没有采样率头信息必须用fssample_rate显式传入真实采样率音频加载器 正是这样使用的——不要只改波形数据的名义采样率。输入形式的底层支持从 prepare_data_iterator 的实现可以看到input参数实际支持多种形式这为后续批量处理打下了基础字符串路径本地 WAV/MP3 等http://或https://开头的 URL自动下载文件列表.scp、.txt、.json、.jsonl、.text扩展名Pythonlist/tuple批量输入或多种模态组合bytes原始音频字节经load_bytes加载原始文本供标点模型使用。另外两点值得注意disable_updateTrue只跳过 SDK 启动时的版本检查version_checker如果使用断网环境请参照离线清单预先准备完整的本地模型目录与本地输入文件。后续所有代码块在同一个 Python 会话中复用第一个块创建的AutoModel、audio和model。2. 理解参数与结果AutoModel(...)负责构造主模型与可选的管线组件model.generate(input..., **options)执行推理。底层实现可参考 AutoModel、hub 别名映射 以及所选模型的inference()实现。核心参数表参数作用域与含义model、hub模型 ID/别名或本地目录hub默认 ModelScopems可用hf使用 Hugging Face。别名可能解析到不同的 hub 仓库。device、ncpu起步阶段显式使用cpu只有在验证了 PyTorch 构建与模型支持后才选择加速器。加载器有 CPU 回退路径ncpu控制 PyTorch CPU 线程数。vad_model、punc_model、spk_model可选、独立加载的模型。通过vad_kwargs、punc_kwargs、spk_kwargs配置。并非所有 ASR 后端都自动支持它们。batch_size普通非 VAD路径下每个解码批次的输入数量后端自身的限制仍然适用。batch_size_sVAD 分段批处理的时长预算秒基于补齐后的段长计算而不是文件数量。当前 CPU VAD 路径逐段解码。batch_size_threshold_sVAD 批处理启发式使用的段时长阈值秒不是输入时长上限也不是通用的内存上限。output_dir可选的后端输出目录。返回的 Python 结果仍然可用文件与格式取决于模型。构造阶段的底层行为阅读 AutoModel.build_model 可以看到构造阶段完成的完整链路从 hub 下载模型文件 → 解析config.yaml确定模型类、tokenizer、frontend → 通过注册表实例化组件 → 从model.pt加载预训练权重。其中几个细节值得了解设备自动回退当指定的cuda/xpu/mps/npu不可用或ngpu0时会自动回退到 CPU 并把batch_size强制设为 1见 L557-L567。CPU 线程控制ncpu默认值为 4会通过torch.set_num_threads(ncpu)生效L46-L53、L569-L572。别名解析paraformer-zh等短别名在 name_maps_from_hub.py 中映射到完整模型 ID且ms与hf两个 hub 的映射可能不同。generate() 的返回结构generate()返回字典列表通常每个输入录音对应一个字典。在依赖可选字段之前先检查返回键for item in results: print(sorted(item.keys())) print(item.get(text, )) print(item.get(timestamp, []))对 Paraformer 路径而言当检查点提供timestamp时它包含字符/词/词元的[start_ms, end_ms]区间对。不要假设标点或文本归一化之后每个展示字符都对应一个区间对。其他后端可能返回不同 schema 的timestamps请遵循对应后端的指南。静音输入可能产生空文本/空时间戳而非有意义的转录。从 generate() 源码看它内部按是否配置vad_model自动路由无 VAD 时走inference()单句识别可选叠加标点模型有 VAD 时走inference_with_vad()长音频分段识别。两种路径结束后都会统一执行apply_postprocess_hotwords_to_results即第 5 节要讲的热词后处理。3. 添加 VAD、标点与句子时间戳3.1 独立使用 VADVAD 检测语音区间但不做转录。下面的独立调用使用同一段音频vad AutoModel(modelfsmn-vad, devicecpu, disable_updateTrue) vad_results vad.generate(inputaudio) for item in vad_results: print(item[key], item[value])value是相对录音起始点的[start_ms, end_ms]语音区间列表。空列表表示未检测到任何语音段。可对照 FSMN VAD 示例。fsmn-vad别名解析为iic/speech_fsmn_vad_zh-cn-16k-common-pytorch见 别名映射。3.2 VAD 标点 句子时间戳的分段识别pipeline AutoModel( modelparaformer-zh, vad_modelfsmn-vad, punc_modelct-punc, vad_kwargs{max_single_segment_time: 30000}, devicecpu, disable_updateTrue, trust_remote_codeFalse, ) segmented_results pipeline.generate( inputaudio, batch_size_s60, batch_size_threshold_s30, sentence_timestampTrue, ) for item in segmented_results: print(item.get(text, )) for sentence in item.get(sentence_info, []): print(sentence.get(start), sentence.get(end), sentence.get(text, ))单位约定要格外注意max_single_segment_time单位是毫秒而batch_size_s与batch_size_threshold_s单位是秒。分段有助于处理较长文件但并不保证无限时长或内存有界音频加载阶段和每个模型仍会消耗资源。内存紧张时改用更短的录音/分段与更小的支持批次然后重新测量。从 inference_with_vad 的实现看完整的管线分为五步见 L861-L866 的文档注释VAD把音频切成语音区间ASR按段长排序后分批识别排序是为了高效批处理时间戳合并把每段的时间戳与 VAD 偏移量叠加标点若配置punc_model对合并文本添加标点说话人分离若配置spk_model对说话人嵌入做聚类并打标签。底层细节包括batch_size_s默认 300 秒、batch_size_threshold_s默认 60 秒L899-L900当设备为 CPU 时batch_size被置 0即逐段解码L935-L936。这解释了文档中当前 CPU VAD 路径逐段解码的结论。此外当标点时间戳无法与词对齐时punc_alignment_failed句子边界会回退到 VAD 段L1218-L1222因此拿到sentence_info后应检查实际返回的数据而不是假设每个句子都精确对齐。3.3 说话人分离Diarization构造同样的管线并配置spk_modelcam若所选组件支持然后遍历每个输入的item.get(sentence_info, [])读取sentence.get(spk)。不要从外层结果列表直接读spk。聚类标签并不等同于经过核实的真实身份。参考 SenseVoice 说话人示例。从源码看说话人分离有两个模式L505-L508默认punc_segment按标点句切分与vad_segment按 VAD 段切分当缺少标点模型或时间戳不可用时会自动回退到vad_segmentL1130-L1156。说话人嵌入经过 ClusterBackend 聚类后写入sentence_info若开启return_spk_centerTrue还会额外返回每个说话人的spk_embedding_center质心L1143-L1150。cam别名解析为iic/speech_campplus_sv_zh-cn_16k-common。4. 批量处理多个录音下面的代码刻意重复同一示例音频以演示列表输入而不需要额外文件。请把列表项替换为本地 WAV 路径batch_results model.generate(input[audio, audio], batch_size1) for index, item in enumerate(batch_results): print(index, item.get(key), item.get(text, ))只有所选模型支持且内存允许时才提高batch_size。文件列表如wav.scp同样受支持每行一个utterance_id path路径相对于进程工作目录解析每个录音使用唯一 ID。如果需要模型写出的工件再设置output_dir仅接收返回的列表并不需要它。参考 数据清单示例其格式如下BAC009S0764W0121 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav asr_example_cn_en https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_cn_en.wav注意独立的文件批处理与单条话语的流式分块见第 6 节是两回事不要混淆。5. 热词Hotwords与语言边界5.1 模型级热词偏置context biasing本仓库中 ModelScope 的paraformer-zh别名解析为 SeACo Paraformer 模型见 name_maps_from_hub.py 中的speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch其实现接受单个hotword值为空格分隔的字符串biased_results model.generate(inputaudio, hotword魔搭 达摩院) print([item.get(text, ) for item in biased_results])这是模型级的语义上下文偏置semantic context biasing不是保证插入词或确定性替换。请核实解析到的模型并与无热词基线对比效果。底层实现见 SeACo 模型其文档注释明确指出它将 Paraformer 的非自回归架构与语义上下文偏置结合以提升热词识别配套示例见 contextual Paraformer 示例model AutoModel(modeliic/speech_paraformer-large-contextual_asr_nat-zh-cn-16k-common-vocab8404) res model.generate( inputhttps://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav, hotword达摩院 魔搭, )5.2 文本级热词后处理postprocess在本仓库源码中文本后处理是另一个独立的操作作用于解码后的最终文本corrected_results model.generate( inputaudio, postprocess_hotwords{科大迅飞: 科大讯飞}, return_postprocess_hotword_matchesTrue, ) for item in corrected_results: print(item.get(text, ), item.get(postprocess_hotword_matches, []))显式映射会替换匹配到的输出文本。postprocess_hotword_file还支持每行一个目标词或wrongright形式的映射。模糊匹配额外需要pypinyin与rapidfuzz纯显式映射则不需要。postprocess_hotwords.py 是这一功能的完整实现几个关键点两种桶显式映射explicit_map与模糊目标fuzzy_targets。显式替换按长度降序贪心进行模糊匹配先把文本与目标转成拼音键lazy_pinyin再用rapidfuzz.ratio打分默认阈值postprocess_hotword_threshold0.85可配置范围为[0.0, 1.0]L176-L241。文件格式支持#注释显式分隔符为、-、→L82-L103。保留时间戳替换文本时会保留原有timestamp而不是重新对齐修正后的文本L277-L279。因此在制作字幕或做对齐声明之前务必人工复核替换结果。匹配详情开启return_postprocess_hotword_matchesTrue后每个匹配项会返回original、replacement、score、start、end字段见 HotwordMatch。上述行为均有 test_postprocess_hotwords.py 测试佐证例如{科大迅飞: 科大讯飞}被视为显式映射而[科大讯飞]属于模糊目标文件解析同样支持注释与wrongright混合写法。5.3 热词与语言参数的边界hotword、hotwords、language不是可以互换的通用 SDK 选项。例如 Fun-ASR-Nano 示例 读取复数形式的hotwords和模型专属的语言提示。修改语言提示并不会把单语种检查点变成多语种模型。请使用 Model Zoo 与对应检查点的精确指南确认支持的语言、可接受的提示值、流式能力、对齐能力与依赖版本不要在模型家族之间照搬语言数量或安装锁定。6. 按具体工作流继续深入流式识别Paraformer 流式示例。每个流保持独立的cache{}最后一个分块设置is_finalTrue。对于 16 kHz 下的[0, 10, 5]块600 ms 对应9600 个采样点而不是 960分块时长并不等于端到端延迟保证。流式 VAD 可能返回[start, -1]、[-1, end]、完整区间或空区间单位均为毫秒。标点与对齐CT-Transformer 标点示例 与 时间戳预测示例。对齐需要对应的文本输入并不等同于 ASR。其他模型家族SenseVoice、Fun-ASR-Nano 与 第三方 OpenMOSS 集成。更多条目可通过 Model Zoo 发现。CLI 与服务化CLI 参考、运行时总览 与 Docker 部署。注意 Python 选项并不代表服务端请求 schema 与之完全相同。7. 模型训练、导出与自定义模型注册7.1 训练与测试使用 Paraformer 训练配方、finetune.sh 与 训练数据示例。启动前务必检查数据集路径、标签对齐、模型许可、GPU 分配与输出目录。训练不是安装冒烟测试。对于训练好的权重检查 infer_from_local.sh配置、tokenizer/frontend 资产与检查点路径必须一致。同时保持验证数据与训练数据分离。7.2 模型导出与测试遵循模型的 Paraformer 导出示例 与 ONNX Runtime 指南。导出支持与额外依赖是模型/后端相关的。从源码看AutoModel.export 会对模型与配置做深拷贝隔离 ONNX 算子 monkey-patching 与deep_update/del的引用污染原模型在导出后仍可使用。但导出成功并不等于输出等价部署前务必用有代表性的输入测试导出产物并与原模型对比。7.3 注册自定义模型使用模型注册教程与一个真实实现例如 SenseVoice 模型。仅完成注册并不保证generate()契约可用模型的推理结果必须与其将使用的下游组件匹配。7.4 故障排查失败时回到 troubleshooting并附带解释器/包版本、解析后的模型 ID/revision、输入格式与最小可复现样例。不要包含私有音频或凭据。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FunASR Python SDK 实战指南：基于 AutoModel 的语音识别、VAD、标点与说话人分离
FunASR Python SDK 实战指南基于 AutoModel 的语音识别、VAD、标点与说话人分离【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASRFunASR 是开源的语音识别工具包funasr.AutoModel是其 Python SDK 的核心统一入口一次构造即可完成模型下载、组件装配与推理调用覆盖离线识别、VAD 语音活动检测、标点恢复、句子时间戳、批量转录、热词偏置乃至说话人分离等常见语音任务。本文以仓库 examples/README.md 为主线结合 AutoModel 源码 与各示例程序从第一个转录开始逐步深入读完你将掌握 AutoModel 的完整参数语义、VAD/标点/说话人分离管线的正确用法、批量输入与热词纠正的实战细节并能独立完成训练、导出与自定义模型的注册与排查。适用范围说明本文讲解的是funasr.AutoModel工具包路径。若你只需要 Fun-ASR-Nano 的原生转录能力可参考 Transformers 5.17.0 原生集成指南它直接加载独立的-hf权重而无需 FunASR 工具包。两条路径的依赖、参数与输出契约各不相同不要混用。模型选择、语言支持、依赖与模型卡信息请以 Model Zoo 为准而不是一份通用的能力清单尚未配置本地环境的读者可先跑 Colab 快速开始。1. 环境准备与第一个转录FunASR 使用 MIT 许可但每个模型权重拥有独立的许可协议请记录完整的模型 ID 与 revision并遵守对应模型卡。仅当模型卡明确链接到 FunASR 模型许可协议 时才适用该协议。第三方集成仍属于第三方模型例如 MOSS-Transcribe-Diarize 来自 OpenMOSS并非 FunASR 训练的权重。安装 SDK 并准备好匹配的 PyTorch/torchaudio 环境后先阅读 安装与环境验证然后运行下面的 Python 代码块。首次运行需要联网以下载模型和示例 WAV并需要足够的磁盘与内存空间。以下代码基于仓库的 Paraformer 示例 改写from funasr import AutoModel audio https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav model AutoModel( modelparaformer-zh, hubms, devicecpu, ncpu4, disable_updateTrue, trust_remote_codeFalse, ) results model.generate(inputaudio) for item in results: print(item.get(key), item.get(text, )) print(Model directory:, model.model_path)要转录你自己的录音把audio替换为本地 WAV 路径即可。建议从短的单声道录音开始采样率与所选模型匹配本例为 16 kHz。文件解码依赖已安装的音频后端一个可读的 WAV 比任意媒体容器更适合作为第一步验证。若输入是 NumPy 波形数组由于没有采样率头信息必须用fssample_rate显式传入真实采样率音频加载器 正是这样使用的——不要只改波形数据的名义采样率。输入形式的底层支持从 prepare_data_iterator 的实现可以看到input参数实际支持多种形式这为后续批量处理打下了基础字符串路径本地 WAV/MP3 等http://或https://开头的 URL自动下载文件列表.scp、.txt、.json、.jsonl、.text扩展名Pythonlist/tuple批量输入或多种模态组合bytes原始音频字节经load_bytes加载原始文本供标点模型使用。另外两点值得注意disable_updateTrue只跳过 SDK 启动时的版本检查version_checker如果使用断网环境请参照离线清单预先准备完整的本地模型目录与本地输入文件。后续所有代码块在同一个 Python 会话中复用第一个块创建的AutoModel、audio和model。2. 理解参数与结果AutoModel(...)负责构造主模型与可选的管线组件model.generate(input..., **options)执行推理。底层实现可参考 AutoModel、hub 别名映射 以及所选模型的inference()实现。核心参数表参数作用域与含义model、hub模型 ID/别名或本地目录hub默认 ModelScopems可用hf使用 Hugging Face。别名可能解析到不同的 hub 仓库。device、ncpu起步阶段显式使用cpu只有在验证了 PyTorch 构建与模型支持后才选择加速器。加载器有 CPU 回退路径ncpu控制 PyTorch CPU 线程数。vad_model、punc_model、spk_model可选、独立加载的模型。通过vad_kwargs、punc_kwargs、spk_kwargs配置。并非所有 ASR 后端都自动支持它们。batch_size普通非 VAD路径下每个解码批次的输入数量后端自身的限制仍然适用。batch_size_sVAD 分段批处理的时长预算秒基于补齐后的段长计算而不是文件数量。当前 CPU VAD 路径逐段解码。batch_size_threshold_sVAD 批处理启发式使用的段时长阈值秒不是输入时长上限也不是通用的内存上限。output_dir可选的后端输出目录。返回的 Python 结果仍然可用文件与格式取决于模型。构造阶段的底层行为阅读 AutoModel.build_model 可以看到构造阶段完成的完整链路从 hub 下载模型文件 → 解析config.yaml确定模型类、tokenizer、frontend → 通过注册表实例化组件 → 从model.pt加载预训练权重。其中几个细节值得了解设备自动回退当指定的cuda/xpu/mps/npu不可用或ngpu0时会自动回退到 CPU 并把batch_size强制设为 1见 L557-L567。CPU 线程控制ncpu默认值为 4会通过torch.set_num_threads(ncpu)生效L46-L53、L569-L572。别名解析paraformer-zh等短别名在 name_maps_from_hub.py 中映射到完整模型 ID且ms与hf两个 hub 的映射可能不同。generate() 的返回结构generate()返回字典列表通常每个输入录音对应一个字典。在依赖可选字段之前先检查返回键for item in results: print(sorted(item.keys())) print(item.get(text, )) print(item.get(timestamp, []))对 Paraformer 路径而言当检查点提供timestamp时它包含字符/词/词元的[start_ms, end_ms]区间对。不要假设标点或文本归一化之后每个展示字符都对应一个区间对。其他后端可能返回不同 schema 的timestamps请遵循对应后端的指南。静音输入可能产生空文本/空时间戳而非有意义的转录。从 generate() 源码看它内部按是否配置vad_model自动路由无 VAD 时走inference()单句识别可选叠加标点模型有 VAD 时走inference_with_vad()长音频分段识别。两种路径结束后都会统一执行apply_postprocess_hotwords_to_results即第 5 节要讲的热词后处理。3. 添加 VAD、标点与句子时间戳3.1 独立使用 VADVAD 检测语音区间但不做转录。下面的独立调用使用同一段音频vad AutoModel(modelfsmn-vad, devicecpu, disable_updateTrue) vad_results vad.generate(inputaudio) for item in vad_results: print(item[key], item[value])value是相对录音起始点的[start_ms, end_ms]语音区间列表。空列表表示未检测到任何语音段。可对照 FSMN VAD 示例。fsmn-vad别名解析为iic/speech_fsmn_vad_zh-cn-16k-common-pytorch见 别名映射。3.2 VAD 标点 句子时间戳的分段识别pipeline AutoModel( modelparaformer-zh, vad_modelfsmn-vad, punc_modelct-punc, vad_kwargs{max_single_segment_time: 30000}, devicecpu, disable_updateTrue, trust_remote_codeFalse, ) segmented_results pipeline.generate( inputaudio, batch_size_s60, batch_size_threshold_s30, sentence_timestampTrue, ) for item in segmented_results: print(item.get(text, )) for sentence in item.get(sentence_info, []): print(sentence.get(start), sentence.get(end), sentence.get(text, ))单位约定要格外注意max_single_segment_time单位是毫秒而batch_size_s与batch_size_threshold_s单位是秒。分段有助于处理较长文件但并不保证无限时长或内存有界音频加载阶段和每个模型仍会消耗资源。内存紧张时改用更短的录音/分段与更小的支持批次然后重新测量。从 inference_with_vad 的实现看完整的管线分为五步见 L861-L866 的文档注释VAD把音频切成语音区间ASR按段长排序后分批识别排序是为了高效批处理时间戳合并把每段的时间戳与 VAD 偏移量叠加标点若配置punc_model对合并文本添加标点说话人分离若配置spk_model对说话人嵌入做聚类并打标签。底层细节包括batch_size_s默认 300 秒、batch_size_threshold_s默认 60 秒L899-L900当设备为 CPU 时batch_size被置 0即逐段解码L935-L936。这解释了文档中当前 CPU VAD 路径逐段解码的结论。此外当标点时间戳无法与词对齐时punc_alignment_failed句子边界会回退到 VAD 段L1218-L1222因此拿到sentence_info后应检查实际返回的数据而不是假设每个句子都精确对齐。3.3 说话人分离Diarization构造同样的管线并配置spk_modelcam若所选组件支持然后遍历每个输入的item.get(sentence_info, [])读取sentence.get(spk)。不要从外层结果列表直接读spk。聚类标签并不等同于经过核实的真实身份。参考 SenseVoice 说话人示例。从源码看说话人分离有两个模式L505-L508默认punc_segment按标点句切分与vad_segment按 VAD 段切分当缺少标点模型或时间戳不可用时会自动回退到vad_segmentL1130-L1156。说话人嵌入经过 ClusterBackend 聚类后写入sentence_info若开启return_spk_centerTrue还会额外返回每个说话人的spk_embedding_center质心L1143-L1150。cam别名解析为iic/speech_campplus_sv_zh-cn_16k-common。4. 批量处理多个录音下面的代码刻意重复同一示例音频以演示列表输入而不需要额外文件。请把列表项替换为本地 WAV 路径batch_results model.generate(input[audio, audio], batch_size1) for index, item in enumerate(batch_results): print(index, item.get(key), item.get(text, ))只有所选模型支持且内存允许时才提高batch_size。文件列表如wav.scp同样受支持每行一个utterance_id path路径相对于进程工作目录解析每个录音使用唯一 ID。如果需要模型写出的工件再设置output_dir仅接收返回的列表并不需要它。参考 数据清单示例其格式如下BAC009S0764W0121 https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav asr_example_cn_en https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_cn_en.wav注意独立的文件批处理与单条话语的流式分块见第 6 节是两回事不要混淆。5. 热词Hotwords与语言边界5.1 模型级热词偏置context biasing本仓库中 ModelScope 的paraformer-zh别名解析为 SeACo Paraformer 模型见 name_maps_from_hub.py 中的speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch其实现接受单个hotword值为空格分隔的字符串biased_results model.generate(inputaudio, hotword魔搭 达摩院) print([item.get(text, ) for item in biased_results])这是模型级的语义上下文偏置semantic context biasing不是保证插入词或确定性替换。请核实解析到的模型并与无热词基线对比效果。底层实现见 SeACo 模型其文档注释明确指出它将 Paraformer 的非自回归架构与语义上下文偏置结合以提升热词识别配套示例见 contextual Paraformer 示例model AutoModel(modeliic/speech_paraformer-large-contextual_asr_nat-zh-cn-16k-common-vocab8404) res model.generate( inputhttps://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav, hotword达摩院 魔搭, )5.2 文本级热词后处理postprocess在本仓库源码中文本后处理是另一个独立的操作作用于解码后的最终文本corrected_results model.generate( inputaudio, postprocess_hotwords{科大迅飞: 科大讯飞}, return_postprocess_hotword_matchesTrue, ) for item in corrected_results: print(item.get(text, ), item.get(postprocess_hotword_matches, []))显式映射会替换匹配到的输出文本。postprocess_hotword_file还支持每行一个目标词或wrongright形式的映射。模糊匹配额外需要pypinyin与rapidfuzz纯显式映射则不需要。postprocess_hotwords.py 是这一功能的完整实现几个关键点两种桶显式映射explicit_map与模糊目标fuzzy_targets。显式替换按长度降序贪心进行模糊匹配先把文本与目标转成拼音键lazy_pinyin再用rapidfuzz.ratio打分默认阈值postprocess_hotword_threshold0.85可配置范围为[0.0, 1.0]L176-L241。文件格式支持#注释显式分隔符为、-、→L82-L103。保留时间戳替换文本时会保留原有timestamp而不是重新对齐修正后的文本L277-L279。因此在制作字幕或做对齐声明之前务必人工复核替换结果。匹配详情开启return_postprocess_hotword_matchesTrue后每个匹配项会返回original、replacement、score、start、end字段见 HotwordMatch。上述行为均有 test_postprocess_hotwords.py 测试佐证例如{科大迅飞: 科大讯飞}被视为显式映射而[科大讯飞]属于模糊目标文件解析同样支持注释与wrongright混合写法。5.3 热词与语言参数的边界hotword、hotwords、language不是可以互换的通用 SDK 选项。例如 Fun-ASR-Nano 示例 读取复数形式的hotwords和模型专属的语言提示。修改语言提示并不会把单语种检查点变成多语种模型。请使用 Model Zoo 与对应检查点的精确指南确认支持的语言、可接受的提示值、流式能力、对齐能力与依赖版本不要在模型家族之间照搬语言数量或安装锁定。6. 按具体工作流继续深入流式识别Paraformer 流式示例。每个流保持独立的cache{}最后一个分块设置is_finalTrue。对于 16 kHz 下的[0, 10, 5]块600 ms 对应9600 个采样点而不是 960分块时长并不等于端到端延迟保证。流式 VAD 可能返回[start, -1]、[-1, end]、完整区间或空区间单位均为毫秒。标点与对齐CT-Transformer 标点示例 与 时间戳预测示例。对齐需要对应的文本输入并不等同于 ASR。其他模型家族SenseVoice、Fun-ASR-Nano 与 第三方 OpenMOSS 集成。更多条目可通过 Model Zoo 发现。CLI 与服务化CLI 参考、运行时总览 与 Docker 部署。注意 Python 选项并不代表服务端请求 schema 与之完全相同。7. 模型训练、导出与自定义模型注册7.1 训练与测试使用 Paraformer 训练配方、finetune.sh 与 训练数据示例。启动前务必检查数据集路径、标签对齐、模型许可、GPU 分配与输出目录。训练不是安装冒烟测试。对于训练好的权重检查 infer_from_local.sh配置、tokenizer/frontend 资产与检查点路径必须一致。同时保持验证数据与训练数据分离。7.2 模型导出与测试遵循模型的 Paraformer 导出示例 与 ONNX Runtime 指南。导出支持与额外依赖是模型/后端相关的。从源码看AutoModel.export 会对模型与配置做深拷贝隔离 ONNX 算子 monkey-patching 与deep_update/del的引用污染原模型在导出后仍可使用。但导出成功并不等于输出等价部署前务必用有代表性的输入测试导出产物并与原模型对比。7.3 注册自定义模型使用模型注册教程与一个真实实现例如 SenseVoice 模型。仅完成注册并不保证generate()契约可用模型的推理结果必须与其将使用的下游组件匹配。7.4 故障排查失败时回到 troubleshooting并附带解释器/包版本、解析后的模型 ID/revision、输入格式与最小可复现样例。不要包含私有音频或凭据。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考