FunASR 实战选型指南：从评估、部署到 Agent 集成的完整用例路径

FunASR 实战选型指南：从评估、部署到 Agent 集成的完整用例路径

【免费下载链接】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 的能力远不止一条离线转写命令。这篇指南以仓库中的 use_case_showcase.md 为核心脉络，系统梳理了在真实产品中评估、部署、集成语音理解的各类使用场景：从浏览器快速体验、本地单文件转写、私有语音 API、流式服务，到 Agent 语音输入、字幕生成与批量转写。读完本文，你将能根据目标场景快速锁定最短可行的技术路径，掌握每条路径的关键命令、配置参数与验证方法，并理解其底层实现原理。

选择正确的路径：先看目标，再选入口

不同目标对应不同的最短路径。下表整理了 FunASR 官方推荐的场景入口，避免在无关环节上浪费时间：

这些入口之间存在明确的分层关系：先通过 Colab 或 Python API 验证“能不能用”，再根据延迟、吞吐与集成需求决定“怎么部署”，最后才考虑 vLLM、Triton 这类重型运行时。

生产导向的实战配方

私有转写 API：让应用直接复用 OpenAI 风格客户端

当应用已经会说 OpenAI 风格的 API，或者音频不能离开你的环境时，私有转写 API 是最短路径。安装依赖并启动服务：

pip install funasr fastapi uvicorn python-multipart funasr-server --model sensevoice --device cuda

然后用 curl 完成一次转写验证：

curl http://localhost:8000/v1/audio/transcriptions \ -F file=@sample.wav \ -F model=sensevoice \ -F response_format=verbose_json

推荐下一步：

• 运行 OpenAI 兼容 API 冒烟测试脚本 或跨平台的 Python 冒烟测试，验证健康检查、模型列表与转写输出。
• 需要浏览器上传或麦克风演示，从 Gradio 浏览器 Demo 开始。
• 服务是 Node.js 或 Next.js 项目，参考 JavaScript/TypeScript 配方。
• 集群级服务，从 Kubernetes 部署模板 开始。
• 对外提供服务前，务必在服务边界补充鉴权与网络控制，参考 安全与网关指南。
• 提交 Bug 与基准数据时，记录模型名、设备、驱动与音频时长。

底层实现要点（源码依据：examples/openai_api/server.py）：

示例服务的启动参数在 server.py 的 main() 中定义：

需要特别留意“接口边界”：示例服务预加载模型与省略 multipartmodel字段时的默认值均为sensevoice；而打包的funasr-server在--model auto时会根据设备字符串选择fun-asr-nano（cuda 开头）或sensevoice，省略 multipartmodel时默认fun-asr-nano。因此每次请求都应显式指定model，并以实际运行服务的/v1/models为准，不能只依赖仓库中的示例规范。

response_format=verbose_json只选择响应格式，不会启用说话人分离，也不会强制生成时间戳。示例仅在模型返回sentence_info时才将其转换为segments，否则返回segments=[]；说话人标签可能缺失或为 null。另外，示例返回的duration是generate()调用的耗时（不含首次模型加载），不是音频时长；打包服务 verbose 响应中的duration才是秒单位的音频时长。两套服务不能互换性能结论与 JSON 字段假设。

示例服务的端点如下：

Docker 部署时使用环境变量（默认镜像以 CPU 模式启动）：

从仓库根目录执行FUNASR_HOST_PORT=127.0.0.1:8000 docker compose up --build（位于examples/openai_api目录）即可启动回环地址绑定的本地服务；GPU 环境需要 NVIDIA Container Toolkit 与 CUDA-capable 镜像。

Agent 语音输入：把本地 ASR 变成工具

当你想对编码 Agent、内部助手或工作流工具说话时，走 Agent 语音输入路径：

• 面向 Claude/Cursor 风格工具，从 MCP 服务器示例 开始。它以 SenseVoiceSmall 提供本地音频转写工具，pip install funasr即可安装，可通过 Docker 以 stdio 方式运行（docker build -t funasr-mcp examples/mcp_server），工具名为transcribe_audio。
• 桌面语音输入实验，用 语音输入示例。它实现“按快捷键 → 录音 → 再按快捷键 → 发送到 funasr-server → 识别 → 自动粘贴到光标位置”的完整流程，支持 macOS（AppleScript 自动粘贴）、Linux（xdotool）与 Windows（手动 Ctrl+V），内部统一使用 WAV 16kHz。配置项包括--server（默认http://localhost:8000/v1）、--model（默认 sensevoice）、--hotkey与--lang。
• 保持延迟可见：为每个请求记录音频时长、处理时间与所选模型。

流式与呼叫中心负载

当部分结果和低感知延迟比单一最终转写更重要时：

• 从 Runtime 服务文档 开始，选择模型与协议后再选容器或二进制。C++ 两遍（two-pass）流式与 Fun-ASR-Nano Python 流式是不同实现，需分别按各自协议（如 websocket_protocol.md）验证。
• 当转写结果需要人读时，把 ASR 与 VAD、标点、说话人分离搭配使用。
• 用真实音频验证：背景噪声、长静音、说话人重叠、不同的麦克风质量；并验证分块大小、VAD、断句（endpointing）、重连与客户端背压。

迁移 Whisper 前先做基准

当你在判断 FunASR 是否值得替换 Whisper 或云 ASR 提供商时：

• 按迁移指南映射功能并评测代表性音频。迁移指南建议挑选 20–50 个覆盖短片段、长录音、噪声、不同说话人与目标语言/方言的代表性文件，分别跑旧流水线与 FunASR，用 WER/CER 或人工评审对比，而不是只对比单个干净的 Demo 文件。
• 在自有样本集上做基准，同时包含短片段与长录音；记录暖机时间、模型下载时间、设备、GPU/CPU 类型、batch size 与稳态吞吐分开统计。
• 成本与吞吐一起跟踪：GPU 速度、CPU 可行性、模型下载大小与部署复杂度。

仓库提供了可复现的迁移基准工具：examples/migration/benchmark_funasr.py 可对指定音频目录输出results.jsonl与summary.md。从源码结构看，该脚本面向文件夹级批量评测，适合在自有数据集上生成可引用的对比结果。

模型选择提示：不同需求的第一个选择

深度对比 SenseVoice、Paraformer、Fun-ASR-Nano、流式 Runtime 与 OpenAI API 别名，请查阅模型选择指南。快速参考：

OpenAI API 别名与底层模型（源码依据：examples/openai_api/server.py 的MODEL_CONFIGS）：

• sensevoice：iic/SenseVoiceSmall+ FSMN-VAD，多语种 HTTP 转写，返回文本会去除<|...|>富文本标签。
• paraformer：paraformer-zh+ FSMN-VAD + CT 标点，面向中文的路线。
• paraformer-en：paraformer-en+ FSMN-VAD，OpenAI 风格客户端中的英文路线（示例服务专有别名）。
• fun-asr-nano：FunAudioLLM/Fun-ASR-Nano-2512，覆盖中、英、日与中文方言/口音评估；示例服务不使用 vLLM，CTC 时间戳依赖完整 checkpoint 权重。
• moss-transcribe-diarize：第三方OpenMOSS-Team/MOSS-Transcribe-Diarize，离线转写 + 匿名说话人标签，需要独立依赖环境，且不能外挂 VAD 或说话人模型。

这些别名描述的是示例服务，不自动选择AutoModelVLLM或原生 vLLM；打包的funasr-server有独立的加载器与后端选择逻辑，不要在未核对对应 HTTP 指南 的情况下在两套服务间复制别名或性能结论。别名出现在/v1/models中，也不代表其依赖及权重已经就绪。

需要原始情感/事件标签时，verbose_json不会恢复它们；请使用 Python SDK 并保留返回的text，参考 原始标签配方。

部署路径的快速决策

部署矩阵 给出了“先最小化再重型”的选择原则：

容器冒烟测试的一条便捷命令（Python 3.10+，仅依赖标准库）：

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

该客户端仅在缺少sample.wav时才下载公开中文样例，会打印健康状态、模型元数据与转写 JSON；注意退出码为 0 只代表请求成功，不代表识别质量或并发能力。

批量转写与字幕生成：媒体工作流的两大利器

批量 ASR 脚本

examples/batch_asr_improved.py 面向归档、会议与数据集构建，使用 argparse 提供完整命令行配置：

从源码实现看，脚本对每个文件单独调用model.generate(input=str(fpath), language="auto")，并用rich_transcription_postprocess清理富文本标签；单文件失败不会中断整个批次（错误会写入输出），输出目录缺失时会自动创建。生产环境还应补充队列、清单与重试日志。

字幕生成

examples/subtitle/generate_subtitle.py 把长音频或视频转为 SRT/VTT 字幕：

python generate_subtitle.py input.mp4 python generate_subtitle.py input.wav --format vtt python generate_subtitle.py meeting.mp3 --spk # 带说话人标签

其核心参数包括--format（srt/vtt，默认 srt）、--segment-mode（readable按可读性分句或sentence按模型原始句界）、--model（默认iic/SenseVoiceSmall）、--device（默认cuda）与--max-single-segment-time（默认 60000 ms）。源码内部从funasr.cli复用_sentence_timestamp_words与merge_subtitle_segments完成句子时间戳与分段合并，时间戳同时兼容timestamp与timestamps两种返回字段（字典或列表形式），对可读性要求高的场景还可利用说话人标签。

分享你的成果

如果 FunASR 在你的项目中工作良好，可以发起 showcase issue、Migration Benchmark Report 或 GitHub Discussion，并附上：

• 使用场景与部署模式。
• 模型、设备与处理速度。
• 音频领域、语言与大致时长。
• 可用的公开 Demo、截图、基准摘要或集成链接。

具体的使用报告既帮助新用户选择正确的路径，也帮助维护者确定下一轮文档与示例的优先级。提交部署类问题时，记得附上部署路径、确切命令/配置、日志、模型、设备与音频特征，参考故障排查文档的清单逐项核对，可显著提高问题被定位与解决的速度。

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