FunASR OpenAI 兼容 API 低代码工作流接入实战Dify、n8n 与 Webhook Worker 的 Multipart 转写配方【免费下载链接】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 仓库examples/openai_api中的 OpenAI 兼容语音服务为核心系统讲解如何让 Dify、n8n、HTTP 节点、webhook worker 等低代码工作流引擎调用私有 FunASR 语音转写 API。你将掌握服务预检、multipart 请求构造、响应字段语义辨析、Dify/n8n 节点配置、Webhook worker 函数实现以及上线前必须落实的安全护栏与故障排查方法。这些内容是面向特定工作流引擎的 multipart HTTP 接入配方不是对所有工作流产品或版本的兼容保证接入前请始终以实际部署服务的/openapi.json与/v1/models为准。服务预检先跑通本地 loopback 服务启动示例服务在配置任何低代码工具之前先按示例 README 的准备步骤完成代码检出与环境搭建。README 中固定的源码 revision 只锁定源码不是依赖/模型锁定也不代表已验证的全新安装或声学正确性。以下命令假定已在该 checkout 根目录准备好.venvcd examples/openai_api source ../../.venv/bin/activate python server.py --host 127.0.0.1 --model sensevoice --device cpu --port 8000准备好 CUDA 依赖后将 CPU 命令替换为python server.py --host 127.0.0.1 --model sensevoice --device cuda --port 8000注意--host 127.0.0.1是必须显式传入的因为示例服务的默认监听地址是0.0.0.0见 server.py。如果服务已经在运行请跳过启动步骤直接做健康检查不要在同一端口再启动第二个进程。另一个实现是打包的funasr-server路线见 Agent 集成指南其启动默认值、别名与响应字段与本示例不同本文聚焦示例server.py。检查本地服务在同一主机的第二个终端进入同一 checkout 的examples/openai_api目录激活同一环境等待模型加载完成后检查source ../../.venv/bin/activate export FUNASR_BASE_URLhttp://127.0.0.1:8000 curl -fsS $FUNASR_BASE_URL/health curl -fsS $FUNASR_BASE_URL/v1/models curl -fsS $FUNASR_BASE_URL/openapi.json这三个端点分别对应 server.py 中的健康检查返回设备、已加载模型与可用别名、OpenAI 风格模型列表带ready标志以及由 FastAPI 动态生成的 OpenAPI schema。健康与 schema 检查只能确认服务可达不能验证声学正确性真正的转写验证请使用下方 multipart 请求。转写命令中的meeting.wav应替换为你本地的真实音频文件README 中的公开中文 smoke 样例不是多语言准确率基准。Docker 工作流引擎的连通性如果工作流引擎运行在 Docker 容器中localhost通常指向工作流容器自身主机上的 loopback 服务不会自动对容器可达。正确做法是明确配置一个私有的网关/容器网络将FUNASR_BASE_URL以及下方 worker 中的FUNASR_URL替换为工作流运行时实际可达的地址需要网关鉴权时使用真实凭据本地 curl/Python 示例不添加鉴权 header不要通过把未鉴权端口暴露到公网来解决连通性问题。Postman smoke test低代码接入前的图形化验证在配置低代码工具之前可以先导入 Postman collection 从图形界面跑通 health、模型列表和转写请求偏好 schema 驱动导入时使用 OpenAPI spec。操作要点将 collection 变量FUNASR_BASE_URL设置为可达的服务地址如http://localhost:8000在转写请求的Body标签页为 multipart 的file字段选择本地音频文件第一次测试保持MODEL_ALIASsensevoice或切换为/v1/models返回的其他别名。处理离线多人会议时先按 MOSS 部署指南 准备独立的第三方 MOSS 服务注意其 GPU 与文件时长边界再将MODEL_ALIAS改为moss-transcribe-diarize并保持response_formatverbose_json以保留原生匿名说话人 segments。不要额外添加外部 VAD 或spktrue——MOSS 自带原生说话人标签录音内标签不是已验证身份也不是跨录音稳定编号。仅修改客户端别名并不会自动准备好该服务环境。Multipart HTTP 请求所有工作流引擎的统一请求形态无论使用何种低代码工具最终都需要发出下面这种请求Method:POSTURL:http://funasr-host:8000/v1/audio/transcriptionsBody type:multipart/form-dataFile field:fileText field:modelsensevoiceText field:response_formatverbose_jsonTimeout:根据最长音频时长设置例如长录音可先设为 300 秒等价 curl 命令curl -fsS $FUNASR_BASE_URL/v1/audio/transcriptions \ -F filemeeting.wav \ -F modelsensevoice \ -F response_formatverbose_json将text映射为转写文本。response_formatverbose_json只选择响应格式不会开启说话人分离也不会强制生成时间戳。在消费其他字段前先阅读 客户端响应契约。两种服务的响应语义差异从源码看示例server.py与打包的funasr-server共享 multipart 转写请求子集但默认值、别名与响应 schema 并不相同维度示例server.py打包funasr-serverdurationgenerate()调用周围的耗时秒数不含初次模型加载不是录音时长音频时长秒数无法读取音频元数据时 fallback 可为 0segments仅来自模型返回的sentence_info否则为segments[]使用可用片段fallback 可合成按文本划分的粗粒度时间区间start/end秒为单位秒为单位不保证是词级强制对齐speaker模型提供或 null有标签才包含非原生说话人模型需spktrueMOSS 为原生标签其他字段包含modellanguage回显请求提示或auto非检测语言包含task和片段id/words无顶层model语言可用后端检测具体到示例服务的实现server.py 中segments由模型返回的sentence_info转换而来start/end除以 1000 从毫秒转为秒否则返回空数组language只是回显你提交的提示或auto。其他需要牢记的语义片段start/end单位是秒不是 SDK 的毫秒坐标speaker字段可能缺失、为 null、数字或字符串标签不标识真实身份非空 segments 或verbose_json都不保证准确的字幕对齐HTTP 展示文本会剥离 SenseVoice 富标签clean_text正则去除|...|不等于 SDK 原始标签结果也不是独立的情绪/事件响应SDK 字段如timestamp、timestamps、ctc_timestamps、use_itn、hotwords 与原始数组不是额外的表单字段原始 SDK 时间戳不会自动转换为 HTTP segments。响应示例无sentence_info时示例服务的示意响应0.42是处理耗时不是音频时长{text: recognized speech, segments: [], language: auto, duration: 0.42, model: sensevoice}3.2 秒文件对应的打包服务响应示意粗粒度 fallback 片段未开启说话人选项。这些示例只描述 schema不是新模型测量结果{ task: transcribe, language: en, duration: 3.2, text: recognized speech, segments: [ {id: 0, start: 0.0, end: 3.2, text: recognized speech, words: []} ] }Dify 自定义工具或 HTTP 节点当 Dify 应用接收到上传的音频文件或收到内部音频存储 URL 时可以使用下面两种模式。直接文件上传路径在 HTTP request 节点或自定义工具中配置Method:POSTURL:http://funasr-host:8000/v1/audio/transcriptionsBody:multipart/form-dataFile part:file绑定到上传的音频变量Text parts:modelsensevoice、response_formatverbose_jsonOutput variable:将text映射为转写文本在使用时间戳或说话人标签前先检查segments是否可用及其来源音频 URL 路径有些工作流工具只能传文件 URL 而不是原始 multipart 二进制。multipartfile字段中的 URL 字符串不是音频上传。优先直接上传二进制或传受控存储对象 ID 并由经过审查的存储客户端解析。下面的 sketch仅用于运维人员批准的可信存储 URL。目标 allowlist、私网访问策略、重定向校验、下载字节上限与鉴权均未实现requests.get会跟随重定向并将整个响应缓存在内存中其 timeout 不是字节限制也不是完整的端到端截止时限。不要将用户提供的 URL 传给这个 helper。接受此类 URL 前必须使用经过审查的下载边界执行全部控制包括阻止非预期私网/元数据目标并检查每次重定向——位于可信内网并不能防止 SSRF。对可信输入的工作流运维人员向 worker 提供已批准的音频 URL 和元数据worker 从可信存储下载音频worker 使用 multipart 请求调用 FunASRworker 返回服务 JSON由下游节点检查可选字段。日志不得暴露签名 URL、凭据或私有转写。在同一已激活的客户端环境安装独立 HTTP 依赖python -m pip install requests按已准备的服务设置FUNASR_URL默认值适用于同主机 worker。以下函数定义可被你的 worker 导入但它们不创建 HTTP 监听器也不实现入站鉴权或上传限制import requests FUNASR_URL http://127.0.0.1:8000/v1/audio/transcriptions def transcribe_from_url(audio_url: str) - dict: audio_response requests.get(audio_url, timeout120) audio_response.raise_for_status() files {file: (audio.wav, audio_response.content, audio/wav)} data {model: sensevoice, response_format: verbose_json} response requests.post(FUNASR_URL, filesfiles, datadata, timeout300) response.raise_for_status() return response.json()请把此示意限制在已批准的输入内仅校验主机名不是完整的安全下载策略。n8n HTTP Request 节点一个常见的 n8n 流程是触发器 → 二进制音频数据 → HTTP Request → 转写结果消费节点。推荐配置Method:POSTURL:http://funasr-host:8000/v1/audio/transcriptionsSend Body:开启Body Content Type:Form-Data/ multipartBinary file field:fileAdditional form fields:modelsensevoice、response_formatverbose_jsonResponse Format:JSONTimeout:长录音场景需要调大请求之后使用{{$json.text}}作为转写文本。只有先确认{{$json.segments}}存在且适合当前任务才将其传给后续节点空片段或粗粒度片段不能当作已验证的字幕时刻或说话人分离结果。节点标签与二进制属性配置随所安装的 n8n 版本变化file是发出的multipart 字段名不一定是传入二进制属性的名字。n8n OpenAI Audio 节点对于发送modelwhisper-1的 OpenAI Audio Transcribe 节点版本FunASR 会把该兼容别名映射到服务启动时选择的模型而不是选择 Whisper checkpoint。这一映射在源码中有明确实现N8N_OPENAI_MODEL_ALIAS whisper-1resolve_openai_transcription_model 将其解析为DEFAULT_MODEL即--model启动参数仓库测试 test_openai_api_n8n_compat.py 也验证了该映射行为。配置要点Base URL使用可达的服务地址并带/v1非空占位 key 仅适用于未保护的本地端点访问鉴权网关时应提供真实凭据请核验所安装节点版本的请求行为不要假定所有版本一致此配方适用于纯文本转写需要显式response_format或服务支持的说话人选项时改用 HTTP Request 节点并仍受上述响应边界限制。Webhook worker 模式当工作流引擎不能稳定发送 multipart 文件或音频需要预处理时可以使用下面的函数。该 POSIX 临时文件示例使用同一个requests依赖并在上传后关闭句柄。它接受已驻留内存的 bytes——应在缓冲之前应用上传大小限制。它是普通函数不是受保护的 webhook 服务。from pathlib import Path import tempfile import requests FUNASR_URL http://127.0.0.1:8000/v1/audio/transcriptions def transcribe_bytes(filename: str, payload: bytes, content_type: str audio/wav) - dict: with tempfile.NamedTemporaryFile(suffixPath(filename).suffix or .wav) as tmp: tmp.write(payload) tmp.flush() with open(tmp.name, rb) as audio: response requests.post( FUNASR_URL, files{file: (filename, audio, content_type)}, data{model: sensevoice, response_format: verbose_json}, timeout300, ) response.raise_for_status() return response.json()注意此处未实现音频转码、文件大小检查、请求 ID、入站/上游鉴权和重试策略共享使用前必须在相应边界落实这些控制——重试可能重复执行昂贵的转写工作。示例服务本身会把上传内容写入临时文件并在处理结束后删除server.py但这不构成无磁盘或安全擦除保证。生产环境护栏在跨团队共享 FunASR 服务前务必落实以下护栏在 FunASR 前置鉴权、TLS、上传大小限制和限流代理与网关模式见 安全与网关指南含 NGINX Basic-auth 与 Caddy 反向代理 sketch、Kubernetes NetworkPolicy 要点与逐步上线检查清单。示例服务没有内置鉴权或上传大小限制占位api_key不会让服务具备鉴权使用/health做工作流 readiness check使用/v1/models校验模型别名记录 request id、音频时长、模型别名、响应格式、设备、延迟和错误类型按最长音频时长设置工作流超时超长录音先切分再交给低代码工具处理私有音频放在可信存储中避免把签名 URL、凭据或转写文本写入公开日志上生产前至少用一个公开 smoke 样例和一个真实业务样例完整跑通同一条工作流。仓库提供了可复用的 smoke 工具smoke_test.sh 与 smoke_test.py它们会依次检查/health、/v1/models并执行转写Python 版本在缺少音频文件时会下载公开中文样例其 multipart 构造逻辑可作为低代码工具配置的参考。故障排查工作流能访问/health但转写失败确认请求是multipart/form-data且二进制字段名是fileDify 或 n8n 访问localhost失败换成工作流运行时可访问的主机名、Compose service name 或 Kubernetes service name响应中没有可用segments检查格式与已部署的 schema再检查模型的sentence_info与说话人配置仅设置verbose_json不能创建时间戳或标签请求超时调大 HTTP timeout或先切分长录音第一次请求很慢使用--model sensevoice预加载模型并用/health做 readiness check模型别名未知调用/v1/models使用返回列表中的别名。相关文档示例服务 README快速开始、API 契约、模型别名、Docker 与 Kubernetes 部署客户端接入配方OpenAI SDK、requests、Agent 工具与响应格式详解OpenAPI 规范schema 驱动导入与客户端生成安全与网关指南共享服务前的 TLS、鉴权、限流与数据治理MOSS 部署指南离线多人会议转写与说话人分离Python SDK 指南进程内AutoModel.generate()用法【免费下载链接】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），仅供参考