用litellm搭建语音交互系统的完整指南从实时语音转写到自然语音合成一次跑通【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm摘要如果你正在为接哪个语音API、写几套适配代码、怎么跟踪成本发愁这篇指南能帮你在半小时内把整套流程跑通。文章基于开源项目litellmLiteLLM它用一套统一的OpenAI格式接口连接100大模型语音识别、语音合成、实时对话都能在同一个网关下完成。我会从实际场景切入讲清楚选型思路再带你走完环境准备→网关配置→实时转写→语音合成→效果验收的完整落地路径最后分享几个我踩过的坑。一、语音功能开发者的真实困境三个 API三套写法一锅乱麻做语音交互的开发者大多经历过这样的夜晚你手里握着三四家厂商的语音API——想用某云厂商的低延迟实时转写又想用另一家的自然语音合成还想着哪天把底层大模型从 A 家换成 B 家。于是你开始写适配层azure_speech.py、aws_transcribe.py、openai_tts.py……每个文件一套鉴权逻辑、一套消息格式、一套错误处理。功能是跑通了但代码里到处是 if-else改一个供应商就要动三处代码成本追踪更是靠 Excel 手工记账。这不是某个团队的特例而是几乎所有多模型接入项目的通病模型越多集成的复杂度就呈指数增长。有没有一种方式让语音转写、语音合成、实时对话这些能力都走同一个接口、同一套鉴权、同一份日志这就是本篇文章的主角——litellmLiteLLMAI Gateway要解决的问题。二、为什么选 litellm 当语音网关先看懂它解决的核心问题litellm 的核心定位是一句话Rust 内核 Python SDK 的极速 AI 网关用 OpenAI 格式调用 100 LLM API。你可以把它理解成一个翻译层——你的业务代码永远只说 OpenAI 的话至于背后是 Bedrock 的 Nova Sonic、OpenAI 的 Realtime、还是 Azure 的 GPT-Realtime都由网关去翻译和转发。对照一下三种常见方案你就明白它强在哪对比维度直接接各家 SDK自研适配层litellm 网关接入新模型成本每加一家重写一遍长期维护成本高改一行 YAML 配置语音文本接口统一各写各的需要自己抽象原生统一 OpenAI 格式成本/用量追踪无自己造轮子内置后台可视化负载均衡与故障转移无自己写重试内置路由器自动切换团队/密钥管理无无虚拟密钥预算控制用说人话的方式理解litellm 把调用什么模型和怎么调用彻底解耦。你的前端代码只认ws://localhost:4000/v1/realtime?modelbedrock-sonic这一个地址换模型只改 URL 里的 model 参数别的什么都不用动。在语音场景里这个优势会被放大到极致——因为语音服务往往比文本模型更碎片化AWS 有 Nova SonicOpenAI 有 Realtime APIxAI 有 Grok VoiceAzure 有自己的实时语音通道。你要统一它们litellm 的litellm/realtime_api/目录下已经内置了 OpenAI、Azure、Bedrock、xAI、Vertex 的实时协议转换你几乎不需要写一行协议代码。三、从 0 到 1 落地四个里程碑跑通全链路语音交互接下来我们按准备 → 配置 → 跑通第一个效果 → 进阶优化的节奏一步步来。每个里程碑结束你都能看到可验证的成果。里程碑 1环境准备——两个依赖一个仓库先把 litellm 仓库克隆到本地git clone https://gitcode.com/GitHub_Trending/li/litellm cd litellm然后安装核心依赖和语音场景需要的两个库pip install -r requirements.txt pip install pyaudio websockets这里多说一句为什么需要pyaudio和websockets前者负责从麦克风采集音频、向扬声器播放音频后者负责和网关建立 WebSocket 长连接——litellm 的实时语音走的就是 WebSocket 通道而不是普通的 HTTP 请求。这两个库装好你就有了一台能听会说的机器。里程碑 2网关配置——三行 YAML 挂上一个语音模型litellm 的网关配置文件是仓库根目录的proxy_server_config.yaml。语音模型的注册方式和文本模型完全一样以 AWS Bedrock 的 Nova Sonic 为例model_list: - model_name: bedrock-sonic # 业务侧使用的名字随意起 litellm_params: model: bedrock/amazon.nova-sonic-v1:0 aws_access_key_id: your_aws_key aws_secret_access_key: your_aws_secret region_name: us-east-1注意model_name和litellm_params.model的区别前者是你业务代码里用的别名后者是 litellm 理解的真实模型路径。别名的价值在于未来你把 Nova Sonic 换成别的模型只需改litellm_params这一块业务代码零改动。保存配置后启动网关litellm --config proxy_server_config.yaml --port 4000看到类似Uvicorn running on http://0.0.0.0:4000的输出网关就绪了。这个配置文件的完整结构包括负载均衡、缓存、预算等进阶项你可以在仓库根目录的proxy_server_config.yaml里对照查看——它本身就是一份很好的配置参考文档。里程碑 3跑通第一个效果——对着麦克风说一句话听到 AI 回话现在到了最有成就感的一步。仓库的cookbook/nova_sonic_realtime.py是一个开箱即用的实时语音客户端它实现了完整的麦克风采集 → 流式传输 → 服务端语音检测 → 语音合成回放闭环。直接运行python cookbook/nova_sonic_realtime.py对着麦克风说一句话几秒后你就能从扬声器里听到 AI 的语音回复。这个脚本里有几个关键点值得看懂音频参数要和模型匹配。脚本开头定义了这样一段INPUT_SAMPLE_RATE 16000 # Nova Sonic 期望 16kHz 输入 OUTPUT_SAMPLE_RATE 24000 # Nova Sonic 输出 24kHz CHANNELS 1 FORMAT pyaudio.paInt16为什么输入输出采样率不一样因为 Nova Sonic 的音频处理管线是16kHz 进、24kHz 出——输入采样率过高纯属浪费带宽输出采样率过低则音质受损。如果你换成别的语音模型第一件事就是查它的规格表把这两个值改对。会话配置控制AI 的性格和耳朵。脚本里的session.update消息值得逐行体会session_update { type: session.update, session: { instructions: 你是一个友好的助手。保持回答简短且对话式。, voice: matthew, temperature: 0.8, max_response_output_tokens: 1024, modalities: [text, audio], input_audio_format: pcm16, output_audio_format: pcm16, turn_detection: { type: server_vad, threshold: 0.5, # 音量阈值多大声音算开始说话 prefix_padding_ms: 300, # 语音开始前的缓冲 silence_duration_ms: 500 # 安静多久算说完了 } } }turn_detection就是服务端语音活动检测VAD——它决定了 AI 什么时候开始听、什么时候觉得你说完了。silence_duration_ms: 500表示你停顿超过半秒AI 就认为你结束发言并开始回复。调小这个值对话更敏捷调大则更适合语速慢、爱停顿的用户。下图是 litellm 的产品定位示意图可以看到语音转写、成本追踪、护栏、负载均衡都是同一套网关能力图litellm 网关把多模型接入、成本追踪、护栏等能力统一在一个入口语音交互只是其中之一。里程碑 4进阶——把实时语音接进 LiveKit做真正的语音 Agent如果你不满足于命令行对话想把语音能力接进 LiveKit 这类实时通信平台仓库的cookbook/livekit_agent_sdk/main.py提供了一个更工程化的参考实现——它演示的是通过 litellm 网关调用 xAI 的实时语音模型。它的核心逻辑其实只有两步。第一步通过 WebSocket 发送用户消息await ws.send(json.dumps({ type: conversation.item.create, item: { type: message, role: user, content: [{type: input_text, text: user_message}] } }))第二步请求 AI 以文本音频双模态回复await ws.send(json.dumps({ type: response.create, response: {modalities: [text, audio]} }))然后监听response.audio.delta事件流式接收音频分片。注意 URL 的构造方式ws://localhost:4000/v1/realtime?modelgrok-voice-agent——model 参数指向你在配置里定义的别名这意味着把 xAI 换成 OpenAI 或 Azure 的实时模型只需要改配置文件和这一个参数。四、实战效果验收拿数据说话跑通之后怎么证明这套系统真的能上生产我建议从三个维度验收1. 延迟体感。VAD 参数调优后从用户停止说话到AI 开口的间隔应该控制在 1 秒以内。这个数据可以在代码里埋点统计也可以直接用秒表体感测。如果偏慢优先检查silence_duration_ms是否过大、模型是否距离用户太远地理距离对 WebSocket 延迟影响明显。2. 成本可视化。litellm 网关自带用量追踪——每个模型、每个虚拟密钥的 token 消耗和费用都自动记录。你可以接一个 Langfuse 之类的可观测平台把每一次语音交互的链路完整记录下来图一次语音交互在 Langfuse 上的完整追踪——首 token 延迟 2.39 秒、成本精确到小数点后六位。3. 运维审计。如果多人协作或对外提供服务网关内置的审计日志会记录每一次密钥创建、轮换、删除操作图审计日志界面谁在什么时间改了哪张表的哪条数据一目了然。五、避坑指南三个我踩过的坑帮你绕开坑一说话没反应一看是采样率不匹配。把INPUT_SAMPLE_RATE改成 44100 甚至 48000 想提高音质结果服务端根本解析不了。原因实时语音服务端通常对输入采样率有硬性要求Nova Sonic 就要 16kHz。解法以模型规格文档为准改完还要重启脚本让 PyAudio 重新打开设备。采样率影响的是能不能被识别而不是音质好坏。坑二VAD 太灵敏AI 总抢话。用户只是咳嗽一声或清了清嗓子AI 就以为对方说完了。原因threshold阈值设得太低。解法把threshold从 0.5 提到 0.7同时把prefix_padding_ms适当调大——它决定了语音开头的短暂音量波动会不会被当成说话开始。记住这个调节口诀用户抢话就调高 threshold用户说话被截断就调大 silence_duration_ms。坑三WebSocket 莫名断连没有错误提示。原因往往在两端一是代理或防火墙对长连接的闲置超时二是服务端消息超过客户端设置的max_size。脚本里已经预设了max_size10 * 1024 * 102410MB但如果你在网络环境复杂的公司内网建议再给连接加上心跳机制。连接断开的兜底处理参考脚本底部的这段except websockets.exceptions.ConnectionClosed: print(\n✗ Connection closed) except Exception as e: print(f\n✗ Error receiving messages: {e})六、结语从会调接口到拥有自己的语音产品回到开头的那个深夜场景——现在你的代码里不再有三套 SDK、三个适配文件取而代之的是一份 YAML 配置和几个别名。litellm 的价值不在于它支持 100 模型这个数字而在于它把接入成本从按天计算压缩到按分钟计算同时把成本追踪、负载均衡、审计这些生产级能力变成了开箱即用的默认项。如果你正在做语音助手、语音客服、智能硬件交互或者只是想给现有应用加一个说话的能力我的建议路径是先用cookbook/nova_sonic_realtime.py跑通第一个对话建立整体直觉再读cookbook/livekit_agent_sdk/main.py理解如何把实时语音嵌入真实业务最后回头精读proxy_server_config.yaml把负载均衡、预算、护栏一个个加上——这才是 litellm 真正拉开差距的地方。语音交互的下一个风口不会是谁能调通 API而是谁能把体验和成本控制到极致。而 litellm已经帮你把最难的那部分路铺好了。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/8/20 16:00:17 · 阅读 1.2k 用litellm搭建语音交互系统的完整指南：从实时语音转写到自然语音合成一次跑通
用litellm搭建语音交互系统的完整指南从实时语音转写到自然语音合成一次跑通【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm摘要如果你正在为接哪个语音API、写几套适配代码、怎么跟踪成本发愁这篇指南能帮你在半小时内把整套流程跑通。文章基于开源项目litellmLiteLLM它用一套统一的OpenAI格式接口连接100大模型语音识别、语音合成、实时对话都能在同一个网关下完成。我会从实际场景切入讲清楚选型思路再带你走完环境准备→网关配置→实时转写→语音合成→效果验收的完整落地路径最后分享几个我踩过的坑。一、语音功能开发者的真实困境三个 API三套写法一锅乱麻做语音交互的开发者大多经历过这样的夜晚你手里握着三四家厂商的语音API——想用某云厂商的低延迟实时转写又想用另一家的自然语音合成还想着哪天把底层大模型从 A 家换成 B 家。于是你开始写适配层azure_speech.py、aws_transcribe.py、openai_tts.py……每个文件一套鉴权逻辑、一套消息格式、一套错误处理。功能是跑通了但代码里到处是 if-else改一个供应商就要动三处代码成本追踪更是靠 Excel 手工记账。这不是某个团队的特例而是几乎所有多模型接入项目的通病模型越多集成的复杂度就呈指数增长。有没有一种方式让语音转写、语音合成、实时对话这些能力都走同一个接口、同一套鉴权、同一份日志这就是本篇文章的主角——litellmLiteLLMAI Gateway要解决的问题。二、为什么选 litellm 当语音网关先看懂它解决的核心问题litellm 的核心定位是一句话Rust 内核 Python SDK 的极速 AI 网关用 OpenAI 格式调用 100 LLM API。你可以把它理解成一个翻译层——你的业务代码永远只说 OpenAI 的话至于背后是 Bedrock 的 Nova Sonic、OpenAI 的 Realtime、还是 Azure 的 GPT-Realtime都由网关去翻译和转发。对照一下三种常见方案你就明白它强在哪对比维度直接接各家 SDK自研适配层litellm 网关接入新模型成本每加一家重写一遍长期维护成本高改一行 YAML 配置语音文本接口统一各写各的需要自己抽象原生统一 OpenAI 格式成本/用量追踪无自己造轮子内置后台可视化负载均衡与故障转移无自己写重试内置路由器自动切换团队/密钥管理无无虚拟密钥预算控制用说人话的方式理解litellm 把调用什么模型和怎么调用彻底解耦。你的前端代码只认ws://localhost:4000/v1/realtime?modelbedrock-sonic这一个地址换模型只改 URL 里的 model 参数别的什么都不用动。在语音场景里这个优势会被放大到极致——因为语音服务往往比文本模型更碎片化AWS 有 Nova SonicOpenAI 有 Realtime APIxAI 有 Grok VoiceAzure 有自己的实时语音通道。你要统一它们litellm 的litellm/realtime_api/目录下已经内置了 OpenAI、Azure、Bedrock、xAI、Vertex 的实时协议转换你几乎不需要写一行协议代码。三、从 0 到 1 落地四个里程碑跑通全链路语音交互接下来我们按准备 → 配置 → 跑通第一个效果 → 进阶优化的节奏一步步来。每个里程碑结束你都能看到可验证的成果。里程碑 1环境准备——两个依赖一个仓库先把 litellm 仓库克隆到本地git clone https://gitcode.com/GitHub_Trending/li/litellm cd litellm然后安装核心依赖和语音场景需要的两个库pip install -r requirements.txt pip install pyaudio websockets这里多说一句为什么需要pyaudio和websockets前者负责从麦克风采集音频、向扬声器播放音频后者负责和网关建立 WebSocket 长连接——litellm 的实时语音走的就是 WebSocket 通道而不是普通的 HTTP 请求。这两个库装好你就有了一台能听会说的机器。里程碑 2网关配置——三行 YAML 挂上一个语音模型litellm 的网关配置文件是仓库根目录的proxy_server_config.yaml。语音模型的注册方式和文本模型完全一样以 AWS Bedrock 的 Nova Sonic 为例model_list: - model_name: bedrock-sonic # 业务侧使用的名字随意起 litellm_params: model: bedrock/amazon.nova-sonic-v1:0 aws_access_key_id: your_aws_key aws_secret_access_key: your_aws_secret region_name: us-east-1注意model_name和litellm_params.model的区别前者是你业务代码里用的别名后者是 litellm 理解的真实模型路径。别名的价值在于未来你把 Nova Sonic 换成别的模型只需改litellm_params这一块业务代码零改动。保存配置后启动网关litellm --config proxy_server_config.yaml --port 4000看到类似Uvicorn running on http://0.0.0.0:4000的输出网关就绪了。这个配置文件的完整结构包括负载均衡、缓存、预算等进阶项你可以在仓库根目录的proxy_server_config.yaml里对照查看——它本身就是一份很好的配置参考文档。里程碑 3跑通第一个效果——对着麦克风说一句话听到 AI 回话现在到了最有成就感的一步。仓库的cookbook/nova_sonic_realtime.py是一个开箱即用的实时语音客户端它实现了完整的麦克风采集 → 流式传输 → 服务端语音检测 → 语音合成回放闭环。直接运行python cookbook/nova_sonic_realtime.py对着麦克风说一句话几秒后你就能从扬声器里听到 AI 的语音回复。这个脚本里有几个关键点值得看懂音频参数要和模型匹配。脚本开头定义了这样一段INPUT_SAMPLE_RATE 16000 # Nova Sonic 期望 16kHz 输入 OUTPUT_SAMPLE_RATE 24000 # Nova Sonic 输出 24kHz CHANNELS 1 FORMAT pyaudio.paInt16为什么输入输出采样率不一样因为 Nova Sonic 的音频处理管线是16kHz 进、24kHz 出——输入采样率过高纯属浪费带宽输出采样率过低则音质受损。如果你换成别的语音模型第一件事就是查它的规格表把这两个值改对。会话配置控制AI 的性格和耳朵。脚本里的session.update消息值得逐行体会session_update { type: session.update, session: { instructions: 你是一个友好的助手。保持回答简短且对话式。, voice: matthew, temperature: 0.8, max_response_output_tokens: 1024, modalities: [text, audio], input_audio_format: pcm16, output_audio_format: pcm16, turn_detection: { type: server_vad, threshold: 0.5, # 音量阈值多大声音算开始说话 prefix_padding_ms: 300, # 语音开始前的缓冲 silence_duration_ms: 500 # 安静多久算说完了 } } }turn_detection就是服务端语音活动检测VAD——它决定了 AI 什么时候开始听、什么时候觉得你说完了。silence_duration_ms: 500表示你停顿超过半秒AI 就认为你结束发言并开始回复。调小这个值对话更敏捷调大则更适合语速慢、爱停顿的用户。下图是 litellm 的产品定位示意图可以看到语音转写、成本追踪、护栏、负载均衡都是同一套网关能力图litellm 网关把多模型接入、成本追踪、护栏等能力统一在一个入口语音交互只是其中之一。里程碑 4进阶——把实时语音接进 LiveKit做真正的语音 Agent如果你不满足于命令行对话想把语音能力接进 LiveKit 这类实时通信平台仓库的cookbook/livekit_agent_sdk/main.py提供了一个更工程化的参考实现——它演示的是通过 litellm 网关调用 xAI 的实时语音模型。它的核心逻辑其实只有两步。第一步通过 WebSocket 发送用户消息await ws.send(json.dumps({ type: conversation.item.create, item: { type: message, role: user, content: [{type: input_text, text: user_message}] } }))第二步请求 AI 以文本音频双模态回复await ws.send(json.dumps({ type: response.create, response: {modalities: [text, audio]} }))然后监听response.audio.delta事件流式接收音频分片。注意 URL 的构造方式ws://localhost:4000/v1/realtime?modelgrok-voice-agent——model 参数指向你在配置里定义的别名这意味着把 xAI 换成 OpenAI 或 Azure 的实时模型只需要改配置文件和这一个参数。四、实战效果验收拿数据说话跑通之后怎么证明这套系统真的能上生产我建议从三个维度验收1. 延迟体感。VAD 参数调优后从用户停止说话到AI 开口的间隔应该控制在 1 秒以内。这个数据可以在代码里埋点统计也可以直接用秒表体感测。如果偏慢优先检查silence_duration_ms是否过大、模型是否距离用户太远地理距离对 WebSocket 延迟影响明显。2. 成本可视化。litellm 网关自带用量追踪——每个模型、每个虚拟密钥的 token 消耗和费用都自动记录。你可以接一个 Langfuse 之类的可观测平台把每一次语音交互的链路完整记录下来图一次语音交互在 Langfuse 上的完整追踪——首 token 延迟 2.39 秒、成本精确到小数点后六位。3. 运维审计。如果多人协作或对外提供服务网关内置的审计日志会记录每一次密钥创建、轮换、删除操作图审计日志界面谁在什么时间改了哪张表的哪条数据一目了然。五、避坑指南三个我踩过的坑帮你绕开坑一说话没反应一看是采样率不匹配。把INPUT_SAMPLE_RATE改成 44100 甚至 48000 想提高音质结果服务端根本解析不了。原因实时语音服务端通常对输入采样率有硬性要求Nova Sonic 就要 16kHz。解法以模型规格文档为准改完还要重启脚本让 PyAudio 重新打开设备。采样率影响的是能不能被识别而不是音质好坏。坑二VAD 太灵敏AI 总抢话。用户只是咳嗽一声或清了清嗓子AI 就以为对方说完了。原因threshold阈值设得太低。解法把threshold从 0.5 提到 0.7同时把prefix_padding_ms适当调大——它决定了语音开头的短暂音量波动会不会被当成说话开始。记住这个调节口诀用户抢话就调高 threshold用户说话被截断就调大 silence_duration_ms。坑三WebSocket 莫名断连没有错误提示。原因往往在两端一是代理或防火墙对长连接的闲置超时二是服务端消息超过客户端设置的max_size。脚本里已经预设了max_size10 * 1024 * 102410MB但如果你在网络环境复杂的公司内网建议再给连接加上心跳机制。连接断开的兜底处理参考脚本底部的这段except websockets.exceptions.ConnectionClosed: print(\n✗ Connection closed) except Exception as e: print(f\n✗ Error receiving messages: {e})六、结语从会调接口到拥有自己的语音产品回到开头的那个深夜场景——现在你的代码里不再有三套 SDK、三个适配文件取而代之的是一份 YAML 配置和几个别名。litellm 的价值不在于它支持 100 模型这个数字而在于它把接入成本从按天计算压缩到按分钟计算同时把成本追踪、负载均衡、审计这些生产级能力变成了开箱即用的默认项。如果你正在做语音助手、语音客服、智能硬件交互或者只是想给现有应用加一个说话的能力我的建议路径是先用cookbook/nova_sonic_realtime.py跑通第一个对话建立整体直觉再读cookbook/livekit_agent_sdk/main.py理解如何把实时语音嵌入真实业务最后回头精读proxy_server_config.yaml把负载均衡、预算、护栏一个个加上——这才是 litellm 真正拉开差距的地方。语音交互的下一个风口不会是谁能调通 API而是谁能把体验和成本控制到极致。而 litellm已经帮你把最难的那部分路铺好了。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考