用 LiveKit Agents 集成 Baseten：STT / TTS / LLM 三合一语音插件实战指南

用 LiveKit Agents 集成 BasetenSTT / TTS / LLM 三合一语音插件实战指南【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents本指南以 livekit-plugins-baseten 插件为主线讲解如何在 LiveKit Agents 语音 Agent 中接入 Baseten 托管的 Whisper Streaming 语音识别、Orpheus / Qwen3 语音合成以及 OpenAI 兼容的大模型推理端点。读完本文你将掌握插件安装、三种端点指定方式、STT/TTS 全部配置参数的含义与源码级原理、Qwen3 语音克隆方案并能直接搭出一条可运行的实时语音对话管线。插件概览与核心能力Baseten 是一个模型托管与推理平台而livekit-plugins-baseten是 LiveKit Agents 框架下的官方插件为 Baseten 上托管的模型提供三类集成STT语音识别连接 Baseten 的 Whisper Streaming WebSocket 端点做实时转写同时支持truss与chain两种部署形态TTS语音合成通过 HTTP 或 WebSocket 调用 Baseten 托管的 Orpheus 3B 等 TTS 模型并额外支持 Qwen3-TTS 的语音克隆协议LLM大模型封装 Baseten 的 OpenAI 兼容推理端点可在 LiveKit Agent 中直接复用工具调用、流式输出等能力。插件源码位于 livekit-plugins/livekit-plugins-baseten/livekit/plugins/baseten对外导出STT、TTS、LLM、SpeechStream、SynthesizeStream以及语音克隆相关的register_voice/list_voices见init.py。安装与前置条件pip install livekit-plugins-baseten插件依赖livekit-agents[openai]1.8.0、aiohttp与livekit要求 Python 3.10具体见 pyproject.toml。使用前需要准备两样东西Baseten API Key推荐通过环境变量注入插件会自动读取BASETEN_API_KEY。从源码看STT、TTS、LLM三者在构造时会依次回退到该环境变量若最终仍未解析到 API Key 会直接抛出ValueError参见 stt.py 与 llm.py。已部署的模型端点你需要先在 Baseten 上把模型部署成 truss 或 chain拿到对应的 model ID / chain ID 或完整端点 URL 来配置插件。端点解析三种方式与优先级STT 插件支持三种方式指定模型端点优先级从高到低为model_endpointmodel_idchain_id三者都没给时再回退到BASETEN_MODEL_ENDPOINT环境变量该逻辑在 stt.py 中有完整实现部署类型URL 模式Trusswss://model-{model_id}.api.baseten.co/environments/production/websocketChainwss://chain-{chain_id}.api.baseten.co/environments/production/websocket其中 truss 与 chain 的 URL 模板在源码中分别定义为_TRUSS_URL_TEMPLATE与_CHAIN_URL_TEMPLATE见 stt.py。Qwen3 系列模型复用了同一套解析规则集中实现在 _endpoint.py 的resolve_endpoint函数中并且会校验协议前缀必须是wss://或ws://。特别提醒若向非本机地址使用明文ws://插件会打印警告提示 API Key 与音频将以未加密形式传输生产环境务必使用wss://。STT接入 Whisper Streaming 实时转写Baseten 官方推荐的 STT 模型是Whisper v3 Turbo – WebSocketWhisper Streaming large-v3。插件通过 WebSocket 连接做实时转写示例代码如下from livekit.plugins import baseten # 1. 使用 truss model IDtruss 部署推荐 stt baseten.STT( api_keyyour-baseten-api-key, # 或设置 BASETEN_API_KEY 环境变量 model_idyour-model-id, languageen, ) # 2. 使用 chain IDchain 部署推荐 stt baseten.STT( api_keyyour-baseten-api-key, chain_idyour-chain-id, languageen, ) # 3. 使用完整端点 URL自定义路由或部署 URL 场景 stt baseten.STT( api_keyyour-baseten-api-key, model_endpointwss://model-{model_id}.api.baseten.co/environments/production/websocket, languageen, )配置参数详解下表完整列出 STT 插件whisper模型路径的全部配置项均对应 stt.py 构造函数签名参数默认值说明api_keyBASETEN_API_KEY环境变量Baseten API Keymodel_endpointBASETEN_MODEL_ENDPOINT环境变量完整 WebSocket URL优先级高于model_id/chain_idmodel_id—Baseten truss 模型 ID自动拼接端点 URLchain_id—Baseten chain ID自动拼接端点 URLlanguageenBCP-47 语言码设为auto启用自动检测language_options[]将自动检测限定到这些语言码如[en, de]。对 1~2 秒的短电话语音比auto更可靠要求 Whisper runtime v0.5.0encodingpcm_s16le音频编码可选pcm_s16le或pcm_mulawsample_rate16000音频采样率Hzenable_partial_transcriptsTrue说话过程中是否输出中间转写结果partial_transcript_interval_s1.0中间转写更新的间隔秒final_transcript_max_duration_s30强制输出最终转写前的最大音频时长秒show_word_timestampsTrue结果中是否包含词级时间戳vad_threshold0.5服务端 VAD 语音概率阈值0.0–1.0vad_min_silence_duration_ms300判定语音结束所需的最小静音时长msvad_speech_pad_ms30检测到的语音前后增加的填充时长ms握手协议与底层实现从源码看每次 WebSocket 连接建立后插件会先发送一条元数据消息其结构必须与 Baseten 服务端的StreamingWhisperInputPydantic 模型完全一致该模型使用extraforbid多传字段会被拒绝见 stt.pywhisper_paramsWhisper 模型参数包括audio_language与show_word_timestampsstreaming_params编码、采样率、中间转写开关与间隔、强制最终转写时长streaming_vad_config服务端 Silero VAD 的阈值、最小静音时长与语音填充时长。language_options只有在显式设置时才会被写入whisper_params注释里特别说明较旧的 Whisper runtime低于 v0.5.0会拒绝未知字段因此默认省略。音频发送采用 512 samples/channel 分帧的AudioByteStream封装为 raw PCM 字节流接收侧对type transcription的消息解析segments与词级时间戳转写文本优先取顶层transcript字段否则拼接各 segment 的text见 stt.py。此外SpeechStream实现了断线自动重连与update_options热更新可动态调整 VAD 阈值、语言等参数。Qwen3 系列STT TTS 的双模型支持Baseten 还托管Qwen3-ASR与Qwen3-TTS它们与 Whisper / Orpheus truss 走的是不同的线上协议wire protocol因此需要通过model参数显式选择——同一个baseten.STT/baseten.TTS类内部会根据model值切换到不同的后端实现Qwen3 后端的协议定义见 models.py 中的STTModels与TTSModels。from livekit.agents import AgentSession from livekit.plugins import baseten session AgentSession( sttbaseten.STT(modelqwen3-asr, model_idyour-qwen3-asr-model-id), ttsbaseten.TTS(modelqwen3-tts, model_idyour-qwen3-tts-model-id, voiceyour-voice), # llm... )两种模型族的协议差异如下modelwhisper/orpheus默认modelqwen3-asr/qwen3-ttsSTT 音频原始二进制 PCMbase64input_audio_buffer.appendSTT 结果message_type/transcripttype: transcription/segments[].textTTS 传输HTTP或带__END__哨兵的 WebSocketsession.config→input.text→input.doneTTS 音色预置音色名如tara已注册的语音克隆默认值随模型联动选择 Qwen3 模型后部分参数默认值会自动切换以匹配各部署自身的默认配置见 stt.py 与 tts.py参数whisper/orpheusqwen3-asr/qwen3-ttslanguageenautoSTT/AutoTTSpartial_transcript_interval_s1.00.5vad_min_silence_duration_ms300500vad_speech_pad_ms30100show_word_timestamps开关需要部署端开启STREAM_ALIGNERmmsvoicetara必填——必须是已注册的克隆音色注意 Qwen3-ASR 的language参数含义与 Whisper 不同它接受 Qwen3-ASR 的规范语言名如English、Cantonese强制指定某个语言同时会锁定输出语言甚至产生翻译效果因此只在确实需要固定口语语言时使用。Qwen3-ASR 协议的详细说明握手帧、base64 音频、Silero VAD 切分 turn、is_final: false的替换式中间结果见 qwen3_stt.py 顶部 docstring。词级时间戳需要部署端同时设置STREAM_ALIGNERmms与STREAM_ALIGNER_DEVICEcuda否则服务端会静默忽略该请求。Qwen3-TTS 语音克隆无内置音色的应对方案Qwen3-TTS Base 版本不附带任何内置说话人不存在tara这样的预置音色。你需要先用 10~20 秒的干净语音注册一个克隆音色再把音色名传给voicefrom livekit.plugins.baseten import list_voices, register_voice await register_voice( model_endpointwss://model-{model_id}.api.baseten.co/environments/production/websocket, namemy_voice, ref_audio_path./reference.wav, ref_textTranscript of the reference audio., ) await list_voices(model_endpoint...) # {voices: [...], uploaded_voices: [...]}register_voice的实现位于 qwen3_tts.py它把参考音频 base64 编码后通过voice.add消息发送给模型端点可附带ref_text与consent默认user_consent字段list_voices则发送voice.list消息返回值中voices是内置音色Base 部署下为空uploaded_voices是当前副本replica上已上传的克隆。必须理解的副本replica限制服务端把上传的音色保存在容器的本地磁盘上因此运行时注册的音色只存在于一个副本容器重启即丢失。如果规模超出单副本测试有两种做法把参考音频烘焙进部署通过REQUIRED_VOICES配置让每个副本启动时都带有该音色每次会话都通过ref_audio/ref_text参数内联克隆。Qwen3-TTS 专属参数以下参数仅对modelqwen3-tts生效定义见 tts.pytask_typeBase语音克隆检查点CustomVoice/VoiceDesign部署使用各自的检查点并暴露预置说话人instructions风格提示词仅CustomVoice/VoiceDesignmax_new_tokens每句生成的音频 token 上限initial_codec_chunk_frames首块大小越大换取更好的起始音质但会牺牲首字延迟x_vector_only_mode仅用说话人嵌入做条件生成跳过参考音频的上下文学习更快但保真度低ref_audio/ref_text内联克隆用的参考音频http(s) URL 或本地文件路径与对应转写文本extra_config最后合并进session.config的字典用于插件版本落后于服务端新字段的场景——注意未识别字段会使整个 config 失效。协议层面Qwen3-TTS 是session.config→input.text可多次→input.doneflush 而非关闭→audio.start/ PCM /audio.done/session.done的状态机见 qwen3_tts.py 顶部 docstring。实现上后端会跨 turn 保持一条温热 WebSocketsession.config是粘性的并内置 15 秒一次的空input.done保活循环避免被服务端空闲超时断开speed被强制为 1.0因为渐进式 PCM 只按原生速度输出。开启word_timestampsTrue时插件会把服务端audio.done里携带的词级对齐信息timestamp_typeword、timestamp_transport_strategysync重算为句子时间轴上的 timed transcript 推送给 LiveKit。TTS接入 Orpheus 语音合成TTS 插件通过 HTTP 调用 Baseten 托管的 TTS 模型如 Orpheus 3B也支持wss://流式端点tts baseten.TTS( api_keyyour-baseten-api-key, model_endpointhttps://model-{model_id}.api.baseten.co/environments/production/predict, voicetara, languageen, )从源码看Orpheus 路径的 TTS 构造函数还支持temperature默认 0.6、max_tokens默认 2000与buffer_size流式时每块字数默认 10等参数见 tts.py。实现细节HTTP 模式ChunkedStream向端点 POST{prompt: ..., voice: ..., temperature: ..., language: ...}以Api-Key头鉴权输出 24 kHz 单声道 PCM见 tts.pyWebSocket 模式连接后先发送{voice, max_tokens, buffer_size}配置消息随后逐句发送文本结束时发送__END__哨兵_END_SENTINEL定义于 tts.py二进制消息直接 push 给输出流。LLMOpenAI 兼容推理端点LLM 插件包装 Baseten 的 OpenAI 兼容推理端点llm baseten.LLM( api_keyyour-baseten-api-key, modelopenai/gpt-oss-120b, )源码层面 llm.py 直接继承livekit.plugins.openai.LLM默认base_url为https://inference.baseten.co/v1因此天然具备 OpenAI 生态的完整能力tool calling、parallel_tool_calls、tool_choice、reasoning_effort、top_p、temperature等。一个细节当model openai/gpt-oss-120b且未显式指定reasoning_effort时插件会自动设置为low以降低推理开销。LLMModels类型别名列出了插件内置建议的模型集合包括deepseek-ai/DeepSeek-R1、deepseek-ai/DeepSeek-V3-0324、meta-llama/Llama-4-Scout-17B-16E-Instruct、meta-llama/Llama-4-Maverick-17B-128E-Instruct、moonshotai/Kimi-K2-Instruct、openai/gpt-oss-120b与Qwen/Qwen3-235B-A22B-Instruct-2507见 models.py但该参数类型为字符串你同样可以传入其他已部署的模型名。完整语音管线示例把三者组合进一个实时语音 Agent需要先把模型部署到 Baseten再运行以下代码完整示例来自 READMEimport os from livekit import agents from livekit.agents import AgentSession, Agent, RoomInputOptions, inference from livekit.plugins import baseten, openai, noise_cancellation from livekit.agents.inference import TurnDetector BASETEN_API_KEY os.getenv(BASETEN_API_KEY) whisper_model_id your-whisper-model-id # 或 chain 部署用 chain_id orpheus_model_id your-orpheus-model-id class Assistant(Agent): def __init__(self) - None: super().__init__(instructionsYou are a helpful voice AI assistant.) async def entrypoint(ctx: agents.JobContext): session AgentSession( sttbaseten.STT( api_keyBASETEN_API_KEY, model_idwhisper_model_id, # 或 chain_idyour-chain-id languageen, enable_partial_transcriptsTrue, ), llmopenai.LLM( api_keyBASETEN_API_KEY, base_urlhttps://inference.baseten.co/v1, modelopenai/gpt-oss-120b, ), ttsbaseten.TTS( api_keyBASETEN_API_KEY, model_endpoint( fhttps://model-{orpheus_model_id} .api.baseten.co/environments/production/predict ), ), vadinference.VAD(), turn_detectionTurnDetector(), ) await session.start( roomctx.room, agentAssistant(), room_input_optionsRoomInputOptions( noise_cancellationnoise_cancellation.BVC(), ), ) await session.generate_reply( instructionsGreet the user and offer your assistance. ) if __name__ __main__: agents.cli.run_app(agents.WorkerOptions(entrypoint_fncentrypoint))这条管线的工作链路为baseten.STTWhisper Streaming WebSocket 实时转写→openai.LLMBaseten 推理端点生成回复→baseten.TTSOrpheus HTTP 合成语音配合inference.VAD与人声活动检测、TurnDetector做对话轮次判断外加noise_cancellation.BVC()做环境噪声消除。如需换成 Qwen3 全链路只需将 STT/TTS 的model分别改为qwen3-asr/qwen3-tts并传入已注册的voice。小结livekit-plugins-baseten的价值在于用一个统一 API 表面覆盖了 Baseten 上多套互不相同的模型协议Whisper Streaming 的原始 PCM WebSocket、Orpheus 的 HTTP/WS 合成、Qwen3-ASR 的 OpenAI-realtime 风格帧与 Qwen3-TTS 的会话式协议均由model参数在内部路由到对应后端实现。配置时牢记三点即可快速上手端点优先用model_endpoint/model_id/chain_id三选一可回退到环境变量、Qwen3-TTS 必须预先注册音色并注意副本生命周期、Whisper 的language_options与词级时间戳需要较新 runtime 或部署端对齐器支持。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考