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/FunASRFunASR 的能力远不止一条离线转写命令。这篇指南以仓库中的 use_case_showcase.md 为核心脉络系统梳理了在真实产品中评估、部署、集成语音理解的各类使用场景从浏览器快速体验、本地单文件转写、私有语音 API、流式服务到 Agent 语音输入、字幕生成与批量转写。读完本文你将能根据目标场景快速锁定最短可行的技术路径掌握每条路径的关键命令、配置参数与验证方法并理解其底层实现原理。选择正确的路径先看目标再选入口不同目标对应不同的最短路径。下表整理了 FunASR 官方推荐的场景入口避免在无关环节上浪费时间目标从哪里开始为什么重要在浏览器里体验 FunASRColab 快速上手无需搭建本地环境先跑公开样例、上传自己的音频做验证本地转写单个文件README 快速开始 与 模型选择指南几分钟内完成安装、选型与模型下载的验证对比准确率与速度历史基准 与 当前评测方法先读历史结果及其出处限制再在本地音频上实测选型从 Whisper / 云 ASR 迁移迁移指南映射现有流水线、评测代表性音频、规划安全上线构建私有语音 APIOpenAI 兼容 API 示例、Gradio 浏览器 Demo、客户端配方、JavaScript/TypeScript 配方、工作流配方复用 LangChain、Dify、n8n、AutoGen 等 OpenAI 风格客户端音频不出本地复用已有集成社区集成项目从已验证的上游路径起步语音 Agent、本地助手、桌面字幕、模型服务、Rust VAD为 Agent 增加语音输入MCP 服务器 与 语音输入将本地 ASR 接入 Claude、Cursor 与桌面 Agent 工作流选择部署路径部署矩阵横向对比 Python API、OpenAI API、Docker Compose、Kubernetes、WebSocket、vLLM、MCP、批量、字幕与 Triton提供流式 ASR 服务Runtime 服务文档用 WebSocket 或服务模式支撑实时字幕、呼叫中心类负载加速 LLM 类 ASRvLLM 指南为 Fun-ASR-Nano 提供张量并行解码与流式服务支持生成字幕字幕示例把长音频或视频转成字幕文件服务媒体类工作流批量处理大量录音批量 ASR 示例为归档、会议与数据集构建可重复的离线任务这些入口之间存在明确的分层关系先通过 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 filesample.wav \ -F modelsensevoice \ -F response_formatverbose_json推荐下一步运行 OpenAI 兼容 API 冒烟测试脚本 或跨平台的 Python 冒烟测试验证健康检查、模型列表与转写输出。需要浏览器上传或麦克风演示从 Gradio 浏览器 Demo 开始。服务是 Node.js 或 Next.js 项目参考 JavaScript/TypeScript 配方。集群级服务从 Kubernetes 部署模板 开始。对外提供服务前务必在服务边界补充鉴权与网络控制参考 安全与网关指南。提交 Bug 与基准数据时记录模型名、设备、驱动与音频时长。底层实现要点源码依据examples/openai_api/server.py示例服务的启动参数在 server.py 的 main() 中定义参数默认值说明--host0.0.0.0监听地址--port8000监听端口--devicecudacuda、cpu或mps--modelsensevoice启动时预加载的模型需要特别留意“接口边界”示例服务预加载模型与省略 multipartmodel字段时的默认值均为sensevoice而打包的funasr-server在--model auto时会根据设备字符串选择fun-asr-nanocuda 开头或sensevoice省略 multipartmodel时默认fun-asr-nano。因此每次请求都应显式指定model并以实际运行服务的/v1/models为准不能只依赖仓库中的示例规范。response_formatverbose_json只选择响应格式不会启用说话人分离也不会强制生成时间戳。示例仅在模型返回sentence_info时才将其转换为segments否则返回segments[]说话人标签可能缺失或为 null。另外示例返回的duration是generate()调用的耗时不含首次模型加载不是音频时长打包服务 verbose 响应中的duration才是秒单位的音频时长。两套服务不能互换性能结论与 JSON 字段假设。示例服务的端点如下EndpointMethod说明/v1/audio/transcriptionsPOSTOpenAI 兼容音频转写/v1/modelsGET列出模型别名/healthGET健康检查、已加载模型和可用模型/docsGETFastAPI Swagger 文档Docker 部署时使用环境变量默认镜像以 CPU 模式启动Env默认值说明FUNASR_PORT8000传给server.py的容器端口FUNASR_DEVICEcpu容器设备模式只有镜像已适配 CUDA 时才设为cudaFUNASR_MODELsensevoice容器启动时加载的模型别名从仓库根目录执行FUNASR_HOST_PORT127.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 → 识别 → 自动粘贴到光标位置”的完整流程支持 macOSAppleScript 自动粘贴、Linuxxdotool与 Windows手动 CtrlV内部统一使用 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 别名请查阅模型选择指南。快速参考需求首选备注快速多语种转写SenseVoice-Small本地 Demo 与私有 API 的稳妥默认非自回归、CPU 可行中文生产 ASRParaformer-Large中文语音识别的成熟选择LLM 类 ASR 实验Fun-ASR-Nano追求吞吐时搭配 vLLM 指南带说话人信息的转写SenseVoice 或 Paraformer 搭配spk_modelcam适合会议、访谈与客户通话离线长音频、说话人标注的完整转写MOSS-Transcribe-Diarize一次离线请求返回转写、时间戳与单段录音内匿名说话人标签不是实时 WebSocket 路径实时音频Runtime WebSocket 服务用真实流量验证分块、VAD 与断句OpenAI API 别名与底层模型源码依据examples/openai_api/server.py 的MODEL_CONFIGSsensevoiceiic/SenseVoiceSmall FSMN-VAD多语种 HTTP 转写返回文本会去除|...|富文本标签。paraformerparaformer-zh FSMN-VAD CT 标点面向中文的路线。paraformer-enparaformer-en FSMN-VADOpenAI 风格客户端中的英文路线示例服务专有别名。fun-asr-nanoFunAudioLLM/Fun-ASR-Nano-2512覆盖中、英、日与中文方言/口音评估示例服务不使用 vLLMCTC 时间戳依赖完整 checkpoint 权重。moss-transcribe-diarize第三方OpenMOSS-Team/MOSS-Transcribe-Diarize离线转写 匿名说话人标签需要独立依赖环境且不能外挂 VAD 或说话人模型。这些别名描述的是示例服务不自动选择AutoModelVLLM或原生 vLLM打包的funasr-server有独立的加载器与后端选择逻辑不要在未核对对应 HTTP 指南 的情况下在两套服务间复制别名或性能结论。别名出现在/v1/models中也不代表其依赖及权重已经就绪。需要原始情感/事件标签时verbose_json不会恢复它们请使用 Python SDK 并保留返回的text参考 原始标签配方。部署路径的快速决策部署矩阵 给出了“先最小化再重型”的选择原则工作负载Runtime 路径备注Notebook 或一次性评估PythonAutoModel安装、下载、输出形状检查的最短路径内部 HTTP 服务OpenAI 兼容 API复用 OpenAI 风格客户端、Dify、n8n、LangChain、AutoGen可重复的本地容器 DemoDocker Compose API默认 CPU使用 CUDA 前需适配镜像内部集群服务Kubernetes API 模板私有ClusterIP、持久化模型缓存、/health探针、port-forward 冒烟测试实时音频Runtime WebSocket 服务用真实音频验证分块、VAD、断点、重连与背压LLM 类 ASR 吞吐split-engine 或原生 vLLM匹配 checkpoint、加载 API 与测试环境不是 Paraformer 后端容器冒烟测试的一条便捷命令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 提供完整命令行配置参数默认值说明--input-folder/-iexamples/audio_samples音频目录--output-file/-oexamples/batch_transcriptions.txt输出文本文件--model/-mparaformer-zh可选paraformer-zh、paraformer-en、SenseVoiceSmall等--device/-dcpu推理设备--recursive/-r关递归扫描子目录--extensions/-e.wav .mp3接受的音频扩展名--vad-modelfsmn-vad设为none可禁用 VAD从源码实现看脚本对每个文件单独调用model.generate(inputstr(fpath), languageauto)并用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 # 带说话人标签其核心参数包括--formatsrt/vtt默认 srt、--segment-modereadable按可读性分句或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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考