Skip to content

deployment_matrix_zh.md

Latest commit

 

History

History
101 lines (66 loc) · 11.6 KB

deployment_matrix_zh.md

File metadata and controls

101 lines (66 loc) · 11.6 KB
Raw

FunASR 部署选型表

这个页面帮助你为产品、demo、benchmark 或内部工作流选择最短部署路径。先选择能满足目标的最小方案，只有在吞吐、延迟或集成方式有明确要求时，再切换到更重的运行时。

快速决策表

路径 适合场景 从这里开始 运维提示
原生 Transformers Nano 首次转写、Notebook 与 Hugging Face Python 应用 原生 Fun-ASR-Nano 指南 正式版 5.17.0，官方 -hf checkpoint，CPU 与批处理示例。是 Python 推理入口，不是 HTTP 或实时服务器。
Colab Notebook 浏览器 smoke test、首次评估、可分享 demo Colab 快速体验 不需要本地环境；首次运行会下载模型，GPU runtime 更快。
Python API Notebook、离线任务、首次模型评测 README 快速开始 最简单；调用方自己负责批处理、重试和文件管理。
OpenAI 兼容 API 私有语音 API、Agent、Dify/LangChain/AutoGen 风格客户端 OpenAI API 示例 已支持 OpenAI audio API 的应用最容易接入。
Xinference 已经使用 Xinference 统一管理模型服务的团队 Xinference 仓库 使用包含 xorbitsai/inference#5140 的版本或 commit，确保 Fun-ASR-Nano 使用打包发布的 funasr~=1.3.0，而不是旧的 git commit pin。
Docker Compose API 本地 smoke test 或小型内部服务 OpenAI API Docker 文档 默认 CPU；容器里使用 CUDA 前需要先适配 CUDA-capable 镜像。
Kubernetes API 集群内私有语音 API Kubernetes 模板 默认私有 ClusterIP；对外开放前补齐鉴权、TLS、网络策略和 GPU 调度。
Runtime WebSocket 服务 实时字幕、会议、客服流式音频 Runtime 服务文档 需要中间结果、断句或长连接音频流时选择。
ONNX/C++ Runtime 高并发 CPU 服务或嵌入式实时 ASR ONNX Runtime 文档 如果延迟和并发已经验证，不要轻易替换；固定业务词优先做文本后处理。
vLLM 加速 Fun-ASR-Nano 原生文件转写或 split-engine LLM 解码 官方原生验证；split-engine 指南 原生路径固定官方 a4362c94 本地快照、vLLM 0.27.1，仅为既有环境功能验证，不是全新安装或容量验证；不适用于非自回归 Paraformer。
MOSS-Transcribe-Diarize 长音频多人转写、时间戳和说话人标签 第三方 MOSS 部署指南 OpenMOSS Apache-2.0 模型，已接入 FunASR AutoModel；可选本地 HF（backend="hf"）、vLLM（backend="vllm"）或 SGLang Omni（backend="sglang"）。模型仍由 OpenMOSS 发布和维护。
MCP 服务 Claude/Cursor/桌面 Agent 语音工具 MCP 示例 适合把 ASR 结果暴露成一个本地工具。
字幕生成 从长音频或视频生成 SRT/VTT 字幕示例 需要可读性时使用 verbose segments 和说话人标签。
批处理脚本 录音归档、会议纪要、数据集处理 批处理示例 生产使用时建议增加队列、manifest 和重试日志。
Triton Runtime 专门的高性能推理服务 Triton 文档 配置更重；适合已经在运维 Triton/GPU serving 的团队。

常见选择

我想五分钟内试跑 FunASR

如果只想在浏览器里 smoke test，可以先用 Colab 快速体验；本地工作再使用 README 里的 Python API。它是验证安装、模型下载、设备选择和基础输出格式的最短路径。如果还不确定先用哪个模型，请看 模型选择指南。

我想替代云端转写服务

使用 OpenAI 兼容 API。它提供 /v1/audio/transcriptions、/v1/models、/health 和 Swagger docs。先用 sensevoice 跑通 examples/openai_api/smoke_test.sh 或 examples/openai_api/smoke_test.py，再根据 客户端配方 和 JavaScript/TypeScript 配方 接入 SDK 或 HTTP 客户端。浏览器上传或麦克风 demo 可使用 Gradio 浏览器 Demo。Dify、n8n、HTTP 节点或 webhook worker 可参考 工作流配方。API 网关、开发者门户或按 schema 导入时可使用 OpenAPI 规范。跨团队共享服务前，请先阅读 安全与网关指南。

我已经在使用 Xinference

如果你的系统已经用 Xinference 管理模型注册、virtualenv 隔离和服务生命周期，可以选择 Xinference 路径。请确认使用的 Xinference 版本或 commit 包含 xorbitsai/inference#5140；该更新把 Fun-ASR-Nano model spec 从旧的 FunASR git SHA 改为打包发布的 funasr~=1.3.0 依赖。首次评估 FunASR，或需要面向 Agent 的 OpenAI 兼容转写接口时，仍建议先从上面的 FunASR 原生 OpenAI API 示例开始。

我想要可复现的容器 demo

在 FunASR 仓库根目录，准备好 Docker Engine 和 Docker Compose 插件后，启动本地 SenseVoice CPU 服务。这条命令不会覆盖已有 .env，显式设置会在本次启动中覆盖环境里遗留的端口、设备和模型值。主机端口仅绑定 loopback，不是鉴权网关；共享前先阅读安全与网关指南。

FUNASR_HOST_PORT=127.0.0.1:8000 FUNASR_DEVICE=cpu FUNASR_MODEL=sensevoice \
  docker compose -f examples/openai_api/docker-compose.yml up --build

保持该终端中的 Compose 运行。打开第二个终端，仍位于同一仓库根目录，使用 Python 3.10 或更高版本运行；smoke 客户端仅依赖标准库，不需要在主机安装 FunASR：

python3 examples/openai_api/smoke_test.py --base-url http://127.0.0.1:8000 --model sensevoice --response-format verbose_json

客户端仅在当前目录不存在 sample.wav 时下载公开中文样本，已有文件会被复用。它打印 health、模型 metadata 和转写 JSON；请自行检查文本，退出码成功不代表识别质量或并发验收。客户端不发送 Authorization，安全指南的仅转写网关会拒绝该 smoke 使用的 metadata 路由。请通过本地端点运行，避免保留敏感音频和未脱敏输出。

CPU 镜像复制 example 服务，但从 PyPI 安装 FunASR，依赖环境未锁定。声称可复现前，请记录实际包版本和镜像 digest。单独修改 FUNASR_DEVICE 不会增加 CUDA 依赖或容器 GPU 访问能力；GPU 镜像与调度需要另外准备和验证，参见完整 HTTP 部署指南及所选模型的服务要求。

我想部署集群内服务

使用 Kubernetes 模板 部署私有 ClusterIP OpenAI 兼容 API，包含持久化模型缓存、/health probes 和 port-forward smoke test 路径。在没有 CUDA-capable 镜像和集群 GPU 调度前，请保持默认 CPU 模式。

我需要流式识别或实时字幕

使用 Runtime WebSocket 服务。上线前请用真实音频验证 chunk size、VAD、断句、标点、说话人分离、重连行为和客户端背压。

我已有高并发 ONNX，但需要热词

不要只因为当前 CPU ONNX/C++ 实时链路缺少热词，就把整条已经跑稳的链路迁到 GPU 大模型。先确认产品里的“热词”到底是哪一种：

  • 如果是公司名、产品名、专有名词或固定误识别纠错，优先保留 ONNX 链路，在最终文本上做确定性后处理。这样能保留已经验证过的 CPU 并发能力，也更容易审计。
  • 如果必须在解码阶段影响识别，或者确实存在多语言/语义理解上的质量缺口，再测试 Fun-ASR-Nano、Qwen3-ASR 等 GPU 路径；但要按首包延迟、尾包延迟、音频切片长度、VAD 策略和同时说话路数重新压测。
  • 如果两类需求都有，只在 GPU 模型质量或语言覆盖明显更好的流量上使用 GPU，其他高吞吐稳定流量继续走 ONNX。

开部署 issue 时，请附上当前 ONNX 并发、CPU 核数、目标热词、可接受端到端延迟、GPU 型号、模型启动命令，以及热词是“识别后纠错”还是“解码阶段偏置”。

我需要更高的 LLM-based ASR 吞吐

Fun-ASR-Nano 走 vLLM 路径。请用自己的音频分布做 benchmark，并关注 GPU 显存、tensor parallel size、首 token 延迟和 warmup 时间。

我想在昇腾 NPU 上跑 Fun-ASR-Nano

Fun-ASR-Nano 的 LLM-based 路径目前主要按 CUDA/vLLM、标准 PyTorch CPU/GPU，以及 CPU/边缘 GGUF runtime 记录和验证；Ascend NPU（torch_npu）仍不是这个模型的官方生产运行时。不要因为 SenseVoice 或 Paraformer 能在 NPU 上跑，就默认 Fun-ASR-Nano 也能直接跑通，因为 Nano 还会经过 Qwen 解码器、inputs_embeds，以及后端相关的 autocast / 算子路径。

#3034 里的社区复测表明：修复 autocast device 之后，PyTorch AutoModel(..., device="npu:*") 路径已经能进入 NPU 后端，并在 310P3、torch_npu 2.5.1、CANN 8.5.1 环境里产出正确文本。但该 smoke run 明显慢于 CPU（NPU rtf_avg 约 124，CPU 约 1.9），所以这只能作为兼容性证据，不是性能推荐。同一报告里，AutoModelVLLM + vllm_ascend 0.9.2rc1 仍在 Qwen3 rotary embedding / TransData 算子支持处失败；这条路径应按 vLLM-Ascend runtime / 算子兼容问题继续排查，并建议带 ASCEND_LAUNCH_BLOCKING=1 复现日志。

如果你正在适配这个后端，请保持第一版范围很小：先从 torch.bfloat16 开始，记录 torch / torch_npu / CANN / 驱动 / NPU 型号，把 PyTorch AutoModel 和 AutoModelVLLM 分开验证，并在 PR 或 deployment issue 里附上最小命令和完整 stack trace。

上线检查清单

  • 选择模型 alias，并写入部署说明。
  • 记录 FunASR 版本、模型版本、设备、CUDA/PyTorch 版本、Docker 镜像 tag 和启动命令。
  • 跑一个公开短音频 smoke sample，再跑至少一个真实私有样本。
  • 每次请求记录音频时长、模型、设备、延迟、响应格式和错误类型。
  • API 暴露到可信网络外之前，增加上传大小限制、鉴权、TLS 和限流；可用 安全与网关指南 规划边界。
  • 热词或纠错需求要先记录它是确定性后处理，还是解码阶段偏置；替换已有 runtime 前同时 benchmark 质量和延迟。
  • 流式场景需要测试静音、噪声、多人重叠、长连接、重连和慢客户端。
  • 发布 benchmark 结论时，说明输入时长、硬件、batch size、模型、运行路径，以及是否排除模型下载和 warmup 时间。

什么时候开 issue

Runtime、Docker、vLLM、Triton、Android、浏览器或 Agent 集成问题，请使用 Deployment Help。请附上部署路径、完整命令/config、日志、模型、设备和音频特征。