Fun-ASR-Nano + Transformers：先选对权重，再接入应用
在已有 Hugging Face 应用里接入语音识别，最容易踩的坑往往不是模型大小，而是把“同一模型家族”当成“同一种权重和接口”。Fun-ASR-Nano 已进入 Transformers 主线。这篇文章从 checkpoint、处理器到生成结果，解释如何把这次集成接到自己的应用中。
先确认安装包，不只看合并状态
PR #46180 于 2026-09-09 合并。当天核验的稳定版 5.16.1 还没有原生 fun_asr_nano 文件；源码包显示的 5.17.0.dev0 也不是下一稳定版发布承诺。请从固定版本接入指南安装明确的源码提交，不要只执行一次无版本约束的升级就假定已经兼容。
这种区别影响排障方向：未知模型类型可能是安装包未包含实现，不一定是 checkpoint 损坏；模型能下载也不代表所选运行时认识它。
同一模型家族，四条不同路径
| 应用已有的接口 | 选择什么 | 不要混淆 |
|---|---|---|
| FunASR AutoModel | Fun-ASR-Nano-2512 | 原始工具包路径；拆分引擎看对应文档。 |
| Transformers processor / generate | Fun-ASR-Nano-2512-hf | 本篇的原生接口，不是 vLLM 的转换包。 |
| 原生 vLLM HTTP 服务 | Fun-ASR-Nano-2512-vllm | 使用独立运行时、模型格式及服务参数。 |
| C++ / GGML 运行时 | 与运行时匹配的 GGUF | 不是把 Transformers 目录改后缀。 |
这几个官方模型仓库位于 FunAudioLLM 下。原生 Transformers 路径加载 官方 -hf checkpoint，模型和处理器代码来自固定的 Transformers 安装，不需要执行 checkpoint 的远程 Python 代码。它减少了一种接入依赖，并不自动提供鉴权、队列或服务监控。
如果目标是多客户端并发请求，直接查看原生 vLLM 部署页；如果目标是离线 C++ 运行，查看llama.cpp 部署页。原生 Python 接口是一个可组合入口，不是所有服务的替换品。
从声音到文本，中间实际经过什么？
- 音频样本。采样率与声道是数据含义的一部分。48 kHz 的数组不能只改参数标成 16 kHz；那会改变模型看到的时间尺度。指南先要求明确的单声道 16 kHz WAV。
- 音频特征。原生特征提取器用 torchaudio 的 Kaldi fbank，再做 LFR 堆叠与降采样。这里仍需要匹配版本的 torchaudio；不能套用 FunASR 工具包的可选依赖结论。
- 转写请求。
apply_transcription_request把音频、语言、上下文和关键词整理成模型的聊天模板，并对齐音频占位 token 与特征。 - 生成和解码。
AutoModelForSpeechSeq2Seq返回 token。去掉输入 prompt 的长度后再解码，才能避免把模板混进转写文本。
先用合成静音验证配置和张量形状，可以把依赖、模板错误与权重加载问题分开。但预处理没有调用生成模型，不能据此宣布“识别通过”。
应用上下文应该放在哪里？
业务词表通过原生 keywords 参数传入，相关背景通过 prompt 传入。它们不是工具包的 hotword 参数，也不是 HTTP 层字段。给两份录音分别传上下文时，语言、prompt 和嵌套关键词列表应与录音数量一致。输出顺序应回到同一份输入清单。
例如客服录音里的人名、产品名，可以作为候选关键词；但“模板中出现了关键词”和“模型在噪声中识别对了这个词”是两项测试。不要把拼写纠正或摘要改写后的文本冒充原始 ASR 输出。
当前固定快照默认左侧 padding；批量示例仍可显式设置 padding 以便阅读。生成返回值要按整批输入张量的宽度去除 prompt，不是各条 attention mask 有效长度。空录音和空列表应在应用边界提前拒绝。
一次真实短录音检查说明了什么？
在固定源码、官方 -hf revision 和 CPU float32 环境中，我们运行了中文单录音、英文单录音、中英混合批量，以及一个带关键词的中文请求。四个请求均返回文本并在上限前生成 EOS；批量结果顺序正确。这是两份公开短音频的功能检查，不是准确率排行榜。
| 同一份中文音频 | 原始输出 |
|---|---|
| 不传关键词 | 开饭时间早上九点至下午五点。 |
| 候选关键词：开放时间 | 开饭时间：早上九点至下午五点。 |
这个例子没有显示关键词强制生效，不能包装成“加热词就会识别对”。API 参数被接收、输出发生变化和业务词写对，是不同结论。保留原文，再结合人工参考检查；不要用提示词替代验收。环境、样本来源与重采样口径见验证记录。
接入成功之后，还要验收什么？
- 范围。这条 -hf 路径用于生成式转写，不包含原生 CTC 分支；不能把结果文本当作字级时间戳或说话人分离输出。
- 完整性。短文件示例的生成上限是 128 个新 token。触顶可能截断；增加上限不会自动证明长录音没有漏句。
- 资源。独立 CPU 示例不是 CUDA、服务并发或 vLLM 性能测试。分别记录下载、模型加载和生成，不把首次下载算成模型推理，也不把一次短录音当作容量规划。
- 质量与隐私。在授权录音中回听关键数字、否定词和末尾，保留固定版本与原始结果；公开反馈不要携带客户录音、token 或身份信息。
需要段级时间戳和匿名说话人时，可比较 OpenMOSS 的第三方 MOSS 统一转写与分离路径。匿名标签不是人物身份，模型选型仍应从应用真正需要的输出开始。
从哪里开始
先打开原生 Transformers 安装与推理指南，完成独立 CPU 环境、无权重预处理和短录音生成，再决定是否需要批量或服务化。模型页和 Model Zoo保留格式入口；会议录音验收清单帮助把结果交付到应用。
源码依据：固定提交的官方模型文档、固定 revision 的模型卡。模型项目与贡献入口见 Fun-ASR 和 FunASR。