LiveKit Agents 集成 DeepgramSTT 与 TTS 插件完整实战指南【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读livekit-plugins-deepgram是 LiveKit Agents 官方插件之一为实时语音 AI Agent 提供 Deepgram 的语音服务接入能力既能通过流式 WebSocket 将说话人音频实时转写为文字STT含 Nova 系列与新一代 Flux V2 模型也能把 Agent 的回复文本合成为可播放的语音TTS含 Aura 与 Flux 系列音色。读完本文你将掌握该插件的安装与鉴权方式、STT/TTS 两大类共四个入口类STT、STTv2、TTS、TTSv2的完整参数体系与典型用法并能理解其底层 WebSocket 连接管理、事件映射与用量上报机制。一、插件定位与能力总览该插件是 LiveKit Agents 官方插件家族的一员与 pyproject.toml 中描述一致Agent Framework plugin for services using Deepgrams API。它依赖livekit-agents[codecs]1.8.0与numpy1.26要求 Python 3.10 及以上采用 Apache-2.0 协议发布。从包入口 livekit/plugins/deepgram/init.py 可以看出插件对外导出四组核心能力入口类所属模块面向 API典型模型STTstt.pyv1 Listen Streaming / RESTnova-3默认STTv2stt_v2.pyv2 Flux Listenflux-general-en默认TTStts.pyv1 SpeakAuraaura-2-andromeda-en默认TTSv2tts_v2.pyv2 SpeakFlux TTSflux-alexis-en默认同时导出了DeepgramModels、DeepgramLanguages、TTSModels、FluxTTSModels等类型别名见 models.py模块加载时会自动通过Plugin.register_plugin(DeepgramPlugin())完成插件注册。二、安装按官方文档 README.md 的说明直接通过 pip 安装即可pip install livekit-plugins-deepgram安装后包内会自动注册为 LiveKit Agents 插件依赖livekit-agents[codecs]1.8.0codecs 扩展提供了音频编解码能力并在包入口完成插件注册无需额外手动初始化。若使用 uv 管理环境也可参考仓库根目录的 pyproject.toml 与 uv.lock 以锁定依赖版本。三、前置条件API Key 配置使用前需要申请 Deepgram API Key并设置为环境变量export DEEPGRAM_API_KEYyour_deepgram_api_key这一约定在源码中被严格执行STT、STTv2、TTS、TTSv2四个类的构造函数都支持api_key参数未显式传入时则读取DEEPGRAM_API_KEY环境变量两者都没有时直接抛出ValueError。以 stt.py 为例deepgram_api_key api_key if is_given(api_key) else os.environ.get(DEEPGRAM_API_KEY) if not deepgram_api_key: raise ValueError( Deepgram API key is required, either as argument or set DEEPGRAM_API_KEY environment variable )TTS 侧同样如此见 tts.py。因此生产环境推荐只设置环境变量把密钥排除在代码仓库之外。四、语音识别Deepgram STT 深入使用4.1 快速上手接入 AgentSessionSTT 实现了stt.STT抽象基类声明的能力包括流式转写streamingTrue、中间结果interim_results、说话人分离diarization、词级对齐转录aligned_transcriptword以及关键词keytermsTrue。在 Agent 中最常见的是把它作为AgentSession的stt参数传入例如仓库示例 examples/avatar/agent.py 和 examples/hotel_receptionist/agent.pyfrom livekit.agents import AgentSession, Agent, RoomInputOptions from livekit.plugins import deepgram session AgentSession( sttdeepgram.STT(), llm..., tts..., )更简洁的写法是直接使用模型描述字符串deepgram/nova-3LiveKit Inference 机制会把provider/model形式的字符串自动解析为对应插件实例这一点在仓库示例中随处可见例如 examples/homepage/agent.py 默认stt_model: str deepgram/nova-3examples/data_capture_sim/agent.py、examples/frontdesk/agent.py 亦采用inference.STT(deepgram/nova-3)的写法。4.2 STT 构造函数完整参数STT构造函数的参数非常丰富默认值与说明如下对应 stt.py参数默认值说明modelnova-3识别模型支持DeepgramModels中的全部取值见下文languageen-US识别语言如zh-CN、en-US、ja、ko、multi等detect_languageFalse是否启用自动语言检测仅非流式 REST 模式支持interim_resultsTrue是否返回中间非最终转写结果punctuateTrue是否添加标点开启后对 turn detector 更友好smart_formatFalse智能格式化数字、日期等sample_rate16000音频采样率Hzno_delayTrue配合 smart_format不必等整段序列完成即返回结果endpointing_ms25判定语音结束的静音时长毫秒设为 0 禁用enable_diarizationFalse说话人分离仅流式模式支持filler_wordsTrue是否保留语气词um、uh 等默认开启以提升 turn detector 精度keywordsNOT_GIVEN(关键词, 权重)元组列表提升识别准确率仅适用于 Nova-2/Nova-1/Enhanced/BaseNova-3 需改用keytermkeytermNOT_GIVEN关键词提示Keyterm Prompting仅 Nova-3 支持tagsNOT_GIVEN请求标签用于用量统计上报单个 tag 不超过 128 字符profanity_filterFalse是否过滤不雅词redactNOT_GIVEN脱敏配置支持pci、numbers、ssn、true或列表api_key环境变量Deepgram API Keybase_urlhttps://api.deepgram.com/v1/listen服务端点可覆盖numeralsFalse是否输出数字形式mip_opt_outFalse是否退出模型改进计划MIPvad_eventsTrue是否启用 VAD 事件说话开始SpeechStartedutterance_end_msNone静音达到该时长后触发UtteranceEnd需要interim_resultsTruedictationFalse听写模式将口语标点指令comma 等转为标点replaceNone词典替换如{hello: hi}searchNone在转写中检索指定词并返回置信度注意两个模型兼容性约束见 stt.py 的_validate_keytermNova-3 模型使用keywords会直接抛出ValueError反之非 Nova-3 模型使用keyterm也会报错。此外keyterms参数已弃用请统一使用keyterm。4.3 模型与语言清单DeepgramModels见 models.py涵盖 nova 系列nova、nova-2 各垂直场景、nova-3 系列、enhanced 系列、base 系列、whisper 系列及flux-general-en。其中部分 nova-2 垂直模型如nova-2-meeting、nova-2-finance、nova-2-medical、nova-2-drivethru等仅支持英语当传入其他语言时会自动回退到nova-2-general并给出告警日志见 stt.py。DeepgramLanguages支持zh、zh-CN、zh-TW、zh-HK、en、en-US、en-GB、fr、de、ja、ko、ru、es、pt-BR、hi、multi等 35 个语言标识满足多语言 Agent 场景。4.4 流式事件与 turn 检测SpeechStreamstt.py 起把 Deepgram WebSocket 消息映射为 LiveKit 标准 STT 事件SpeechStarted→START_OF_SPEECH开始说话Resultsis_finalfalse→INTERIM_TRANSCRIPT中间结果Resultsis_finaltrue且speech_final→FINAL_TRANSCRIPT后跟END_OF_SPEECH最终结果与说话结束UtteranceEnd→END_OF_SPEECH当配置了utterance_end_ms时触发。源码中还对两类边界情况做了兜底若收到带文本的转写却没有SpeechStarted会补发START_OF_SPEECH事件见 stt.py只有收到过SpeechStarted或非空转写才在端点处结束本轮说话见 stt.py。此外aligned_transcriptword能力意味着转写会附带词级时间戳与置信度供下游做字幕对齐或延迟分析。4.5 非流式识别预录音频STT还支持一次性识别预录音频_recognize_impl会把音频 buffer 编码为 WAV通过POST /v1/listenREST 接口上传见 stt.py请求头携带Authorization: Token {api_key}超时与连接错误分别映射为APITimeoutError、APIStatusError、APIConnectionError。语言检测detect_languageTrue仅在此路径生效流式模式不支持。五、新一代 FluxSTTv2 深入使用STTv2stt_v2.py面向 Deepgram v2 Flux API默认模型flux-general-en另有flux-general-multi多语言。其显著差异包括仅支持流式_recognize_impl直接抛NotImplementedError提示需配合 StreamAdapter 使用见 stt_v2.py端到端静音检测阈值新增eager_eot_threshold默认关闭取值建议 0.3~0.9用于预生成/抢先打断、eot_threshold说话结束阈值范围 0.5~0.9默认 0.7、eot_timeout_ms结束检测超时默认 3000三者共同支撑更细腻的轮次切换语言提示language_hint列表仅对flux-general-multi生效其他模型会打印告警并忽略带内动态配置Flux 支持通过Configure消息在连接中动态调整阈值、keyterm、语言提示而numerals、profanity_filter、redact、model、sample_rate等参数只能在连接时生效变更会触发优雅重连见 stt_v2.py事件模型更丰富基于TurnInfo事件驱动包含StartOfTurn、Update、EagerEndOfTurn触发PREFLIGHT_TRANSCRIPT预生成事件、TurnResumed、EndOfTurn天然适配“抢先合成”场景见 stt_v2.py。六、语音合成Deepgram TTS 深入使用6.1 TTSAura 系列TTStts.py默认模型aura-2-andromeda-en声明能力streamingTrue。主要参数参数默认值说明modelaura-2-andromeda-enAura 音色模型见TTSModels清单encodinglinear16音频编码sample_rate24000采样率Hzbit_rateNone压缩编码如 mp3的码率base_urlhttps://api.deepgram.com/v1/speakv1 合成端点word_tokenizer基础WordTokenizer文本分词器决定流式合成的切分粒度mip_opt_outFalse是否退出模型改进计划TTSModelsmodels.py提供 40 个 Aura-2 英语音色与十余个 Aura-1 英语音色。两条合成路径流式路径stream()→SynthesizeStream把文本按词切分后逐词发送{type:Speak,text:...}消息段末发送Flush收到服务端Flushed后结束该段见 tts.py批式路径synthesize()→ChunkedStream通过POST /v1/speak一次性提交{text: ...}以containernone返回裸音频流见 tts.py。实现上 TTS 通过ConnectionPool复用 WebSocket 连接最长 1 小时并实现prewarm()预热连接update_options()修改模型/编码/采样率等连接级参数时会invalidate()连接池以保证新参数生效见 tts.py。关闭连接时会先发送Flush与Close并等待服务端确认避免残留会话引发 429见 tts.py。6.2 TTSv2Flux TTSTTSv2tts_v2.py面向/v2/speak端点默认音色flux-alexis-en模型名遵循flux-{voice}-{language}格式。值得注意的编码约束见 tts_v2.py流式路径仅支持裸 PCMlinear16因为 LiveKit 管线只能解码linear16/mp3/opus/flac/aac中的部分格式压缩编码mp3、opus、flac、aac仅用于批式synthesize()路径bit_rate同理服务端提供的mulaw/alaw编码目前管线不可播放源码中明确未列入支持表。七、源码级机制解析7.1 统一的 URL 构建器所有连接参数最终由 _utils.py 的_to_deepgram_url编码为查询串布尔值转为小写字符串、keywords转为词:权重列表、replace转为原词:替换词列表并根据websocket标志自动在http/https与ws/wss之间切换 scheme。这也是为什么base_url既可以是 https 也可以是 wss。7.2 连接保活与自动重连流式 STT 的_run循环stt.py同时运行三个任务send_task按 50ms 音频块转发 PCM 数据结束时发送Finalize/CloseStreamrecv_task解析服务端消息若连接被非预期关闭则抛出APIStatusError触发重连keepalive_task每 5 秒发送一次{type:KeepAlive}保证空闲连接不被服务端回收。update_options会设置_reconnect_event主循环据此优雅地重连并携带最新参数。7.3 用量上报两个 STT 流都内置PeriodicCollector见 _utils.py每 5 秒把累积的音频时长以RECOGNITION_USAGE事件上报给 LiveKit 遥测体系见 stt.py。v1 实现还会在连接关闭时补报“WebSocket 存活时长与已上报音频时长的差额”因为 Deepgram 按连接存活时间计费而不仅仅是音频时长见 stt.py保证计费口径与上报口径一致。7.4 动态关键词session keytermsv1 与 v2 的 STT 都实现了_update_session_keyterms框架在会话中动态注入关键词时会与用户层keyterm去重合并后下发。v1 实现中若用户正在说话会把新关键词延迟到END_OF_SPEECH再应用避免打断当前转写见 stt.pyv2 则因为 Flux 支持带内Configure可以安全地中途应用见 stt_v2.py。八、完整示例最小语音 Agent把 STT 与 TTS 组合进一个最小 Agent参照 examples/avatar/agent.py 的结构import os from livekit import rtc from livekit.agents import Agent, AgentSession, RoomInputOptions from livekit.plugins import deepgram, openai, cartesia # DEEPGRAM_API_KEY 通过环境变量提供 agent Agent( instructions你是一个简洁的语音助手。, ) session AgentSession( sttdeepgram.STT(modelnova-3, languagezh-CN), llmopenai.LLM(modelgpt-4o-mini), ttscartesia.TTS(modelsonic-2), ) async def main(room: rtc.Room) - None: await session.start( roomroom, agentagent, room_input_optionsRoomInputOptions(audioTrue, videoFalse), ) # 将 main 挂接到 LiveKit Worker 或房间事件循环中如需更低时延的轮次切换可改用 Flux 组合sttdeepgram.STTv2(modelflux-general-multi, eot_threshold0.7, eager_eot_threshold0.5)配合ttsdeepgram.TTSv2(modelflux-alexis-en)实现端到端 Deepgram 方案。九、注意事项与最佳实践API Key 安全优先使用DEEPGRAM_API_KEY环境变量避免在代码或日志中明文出现源码在异常处理中有意不把请求头含 Token链入异常 repr防止密钥泄漏见 stt.py。模型与关键词的匹配Nova-3 用keytermNova-2 及更早用keywords混用会抛异常。流式 vs 非流式语言检测detect_language仅 REST 预录路径可用流式场景请显式指定language否则SpeechStream构造会抛ValueError见 stt.py。Flux v2 则完全不支持非流式。编码选型Flux TTS 流式路径只用linear16需要压缩格式时走批式synthesize()。标点与语气词punctuateTrue与filler_wordsTrue是官方默认值前者提升 turn detector 效果后者避免语气词被误判为语音结束两者共同影响打断与轮次质量。十、进一步探索插件声明与依赖pyproject.toml模型/语言/音色完整清单models.pyv1 流式 STT 实现stt.pyFlux v2 STT 实现stt_v2.pyAura TTS 实现tts.pyFlux TTS 实现tts_v2.py仓库内的实际用法示例examples/avatar/agent.py、examples/hotel_receptionist/agent.py、examples/drive_thru/agent.py结合仓库中的示例与源码你可以在自己的实时语音 Agent 中直接替换stt/tts为deepgram.STT/deepgram.TTS或 v2 版本快速获得 Deepgram 的流式转写与合成能力。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考