FunASR 应用选型实战：音频剪辑、实时语音识别与语音对话的完整落地指南

FunASR 应用选型实战音频剪辑、实时语音识别与语音对话的完整落地指南【免费下载链接】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 官方参考文档《Speech Applications》为骨架围绕先选应用场景、再选模型与服务契约的核心方法论展开系统讲解音频剪辑Audio Cut、实时语音识别Realtime Speech Recognition、语音对话Audio Chat三大应用方向的选型依据、部署路径与底层原理。读完本文你将掌握如何借助 FunClip 与 MOSS-Transcribe-Diarize 完成带说话人标签的音频/视频剪辑如何基于原生 C WebSocket 服务与实时基准方法学评估低延迟识别以及如何通过 OpenAI 兼容 HTTP 服务把 FunASR 接入 Dify、n8n、LangChain 等 Agent 工作流。应用先行先选场景再选模型与服务契约FunASR 是一个覆盖训练、推理、流式识别、VAD、标点、说话人分离与 OpenAI 兼容/MCP 服务的开源语音工具包。面对如此多的模型与服务形态最容易犯的错误是先选模型再想用途。官方参考文档 docs/reference/application.md 给出的核心方法论非常明确Choose the application first, then select its model and serving contract.先选应用再选模型与对外服务契约。也就是说落地一个语音产品时第一步应当明确这个应用到底要完成什么任务——是剪辑、实时转写还是对话交互——再根据任务性质决定使用哪条推理路径、暴露哪种服务接口。三条已维护的落地路径分别对应三大类应用应用方向典型任务首选技术路径Audio Cut音频剪辑基于转写稿剪辑音频/视频、按说话人切分片段FunClip MOSS-Transcribe-DiarizeRealtime Speech Recognition实时识别实时字幕、会议/呼叫中心流式转写原生 C WebSocket 服务 实时基准方法学Audio Chat语音对话Agent 工作流中的文件/句子转写OpenAI 兼容 Python HTTP 服务 工作流集成更丰富的场景速查可参考 docs/use_case_showcase.md按目标给出去处与理由与 docs/community_projects.md社区已验证的第三方集成清单部署形态的横向对比见 docs/deployment_matrix.md。场景一音频剪辑Audio Cut转写驱动的剪辑与说话人归属两条互补的剪辑路径音频剪辑的核心需求是找到音频里说了什么、谁在什么时候说的再据此切分素材。官方文档给出两条路径FunClip转写驱动的音频/视频剪辑工具适合按文本内容定位并裁剪片段MOSS-Transcribe-Diarize面向带说话人归属的录音一次推理同时产出转写文本、时间戳、匿名说话人标签如[S01]无需外部 VAD/说话人分离流水线。MOSS 说话人标签的语义边界必须理解MOSS 输出的标签是录音内匿名的[S01]不代表某个已知人物的真实身份不验证已登记的声纹也不保证与另一段录音中的[S01]是同一人。在对接字幕、会议纪要或剪辑逻辑时切勿把标签当做人名或跨录音身份 ID 使用。另一个工程要点接入 MOSS 前必须核对所选 FunClip 版本及其后端不能假设每个 ASR 选项的输出字段一致例如时间戳粒度、标签字段命名否则下游剪辑逻辑会拿不到预期字段。FunASR AutoModel 契约一次生成转写 时间戳 说话人MOSS 是 OpenMOSS 发布的 Apache-2.0 第三方模型非 FunASR 自研模型FunASR 为其提供适配层保留原始模型名、许可证与上游版本。在本地 Transformers 后端下调用方式如下docs/moss_transcribe_diarize.mdfrom funasr import AutoModel model AutoModel( modelOpenMOSS-Team/MOSS-Transcribe-Diarize, model_revisione8681d68e7042738ffca8ac8212bc8fcb1131ab8, backendhf, devicecuda:0, dtypebf16, attn_implementationsdpa, disable_updateTrue, ) result model.generate(audio.wav, max_new_tokens5120)[0] print(result[text]) for segment in result[sentence_info]: print(segment[start], segment[end], segment[spk], segment[text])关键约束MOSS 在同一轮生成中完成长音频转写与说话人分离因此严禁传入vad_model或spk_model——外部 VAD 切分会破坏跨 chunk 的匿名说话人一致性。适配层保留原始带标签生成在raw_text同时返回 FunASR 通用字段源码 funasr/auto/auto_model.py 中generate的结果注释确认了这些字段text去掉 MOSS 控制标签后的可读转写timestamp段级[start_ms, end_ms]时间对sentence_info每段的start、end、text、sentence、spk、timestampraw_text供审计的精确[start][Sxx]text[end]原始生成。安全设计上如果解析器无法证明标签结构成立它会把模型文本原样留在text与raw_text并返回空的时间戳/分段数组绝不臆造说话人元数据——这是值得在对接时专门做一次负向测试的失败模式。同样的结果契约还可以包装一个已运行的 vLLM 服务无需下载本地权重from funasr import AutoModel model AutoModel( modelOpenMOSS-Team/MOSS-Transcribe-Diarize, backendvllm, vllm_base_urlhttp://127.0.0.1:8898/v1, vllm_modelmoss-transcribe-diarize, vllm_response_formatdiarized_json, disable_updateTrue, ) result model.generate(audio.wav, max_completion_tokens8192)[0]服务化与容器化落地内置离线 HTTP 服务把同一规范化结果通过/v1/audio/transcriptions暴露出来加载固定版本的 Transformers 模型且不挂外部 VAD/说话人模型python -m pip install transformers5.6,6 fastapi uvicorn python-multipart funasr-server --model moss-transcribe-diarize --device cuda:0 --port 8000 curl -fsS http://127.0.0.1:8000/v1/audio/transcriptions \ -F filemeeting.wav \ -F modelmoss-transcribe-diarize \ -F response_formatverbose_json响应包含text、音频duration以及带start/end/text/匿名speaker的segments。请求不需要spktrue即使通用客户端传了该字段服务仍使用 MOSS 原生标签不会启动第二条分离流水线。MOSS 是离线长文模型不会被 FunASR 的实时 WebSocket 服务暴露请用 HTTP 端点处理完整文件FunClip 消费的是同一个sentence_info契约来做说话人感知的字幕与剪辑。可复现的 GPU 容器可从仓库根目录用examples/openai_api/docker-compose.moss.yml构建Kubernetes 操作者可构建同名镜像并应用examples/openai_api/kubernetes/funasr-moss-api.yaml上线前把本地镜像引用替换为仓库里的不可变 digest。场景二实时语音识别Realtime Speech Recognition协议、消息状态与延迟度量先看部署矩阵再选运行时实时识别与离线转写的选型逻辑完全不同。官方文档建议从 docs/deployment_matrix.md 和 runtime/docs/websocket_protocol.mdWebSocket/gRPC 通信协议入手。矩阵中与实时/流式相关的路径包括Runtime WebSocket 服务适合实时字幕、会议、呼叫中心流关注部分结果partial results、端点检测endpointing与长连接流ONNX/C 运行时高并发 CPU 服务或嵌入式实时 ASR适合延迟/并发已被验证的场景vLLM 加速Fun-ASR-Nano 的文件转写或分流引擎解码不适用于非自回归的 Paraformer。一个必须强调的边界Python vLLM preview 会话与原生 C 流式服务使用不同的消息与状态迁移客户端不可互换。上线前务必用真实音频验证 chunk 大小、VAD、端点检测、标点、说话人分离、断线重连与客户端背压。原生 WebSocket 协议offline / online / 2pass 三种模式协议文档runtime/docs/websocket_protocol.md明确了配置参数与元信息走 JSON、音频数据走二进制字节的混合消息格式离线文件转写offline初始化消息{mode: offline, wav_name: wav_name, wav_format:pcm, is_speaking: True, hotwords:{阿里巴巴:20,通义实验室:30}, itn:True}实时识别2pass初始化消息{mode: 2pass, wav_name: wav_name, is_speaking: True, wav_format:pcm, chunk_size:[5,10,5],hotwords:{阿里巴巴:20,通义实验室:30},itn:true}关键参数语义参数含义modeoffline单句识别online实时识别2pass实时识别 句尾离线模型纠正wav_name待转写音频名wav_format音频/视频扩展名pcm、mp3、mp4 等1.0 版实时流仅支持 PCMis_speakingFalse表示一句话结束VAD 切分点或 WAV 文件末尾chunk_size流式模型延迟配置[5,10,5]表示当前音频 600ms含 300ms 前瞻与回看audio_fsPCM 输入时需指定采样率参数hotwords热词数据字符串如{阿里巴巴:20,通义实验室:30}itn是否启用逆文本正则化默认 truePCM 格式直接发送音频数据其他格式需连同头信息一起发送。发送完毕后必须发送结束标志{is_speaking: False}。服务端返回消息中2pass-online表示实时识别结果、2pass-offline表示 2-pass 纠正结果时间戳模型会返回timestamp如[[100,200], [200,500]]与stamp_sents字段。MOSS 不是流式模型的澄清MOSS 适合长文转写/分离但不是原生低延迟流式模型的替代品分块上传接收音频并不等于底层模型具备流式识别能力。如果产品需要实时字幕或逐字输出应选择 WebSocket 服务而非 MOSS。用实时基准方法学度量端到端延迟离线RTFx与实时服务延迟是两回事。官方实时基准docs/benchmark/realtime_ws_benchmark.md聚焦首条更新延迟、STOP 后最终延迟、响应滞后与多客户端行为基准客户端只接受 16kHz 单声道 PCM16 WAV 输入以排除重采样与文件解码对测量的干扰。启动服务建议有界部分结果窗口 适中的部分刷新间隔CUDA_VISIBLE_DEVICES0 python examples/industrial_data_pretraining/fun_asr_nano/serve_realtime_ws.py \ --port 10095 --language 中文 \ --partial-window-sec 8 --decode-interval 0.8 \ --vad-device cpu --vad-ncpu 1 \ --decode-batch-wait-ms 10 --decode-max-batch-size 16 \ --log-decode-profile说明说话人分离默认关闭只有确实需要spk字段时才加--enable-spk并在结果中注明该设置落在--decode-batch-wait-ms窗口内的兼容跨会话解码会合并为一个引擎 batch对比版本时必须保持所有 batching 参数一致。单客户端实时回放按真实时间速度发送 100ms 帧最接近麦克风/浏览器流python examples/industrial_data_pretraining/fun_asr_nano/realtime_ws_benchmark.py \ audio_16k_mono_pcm16.wav \ --server ws://localhost:10095 \ --clients 1 \ --output-jsonl realtime_ws_1c.jsonl并发回放python examples/industrial_data_pretraining/fun_asr_nano/realtime_ws_benchmark.py \ audio_16k_mono_pcm16.wav \ --server ws://localhost:10095 \ --clients 8 \ --loops 3 \ --chunk-ms 100 \ --client-ping-interval 20 \ --client-ping-timeout 0 \ --language 中文 \ --output-jsonl realtime_ws_8c.jsonl0表示禁用对应客户端 ping 设置--no-pace为非定速压力测试其结果是吞吐压力信号而非面向用户的实时延迟。核心指标指标含义aggregate_audio_per_wall所有客户端总输入音频秒数 ÷ 基准墙钟时间first_update_ms_p50/p95从首帧音频到首个含sentences/partial/is_final结果消息的耗时final_after_stop_ms_p50/p95从发送STOP到收到最终结果的耗时client_response_lag_ms_p95_max各客户端 p95 中最大的非最终响应滞后定速模式下用于观察预览/部分结果滞后partial_messages/final_messages非最终部分结果 / 最终结果消息计数errors连接、超时、协议或客户端校验错误基准脚本只能观测客户端侧时序与服务端返回字段。做性能排查时应加--log-decode-profile让每次引擎调用输出一行结构化日志请求/样本数、音频时长范围、队列等待 p50/max、引擎总延迟并配合 GPU 利用率与服务端日志一起分析。注意一个阻塞了 WebSocket 事件循环的服务可能显得更快——因为它处理的部分解码更少这不是引擎吞吐提升用户获得的下发更新也更少。官方仓库还给出了 v1.4.3 与引入并发解码批处理默认值后的回归参考12/16 客户端、47 秒循环中文录音、定速 100ms 帧、单 H100 80GB显示批处理后final_after_stop与响应滞后大幅下降。该数据只是回归参考不是普适容量承诺长语音段会产生同步且昂贵的最终解码不代表所有会议或语音 Agent 负载形态。发布基准或提交 issue 时请按报告模板记录数据音频时长/采样率/语言/静音比、负载--clients/--loops/--chunk-ms/定速与否/ping 参数、服务完整命令与全部--参数、硬件GPU 型号/驱动/CUDA/CANN与软件版本funasr/PyTorch/torchaudio/vLLM/Python/OS。场景三语音对话Audio Chat把 FunASR 接入 Agent 工作流场景定位识别是组件对话是组合在 Agent 工作流中做文件或句子的转写时官方文档指向 examples/openai_api/README.mdPython HTTP 服务与 examples/openai_api/WORKFLOWS.md工作流集成指南。这里有一条重要的架构边界FunASR 只提供识别speech recognition对话生成、语音合成、轮次管理turn-taking与打断处理是独立的应用组件。上线前必须联合验证组合延迟与隐私要求——识别快了 100ms如果下游 LLM 与 TTS 链路慢 2 秒用户体验仍然由最慢环节决定。快速启动一个 OpenAI 兼容转写服务在干净 checkout 与 Python 3.11 环境examples/openai_api/README.md 提供完整步骤下python -m venv .venv source .venv/bin/activate python -m pip install -e . python -m pip install fastapi uvicorn python-multipart python -m pip check cd examples/openai_api python server.py --host 127.0.0.1 --model sensevoice --device cpu --port 8000该命令固定的是源码而非依赖、模型权重或 CUDA有 CUDA 能力后用--device cuda替换且不要在同一端口启动两个服务。等待模型加载完成后再检查GET /health健康检查本身不能证明声学推理正确。curl 转写curl http://localhost:8000/v1/audio/transcriptions \ -F fileaudio.wav \ -F modelsensevoice \ -F response_formatverbose_jsonOpenAI Python SDK 用法from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keynot-needed) with open(meeting.wav, rb) as audio: result client.audio.transcriptions.create(modelsensevoice, fileaudio) print(result.text)API 契约的关键差异示例服务 vs 打包服务仓库中examples/openai_api/server.py的实现与 PyPI 打包的funasr-serverfunasr/bin/_server_app.py 对应的不同实现在契约上存在多处差异对接前务必核对response_formatverbose_json只是选择响应形态不会启用说话人分离或强制生成时间戳源码 examples/openai_api/server.py 的MODEL_CONFIGS中SenseVoice 别名未配置外部spk_model示例服务的duration是generate()的墙钟耗时不含首次模型加载不是音频时长打包服务的duration是音频时长元数据缺失时可能为 0两边的start/end都使用秒示例服务把模型自带的sentence_info拷贝进segments否则返回segments[]而打包服务可通过文本与音频时长合成粗粒度分段——那不是词级强制对齐示例服务接受file、model、language、response_format表单字段SDK 选项use_itn、热词、原始数组、spk不是它的表单字段请求中显式指定model启动预加载与请求默认值是两套设置示例服务启动与缺省 multipartmodel均默认sensevoice打包服务则按设备字符串选择fun-asr-nano/sensevoice。模型别名docs/model_selection.md 中有完整对照sensevoiceiic/SenseVoiceSmall FSMN-VAD、paraformerparaformer-zh VAD CT 标点、paraformer-en示例服务独有别名、fun-asr-nanoFunAudioLLM/Fun-ASR-Nano-2512示例中走 AutoModel 而非 vLLM 路由、moss-transcribe-diarize第三方 MOSS 适配需独立依赖环境。端点一览端点方法说明/v1/audio/transcriptionsPOST转写音频OpenAI 兼容/v1/modelsGET列出可用模型/healthGET健康检查 已加载模型/docsGETSwagger 交互式文档低代码工作流集成Dify / n8n / LangChain所有工作流引擎最终都要发送同一个 multipart 请求形态examples/openai_api/WORKFLOWS.md方法POSTURLhttp://funasr-host:8000/v1/audio/transcriptionsBodymultipart/form-data文件字段file文本字段modelsensevoice、response_formatverbose_json超时按最长音频时长设置长文件建议 300 秒Dify 中可配置 HTTP 请求节点或自定义工具把text映射为转写结果使用segments前必须确认其来源与语义示例服务的segments仅来自模型自带的sentence_info。若工作流工具传的是文件 URL要注意URL 字符串放在 multipartfile字段中不是音频上传requests.get会跟随重定向并整块缓冲响应其 timeout 不是字节上限不要直接把用户提供的 URL 交给该 helper需要先建立经过评审的下载边界目标白名单、私网访问策略、重定向校验、字节上限、认证在可信网络内并不是 SSRF 的防御。n8n 的推荐流程为 trigger → 二进制音频数据 → HTTP Request → 转写消费方LangChain 场景可直接把client.audio.transcriptions.create(...)封装成 Agent 的工具函数见 examples/openai_api/CLIENTS.md。安全边界示例服务无内置认证无论是示例server.py还是打包funasr-server都没有实现网关认证或应用级总上传大小限制默认监听0.0.0.0api_keynot-needed不代表经过认证。官方安全指南examples/openai_api/SECURITY.md推荐如下拓扑OpenAI SDK / Dify / n8n / 浏览器 UI | v TLS 认证 上传限制 日志 反向代理 / API 网关 / ingress / service mesh | v FunASR OpenAI 兼容 API私有主机 / VM / 容器 / K8s ClusterIP共享前的最小控制项TLS音频常含隐私数据、认证Basic/Bearer/OAuth/OIDC 网关对、上传大小限制防多 GB 上传与内存压力、超时长录音需更长超时但卡死客户端不应永久挂起、限流保护 GPU/CPU 容量、私有运维路由/health、/v1/models、schema/UI 在共享监听器上应被拒绝、日志与留存策略原始音频可能敏感。仓库提供了 NGINX 与 Caddy 两套只放行POST /v1/audio/transcriptions的反向代理示例NGINX 用limit_except POST { deny all; }auth_basicclient_max_body_sizeCaddy 用basic_authrequest_body max_sizereverse_proxy两者都在转发前移除Authorization头FunASR 不需要网关的 Basic 凭据。代理超时不会取消已运行的模型推理ClusterIP也不是认证或命名空间隔离需配合强制NetworkPolicy并验证实际网络路径。把 FunASR 留在私有网络把公开 TLS、身份、请求限制与审计日志放在团队已运维的边界上。选型后的检查清单与排障完成三大场景选型后官方文档建议docs/deployment_matrix.md 的 Readiness checklist选定模型别名并在部署文档中固定版本FunASR 版本、模型版本、设备、CUDA/PyTorch 版本、Docker 镜像 tag、完整命令行先跑一个短的公开冒烟样本再跑至少一个贴近业务的实际样本为每个请求记录音频时长、模型、设备、延迟、响应格式与错误类型在暴露到不可信网络前配置上传大小限制、认证、TLS 与限流热词类需求先明确是确定性文本后处理还是解码期偏置再决定是否更换运行时流式场景必须用真实音频测试静音、噪声、重叠说话人、长会话、重连与慢客户端基准声明必须包含输入时长、硬件、batch、模型、运行时路径并说明是否排除模型下载/预热时间。模型选择上多语言快速转写优先 SenseVoice-Small、普通话生产 ASR 优先 Paraformer-Large、LLM 类 ASR 实验用 Fun-ASR-Nano吞吐敏感时配合 docs/vllm_guide.md、带说话人的离线长文转写用 MOSS-Transcribe-Diarize详细对照见 docs/model_selection.md。遇到运行时、Docker、vLLM、Triton、Android、浏览器或 Agent 集成问题可参考 docs/troubleshooting.md提交 issue 时务必带上部署路径、精确命令/配置、日志、模型、设备与音频特征。最后回到方法论本身无论是音频剪辑、实时识别还是语音对话落地顺序都应是场景 → 模型 → 服务契约 → 延迟/隐私验证。FunASR 提供的是一条条已被文档、源码与测试确认的路径而非一个万能模型——先选对场景后续的每一层选型才有意义。【免费下载链接】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），仅供参考