FunASR OpenAI 兼容语音转写 API 服务器从本地部署到 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 仓库 examples/openai_api/README.md 为核心系统讲解如何基于 FunASR 快速搭建一个兼容 OpenAI/v1/audio/transcriptions接口的私有语音转写服务。你将掌握示例服务器与打包版funasr-server的 API 边界差异、基于 Python 3.11 的完整启动流程、OpenAI SDK / curl / LangChain 等客户端的接入方式、可用模型别名与verbose_json响应契约以及 Docker、Kubernetes、网关安全与低代码工作流Dify/n8n的部署要点。读完本文你可以在自有硬件上独立部署一个可被任意 OpenAI 兼容客户端调用的私有 ASR 服务。项目定位一个OpenAI 风格的私有语音转写端点FunASR 仓库中的 examples/openai_api 目录实现了一个 OpenAI 风格的/v1/audio/transcriptions端点用于私有语音转写。需要明确的是它实现的是语音 API 子集而非完整的 OpenAI API也不承诺与每个 SDK/框架特性的完全兼容。在深入部署前必须先厘清两条服务路径的区别本示例服务器examples/openai_api/server.py仓库随附的示例实现通过AutoModel在进程内加载模型。启动时与请求中省略 multipartmodel字段时均默认使用sensevoice。它没有spk表单字段只能保留模型自身返回的说话人标签。打包版funasr-serverfunasr/bin/_server_app.py独立实现。启动时--model auto会根据设备字符串选择以cuda开头则加载fun-asr-nano否则加载sensevoice而请求中省略model时则独立默认fun-asr-nano。spktrue可为非原生说话人分离模型请求独立说话人管线默认False。实践建议无论使用哪条路径都应在请求中显式指定model并查询已部署服务的/v1/models来确认可用别名。例如paraformer-en是示例服务器注册的别名但并非打包服务器的内置别名。同时应以运行时/openapi.json为准校验字段而非只依赖仓库中检入的 示例 schema。理解 API 契约别把格式当能力response_formatverbose_json只是选择响应形状它不会启用说话人分离diarization也不会强制生成时间戳。这是整个示例最容易误解的地方。示例服务器仅在模型返回sentence_info时将其复制到segments否则返回segments[]。说话人标签可能缺失或为null。MOSS第三方 OpenMOSS 联合转写/分离适配器自带匿名说话人标签不需要spktrue也不应叠加外部 VAD 或 CAM 模型。SDK 输出中的timestamp、Nano 的timestamps/ctc_timestamps不会被自动转换成 HTTP 段。示例服务器只接受 multipart 字段file、model、language、response_formatuse_itn、热词、原始数组、spk等 SDK 选项都不是它的表单字段。language字段返回的是你提交的语言提示或auto不是检测出的语言打包版服务才可以使用后端语言检测。关于duration的语义两条路径也存在差异详见 examples/openai_api/CLIENTS.md字段示例server.py打包版funasr-serverdurationgenerate()前后的耗时秒不含初始模型加载不是音频时长音频时长秒音频元数据不可读时兜底可为 0segments由模型提供的sentence_info转换而来否则为[]使用可用段兜底可从文本与音频时长合成粗粒度段start/end段时间单位为秒段时间单位为秒不一定是词级强制对齐speaker模型提供的标签无标签时为null仅当存在标签时返回外部聚类需spktrueMOSS 为原生标签其他字段顶层含modellanguage回显请求提示或auto含task与段级id/wordsverbose 构造器不添加顶层model两侧 JSON 字段并不完全一致请勿假设相同。完整响应示例与说话人请求方式见 examples/openai_api/CLIENTS.md。快速开始十分钟跑通本地 ASR 服务官方推荐在全新检出目录中使用 Python 3.11 与 POSIX shell 搭建环境git clone https://github.com/modelscope/FunASR.git FunASR-api cd FunASR-api git checkout --detach d91d961e37a005837b1523bcc6b09f087877be54 python3.11 -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。仅安装 PyPI 包不会提供仓库示例文件。这是部署步骤说明不是对全新安装或声学推理成功的证明。启动后应等待模型加载完成再检查GET /health下载与启动耗时取决于 checkpoint、缓存、网络与硬件。/health正常不代表转写可用。准备好 CUDA 能力依赖后可把 CPU 命令替换为python server.py --host 127.0.0.1 --model sensevoice --device cuda --port 8000但不要在同一端口同时启动两个服务。端到端冒烟测试在另一个终端进入同一检出目录、激活.venv并进入examples/openai_api后可运行可选的健康与转写检查脚本bash smoke_test.sh # 无需 curl/bash 的跨平台替代方案 python smoke_test.py其中 smoke_test.sh 会依次检查/health并执行一次转写smoke_test.py 是基于标准库urllib的跨平台客户端支持--base-url、--model、--response-format、--timeout等参数并在sample.wav不存在时自动下载公开中文示例音频。等效的手工命令示例音频为公开中文样本非日/韩评测集curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav curl http://localhost:8000/health curl http://localhost:8000/v1/models curl http://localhost:8000/openapi.json curl http://localhost:8000/v1/audio/transcriptions \ -F filesample.wav \ -F modelsensevoice \ -F response_formatverbose_json客户端接入OpenAI SDK、curl 与 requests使用 OpenAI SDKPython在已激活的环境中单独安装 HTTP 客户端python -m pip install openai。注意这是独立的 OpenAI 客户端不是 FunASR Python SDK。将meeting.wav替换为你准备好的解码器支持的本地音频文件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) # 查看 verbose 响应segments 可能为空 with open(meeting.wav, rb) as audio: result client.audio.transcriptions.create( modelsensevoice, fileaudio, response_formatverbose_json, ) # verbose_json 不会启用说话人分离详见上文 API 契约 print(getattr(result, segments, []))大多数 OpenAI SDK 即使在本服务不校验密钥时也要求提供api_key字符串本地开发填入任意占位符即可。使用 curlcurl http://localhost:8000/v1/audio/transcriptions \ -F fileaudio.wav \ -F modelsensevoice # verbose 输出 curl http://localhost:8000/v1/audio/transcriptions \ -F fileaudio.wav \ -F modelsensevoice \ -F response_formatverbose_json使用纯 Python requests这是内部服务、队列、Notebook 与低代码工具中最通用的模式import requests with open(meeting.wav, rb) as audio: response requests.post( http://localhost:8000/v1/audio/transcriptions, files{file: (meeting.wav, audio, audio/wav)}, data{model: sensevoice, response_format: verbose_json}, timeout300, ) response.raise_for_status() print(response.json()[text])可用模型别名与配置以下别名定义于示例服务器的MODEL_CONFIGS见 server.py不是通用 SDK 或服务器模型列表。端点会从返回文本中移除富|...|标签但不提供专门的 emotion/event 字段别名底层配置说明sensevoiceSenseVoiceSmall FSMN-VADmax_single_segment_time30000默认模型默认不启用句子时间戳与外部说话人聚类paraformerparaformer-zh FSMN-VAD CT 标点已配置标点仅verbose_json不会请求句子记录paraformer-enparaformer-en FSMN-VAD仅示例服务器注册打包服务器无此内置别名此处未配置标点组件fun-asr-nano经AutoModel加载 HF hub 的FunAudioLLM/Fun-ASR-Nano-2512 FSMN-VADtrust_remote_codeTrue示例中非 vLLM 路由CTC 时间戳可用性取决于 checkpoint 权重是否完整moss-transcribe-diarizeOpenMOSS-Team 的MOSS-Transcribe-Diarize固定 HF revisionbackendhf第三方原生转写/分离适配器需独立依赖环境保留模型提供的时间戳与匿名标签从源码结构可以推断load_model会将device注入配置并设置disable_updateTrue模型加载成功后缓存在进程内注册表MODEL_REGISTRY中后续请求直接复用。需要强调的事实边界fun-asr-nano与fun-asr-mlt-nano是不同的 checkpointMLT-Nano 是独立的多语言 checkpoint不是任一服务的内置别名基础 Nano 不保证韩语支持。自定 checkpoint 需走打包版路由的--model-path与--hub请求modelcustom这些不是示例服务器的选项。MOSS 使用固定的第三方 HF revision禁止叠加外部 VAD 或说话人模型其标签只是单条录音内的匿名标签不是真实身份或跨录音的说话人识别。完整部署funasr-server、Docker Compose、Kubernetes、vLLM、SGLang Omni、LocalAI、FunClip见 docs/moss_transcribe_diarize.md。别名出现在/v1/models中并不证明其依赖或权重已就绪。模型许可证请参考 docs/model_selection.md 与模型自身许可证——FunASR 软件的 MIT 许可证并不覆盖每个模型权重。API 端点一览端点方法说明/v1/audio/transcriptionsPOST音频转写OpenAI 兼容/v1/modelsGET列出可用模型/healthGET健康检查 已加载模型/docsGET交互式 API 文档Swagger从 server.py 可以看到实现细节转写端点接受file必填二进制、model默认sensevoice、language可选提示、response_formatjson或verbose_json四个 multipart 字段上传文件先写入临时文件generate后清理/v1/models返回含ready标志的 OpenAI 风格模型列表/health返回device、models_loaded与models_available。verbose_json分支会把sentence_info中的毫秒坐标除以 1000 转换为秒并附上model与duration字段。无需编码的检查方式本地上传或录音可用 Gradio 浏览器演示或导入 Postman 集合 直接运行健康、模型列表与转写请求API 网关或客户端生成可使用 OpenAPI 规范。Agent 框架集成把转写变成工具函数multipart HTTP / 工具函数模式可用于集成LangChain、LlamaIndex、AutoGen、CrewAI、Semantic Kernel、Dify与n8n。请注意这些配方不保证与每个框架版本或实时 API 兼容使用前应针对本服务支持的字段做校验。from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyx) def transcribe_for_agent(audio_path: str) - str: LangChain agent 的工具函数。 with open(audio_path, rb) as audio: result client.audio.transcriptions.create(modelsensevoice, fileaudio) return result.text按各框架常规的 tool / function-calling 机制注册上述函数即可。两条服务路径都会把工作流请求中的whisper-1别名映射到启动时选定的模型这并不会运行 OpenAI Whisper。两点部署提醒工作流容器中的localhost指的是该容器自身不是宿主机。应显式配置受控可达的网关/服务地址而不是无限制的公网暴露。低代码工作流Dify HTTP 节点 / n8n HTTP Request 节点的核心请求形状为POST http://funasr-host:8000/v1/audio/transcriptionsbody 类型multipart/form-data文件字段file文本字段modelsensevoice、response_formatverbose_json超时按最大音频时长设置如长文件 300 秒。详细配方见 examples/openai_api/WORKFLOWS.md。配置参数示例服务器的命令行与环境变量以下默认值属于示例server.py见 server.py不适用于funasr-server参数默认值说明--host0.0.0.0绑定地址--port8000端口--devicecuda设备cuda/cpu/mps--modelsensevoice启动时预加载的模型Docker 环境变量定义于 Dockerfile 与 docker-compose.yml环境变量默认值说明FUNASR_PORT8000传给server.py的容器端口FUNASR_DEVICEcpu容器设备模式仅当镜像具备 CUDA 能力依赖时才设为cudaFUNASR_MODELsensevoice容器启动时加载的模型别名Docker 部署在仓库根目录构建示例镜像。默认镜像以 CPU 模式启动示例server.py而非打包版funasr-server。这是本地开发发布设置并非认证机制容器仍监听0.0.0.0只有宿主机发布端口绑定127.0.0.1不要改动容器监听地址为 loopback。当前 Dockerfile 安装的是未固定版本的 PyPI FunASR 依赖并复制本示例因此它不是上述源码固定环境也不是可复现的声学环境。cd examples/openai_api cp .env.example .env FUNASR_HOST_PORT127.0.0.1:8000 docker compose up --build等效的一次性docker run命令docker build -t funasr-api . docker run --rm -p 127.0.0.1:8000:8000 \ -e FUNASR_DEVICEcpu \ -e FUNASR_MODELsensevoice \ funasr-apiGPU 主机需先安装 NVIDIA Container Toolkit 并使用具备 CUDA 能力的 PyTorch/FunASR 镜像docker run --rm --gpus all -p 127.0.0.1:8000:8000 \ -e FUNASR_DEVICEcuda \ -e FUNASR_MODELsensevoice \ funasr-api在另一终端验证容器BASE_URLhttp://localhost:8000 bash smoke_test.sh python smoke_test.py --base-url http://localhost:8000可选的 validate_docker.sh 合并了构建/运行/冒烟步骤但其默认端口发布使用所有主机接口不继承上述 loopback 设置使用前请审查其网络配置。Kubernetes 部署在向团队共享服务或经网关暴露之前请先阅读 安全与网关指南落实 TLS、认证、上传限制、速率限制与日志策略。内部集群服务的推荐起点是 Kubernetes 部署模板ClusterIP服务 持久化模型缓存 健康探针。要点如下从仓库根目录执行构建docker build -f examples/openai_api/Dockerfile -t registry.example.com/speech/funasr-api:cpu-latest examples/openai_api随后推送并更新kustomization.yaml中的镜像。部署kubectl -n speech apply -k examples/openai_api/kubernetes再kubectl -n speech rollout status deploy/funasr-api --timeout15m。验证kubectl -n speech port-forward --address 127.0.0.1 svc/funasr-api 8000:8000随后运行python3 examples/openai_api/smoke_test.py --base-url http://127.0.0.1:8000 --model sensevoice --response-format verbose_json。集群内客户端可使用http://funasr-api.speech.svc.cluster.local:8000作为 HTTP base URL.../v1作为 OpenAI SDK base URL。集群调优参数FUNASR_MODEL默认sensevoice、FUNASR_DEVICE默认cpu、PVC 大小默认 20Gi、内存请求默认 8Gi与启动探针约 10 分钟失败预算。ClusterIP不是认证模板不提供 NetworkPolicy、认证网关、TLS 或请求限制暴露前务必补齐。缓存 PVC 为ReadWriteOnce水平扩展需改用镜像、按 Pod 缓存或共享只读模型缓存。安全边界与网关部署示例服务器与打包版funasr-server均未实现网关认证或应用级总上传大小限制默认监听0.0.0.0api_keynot-needed不构成认证。请将本地测试保持在 loopback 上共享前按 examples/openai_api/SECURITY.md 配置 TLS、网关认证、上传/时间/速率限制、音频与转写留存以及私有化/health、模型列表与 schema 访问。推荐的拓扑OpenAI SDK / Dify / n8n / 浏览器 UI | v TLS 认证 上传限制 日志 反向代理 / API 网关 / Ingress / Service Mesh | v FunASR OpenAI 兼容 API 私有主机 / VM / 容器 / Kubernetes ClusterIP共享前的最低控制项包括TLS音频常含隐私数据、认证Basic/Bearer/OAuth-OIDC/内部 SSO 网关对、上传大小限制防止多 GB 上传与内存压力、超时、速率限制、私有化运营路由/health、/v1/models、schema/UI 暴露服务元数据以及日志与留存策略。SECURITY.md 提供了只放行POST /v1/audio/transcriptions的 NGINXBasic auth client_max_body_size 200m与 Caddy 2.11basic_authrequest_body max_size 200MiB参考配置并强调认证失败必须 fail-closed。请求经网关转发时会移除Authorization头因为 FunASR 不需要网关注入的 Basic 凭证。常见问题排查症状检查项CUDA 不可用用--device cpu做较慢但简单的冒烟测试8000 端口被占用改用--port 9000启动并执行BASE_URLhttp://localhost:9000 bash smoke_test.sh或python smoke_test.py --base-url http://localhost:9000模型下载缓慢在稳定网络下重试或提前从 ModelScope/Hugging Face 预下载模型SDK 报缺少认证本地开发传入任意占位api_key即可400 unknown model调用/v1/models使用其中列出的别名请求超时增大客户端超时或拆分过长的录音首次请求很慢模型可能正在加载用--model sensevoice预加载结语与延伸阅读本文围绕 examples/openai_api/README.md 完整还原了 FunASR OpenAI 兼容转写服务的部署、调用、配置与安全链路并结合 server.py 源码与仓库内配套文档做了纵深说明。核心要点再强调一遍显式指定model、把verbose_json仅当作响应格式、将duration按部署路径区分语义、在任何共享前落实网关安全。如需继续深入可参考客户端配方SDK/JS/Agent 工具/Dify-n8nexamples/openai_api/CLIENTS.md、examples/openai_api/JAVASCRIPT.md、examples/openai_api/WORKFLOWS.md浏览器演示与 OpenAPI/Postmanexamples/openai_api/GRADIO.md、examples/openai_api/OPENAPI.md、examples/openai_api/POSTMAN.md进程内AutoModel.generate()用法非 HTTPdocs/python_api.md打包版服务与 Agent 集成docs/agent_integration.mdMOSS 转写/分离专门指南docs/moss_transcribe_diarize.md【免费下载链接】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），仅供参考