FunASR Python SDK 实战指南从首次转写到 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/FunASR本文以 FunASR 仓库 examples/README_zh.md 为骨架结合 funasr/auto/auto_model.py、funasr/download/name_maps_from_hub.py、funasr/utils/postprocess_hotwords.py 等源码级证据系统讲解funasr.AutoModel的统一推理入口如何完成第一次语音转写、理解参数与返回结构、叠加 VAD/标点/说话人分离、批处理多条录音、使用热词偏置与文本后处理并顺带给出训练、导出与自定义模型注册的入口。读完本文你将能独立完成一条从一段录音到带标点、分句时间戳、甚至说话人标签的转写结果的完整 SDK 推理链路。本文面向只需 Fun-ASR-Nano 原生推理的场景另有捷径使用 Transformers 5.17.0 快速开始它加载独立的-hf权重不要求 FunASR 工具库而本页全部内容都围绕funasr.AutoModel工具库路径展开两者的依赖、参数与输出契约不可混用。0. 前置准备安装、环境验证与许可边界动手之前请先完成安装与环境验证。尚未配置本地环境时可先通过 Colab 快速体验 在云端跑通示例再回到本地环境。需要特别厘清的三点事实软件与权重是两套许可FunASR 软件本体采用 MIT 许可每个模型权重各有独立许可使用时应记录完整模型 ID 与 revision并以对应模型卡为准。只有模型卡明确链接 FunASR 模型许可协议 时该协议才适用于该权重。第三方集成仍属第三方模型例如 MOSS-Transcribe-Diarize 来自 OpenMOSS不是 FunASR 训练的权重其许可与能力边界需按第三方来源确认。模型能力不存在通用清单模型选择、语言支持、依赖版本和模型卡信息请查阅模型仓库不要把某个示例的能力当成所有模型的共性。1. 完成第一次转写安装 SDK 及匹配的 PyTorch / torchaudio 环境后运行下面的 Python 代码即可完成首次转写。首次执行需要联网下载模型权重与公开示例 WAV并预留足够的磁盘与内存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)该示例基于仓库中的 Paraformer 示例后者展示了带 VAD 与标点组件的完整用法是理解本文后续组件组合的最佳起点。几个实战要点识别自己的录音把audio替换为存在的本地 WAV 路径即可。建议先使用与模型采样率匹配的短单声道录音——本示例模型为 16 kHz。音频解码能力取决于后端文件解码依赖已安装的音频后端先检查可读 WAV比直接尝试任意媒体容器更简单。NumPy 波形没有采样率文件头如果直接输入numpy波形必须通过fssample_rate传入真实采样率参见音频加载器。注意仅修改采样率标签而不重采样是错误做法。断网使用需先按离线检查清单准备完整的本地模型目录和本地输入文件disable_updateTrue只是跳过 SDK 启动时的版本检查与离线无关。后续所有 Python 代码块默认在同一会话中复用本节的AutoModel、audio与model三个对象。2. 理解参数和结果generate() 的路由与返回契约AutoModel(...)负责构建模型与可选流水线组件model.generate(input..., **options)执行推理。源码入口有三处主控逻辑在 AutoModel模型 ID 别名解析在 hub 别名映射具体解码行为由所选模型的inference()实现。从源码看generate()是一个自动路由方法在 auto_model.py#L695-L754 中当未配置vad_model时走inference()单条语音直解配置了vad_model时走inference_with_vad()长音频分段解码无论哪条路径最终结果都会统一经过apply_postprocess_hotwords_to_results()做热词文本后处理详见第 5 节。2.1 核心参数速查表参数作用范围与含义model、hub模型 ID/别名或本地目录hub默认为 ModelScopems传hf选择 Hugging Face。同一别名在不同 hub 下可能解析到不同仓库务必以实际下载到的模型为准。device、ncpu入门阶段显式使用cpu在验证 PyTorch 构建与模型支持后再选择 GPU 等加速器。加载器存在 CPU 回退路径ncpu控制 PyTorch CPU 线程数源码中_resolve_ncpu会兜底为不小于 1 的正整数。vad_model、punc_model、spk_model独立加载的可选组件模型通过vad_kwargs、punc_kwargs、spk_kwargs传入各自专属配置。并非所有 ASR 后端都自动支持这些组合。batch_size普通非 VAD 路径下每个解码 batch 的输入数量仍受后端支持限制。batch_size_sVAD 分段组 batch 的秒数预算按填充后的片段长度计算不是文件个数当前 CPU VAD 路径是逐段解码的。batch_size_threshold_sVAD 组 batch 启发式使用的片段时长阈值不是输入时长限制也不是通用内存上限。output_dir可选的后端输出目录即使设置也会返回 Python 结果具体写出的文件与格式取决于模型。2.2 返回结构先查键名再取值generate()返回字典列表通常每条输入录音对应一个结果。可选字段是否出现取决于模型与推理选项因此使用前先检查实际键名for item in results: print(sorted(item.keys())) print(item.get(text, )) print(item.get(timestamp, []))几点判断准则Paraformer 路径当权重提供时间戳时timestamp为字/词元/词级的[start_ms, end_ms]区间。标点恢复或文本规范化之后不要假定每个可见字符都对应一组区间。其他后端可能返回不同结构的timestamps需按对应模型指南解析。无语音片段可能返回空文本或空时间戳这不能当作有效转写。从源码实现看标点与时间戳的对齐是一套精细的表面文本映射逻辑auto_model.py中的_get_punc_tokens把标点模型的预测数组映射回文本 token_surface_token_spans逐个 token 在原始文本中定位精确跨度_punc_symbol把标点 ID 转成。、等符号对 ASCII token 自动转成半角, . ? ,。这正是标点插入不改变 ASR 表面文本的底层保证也是sentence_info句级边界能精确对齐到原文的原因。3. 添加 VAD、标点与句级时间戳3.1 独立 VAD只检测语音区间不做转写VAD 检测语音区间本身并不转写。下面独立检测同一音频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 示例其离线输出即为[[beg1, end1], [beg2, end2], ..., [begN, endN]]单位毫秒格式。3.2 组合流水线分段 ASR 标点 句级时间戳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 时长参数单位为秒。关于分段与资源的几个事实分段有助于处理较长文件但不保证任意时长或固定内存占用——音频加载阶段和各模型仍会消耗资源。内存不足时应缩短录音/片段、或减小模型支持的 batch然后重新测量而不是盲目调大 batch 参数。句子边界依赖可用的时间戳与标点对齐可能回退到 VAD 片段所以务必检查返回的真实sentence_info数据。源码侧_vad_segment_sentences与_timestamp_sentences_from_surface就是这两条路径的具体实现auto_model.py前者在无可用时间戳时直接用 VAD 区间兜底作为句子起止。3.3 说话人分离Diarization需要说话人分割时在所选组件支持的前提下为相同流水线追加spk_modelcam取值位置遍历每条输入的item.get(sentence_info, [])后再读取sentence.get(spk)不要从外层结果列表直接读spk。语义边界聚类标签如 spk 0/1/2不等于已验证的真实身份。完整示例见说话人组合示例。4. 处理多条录音列表输入与 wav.scpgenerate()天然支持列表输入。下面故意重复同一示例以演示列表语法不依赖额外文件实际使用时替换为本地 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。源码中inference()按batch_size切片调用model.inference(**batch, **kwargs)auto_model.py#L808-L826batch 收益与后端实现强相关。wav.scp 文件列表也是合法输入每行使用utterance_id path格式路径相对于进程工作目录解析每条录音使用唯一 ID。可参考数据列表示例。从prepare_data_iterator的源码auto_model.py#L347可以看到输入为字符串时会自动识别.scp/.txt/.json/.jsonl/.text列表文件并兼容http(s)://URL 的自动下载。需要模型写出文件时设置output_dir仅接收返回列表则不强制该参数。概念区分独立文件的批处理 ≠ 同一句话的流式分块见第 6 节。5. 热词与语言边界5.1 模型级热词偏置hotwordSeACo Paraformer在本工作区中ModelScope 的paraformer-zh别名解析到SeACo Paraformer模型——这一点可以直接在 hub 别名映射 中确认paraformer-zh: iic/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])这是模型级上下文偏置SeACoParaformer通过hotword_output_layer等语义偏置模块影响解码参见 SeACo 实现它不保证一定插入指定词也不是确定性文本替换。正确做法是先确认实际解析出的模型再与不加热词的基线结果对比。配套示例见上下文 Paraformer 示例。5.2 文本级后处理postprocess_hotwords与模型热词完全不同的机制本源码工作区的文本后处理是另一种操作作用于解码之后的最终文本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支持每行一个目标词或错误词目标词也兼容-、→映射行#开头为注释。模糊匹配仅输入目标词无显式映射时走模糊匹配默认阈值postprocess_hotword_threshold0.85且额外需要pypinyin与rapidfuzz两个包显式映射不需要。模糊匹配先把目标词转成拼音键lazy_pinyin再按长度分桶做模糊打分。时间戳不重对齐后处理保留原有时间戳不会重新对齐修改后的文本。因此在生成字幕或宣称对齐准确之前务必人工审查替换结果——这也是源码模块 docstring 明确声明的设计意图。5.3 hotword / hotwords / language不是可互换的通用 SDK 选项这是本节最重要的告诫hotwordSeACo Paraformer 语义偏置、hotwords复数如 Fun-ASR-Nano 读取的模型专属提示与language语言提示不是可互换的通用选项各自绑定到具体模型族的实现。修改语言提示不能把单语言权重变成多语言权重。语言支持、提示取值、流式能力、对齐方式和依赖版本都应按模型仓库及精确模型指南确认不要跨模型家族照搬语言数量或安装版本。6. 进入具体工作流流式识别Paraformer 流式示例。每个音频流维护独立的cache{}最后一块设置is_finalTrue。注意采样点换算16 kHz 下chunk_size[0, 10, 5]的 600 ms 对应9600 个采样点chunk_stride chunk_size[1] * 960见示例源码不是 960分块时长不代表端到端延时。流式 VAD 可能返回[start, -1]、[-1, end]、完整区间或空区间单位均为毫秒。标点与对齐标点示例与时间戳预测示例。注意对齐需要对应的文本输入不等同于语音识别。其他模型系列SenseVoice、Fun-ASR-Nano、第三方 OpenMOSS 集成。更多入口统一在模型仓库查找。命令行与服务CLI 参考、运行时概览和 Docker。重要提醒Python 参数不代表服务请求具有相同结构服务化场景请按对应协议文档构造请求。训练与验证入口训练不是安装冒烟测试。请使用 Paraformer 配方、finetune.sh 和训练数据示例。启动前必须检查数据集路径与标签对齐模型许可GPU 分配输出目录。测试训练后权重时先检查 infer_from_local.sh确保配置、分词器/前端资源和 checkpoint 路径三者一致。验证数据应与训练数据严格分开避免数据泄漏导致的虚高指标。导出与运行时验证按模型的 Paraformer 导出示例 和 ONNX Runtime 指南 操作。两点事实必须牢记导出支持与额外依赖由具体模型/后端决定不存在统一导出保证导出成功 ≠ 结果等价部署前应使用有代表性的输入测试导出制品并与原模型逐条比较输出。注册自定义模型参见注册表教程和真实的 SenseVoice 实现。需要强调的是完成注册不代表generate()契约已经满足——模型的推理结果必须与计划使用的下游组件VAD、标点、说话人分离等匹配注册只是第一步。故障排查建议遇到问题时带上以下信息回到常见问题解释器/依赖版本实际解析到的模型 ID/revision而非简写别名输入格式最小可复现脚本。不要在反馈中附带私密音频或凭据。小结本文覆盖了funasr.AutoModel从首次转写到组件化流水线的完整路径。核心心法可以概括为三条① 以模型仓库为准确认每个模型的真实能力与参数契约② 用generate()的自动路由无 VAD 直解、有 VAD 分段理解长音频处理与批处理的行为差异③ 分清模型级热词hotword语义偏置与文本级后处理postprocess_hotwords显式/模糊替换两套完全不同的机制。沿着本文的源码线索深入 auto_model.py 与 postprocess_hotwords.py你将能举一反三地理解其他模型的推理实现。【免费下载链接】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），仅供参考