litellm 语音交互落地指南：3 个端点跑通实时语音转写与语音合成-编程实验室

litellm 语音交互落地指南：3 个端点跑通实时语音转写与语音合成

【免费下载链接】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

本文以 litellm 网关为例，演示如何用一个代理进程同时打通 litellm 语音转写、litellm 语音合成和全双工 realtime 语音会话三条链路。适合有编程基础、没接触过 litellm 的开发者照做：装依赖、改配置、起服务，最后用 3 个 HTTP/WebSocket 端点完成一次完整的"听-想-说"闭环。

能力总览：网关给你暴露的 3 条语音端点

litellm 的 proxy 把各厂商的音频 API 统一成 OpenAI 格式，你只需要记住 3 个入口（端点定义见 litellm/proxy/proxy_server.py）：

端点	形态	用途
`/v1/audio/speech`	HTTP POST	语音合成（TTS），流式返回音频
`/v1/audio/transcriptions`	HTTP POST (multipart)	语音转写（STT），Whisper 类接口
`/v1/realtime`	WebSocket	全双工语音会话，支持 OpenAI、Azure、Bedrock、Vertex AI、xAI 等厂商

第三个端点还接受intent=transcription查询参数，表示只开启"转写"模式、不触发回复，适合纯实时语音转写场景（说明见 litellm/realtime_api/README.md）。所有请求都会经过代理的日志链路，长这样：

里程碑 1：注册语音模型，一条配置起代理

先确认依赖，两条命令各装一类：

pip install "litellm[proxy]" # 代理服务本体 pip install pyaudio websockets # 本地麦克风采集与 WebSocket 客户端

代理配置文件里，给每个要用的语音能力起一个"别名"，客户端之后只用别名。下面是三条链路各挂一个模型的写法（仓库自带示例见 proxy_server_config.yaml）：

model_list: - model_name: tts-voice # 语音合成调用时使用的别名 litellm_params: model: openai/tts-1 # 可换 elevenlabs、azure 等厂商 TTS api_key: os.environ/OPENAI_API_KEY - model_name: stt-whisper # 语音转写调用时使用的别名 litellm_params: model: openai/whisper-1 - model_name: realtime-voice # 全双工会话使用的别名 litellm_params: model: openai/gpt-realtime api_key: os.environ/OPENAI_API_KEY

启动并指定代理密钥（客户端后续用它做 Bearer 认证）：

litellm --config proxy_server_config.yaml --port 4000 --master_key sk-1234

预期结果：http://localhost:4000可访问，健康检查返回 200。到这里，网关与各家音频 API 之间的适配层就搭好了。

里程碑 2：两条 HTTP 调用，分别拿到语音和文字

这一段解决"应用开口说话"和"应用听懂用户"两个最小问题。两条 curl 各测一个方向，都指向本地网关，不直连厂商。

语音合成——合成一段中文，存成 mp3 用播放器验证能出声：

curl http://localhost:4000/v1/audio/speech \ -H "Authorization: Bearer sk-1234" \ -H "Content-Type: application/json" \ -d '{"model": "tts-voice", "input": "litellm 网关已就绪", "voice": "alloy"}' \ --output reply.mp3 # 流式写盘，文件即音频结果

语音转写——把一段录音文件转成文字，返回 JSON 文本：

curl http://localhost:4000/v1/audio/transcriptions \ -H "Authorization: Bearer sk-1234" \ -F model=stt-whisper \ -F file=@sample.wav # 16kHz 单声道 WAV 最稳妥

两个接口的参数与 OpenAI 官方文档一致，也就是说你手里现成的 OpenAI 客户端代码改个 base_url 就能切过来。

里程碑 3：接上 /v1/realtime，让 litellm 实时语音转写和语音合成同时发生

HTTP 两条链路是"一问一答"的异步模式；要做出自然对话，得用 WebSocket 全双工端点，音频流进去、文本和音频流同时出来。

连接时通过 query 参数指定模型别名，握手成功后第一个关键动作是发session.update，把音频格式和断句策略告诉服务端：

url = "ws://localhost:4000/v1/realtime?model=realtime-voice" async with websockets.connect(url, additional_headers=headers) as ws: await ws.send(json.dumps({ "type": "session.update", "session": { "modalities": ["text", "audio"], "voice": "alloy", "input_audio_format": "pcm16", # 输入: 16kHz 单声道 "output_audio_format": "pcm16", # 输出: 24kHz 单声道 "turn_detection": { # 服务端 VAD 自动断句 "type": "server_vad", "threshold": 0.5, "silence_duration_ms": 500, }, }, })) # 之后: 持续推送麦克风 PCM 块, 监听 response.audio.delta 播放

事件流按 OpenAI realtime 协议走：response.text.delta出转写文本，response.audio.delta出 base64 音频块。麦克风侧的完整采集、播放、错误处理参考 cookbook/nova_sonic_realtime.py，文本驱动的 agent 形态可看 cookbook/livekit_agent_sdk/main.py。

跑通后的预期现象：说话停顿约半秒后，终端开始打印对方的转写文本，扬声器同步出声；停止说话则无输出。

3 个参数把端到端延迟压下来

链路通了之后，体感延迟主要靠下面三处调，都在session.update或采集参数里：

块大小与采样率：输入保持 16kHz、1024 样本/块（约 64ms 一块）。块越大延迟越高，越小则网络包越多；CHUNK_SIZE = 1024是示例脚本的折中值。
silence_duration_ms：判停静音时长。500ms 偏稳，250ms 左右响应更急，但容易在说话间自然停顿处提前截断。
max_response_output_tokens：限制单轮回复长度（示例取 1024）。回复越长，首包音频来得越晚，对话类场景宁短勿长。

另外两个容易踩的坑：

播放队列要设上限。示例脚本用asyncio.Queue(maxsize=...)（可用环境变量LITELLM_ASYNCIO_QUEUE_MAXSIZE调整），队列无上限时弱网下内存会持续涨。
断连要单独捕获websockets.exceptions.ConnectionClosed，把它和网络超时区分开，方便定位是网关重启还是对端主动断开。