FunASR LangChain 集成指南把本地语音识别接入 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 通过一套 OpenAI 兼容的 HTTP 转写接口/v1/audio/transcriptions对外暴露语音识别能力因此可以像接入云语音 API 一样以极小的代码量把本地 ASR 注册为 LangChain Agent 的工具函数Tool并在 Dify、AutoGen、CrewAI 等支持 OpenAI 音频接口的框架中直接复用。读完本文你将掌握如何启动 FunASR 服务、如何用 OpenAI SDK 在 LangChain 中封装speech_to_text工具并挂载到 AgentExecutor、如何理解verbose_json/spk/热词等关键参数的真实语义以及如何把同一套接口接到其他 Agent 框架。为什么能直接集成OpenAI 兼容 API 的约定LangChain、Dify、AutoGen、CrewAI、n8n 等框架普遍原生支持 OpenAI 的音频转写调用方式client.audio.transcriptions.create(...)。FunASR 在仓库中提供了两种遵循这一约定的服务入口示例服务examples/openai_api/server.py一个 FastAPI 实现的/v1/audio/transcriptions子集端点文档定位是语音 API 子集而非完整 OpenAI API 的兼容保证。打包命令行服务funasr-server实现位于 funasr/bin/_server_app.py默认启动参数、模型别名与响应字段和示例服务并不完全一致。两种服务共享同一个 multipart 请求子集POST /v1/audio/transcriptions二进制字段名为file文本字段为model、response_format等。正因接口形状统一LangChain 侧的集成代码可以保持最小化——框架不关心语音识别的内部实现它只需要拿到输入一个本地音频路径、返回一段文本的普通工具函数。环境准备启动 FunASR 服务并安装 LangChain按 examples/langchain/README.md 的说明先启动本地 FunASR 服务# 启动 FunASR 服务 pip install torch torchaudio pip install funasr vllm fastapi uvicorn python-multipart funasr-server --device cuda # 安装 LangChain pip install langchain langchain-openai几个值得注意的默认值见 examples/openai_api/README.md 的 API Contract 小节打包版funasr-server启动时若省略--model则按--model auto处理设备字符串以cuda开头时预载fun-asr-nano否则预载sensevoice。请求体中若省略model字段打包服务独立默认到fun-asr-nano——启动预载模型与请求默认模型是两套不同的设置建议请求中总是显式指定model。服务端api_key仅为占位符本地开发可用任意值服务本身不做鉴权跨网络共享前需按 examples/openai_api/SECURITY.md 配置 TLS、网关鉴权、上传大小与限流。启动后可用健康检查与模型列表确认服务就绪参考 docs/agent_integration.mdcurl -fsS http://localhost:8000/health curl -fsS http://localhost:8000/v1/models把语音识别注册为 LangChain Tool核心思路是用 OpenAI SDK 创建一个指向本地 FunASR 服务的客户端把它封装成一个被tool装饰的函数再用create_tool_calling_agent挂载到任意 LLM。完整代码来自 examples/langchain/README.mdfrom langchain.tools import tool from openai import OpenAI asr_client OpenAI(base_urlhttp://localhost:8000/v1, api_keyunused) tool def speech_to_text(audio_path: str) - str: Transcribe an audio file to text using local FunASR. Supports wav, mp3, flac. Returns transcribed text with speaker IDs. result asr_client.audio.transcriptions.create( modelfun-asr-nano, fileopen(audio_path, rb), response_formatverbose_json ) return result.text # 与任意 LangChain Agent 配合使用 from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate llm ChatOpenAI(modelgpt-4o) tools [speech_to_text] prompt ChatPromptTemplate.from_messages([ (system, You are a helpful assistant that can transcribe audio files.), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools) result executor.invoke({input: Please transcribe meeting.wav})这段代码中真正与 FunASR 相关的只有三行OpenAI(base_url...)指向本地服务、model指定模型别名、fileopen(...)上传音频字节。Agent 的提示词只需描述可以转写音频文件模型会自行决定何时调用该工具。仓库 examples/openai_api/CLIENTS.md 给出了同构的Agent Tool 模式参考实现并明确说明LangChain、LlamaIndex、AutoGen、CrewAI、Semantic Kernel 等框架都可以用该框架常规的 tool/function-calling 机制注册同一个函数——这是本集成方案可移植性的来源。关于verbose_json的重要澄清response_formatverbose_json只是选择响应格式并不会启用说话人分离也不会强制生成时间戳。以示例服务 examples/openai_api/server.py 的实现为例verbose_json响应会尽力把模型返回的sentence_info复制为segments没有则返回segments[]说话人标签可能缺失或为 null。因此不要把拿到了 verbose_json当作拿到了分句与说话人的证据具体字段语义对照见 examples/openai_api/CLIENTS.md 的 Response formats 小节。深入端点与请求参数的事实依据在 examples/openai_api/server.py 中可以看到端点的真实定义transcribe接受file二进制、model默认sensevoice、language可选语言提示、response_formatjson或verbose_json四个表单字段其余如热词、use_itn、原始数组等 SDK 选项不是该示例的请求字段。服务对外暴露的端点如下端点方法说明/v1/audio/transcriptionsPOSTOpenAI 兼容的音频转写/v1/modelsGET列出可用模型/healthGET健康检查 已加载模型/docsGETSwagger 交互式 API 文档模型别名与适用场景两套服务各自维护一份MODEL_CONFIGS示例版见 examples/openai_api/server.py打包版见 funasr/bin/_server_app.py 与 funasr/cli.py常用别名如下别名模型构成适用场景sensevoiceSenseVoiceSmall FSMN-VAD示例服务启动默认多语言快速转写paraformerparaformer-zh FSMN-VAD CT 标点中文生产级转写自带标点paraformer-enparaformer-en FSMN-VAD英文转写仅为示例服务别名打包服务无此内建别名fun-asr-nanoFun-ASR-NanoLLM 类 ASR FSMN-VADLangChain 示例使用的模型打包服务优先走 vLLM 引擎失败时回退 AutoModelmoss-transcribe-diarizeOpenMOSS 原生转写/说话人分离适配器离线长音频多人转写原生返回匿名说话人标签勿叠加外部 VAD/说话人模型注意事项服务会把 SenseVoice 输出中的富标签如|...|从返回文本中剥除因此 HTTP 接口不是专门的情感/事件输出接口paraformer-en在打包服务中并非内建别名模型权重许可证需以具体模型为准FunASR 软件的 MIT 许可证不等于每个模型权重的许可证选型参考 docs/model_selection.md。打包服务的spktrue说话人分离开关LangChain 示例的tooldocstring 提到Returns transcribed text with speaker IDs但示例服务本身没有spk表单字段。说话人分离属于打包版funasr-server的能力请求中传spktrue时funasr/bin/_server_app.py 会惰性加载 CAM 说话人模型为非原生分离模型做外部聚类默认False对 MOSS 这类原生带标签的模型则不需要spktrue也不应再叠加外部 VAD/说话人模型。说话人标签是单条录音内部的匿名标签不是跨录音的身份 ID语义边界见 docs/speaker_emotion.md。与 Dify / AutoGen / CrewAI 等其他框架集成由于接口是 OpenAI 兼容的任何支持 OpenAI 音频 API 的框架都可以直接连接examples/langchain/README.mdfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, # FunASR 服务 api_keyunused ) result client.audio.transcriptions.create( modelfun-asr-nano, fileopen(audio.wav, rb) )在 Dify 这类低代码平台中还有两条常用路径OpenAI-API-Compatible 模型提供方在 Dify 的 Settings - Model Provider 中选择 OpenAI-API-Compatible配置 API Base URL 为http://your-server:8000/v1、API Key 填任意占位值、Model Name 填fun-asr-nano然后在应用设置的 Features - Speech to Text 中启用并选择该提供方。HTTP 请求节点 / 自定义工具按 examples/openai_api/WORKFLOWS.md 的 multipart 配方接线——方法POST、URLhttp://funasr-host:8000/v1/audio/transcriptions、Body 类型multipart/form-data、二进制字段file、文本字段modelsensevoice与response_formatverbose_json超时按最长音频时长设置如长文件设 300 秒。Dify/n8n 跑在容器里时localhost指的是工作流容器自身需要配置可达的服务地址。不论走哪条路径请求形状都是同一套 multipart HTTP 约定text即转写结果segments是否可用取决于服务与模型实现见上文verbose_json澄清。关键特性与使用边界examples/langchain/README.md 列出的特性对应到仓库实现上各有明确边界多语言SenseVoiceSmall 覆盖中英日韩及粤语等多语种Fun-ASR-Nano 面向中英日及中文方言口音具体覆盖范围需通过模型文档确认不能从 HTTP 接口反推docs/model_selection.md。说话人分离打包服务spktrue触发外部 CAM 聚类MOSS 提供原生匿名标签示例服务无此字段。词级时间戳verbose_json只是格式选择SDK 的毫秒级sentence_info坐标由服务适配层转换为秒级 segments且不保证是逐词强制对齐。热词增强属 SDK 层能力如funasrCLI 的--hotwords参数见 funasr/cli.py不是示例服务的表单字段打包服务的 vLLM 路径可通过请求字段传入funasr/bin/_server_app.py。本地运行、MIT 协议仓库文档宣称全本地推理、MIT 软件许可证速度与规模类数字如 170x realtime为仓库文档描述建议按自己的硬件与工作负载实测模型别名并不定义通用速度指标。生产化注意事项与故障排查把语音能力接入 Agent 前需要注意几个工程边界鉴权与暴露服务无内建鉴权与上传限制api_keyunused不做任何校验对外共享前必须配置 TLS、网关鉴权、上传/超时/限流与音频留存策略examples/openai_api/SECURITY.md。模型预载首次请求会下载并加载权重可能很慢用--model启动预载并用/health作为就绪探针。响应字段示例服务duration是generate()周边的耗时秒不是音频时长打包服务duration是音频时长。消费时间戳前先核对 examples/openai_api/CLIENTS.md 的结果契约。常见问题速查源自 examples/openai_api/README.md 与 examples/openai_api/CLIENTS.md症状处理SDK 报缺少鉴权本地开发传任意占位api_key400 unknown model调/v1/models使用返回的别名之一请求超时增大客户端超时或拆分超长录音首次请求很慢模型可能正在加载用--model预载CUDA 不可用先--device cpu验证 API 链路端口被占用换--port 9000并同步修改客户端 base_url相关资源围绕FunASR 作为 Agent 语音能力这条主线仓库内还提供了这些可直接查阅的配套文档examples/openai_api/README.mdOpenAI 兼容服务完整指南Quick Start、Docker/Kubernetes 部署、配置参数表docs/agent_integration.mdHTTP 服务、SDK/curl、MCP、桌面语音输入、字幕生成等多条 Agent 集成路径examples/openai_api/CLIENTS.mdPython/JS SDK、Agent Tool、响应格式与生产清单examples/openai_api/WORKFLOWS.mdDify、n8n、webhook worker 的低代码接线配方docs/python_api.md进程内AutoModel.generate()的 Python SDK 用法examples/mcp_server/README.md把 FunASR 暴露为本地 MCP 工具【免费下载链接】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），仅供参考
FunASR LangChain 集成指南把本地语音识别接入 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 通过一套 OpenAI 兼容的 HTTP 转写接口/v1/audio/transcriptions对外暴露语音识别能力因此可以像接入云语音 API 一样以极小的代码量把本地 ASR 注册为 LangChain Agent 的工具函数Tool并在 Dify、AutoGen、CrewAI 等支持 OpenAI 音频接口的框架中直接复用。读完本文你将掌握如何启动 FunASR 服务、如何用 OpenAI SDK 在 LangChain 中封装speech_to_text工具并挂载到 AgentExecutor、如何理解verbose_json/spk/热词等关键参数的真实语义以及如何把同一套接口接到其他 Agent 框架。为什么能直接集成OpenAI 兼容 API 的约定LangChain、Dify、AutoGen、CrewAI、n8n 等框架普遍原生支持 OpenAI 的音频转写调用方式client.audio.transcriptions.create(...)。FunASR 在仓库中提供了两种遵循这一约定的服务入口示例服务examples/openai_api/server.py一个 FastAPI 实现的/v1/audio/transcriptions子集端点文档定位是语音 API 子集而非完整 OpenAI API 的兼容保证。打包命令行服务funasr-server实现位于 funasr/bin/_server_app.py默认启动参数、模型别名与响应字段和示例服务并不完全一致。两种服务共享同一个 multipart 请求子集POST /v1/audio/transcriptions二进制字段名为file文本字段为model、response_format等。正因接口形状统一LangChain 侧的集成代码可以保持最小化——框架不关心语音识别的内部实现它只需要拿到输入一个本地音频路径、返回一段文本的普通工具函数。环境准备启动 FunASR 服务并安装 LangChain按 examples/langchain/README.md 的说明先启动本地 FunASR 服务# 启动 FunASR 服务 pip install torch torchaudio pip install funasr vllm fastapi uvicorn python-multipart funasr-server --device cuda # 安装 LangChain pip install langchain langchain-openai几个值得注意的默认值见 examples/openai_api/README.md 的 API Contract 小节打包版funasr-server启动时若省略--model则按--model auto处理设备字符串以cuda开头时预载fun-asr-nano否则预载sensevoice。请求体中若省略model字段打包服务独立默认到fun-asr-nano——启动预载模型与请求默认模型是两套不同的设置建议请求中总是显式指定model。服务端api_key仅为占位符本地开发可用任意值服务本身不做鉴权跨网络共享前需按 examples/openai_api/SECURITY.md 配置 TLS、网关鉴权、上传大小与限流。启动后可用健康检查与模型列表确认服务就绪参考 docs/agent_integration.mdcurl -fsS http://localhost:8000/health curl -fsS http://localhost:8000/v1/models把语音识别注册为 LangChain Tool核心思路是用 OpenAI SDK 创建一个指向本地 FunASR 服务的客户端把它封装成一个被tool装饰的函数再用create_tool_calling_agent挂载到任意 LLM。完整代码来自 examples/langchain/README.mdfrom langchain.tools import tool from openai import OpenAI asr_client OpenAI(base_urlhttp://localhost:8000/v1, api_keyunused) tool def speech_to_text(audio_path: str) - str: Transcribe an audio file to text using local FunASR. Supports wav, mp3, flac. Returns transcribed text with speaker IDs. result asr_client.audio.transcriptions.create( modelfun-asr-nano, fileopen(audio_path, rb), response_formatverbose_json ) return result.text # 与任意 LangChain Agent 配合使用 from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate llm ChatOpenAI(modelgpt-4o) tools [speech_to_text] prompt ChatPromptTemplate.from_messages([ (system, You are a helpful assistant that can transcribe audio files.), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools) result executor.invoke({input: Please transcribe meeting.wav})这段代码中真正与 FunASR 相关的只有三行OpenAI(base_url...)指向本地服务、model指定模型别名、fileopen(...)上传音频字节。Agent 的提示词只需描述可以转写音频文件模型会自行决定何时调用该工具。仓库 examples/openai_api/CLIENTS.md 给出了同构的Agent Tool 模式参考实现并明确说明LangChain、LlamaIndex、AutoGen、CrewAI、Semantic Kernel 等框架都可以用该框架常规的 tool/function-calling 机制注册同一个函数——这是本集成方案可移植性的来源。关于verbose_json的重要澄清response_formatverbose_json只是选择响应格式并不会启用说话人分离也不会强制生成时间戳。以示例服务 examples/openai_api/server.py 的实现为例verbose_json响应会尽力把模型返回的sentence_info复制为segments没有则返回segments[]说话人标签可能缺失或为 null。因此不要把拿到了 verbose_json当作拿到了分句与说话人的证据具体字段语义对照见 examples/openai_api/CLIENTS.md 的 Response formats 小节。深入端点与请求参数的事实依据在 examples/openai_api/server.py 中可以看到端点的真实定义transcribe接受file二进制、model默认sensevoice、language可选语言提示、response_formatjson或verbose_json四个表单字段其余如热词、use_itn、原始数组等 SDK 选项不是该示例的请求字段。服务对外暴露的端点如下端点方法说明/v1/audio/transcriptionsPOSTOpenAI 兼容的音频转写/v1/modelsGET列出可用模型/healthGET健康检查 已加载模型/docsGETSwagger 交互式 API 文档模型别名与适用场景两套服务各自维护一份MODEL_CONFIGS示例版见 examples/openai_api/server.py打包版见 funasr/bin/_server_app.py 与 funasr/cli.py常用别名如下别名模型构成适用场景sensevoiceSenseVoiceSmall FSMN-VAD示例服务启动默认多语言快速转写paraformerparaformer-zh FSMN-VAD CT 标点中文生产级转写自带标点paraformer-enparaformer-en FSMN-VAD英文转写仅为示例服务别名打包服务无此内建别名fun-asr-nanoFun-ASR-NanoLLM 类 ASR FSMN-VADLangChain 示例使用的模型打包服务优先走 vLLM 引擎失败时回退 AutoModelmoss-transcribe-diarizeOpenMOSS 原生转写/说话人分离适配器离线长音频多人转写原生返回匿名说话人标签勿叠加外部 VAD/说话人模型注意事项服务会把 SenseVoice 输出中的富标签如|...|从返回文本中剥除因此 HTTP 接口不是专门的情感/事件输出接口paraformer-en在打包服务中并非内建别名模型权重许可证需以具体模型为准FunASR 软件的 MIT 许可证不等于每个模型权重的许可证选型参考 docs/model_selection.md。打包服务的spktrue说话人分离开关LangChain 示例的tooldocstring 提到Returns transcribed text with speaker IDs但示例服务本身没有spk表单字段。说话人分离属于打包版funasr-server的能力请求中传spktrue时funasr/bin/_server_app.py 会惰性加载 CAM 说话人模型为非原生分离模型做外部聚类默认False对 MOSS 这类原生带标签的模型则不需要spktrue也不应再叠加外部 VAD/说话人模型。说话人标签是单条录音内部的匿名标签不是跨录音的身份 ID语义边界见 docs/speaker_emotion.md。与 Dify / AutoGen / CrewAI 等其他框架集成由于接口是 OpenAI 兼容的任何支持 OpenAI 音频 API 的框架都可以直接连接examples/langchain/README.mdfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, # FunASR 服务 api_keyunused ) result client.audio.transcriptions.create( modelfun-asr-nano, fileopen(audio.wav, rb) )在 Dify 这类低代码平台中还有两条常用路径OpenAI-API-Compatible 模型提供方在 Dify 的 Settings - Model Provider 中选择 OpenAI-API-Compatible配置 API Base URL 为http://your-server:8000/v1、API Key 填任意占位值、Model Name 填fun-asr-nano然后在应用设置的 Features - Speech to Text 中启用并选择该提供方。HTTP 请求节点 / 自定义工具按 examples/openai_api/WORKFLOWS.md 的 multipart 配方接线——方法POST、URLhttp://funasr-host:8000/v1/audio/transcriptions、Body 类型multipart/form-data、二进制字段file、文本字段modelsensevoice与response_formatverbose_json超时按最长音频时长设置如长文件设 300 秒。Dify/n8n 跑在容器里时localhost指的是工作流容器自身需要配置可达的服务地址。不论走哪条路径请求形状都是同一套 multipart HTTP 约定text即转写结果segments是否可用取决于服务与模型实现见上文verbose_json澄清。关键特性与使用边界examples/langchain/README.md 列出的特性对应到仓库实现上各有明确边界多语言SenseVoiceSmall 覆盖中英日韩及粤语等多语种Fun-ASR-Nano 面向中英日及中文方言口音具体覆盖范围需通过模型文档确认不能从 HTTP 接口反推docs/model_selection.md。说话人分离打包服务spktrue触发外部 CAM 聚类MOSS 提供原生匿名标签示例服务无此字段。词级时间戳verbose_json只是格式选择SDK 的毫秒级sentence_info坐标由服务适配层转换为秒级 segments且不保证是逐词强制对齐。热词增强属 SDK 层能力如funasrCLI 的--hotwords参数见 funasr/cli.py不是示例服务的表单字段打包服务的 vLLM 路径可通过请求字段传入funasr/bin/_server_app.py。本地运行、MIT 协议仓库文档宣称全本地推理、MIT 软件许可证速度与规模类数字如 170x realtime为仓库文档描述建议按自己的硬件与工作负载实测模型别名并不定义通用速度指标。生产化注意事项与故障排查把语音能力接入 Agent 前需要注意几个工程边界鉴权与暴露服务无内建鉴权与上传限制api_keyunused不做任何校验对外共享前必须配置 TLS、网关鉴权、上传/超时/限流与音频留存策略examples/openai_api/SECURITY.md。模型预载首次请求会下载并加载权重可能很慢用--model启动预载并用/health作为就绪探针。响应字段示例服务duration是generate()周边的耗时秒不是音频时长打包服务duration是音频时长。消费时间戳前先核对 examples/openai_api/CLIENTS.md 的结果契约。常见问题速查源自 examples/openai_api/README.md 与 examples/openai_api/CLIENTS.md症状处理SDK 报缺少鉴权本地开发传任意占位api_key400 unknown model调/v1/models使用返回的别名之一请求超时增大客户端超时或拆分超长录音首次请求很慢模型可能正在加载用--model预载CUDA 不可用先--device cpu验证 API 链路端口被占用换--port 9000并同步修改客户端 base_url相关资源围绕FunASR 作为 Agent 语音能力这条主线仓库内还提供了这些可直接查阅的配套文档examples/openai_api/README.mdOpenAI 兼容服务完整指南Quick Start、Docker/Kubernetes 部署、配置参数表docs/agent_integration.mdHTTP 服务、SDK/curl、MCP、桌面语音输入、字幕生成等多条 Agent 集成路径examples/openai_api/CLIENTS.mdPython/JS SDK、Agent Tool、响应格式与生产清单examples/openai_api/WORKFLOWS.mdDify、n8n、webhook worker 的低代码接线配方docs/python_api.md进程内AutoModel.generate()的 Python SDK 用法examples/mcp_server/README.md把 FunASR 暴露为本地 MCP 工具【免费下载链接】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），仅供参考
