FunASR Python SDK 实战：AutoModel 构建、推理、VAD 流水线与流式 Cache 生命周期全解析

FunASR Python SDK 实战：AutoModel 构建、推理、VAD 流水线与流式 Cache 生命周期全解析

【免费下载链接】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 开源语音识别工具包（当前仓库）的funasr.AutoModel为绝对主线，系统讲解进程内模型构建与推理的完整契约：构建参数与单次推理参数的语义边界、本地文件批处理、VAD+标点+说话人流水线、模型特有的语言/热词/时间戳控制、流式 Cache 生命周期，以及版本复现与离线使用的注意事项。读完本文，你将能独立基于AutoModel编写可复用的推理脚本，并准确判断哪些能力属于 SDK、哪些属于服务端，避免把两者混用。

from funasr import AutoModel在当前 Python 进程内直接运行模型：它不是 HTTP 客户端，也不实现完整的 OpenAI API。本文描述的是当前代码版本（以仓库内 auto_model.py 等源码为准）的实现，不代表所有历史 FunASR 版本或上游 checkpoint 的行为。若你只需要 Fun-ASR-Nano 的原生推理，可改用 Transformers 5.17.0 快速开始，它加载独立的-hf权重、不依赖 FunASR 工具库；本页的依赖、参数与输出契约与其不可混用。

模型构建与推理调用：两个阶段，两套参数

构建阶段与推理阶段的分工

AutoModel(**kwargs)负责：解析模型配置 → 通过注册表（register.py）查找已注册的实现 → 加载权重 → 按需构建 VAD、标点、说话人三个子模型。而model.generate(input, input_len=None, progress_callback=None, **cfg)只负责用已经加载好的组件执行推理。

因此有一条重要边界：在generate()中传入新的model、vad_model或device，不是重新构建或迁移流水线的受支持方式——需要另建一个实例。包装层接收**kwargs，但并不存在覆盖所有模型的统一参数校验：参数能传进去，不等于所选模型会使用它；同时，模型仓库中的config.yaml配置可能覆盖下表中的代码回退默认值。建议结合以下源码阅读本节：AutoModel 源码、注册表、模型下载与解析、别名映射。

构建参数一览

源码佐证：AutoModel.__init__中会显式拒绝vda_model拼写错误（TypeError），并在构建 VAD/标点/说话人子模型时，把顶层device、ncpu（默认 4）、hub继承进子字典，同时用顶层的xxx_model_revision（默认"master"）覆盖子字典中的model_revision（auto_model.py）。设备回退逻辑位于build_model：当cuda/xpu/mps/npu后端不可用或ngpu==0时强制回退 CPU 并设置batch_size=1，随后_resolve_ncpu保证线程数为不小于 1 的整数并通过torch.set_num_threads生效（auto_model.py）。build_model还完成了从 hub 下载/解析配置、构建 tokenizer 与 frontend、通过tables.model_classes查表实例化模型、加载init_param、按fp16/bf16切换精度并model.eval()的完整链路（auto_model.py）。

单次推理参数一览

源码佐证：generate()入口会先调用_reset_runtime_configs()恢复构建时保存的基线配置，再根据是否配置vad_model分别路由到inference()（单条直接推理）或inference_with_vad()（长音频分段流水线），最后统一经过apply_postprocess_hotwords_to_results做文本级热词后处理（auto_model.py）。_reset_runtime_configs通过_base_kwargs_map快照把每个*_kwargs字典恢复为构建时的深拷贝（auto_model.py）。

务必记住两条使用纪律：

1. generate()在合并本次选项前会恢复构建时保存的配置。每次调用都应明确传入本次需要的语言、批处理、热词等选项，不要依赖上一次调用遗留的值。配置重置不代表线程安全，也不重置每个模型属性——例如说话人模式回退会修改self.spk_mode。除非自行验证过并发行为，否则应串行访问共享实例。
2. 在inference_with_vad中，配置了spk_model且本次调用未显式给出时间戳开关时，包装层会自动打开output_timestamp与return_time_stamps（auto_model.py），因为说话人聚类依赖时间戳。

本地文件与批处理：从单条到清单

先按安装指南 安装 SDK。下面三个示例都是带命令行参数的独立脚本，需要提前准备完整本地模型快照和真实音频；仓库测试仅在"不下载权重"的条件下检查语法与包装层契约，不宣称完成了真实模型推理测试，你自己运行时请同样意识到这一点。

示例一：本地 ASR 目录 + 批量音频

第一个示例依次接收本地 ASR 模型目录和一个或多个音频路径，例如python transcribe.py /models/paraformer recording.wav recording2.wav。路径不存在时会在模型构建前失败（resolve(strict=True)+is_dir()校验）。

import argparse from pathlib import Path from funasr import AutoModel parser = argparse.ArgumentParser() parser.add_argument("model_dir") parser.add_argument("audio", nargs="+") args = parser.parse_args() model_dir = Path(args.model_dir).expanduser().resolve(strict=True) if not model_dir.is_dir(): raise ValueError("model_dir must be a complete local model directory") audio = [str(Path(path).expanduser().resolve(strict=True)) for path in args.audio] model = AutoModel(model=str(model_dir), device="cpu", disable_update=True) results = model.generate(input=audio, batch_size=1) for result in results: print(result.get("key"), result.get("text", ""))

几个容易被误用的点：

• batch_size=1在直接推理路径中逐条处理列表；只有确认模型支持批量并测量过内存占用后再增大它。batch_size_s含义不同，只控制包装层的 VAD 路径。
• VAD 切分不是麦克风增量流式识别，也不保证无限录音长度或固定的总内存占用。
• 波形应为采样率已知的一维单声道 float32 数组。使用通用音频加载器的模型，在generate()中通过fs指定数组的原始采样率（回退值为 16000）；目标采样率由模型前端决定。不要把立体声矩阵或数字列表默认当作单条波形——Python 列表通常被解释为多条输入。
• 文件解码能力取决于已安装的音频后端。顶层 bytes 由load_bytes处理：识别出的容器格式会被解码并重采样为 16 kHz，否则按没有采样率元数据的 int16 PCM 解释。输入格式有歧义时，优先使用解码后的数组并明确采样率。参见音频加载代码 和 bytes 输入测试。
• 不要向不可信调用方直接开放任意路径或 URL 输入。

清单文件与输入迭代器

prepare_data_iterator（auto_model.py）还接受清单文件：

• .scp的一行可以是utterance_id /path/to/audio.wav（以空白切分，首列为 key，其余为数据；只有单列时自动生成rand_key_随机 key）；
• .jsonl使用{"source": "/path/to/audio.wav", "key": "utterance_id"}；
• .txt/.text按文本行处理；
• 字符串 URL 会被download_from_url拉取后再走本地逻辑。

注意：该迭代器不会把.json文件当作任意 JSON 数组解析，.json不在filelist = [".scp", ".txt", ".json", ".jsonl", ".text"]之外的特殊分支中。key字段通常取文件名主干（extract_filename_without_extension），否则生成 13 位随机字符串 key，不保证全局唯一。

VAD、时间戳与说话人：四模型组合流水线

下面示例依次接收ASR、VAD、标点、说话人模型目录，最后是音频路径。它面向兼容的本地 Paraformer/SeACo-Paraformer、FSMN-VAD、CT-Transformer 标点与 CAM++ 组合，不适用于任意模型组合。

import argparse from pathlib import Path from funasr import AutoModel parser = argparse.ArgumentParser() for name in ("asr_dir", "vad_dir", "punc_dir", "spk_dir", "audio"): parser.add_argument(name) args = parser.parse_args() paths = {name: Path(value).expanduser().resolve(strict=True) for name, value in vars(args).items()} if not all(paths[name].is_dir() for name in ("asr_dir", "vad_dir", "punc_dir", "spk_dir")): raise ValueError("All model arguments must be complete local directories") model = AutoModel( model=str(paths["asr_dir"]), vad_model=str(paths["vad_dir"]), punc_model=str(paths["punc_dir"]), spk_model=str(paths["spk_dir"]), spk_mode="punc_segment", device="cpu", disable_update=True, ) for result in model.generate(input=str(paths["audio"]), return_spk_res=True): print(result.get("text", "")) for sentence in result.get("sentence_info", []): print(sentence.get("start"), sentence.get("end"), sentence.get("spk"), sentence.get("text", ""))

包装层到底做了什么

配置vad_model后，inference_with_vad按以下步骤工作（auto_model.py）：

1. VAD 检测语音区域：先对整条输入跑 VAD 模型，得到value中的语音区间（毫秒级[start, end]）。若本次调用merge_vad=True，会按merge_length_s（默认 15 秒，构建时设置）把相邻区域合并（merge_vad，auto_model.py）。
2. 按时长排序组批识别：片段按时长升序排序（sorted_data = sorted(..., key=lambda x: x[0][1] - x[0][0])），以batch_size_s（默认 300 秒预算 =max(int(kwargs.get("batch_size_s", 300)) * 1000, 1)毫秒）与batch_size_threshold_s（默认 60 秒）决定哪些短片段合批；CPU 设备强制单片段处理（if kwargs["device"] == "cpu": batch_size = 0）。
3. 恢复原始顺序：restored_data[index] = results_sorted[j]按 VAD 区间的原始下标还原。
4. 时间戳偏移：每个片段的 token/词时间戳统一加上该片段在原始录音中的起始毫秒偏移（t[0] = int(t[0]) + int(vadsegments[j][0])；Nano 的字典式timestamps同样做秒→毫秒换算并加偏移）。
5. 标点：若配置punc_model且结果中无timestamps字段，对拼接文本跑标点模型，并尝试把标点 ID 对齐回原始 surface 文本（_punctuate_surface_text、_merge_timestamp_units、_timestamp_sentences_from_surface，auto_model.py）。
6. 说话人聚类：对每个 VAD 片段切块提取说话人嵌入（sv_chunk），拼接后交给ClusterBackend（CAM++ 聚类后端）得到匿名spk标签，再按spk_mode把标签分布到sentence_info（distribute_spk）。

要点提醒：

• 只设置spk_model不会给直接推理增加说话人分离——通用说话人聚类只在这条 VAD 路径运行。
• punc_segment依赖可用的标点和时间戳；缺少标点或时间戳字段可能使模式变为vad_segment（源码中会在raw_text is None或结果无timestamp/timestamps时打印 warning 并把self.spk_mode改成"vad_segment"，见 auto_model.py）。
• VAD 边界是语音区域边界，不一定是说话人切换点。spk=0等标签是本次结果内的匿名标签，不是已验证的身份，也不是跨录音稳定的 ID。
• 没有说话人模型而设置sentence_timestamp=True时，当前包装层可在标点与 token 时间戳均缺失、或标点与时间戳长度无法对齐时，返回按 VAD 区域对齐的句子记录（_vad_segment_sentences）。其他组合可能返回空的sentence_info（包括已有时间戳但没有标点结果的情形）。该开关不会创建强制对齐模型。

返回字段解读

generate()返回 Pythonlist，其中是模型结果字典，而不是 OpenAI 响应对象。不要假设所有模型都有全部字段，也不要未经检查直接使用results[0]：VAD 路径中的部分空文本分支会跳过一条结果。没有检测到语音时，VAD 流程通常返回{"key": ..., "text": "", "timestamp": []}。

words、ctc_timestamps、说话人特征等额外字段属于模型特有输出。不能不经换算就把 SDK 毫秒值当作服务端秒值。参见时间戳回归测试（覆盖pred_timestamp优先于output_timestamp回退的参数约定）及下列模型源码。

语言、热词和对齐：全部取决于模型

language、hotword/hotwords、时间戳这类控制没有跨模型的统一语义，必须按具体实现传参：

这些是参数约定，不是语言覆盖、准确率或不同平台 checkpoint 内容相同的承诺。Nano 缺少所需张量时会禁用 CTC 输出，见 checkpoint 校验。MOSS-Transcribe-Diarize 是第三方OpenMOSS模型，原生联合完成转写与说话人分离，拥有独立的输出结构和依赖路径，请使用 MOSS 指南，而不是照搬上面的外部 VAD/CAM++ 组合。

文本级热词纠正（postprocess_hotwords）

包装层还支持在generate()中传入postprocess_hotwords（字符串、列表或字典）和postprocess_hotword_file，用于解码之后的文本级纠正，与模型级的hotword/hotwords提示是完全不同的机制（模块文档明确说明，见 postprocess_hotwords.py）：

• 显式映射可写成{"wrong": "right"}，或文件中一行wrong=>right（分隔符还支持->、→；文件行以#开头视为注释）。
• 回退默认值：postprocess_hotword_threshold=0.85、postprocess_hotword_fuzzy=True、return_postprocess_hotword_matches=False。
• 模糊匹配需要pypinyin和rapidfuzz（懒加载，缺失时抛ImportError并提示安装）；设为postprocess_hotword_fuzzy=False时只做显式替换。postprocess_hotword_threshold必须落在[0.0, 1.0]，越界抛ValueError（postprocess_hotwords.py）。
• 输入形式三态：字符串按行解析（每行可为显式映射或纯目标词）；字典的键值即错误词→目标词（键空或键值相同时退化为模糊目标）；序列逐项按行规则解析（postprocess_hotwords.py）。

关键语义：此处理发生在解码之后，会更新顶层text和句子级text/sentence字段，并有意保留与原始识别对齐的时间戳（源码# Timestamps intentionally remain aligned to the original recognition，见 postprocess_hotwords.py）。它既不影响声学解码，也不对替换后的内容重新对齐。将纠正结果用于逐词字幕前，应检查替换明细（开启return_postprocess_hotword_matches=True时结果带postprocess_hotword_matches列表）。这些参数必须按调用传入：generate()向后处理器传递的是本次cfg，不是构建默认配置。参见实现 和测试。

流式 Cache 生命周期：字典就是会话状态

下面示例只面向本地 Paraformer 流式 checkpoint（如iic/speech_paraformer_asr_nat-zh-cn-16k-common-vocab8404-online），不代表给离线模型传入cache={}就能变成流式。运行时依次传入模型目录和非空的单声道 16 kHz 音频文件。示例依据仓库原有示例 和流式实现。

import argparse from pathlib import Path import soundfile as sf from funasr import AutoModel parser = argparse.ArgumentParser() parser.add_argument("model_dir") parser.add_argument("audio") args = parser.parse_args() model_dir = Path(args.model_dir).expanduser().resolve(strict=True) if not model_dir.is_dir(): raise ValueError("model_dir must be a complete local streaming model directory") speech, sample_rate = sf.read(args.audio, dtype="float32") if sample_rate != 16000 or speech.ndim != 1 or len(speech) == 0: raise ValueError("Expected nonempty mono 16 kHz audio") model = AutoModel(model=str(model_dir), device="cpu", disable_update=True) chunk_size = [0, 10, 5] stride = chunk_size[1] * 960 cache = {} for start in range(0, len(speech), stride): end = min(start + stride, len(speech)) result = model.generate( input=speech[start:end], cache=cache, is_final=end == len(speech), chunk_size=chunk_size, encoder_chunk_look_back=4, decoder_chunk_look_back=1, batch_size=1, ) print(result)

数值与默认值解读：

• 该实现的chunk_size回退值为[0, 10, 5]，is_final回退值为False（paraformer_streaming/model.py）。中间值乘以 960 得到输入步长：16 kHz 下 9600 个采样点为600 ms（[0, 8, 4]则为 480 ms，见 demo 注释）。
• 源码中encoder_chunk_look_back和decoder_chunk_look_back的默认值都是0（paraformer_streaming/model.py）；示例中的4和1是显式示例设置，不是包装层默认值。

生命周期纪律：

1. 每条流创建一个新的cache={}，按顺序处理各块时始终传入同一个字典。
2. 保持 chunk/look-back 设置固定，并在最后一块传入is_final=True冲刷缓冲状态。
3. 当前 Paraformer 流式实现在结束时会重新初始化 cache，但结束、取消或开始其他流时仍应丢弃旧字典。不要在不同录音或并发用户之间共享 cache。
4. 保持batch_size=1：该实现断言每次只有一条波形。
5. 返回文本对应本次调用解码的块，不保证是累计全文；应用侧需要自行保留各次输出。
6. WebSocket 会话协议及服务端缓冲机制与这里的字典生命周期是不同层次，不要混为一谈。

版本复现与离线使用

1. SDK 版本/commit、依赖版本与模型文件必须分别锁定。记录 ASR 及每个辅助模型的平台、完整模型 ID、解析后的上游版本、配置和权重哈希。别名或持续变化的master不是可复现的版本锁定。
2. 通用 ModelScope 加载器会向快照下载器转发model_revision（download_from_ms中model_revision = kwargs.get("model_revision", "master")并传给get_or_download_model_dir，见 download_model_from_hub.py）。通用 Hugging Face 助手虽然接收该参数，当前实际调用却是snapshot_download(model)，没有传入revision、local_files_only或check_latest。不能宣称hub="hf", model_revision=...能锁定这条路径。有些适配器使用自己的加载逻辑（如 Whisper 的openai分支），也要检查实际选用的适配器。
3. 离线运行前，应在联网环境准备并验证完整本地快照，包括 tokenizer/前端文件、配置、权重、嵌套编码器/LLM 以及可选对齐器。为所有组件传入已存在的本地目录。本地路径绕过通用平台下载解析，但嵌套模型代码仍可能联网或缺少依赖，必须在实际网络限制下验证。
4. disable_update=True只跳过包更新检查。check_latest=False不保证离线，这些通用下载助手也没有统一的local_files_only开关。URL 音频和 URL 热词仍需联网；已有缓存的模型别名也可能触发平台请求。
5. 除非审查过的模型代码确实需要，否则保持trust_remote_code=False。ModelScope 通用加载器在信任开启时可以导入remote_code（默认值为"model"）；两个通用平台加载器都可能在信任开启时安装模型的requirements.txt，但代码导入行为并不相同。本地快照不等于安全代码。

FunASR 软件采用 MIT 许可证；模型权重、数据集、第三方适配器和依赖可能采用不同许可证。再分发或部署前，请检查具体模型自身的许可证和使用条件。

SDK 与服务接口边界：别把进程内 API 当 HTTP API

Hydra 推理入口 从配置构建AutoModel后调用generate()，不会把所有 CLI/配置项变成 HTTP 表单字段。开放服务前，应在相应边界落实鉴权、TLS、上传限制、超时及访问限制——OpenAI 客户端的占位 API key 不是访问控制。

延伸阅读：English 版本文档 | 安装指南 | 模型选择 | vLLM 指南 | MOSS 转写+说话人分离指南

【免费下载链接】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