FunASR 官方 checkpoint 原生 vLLM 服务验证全记录：Fun-ASR-Nano 固定 revision 下载、离线启动与多语言转写复现指南

FunASR 官方 checkpoint 原生 vLLM 服务验证全记录：Fun-ASR-Nano 固定 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

本篇文章基于 FunASR 仓库中的官方验证记录 docs/vllm_official_native_validation_zh.md 及其配套可复现元数据 docs/benchmark/vllm_official_native_20260907.json，完整还原一次针对官方FunAudioLLM/Fun-ASR-Nano-2512-vllm固定 revision 的 vLLM 原生服务验证：包括验证范围与环境的界定、不可变本地快照的下载与校验、离线 loopback 启动、中/英/日三语转写与热词请求、并发功能探针，以及部署边界与安全建议。读完本文，你将掌握一条可完整复现的官方权重 vLLM 原生服务验证链路，并理解它与 FunASR 拆分引擎路径、社区 checkpoint 历史记录之间的严格区别。

验证记录的核心定位：官方原生路径，不是拆分引擎

本次验证记录（验证日期 2026-09-07，Asia/Shanghai，对应 HTTP Date 头 2026-09-06 UTC）独立验证的是官方FunAudioLLM/Fun-ASR-Nano-2512-vllm快照，其不可变 revision 为a4362c943d48951f98ca2a62181cc028970270c5。需要特别强调的是：

• 这是模型 revision，不是根目录 FunASR Python 包版本；
• 本次使用 vLLM 原生的FunASRForConditionalGeneration架构直接服务，不经过 FunASR AutoModel，也不是 split-engine 解码器路径（后者将音频编码器/adaptor 保留在 PyTorch、只把 Qwen3-0.6B 解码交给 vLLM，见 funasr/models/fun_asr_nano/inference_vllm.py）；
• 2026-08-13 的社区 checkpoint 历史记录（allendou/Fun-ASR-Nano-2512-vllm@e718b36e）及其 benchmark 保持原样，本次不是给旧数据换模型名称，也不说明官方模型更快。

两条原生/非原生路径的边界

根据 docs/vllm_guide_zh.md 中的说明，Fun-ASR-Nano 存在两条不同的 vLLM 集成路径，checkpoint 与调用接口不能混用：

两条原生路径都只提供请求/响应式转写/v1/audio/transcriptions，不会注册/v1/realtime实时流式端点。FunASRForConditionalGeneration当前不在 vLLM 的 Realtime Transcription 表中；需要实时流式识别时请使用 FunASR 流式 SDK 推理或流式 ASR 服务。原生 HTTP API 也不会自动获得 FunASR WebSocket 服务的 VAD、partial 预览、会话状态或 SPK 处理。

值得注意的版本背景：vLLM 上游 PR#54944于 2026-09-05 合并（merge commite473e9036f979d546830aece9855027049faf0ba），它更新了 supported-model 文档及测试 registry 的官方 checkpoint 引用，没有修改推理实现。2026-09-07 审计时 main 分支已使用官方引用，但v0.28.0 仍引用社区产物——"已合并不等于已发布"。本次验证既不覆盖 main 也不覆盖 v0.28.0，更不覆盖上游测试 registry 独立的 Transformers 版本约束。

仓库测试 tests/test_vllm_model_source_docs.py 对这套边界做了契约校验：test_primary_guide_keeps_native_vllm_and_funasr_realtime_paths_separate与test_primary_vllm_guides_bound_native_transcription_to_request_response分别断言 vLLM 指南文档必须同时包含 "FunAudioLLM/Fun-ASR-Nano-2512-vllm"、"不会注册/v1/realtime" 等标记；test_documentation_hub_keeps_official_and_historical_native_entries_separate则要求官方验证记录与历史社区记录在文档 Hub 中保持分离。

验证范围与环境

验证共记录了8 个 HTTP 请求且全部返回 200：健康检查、模型列表、中/英/日三语单请求转写、中文热词请求，以及两个并发请求。全部23 个文件直接从官方固定 revision 下载，按 Hub Git/LFS 摘要验证，复制到持久备份后再次校验；没有替换为社区缓存文件，也没有修改上游模型代码。

这是既有环境验证，不是全新安装验证：没有安装、升级或重新解析依赖。以上版本是环境观测结果，不是经全新安装验证的 lockfile。不能据此宣称浮动pip install vllm或直接加载浮动 Hub 模型 ID 可复现本次结果。可复现元数据 docs/benchmark/vllm_official_native_20260907.json 中记录了完整的包清单（含 vllm 0.27.1+cu129、torch 2.13.0+cu129、transformers 5.15.0 等 200+ 个包）、CUDA 运行时版本、native 源文件vllm/model_executor/models/funasr.py及其 SHA256 摘要（0cc059845327614a82259c0fe7bd5a1f868565e7e011c113b24c18a47f79c5c7），同时明确"clean_install_validated": false、"first_chinese_request_warmed": false。

环境提示：vLLM 各版本的依赖约束随版本变化，不能概括成"三件套永远相同"。例如 0.19.1 声明torch==2.10.0，而 0.27.1 声明torch==2.13.0。升级时请新建环境并重新验收，遇到驱动过旧错误应检查实际 wheel 的 CUDA 构建与驱动要求，而不是盲目安装最新版。

准备固定的本地快照

验证的第一步是构建不可变的本地模型快照。以下命令将实际验证流程中的私有绝对路径替换成可移植变量，请把VLLM_PYTHON指向已准备好且符合上表的环境；示例.venv路径不代表本次新建过虚拟环境。建议使用全新的隔离验证目录并保留下载 manifest；可使用已有 Hub 认证，但不要输出凭据。

export VLLM_PYTHON="$PWD/.venv/bin/python" export VALIDATION_DIR="$PWD/.official-native-validation" export MODEL_DIR="$VALIDATION_DIR/official-model/a4362c943d48951f98ca2a62181cc028970270c5"

在与实测相同的 native-import 上下文检查版本

这一步特意在导入vllm.model_executor.models.funasr之后检查包版本——因为 setuptools 的 vendored 包会进入sys.path，导入上下文不同可能影响包清单比较结果（下文"Harness 边界"一节会再次遇到这一点）：

"$VLLM_PYTHON" - <<'PY' import importlib.metadata as metadata import torch import vllm.model_executor.models.funasr for name, expected in {"vllm": "0.27.1+cu129", "torch": "2.13.0+cu129", "transformers": "5.15.0"}.items(): assert metadata.version(name) == expected, (name, metadata.version(name)) assert torch.version.cuda == "12.9" and torch.cuda.is_available() PY

按不可变 revision 下载全部 23 个文件并校验

以下脚本先通过HfApi().model_info(..., files_metadata=True)校验 Hub 元数据（info.sha == revision且恰好 23 个 sibling），再用snapshot_download拉到隔离目录。对每个文件逐一核对字节数与摘要：LFS 文件校验 SHA256，非 LFS 文件按blob {size}\0+ content 的 Git blob SHA1 校验；最后断言config.json的architectures为["FunASRForConditionalGeneration"]，并写出下载 manifest。此脚本不执行下载内容中的转换脚本，也不修改快照：

HF_HUB_DISABLE_TELEMETRY=1 HF_XET_CACHE="$VALIDATION_DIR/isolated-xet-cache" "$VLLM_PYTHON" - <<'PY' import hashlib import json import os from pathlib import Path from huggingface_hub import HfApi, snapshot_download model_id = "FunAudioLLM/Fun-ASR-Nano-2512-vllm" revision = "a4362c943d48951f98ca2a62181cc028970270c5" root = Path(os.environ["MODEL_DIR"]) info = HfApi().model_info(model_id, revision=revision, files_metadata=True) assert info.sha == revision and len(info.siblings) == 23 snapshot_download(model_id, revision=revision, local_dir=str(root), cache_dir=str(Path(os.environ["VALIDATION_DIR"]) / "isolated-hf-cache"), max_workers=4) files = [] for item in info.siblings: content = (root / item.rfilename).read_bytes() digest = hashlib.sha256(content).hexdigest() assert len(content) == item.size, item.rfilename if item.lfs: assert digest == item.lfs.sha256, item.rfilename else: assert hashlib.sha1(f"blob {len(content)}\0".encode() + content).hexdigest() == item.blob_id files.append({"path": item.rfilename, "size": len(content), "sha256": digest}) assert json.loads((root / "config.json").read_text())["architectures"] == ["FunASRForConditionalGeneration"] (root.parent / "download-manifest.json").write_text(json.dumps(files, indent=2) + "\n") PY

完整的 23 个文件清单（含.gitattributes、LICENSE、MODEL_PROVENANCE.json、README.md、config.json、config.yaml、configuration.json、convert_from_official.py、5 个示例音频、generation_config.json、merges.txt、model.safetensors、multilingual.tiktoken、preprocessor_config.json、tests/test_conversion.py、tokenizer.json、tokenizer_config.json、vocab.json）以及每个文件的 size、Git blob、LFS SHA256、SHA256，都记录在 docs/benchmark/vllm_official_native_20260907.json 的files字段中，可直接用作下载后的比对基准。

Checkpoint 与音频摘要

验证所用示例音频均为单声道 48 kHz MP3，ffprobe 测得容器时长分别为中文 5.616 s、英文 7.176 s、日文 7.224 s。服务 usage 计数将其向上取整为 6/8/8 秒；取整值不是文件实测时长（元数据中duration_seconds字段记录的是实测值）。

可复现元数据 包含全部 23 个文件的大小、SHA256、上游 Git/LFS 摘要、包版本、精确 HTTP 字段、原始响应摘要及未取整耗时。公开内容省略私有主机路径、GPU 标识和凭据；其中原始/v1/models响应的本地 root 保留在私有证据中，其摘要对应原始字节，不是脱敏后的替代响应。

离线启动与 loopback

启动命令

先确认 GPU 0 空闲、loopback 端口 57185 未被占用。如需换端口，须同步更改所有请求；本记录只使用了 57185。在准备环境的 shell 中以前台启动：

CUDA_VISIBLE_DEVICES=0 PYTHONDONTWRITEBYTECODE=1 \ HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 \ HF_HUB_DISABLE_IMPLICIT_TOKEN=1 HF_HUB_DISABLE_TELEMETRY=1 VLLM_NO_USAGE_STATS=1 \ VLLM_CACHE_ROOT="$VALIDATION_DIR/runtime-cache" TRITON_CACHE_DIR="$VALIDATION_DIR/triton-cache" \ "$VLLM_PYTHON" -B -m vllm.entrypoints.openai.api_server \ --model "$MODEL_DIR" --served-model-name fun-asr-nano-official-a4362c94 \ --host 127.0.0.1 --port 57185 --dtype float32 \ --gpu-memory-utilization 0.40 --enforce-eager

关键点说明：

• 实际服务加载经过验证的本地快照，Hub 与 Transformers 均为离线模式（HF_HUB_OFFLINE=1、TRANSFORMERS_OFFLINE=1）；
• 没有使用--trust-remote-code，也没有让服务从浮动模型 ID 加载；
• --dtype float32是验证记录的服务精度；从 funasr/models/fun_asr_nano/inference_vllm.py 的_resolve_vllm_dtype()可知，Fun-ASR-Nano 的 Qwen3 语言模型在 fp16 下数值不稳定，拆分引擎路径会自动改用 bfloat16 并发出告警，硬件不支持 BF16 时应使用fp32——这与本次原生服务显式使用 FP32 的方向一致；
• --gpu-memory-utilization 0.40是本次实测值而非通用建议：历史记录 docs/vllm_native_funasr_validation.md 显示 0.20 不足以支撑完整模型长度（仅剩 1.70 GiB 给 KV cache，而单条 40,960-token 请求需要 8.75 GiB）。请针对目标 GPU 与负载自行评估，不要盲目照抄；
• 下载完成后，启动至健康状态耗时84.123246 s；这只是单次观测，不是启动性能保证。

健康检查与模型发现

在第二个 shell 中将VALIDATION_DIR和MODEL_DIR设为相同绝对路径，然后等待健康检查成功：

curl --max-time 15 -fsS http://127.0.0.1:57185/health curl --max-time 15 -fsS http://127.0.0.1:57185/v1/models

/v1/models应包含 IDfun-asr-nano-official-a4362c94，其 root 应等于展开后的MODEL_DIR。实测同时检查了二者。

实际转写请求

实测 harness 使用 Python requests，multipart 音频 MIME 为audio/mpeg，连接/读取超时为 5/45 s，显式传入language=zh、language=en、language=ja和response_format=json，没有覆盖 temperature 或生成长度（这与拆分引擎路径默认temperature=0.0、top_p=1.0的确定性解码策略一脉相承）。以下等价 curl 保留实际请求字段，但没有单独测量 curl 耗时：

curl --max-time 45 -fsS http://127.0.0.1:57185/v1/audio/transcriptions -F "file=@$MODEL_DIR/example/zh.mp3;type=audio/mpeg" -F model=fun-asr-nano-official-a4362c94 -F language=zh -F response_format=json curl --max-time 45 -fsS http://127.0.0.1:57185/v1/audio/transcriptions -F "file=@$MODEL_DIR/example/en.mp3;type=audio/mpeg" -F model=fun-asr-nano-official-a4362c94 -F language=en -F response_format=json curl --max-time 45 -fsS http://127.0.0.1:57185/v1/audio/transcriptions -F "file=@$MODEL_DIR/example/ja.mp3;type=audio/mpeg" -F model=fun-asr-nano-official-a4362c94 -F language=ja -F response_format=json curl --max-time 45 -fsS http://127.0.0.1:57185/v1/audio/transcriptions -F "file=@$MODEL_DIR/example/zh.mp3;type=audio/mpeg" -F model=fun-asr-nano-official-a4362c94 -F language=zh -F 'hotwords=开放时间,开放时间,开放时间' -F response_format=json

实际返回文本

• 中文基线：开饭时间早上九点至下午五点。
• 英文：The tribal chieftain called for the boy, and presented him with fifty pieces of gold.
• 日文：うちの中学は弁当制で、持っていけない場合は、五十円の学校販売のパンを買う。
• 中文加hotwords=开放时间,开放时间,开放时间：开放时间早上九点至下午五点。

基线保留了一条误识别结果（"开饭时间"），而重复热词将该样本的输出改变为"开放时间"。元数据中"limitations"字段明确声明：重复热词只证明此样本输出发生改变，不能直接推广为通用热词策略或准确率保证。这与历史社区记录 docs/vllm_native_funasr_validation.md 的结论一致——单个开放时间热词不改变基线输出，重复三次才改变模糊短语；热词强度是需要按代表性音频验证的策略，而非确定性纠错。

已记录请求与耗时

首次中文请求未经转写预热：它是健康检查和模型列表之后的第一个转写请求；后续请求复用同一引擎。时间包含本地 HTTP 与解码，不含模型下载和服务启动；每项只有一次观测，不是延迟分布。原始响应体（含usage字段，如中文返回{"text":"开饭时间早上九点至下午五点。","usage":{"type":"duration","seconds":6}}）与未取整耗时均记录在 docs/benchmark/vllm_official_native_20260907.json 的http.requests数组中，可供逐条比对。

并发功能探针

四个顺序转写请求之后，双 worker 的ThreadPoolExecutor同时发出相同的英文和日文 multipart 请求，均返回 200，文本与顺序请求一致。两请求总 wall time 为0.9112209342420101 s（0.911 s），包含 executor 建立与等待两项完成。这只是两个请求的并发功能探针，不是吞吐量、生产容量或准确率研究，也不是与社区历史 1.123 s 探针的性能对比（元数据"two_request_wall_seconds"字段记录了这一数值）。

Harness 边界与清理

验证过程本身也是一个值得记录的可复现性案例：

• 首次 harness 尝试在创建服务进程之前被包清单 guard 拦截。原因：准备阶段导入 native vLLM，使 setuptools 的 vendored 包进入sys.path，而原始 serve 阶段却使用不同导入上下文比较包清单。统一导入上下文后差异为空，原始失败和修正均已保留（元数据"guard_failure_before_server_spawn": true、"guard_correction"字段记录了这段历史）。
• 早期失败状态字段曾误写为服务已启动，进程证据与修正记录确认当时没有启动；没有修改依赖或模型代码，之后首次实际启动服务即完成 8 请求 smoke。
• 有时限的 harness 终止了自己创建的进程组，并等待服务及子进程退出。清理状态在元数据"cleanup"对象中全部为 true：服务退出码 0、端口关闭、GPU 无计算进程、包与 native 源文件摘要不变。
• 独立检查再次确认全部 23 个原始文件及备份摘要、8 个原始响应、模型身份和清理状态。

手工复现时请注意：探针结束后请停止前台服务，确认其 worker 与端口均已退出，不要终止无关的 GPU 任务。

部署边界与安全建议

• 本次验证只覆盖 request/response/v1/audio/transcriptions，没有验证/v1/realtime实时流式会话；长音频、说话人分离、时间戳准确率、其他 GPU、持续负载与生产容量均不在范围内。
• 不能由原生服务推导 FunASR SDK 或包发布已通过验证——原生服务绕过 AutoModel，未经过 SDK 层。
• worker 应保持绑定127.0.0.1。对外提供 API 前，由网关完成认证、TLS、限流、音频大小/时长限制，隔离上传文件并落实保留策略。网关不在本次 smoke 范围内。更多部署形态与安全边界可参见部署矩阵和服务安全边界。
• 从仓库测试 tests/test_vllm_model_source_docs.py 可以看到，这套验证记录与 vLLM 指南、模型选择文档之间还有文档契约约束：test_model_selection_distinguishes_checkpoint_and_service_paths要求模型选择文档同时包含AutoModelVLLM、FunAudioLLM/Fun-ASR-Nano-2512-vllm、/v1/audio/transcriptions、/v1/realtime、2026-08-13等标记，确保读者能清楚区分 checkpoint 与服务路径；test_vllm_guides_distinguish_official_and_native_model_paths则校验 vLLM 指南必须同时覆盖拆分引擎的prepare_vllm_model_dir()、Qwen3-0.6B-vllm/model.safetensors与原生架构FunASRForConditionalGeneration。

复现要点总结

1. 环境固定：以 docs/vllm_official_native_validation_zh.md 的环境表与 docs/benchmark/vllm_official_native_20260907.json 的包清单为准，在既有环境中复现，不要把它当作全新安装验收；
2. 快照不可变：按 revisiona4362c943d48951f98ca2a62181cc028970270c5下载 23 个文件，逐文件校验 SHA256 / Git blob / LFS 摘要，保留下载 manifest；
3. 服务离线化：加载本地快照 +HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1，不用--trust-remote-code，不加载浮动模型 ID；
4. 请求显式化：非英语音频必须显式传language（vLLM FunASR adapter 对省略 language 的默认是英语，此结论同样记录于历史社区验证 docs/vllm_native_funasr_validation.md），音频 MIME 为audio/mpeg，response_format=json；
5. 结果可核对：三语文本、热词差异、8 个请求的 HTTP 状态与 wall time、双请求并发 wall time 均可与本文表格及元数据逐一对照；
6. 结论边界：本记录是短时功能兼容性探针（元数据"limitations"原话为 "Short functional compatibility probe only"），不是准确率、生产容量或历史 benchmark 等价的声明；对生产环境请在目标 GPU、驱动、语种与话务分布上独立重测。

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