(简体中文 | English)

先完成安装与环境验证。本页按首次转写、结果检查、VAD、批处理、模型专属选项的顺序介绍。模型选择、语言、依赖和模型卡请查阅模型仓库，不要将某个示例当成所有模型的通用能力。尚未配置本地环境时，可先看 Colab 快速体验。

FunASR 软件采用 MIT 许可。每个模型权重都有各自的许可：请记录完整模型 ID 与 revision，并以对应模型卡为准。只有模型卡明确链接 FunASR 模型许可协议时，该协议才适用。第三方集成仍属于第三方模型，例如 MOSS-Transcribe-Diarize 来自 OpenMOSS，不是 FunASR 训练的权重。

1. 完成第一次转写

安装 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(
    model="paraformer-zh", hub="ms", device="cpu", ncpu=4,
    disable_update=True, trust_remote_code=False,
)
results = model.generate(input=audio)
for item in results:
    print(item.get("key"), item.get("text", ""))
print("Model directory:", model.model_path)

识别自己的录音时，将 audio 替换为存在的本地 WAV 路径。建议先使用与模型采样率匹配的短单声道录音，本示例为 16 kHz。文件解码能力取决于音频后端，先检查可读 WAV 比直接尝试任意媒体容器更简单。NumPy 波形没有采样率文件头，需要通过 fs=sample_rate 传入真实采样率，参见音频加载器；不要仅修改采样率标签而不重采样。

后续 Python 代码块在同一会话中复用这里的 AutoModel、audio 和 model。断网使用时，请先按离线检查清单准备完整本地模型目录和本地输入文件。disable_update=True 仅跳过 SDK 启动版本检查。

2. 理解参数和结果

AutoModel(...) 构建模型与可选流水线组件，model.generate(input=..., **options) 执行推理。源码入口：AutoModel、hub 别名映射，以及具体模型的 inference() 实现。

参数	作用范围与含义
`model`、`hub`	模型 ID/别名或本地目录；默认 ModelScope (`ms`)，`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 的输入数量，仍受后端限制。
`batch_size_s`	VAD 分段组 batch 的秒数预算，按填充后的片段长度计算，不是文件数。当前 CPU VAD 路径逐段解码。
`batch_size_threshold_s`	VAD 组 batch 启发式使用的片段时长阈值，不是输入时长限制或通用内存上限。
`output_dir`	可选的后端输出目录；仍会返回 Python 结果。具体文件和格式取决于模型。

generate() 返回字典列表，通常每条输入录音对应一个结果。使用可选字段前先检查实际键名：

for item in results:
    print(sorted(item.keys()))
    print(item.get("text", ""))
    print(item.get("timestamp", []))

Paraformer 路径在权重提供时间戳时，timestamp 为字/词元/词级的 [start_ms, end_ms] 区间。标点恢复或文本规范化后，不要假定每个可见字符都对应一组区间。其他后端可能返回不同结构的 timestamps，请按对应指南解析。无语音时可能返回空文本或空时间戳，不能当成有效转写。

3. 添加 VAD、标点与句级时间戳

VAD 检测语音区间，本身不做转写。下面独立检测同一音频：

vad = AutoModel(model="fsmn-vad", device="cpu", disable_update=True)
vad_results = vad.generate(input=audio)
for item in vad_results:
    print(item["key"], item["value"])

value 为相对于录音起点的 [start_ms, end_ms] 语音区间列表。空列表表示没有检测到区间。参见 FSMN VAD 示例。

组合分段 ASR 与标点：

pipeline = AutoModel(
    model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc",
    vad_kwargs={"max_single_segment_time": 30000},
    device="cpu", disable_update=True, trust_remote_code=False,
)
segmented_results = pipeline.generate(
    input=audio, batch_size_s=60, batch_size_threshold_s=30,
    sentence_timestamp=True,
)
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，再重新测量。句子边界依赖可用的时间戳和标点对齐，可能回退到 VAD 片段，应检查真实结果。

需要说话人分割时，在所选组件支持的前提下，为相同流水线添加 spk_model="cam++"。遍历每条输入的 item.get("sentence_info", []) 后，再读取 sentence.get("spk")；不要从外层结果列表直接读取 spk。聚类标签不等于已验证的真实身份。参见说话人组合示例。

4. 处理多条录音

下面故意重复同一示例，演示列表输入，不依赖额外文件。实际使用时替换为本地 WAV 路径：

batch_results = model.generate(input=[audio, audio], batch_size=1)
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，仅接收返回列表不强制要求该参数。参见数据列表示例。独立文件的批处理不等于同一句话的流式分块。

5. 热词与语言边界

本工作区中 ModelScope 的 paraformer-zh 别名映射到 SeACo Paraformer，其实现接受单数 hotword，值为以空格分隔的字符串：

biased_results = model.generate(input=audio, hotword="魔搭 达摩院")
print([item.get("text", "") for item in biased_results])

这是模型级上下文偏置，不保证一定插入指定词，也不是确定性文本替换。请确认实际解析出的模型，并与不加热词的结果对比。参见 SeACo 实现与上下文 Paraformer 示例。

本源码工作区的文本后处理是另一种操作：

corrected_results = model.generate(
    input=audio,
    postprocess_hotwords={"科大迅飞": "科大讯飞"},
    return_postprocess_hotword_matches=True,
)
for item in corrected_results:
    print(item.get("text", ""), item.get("postprocess_hotword_matches", []))

显式映射替换输出文本中的匹配项。postprocess_hotword_file 还支持每行一个目标词或 错误词=>目标词 映射。模糊匹配额外需要 pypinyin 和 rapidfuzz，显式映射不需要。后处理实现保留原有时间戳，不会重新对齐修改后的文本；生成字幕或宣称对齐准确前，请审查替换结果。

hotword、hotwords 和 language 不是可互换的通用 SDK 选项。例如 Fun-ASR-Nano读取复数 hotwords 和模型专属语言提示。修改提示不能把单语言权重变成多语言权重。语言支持、提示取值、流式能力、对齐和依赖版本应按模型仓库及精确模型指南确认，不要跨模型照搬语言数量或安装版本。

6. 进入具体工作流

流式识别：Paraformer 流式示例。每个音频流维护独立 cache={}，最后一块设置 is_final=True。16 kHz 下 [0, 10, 5] 的 600 ms 对应 9600 个采样点，不是 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() 契约已经满足，模型推理结果必须与计划使用的下游组件匹配。

遇到问题时，带上解释器/依赖版本、实际模型 ID/revision、输入格式和最小复现，回到常见问题。不要在反馈中附带私密音频或凭据。