LiveKit Agents 集成 AssemblyAI 流式语音识别livekit-plugins-assemblyai 插件完整实战指南【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents本文以仓库中 livekit-plugins-assemblyai/README.md 为骨架结合该插件源码stt.py与单元测试test_plugin_assemblyai_stt.py系统讲解如何在 LiveKit Agents 实时语音 Agent 中使用 AssemblyAI 的流式语音识别Streaming Speech-to-Text能力。读完本文你将掌握插件的安装与鉴权、模型选型、全部 STT 构造参数的语义与默认值、语言引导、Voice Focus 降噪、上下文透传agent_context、运行期动态调参update_options以及底层 WebSocket 会话与事件流的工作原理可以直接在项目中完成一次低延迟的语音转写接入。插件定位与适用场景livekit-plugins-assemblyai是 LiveKit Agents 官方插件体系中负责听懂用户说什么STT的一环为实时语音 Agent 提供AssemblyAI 流式语音识别Streaming Speech-to-Text支持。其代码位于仓库的 livekit-plugins/livekit-plugins-assemblyai/ 目录核心实现为livekit.plugins.assemblyai.STT类继承自 livekit-agents 的stt.STT基类通过 WebSocket 将音频流式上传到 AssemblyAI并实时回传中间结果interim、最终转写final与端点检测end-of-turn事件。典型应用场景包括电话客服机器人、会议纪要实时转写、语音助手打断barge-in优化、多语种代码切换对话等。该插件强调低延迟源码注释明确指出我们尽可能最小化延迟即使短语以多个 final transcript 形式到达也可以接受见 stt.py 中min_turn_silence默认值的处理逻辑并针对 LiveKit 的端到端end-of-turn模型做了专门适配。安装与前置条件安装插件根据 README.md通过 pip 直接安装pip install livekit-plugins-assemblyai从 pyproject.toml 可以看到该包的元数据约束Python 版本要求3.10.0运行时依赖livekit-agents1.8.0即必须配合仓库中的 livekit-agents 主框架使用许可证Apache-2.0当前版本号由 version.py 动态提供示例中为1.8.0版本管理由 hatchling 构建系统完成。配置 API KeyAssemblyAI 是付费云服务必须提供 API Key。README 给出的方式是设置环境变量export ASSEMBLYAI_API_KEYyour-assemblyai-api-key源码中鉴权解析的逻辑stt.pySTT.__init__为assemblyai_api_key api_key if is_given(api_key) else os.environ.get(ASSEMBLYAI_API_KEY) if not assemblyai_api_key: raise ValueError( AssemblyAI API key is required. Pass one in via the api_key parameter, or set it as the ASSEMBLYAI_API_KEY environment variable )也就是说API Key 有两种注入方式二选一即可环境变量ASSEMBLYAI_API_KEYREADME 推荐方式构造STT时显式传入api_key参数。如果两种方式都未提供构造时会直接抛出ValueError避免运行时才发现未鉴权。插件在连接 WebSocket 时会把该 Key 放入请求头Authorization并携带User-Agent: AssemblyAI/1.0 (integrationLivekit)见_connect_ws。快速开始在 Agent 中接入流式 STT在 livekit-agents 中STT 通常作为AgentSession的stt选项传入与 LLM、TTS 共同构成语音 Agent 的完整链路。最小化示例import os from livekit.agents import AgentSession, Agent from livekit.plugins import assemblyai, openai, cartesia async def entrypoint(ctx): await ctx.connect() session AgentSession( sttassemblyai.STT(), # 流式语音识别 llmopenai.LLM(modelgpt-4o-mini), # 大语言模型 ttscartesia.TTS(), # 语音合成 ) await session.start( roomctx.room, agentAgent(instructions你是一名乐于助人的语音助手。), )注意这里assemblyai.STT()不传api_key即依赖ASSEMBLYAI_API_KEY环境变量。插件包的对外导出面由init.py 定义公开符号包括STT、SpeechStream、logger与__version__同时以Plugin子类AssemblyAIPlugin的方式自动注册到 livekit-agents 的插件体系。模型选型Speech Model 参数model源码内部名为speech_model决定使用哪套 AssemblyAI 流式识别模型可选值与默认值如下类型为字面量枚举见 stt.pySTTOptions与STT.__init__模型值说明universal-streaming-english纯英语流式模型universal-streaming-multilingual多语种流式模型默认开启语言检测u3-rt-proUniversal-3 Pro 实时系列支持高级参数u3-rt-pro-beta-1Universal-3 Pro 实时 Beta-1参数支持与 u3-rt-pro 一致u3-pro已弃用的别名构造时发出 warning 并自动重写为universal-3-5-prouniversal-3-5-pro默认模型属 U3 Pro 参数家族universal-3-6-proU3 Pro 下一代版本参数支持与 3-5-pro 相同仅服务端 ASR 部署不同关键事实由测试用例 test_plugin_assemblyai_stt.py 明确验证不传model时默认值为universal-3-5-pro传入已弃用的u3-pro会被重写为universal-3-5-pro并打印弃用警告u3-rt-pro-beta-1、universal-3-6-pro同样属于 U3 Pro 参数家族。U3 Pro 参数家族边界务必注意prompt、agent_context、previous_context_n_turns、continuous_partials、interruption_delay、voice_focus、voice_focus_threshold、mode、language_codes这些参数仅对 U3 Pro 家族模型u3-rt-pro / u3-rt-pro-beta-1 / universal-3-5-pro / universal-3-6-pro生效。如果搭配universal-streaming-english等旧模型使用源码会在构造时逐项检查并抛出ValueError提示该参数仅支持 U3 Pro 家族模型。STT 构造参数全解语义、默认值与取值范围STT.__init__是配置的核心入口。除api_key与model外主要参数如下结合源码 docstring 与测试验证整理音频输入参数参数默认值说明sample_rate16000音频采样率Hz。插件按此值切分音频缓冲并写入 WebSocket。encodingpcm_s16le音频编码可选pcm_s16le16 位线性 PCM或pcm_mulawµ-law。buffer_size_seconds0.05音频缓冲时长秒决定每个 WebSocket 二进制帧的粒度越小延迟越低。base_urlwss://streaming.assemblyai.comAssemblyAI 流式端点欧盟数据区需改为wss://streaming.eu.assemblyai.com。端点检测End-of-Turn与打断参数参数默认值说明min_turn_silenceU3 Pro 家族下默认100毫秒对置信度高的结束点最小静音时长毫秒即判定为一轮结束。旧参数min_end_of_turn_silence_when_confident已弃用应改用本参数。max_turn_silence未显式设置时跟随min_turn_silence最大静音窗口毫秒超过后强制结束当前轮。end_of_turn_confidence_threshold不设置NOT_GIVEN端点置信度阈值与min_turn_silence/max_turn_silence配合控制轮次收尾。interruption_delay不设置默认 500ms范围 0–1000首个早期 partial 的发出时间毫秒。仅 U3 Pro 家族。值越低barge-in打断场景的首 token 时延越低值越高首个 partial 越可靠。continuous_partials不设置服务端默认开启但开启speaker_labels时服务端会自动关闭长轮次中按约 3 秒节奏额外输出 partial 转录叠加在基线 partial轮次开始 750ms 后一次、静音超过min_turn_silence时各一次之上。仅 U3 Pro 家族。format_turns不设置是否让服务端对轮次转录做格式化标点/大小写。语言参数参数默认值说明language_detection多语种模型与 U3 Pro 家族下默认True否则False是否启用自动语言检测。language_code已弃用单个语言码的旧参数与language_codes互斥使用会打印弃用警告应改用language_codes。language_codes不设置语言引导steering接受单个字符串如es或列表如[en, es]。每个条目接受常见格式en、en-US、english插件会归一化为裸 ISO 639-1 码并按序去重。仅 U3 Pro 家族最多 10 个multi非引导多语种默认必须单独使用不能与其他码组合。语言归一化由_normalize_language_codes实现对超限10或multi混用会在构造/更新时立即抛ValueError而非等到 WebSocket 阶段才报错这是插件刻意做的前置校验避免运行期整场会话被服务端取消。上下文与词汇参数U3 Pro 家族专属参数默认值说明prompt不设置转写提示词用于引导领域术语等。agent_context不设置描述Agent 刚才说了什么的自由文本用于偏置用户回复的转写。上限 1750 字符超长会抛ValueError_MAX_AGENT_CONTEXT_CHARS常量镜像服务端 MAX_PROMPT_CHARS。可通过update_options(agent_context...)每轮更新。previous_context_n_turns不设置使用服务端默认向前携带的对话条目数用户转写与agent_context范围 0–100设为 0 表示完全关闭自动上下文透传。仅连接时设置不可通过update_options修改。agent_context_carryover已弃用旧版上下文透传开关应改用AgentSession(stt_context_options{forward_chat_context: ...})。U3 Pro 家族默认开启assistant 回复自动写入agent_context超过 1750 字符时截断并保留尾部。keyterms_prompt不设置关键术语列表用于稳定识别专有名词。说话人分离与降噪参数参数默认值说明speaker_labels不设置说话人分离diarization开关开启后SpeechData.speaker_id返回A、B等标签。开启会触发能力声明diarizationTrue。max_speakers不设置最大说话人数。domain不设置领域参数如phonecall等配合服务端行为使用。voice_focus不设置Voice Focus 降噪near-field适合耳机/听筒/近讲麦克风far-field适合会议室/笔记本远场麦克风。在音频进入模型前隔离主声源、抑制背景噪声键盘声、风扇声、回声。仅 U3 Pro 家族仅连接时设置。voice_focus_threshold不设置背景抑制强度浮点数 0.0–1.0越大越激进仅在voice_focus启用时生效。仅 U3 Pro 家族仅连接时设置。测试验证了0.0这一最小抑制边界值必须被原样发送而非被真值过滤丢弃。精度/延迟预设参数默认值说明mode不设置服务端默认balancedU3 Pro 家族的精度/延迟预设min_latency最快出字、balanced服务端默认适合语音 Agent、max_accuracy最高精度适合记录/会后转写。仅 U3 Pro 家族仅连接时设置。mode有一个重要联动行为源码_connect_ws与测试共同验证当设置了mode但未显式给出min_turn_silence/max_turn_silence时插件不会注入默认的 100ms 静音窗口而是留空交给服务端按 mode 各自调优静音参数避免插件默认值覆盖预设效果如果显式传了静音参数则显式值优先于 mode 的默认。运行期动态调参update_options 与 UpdateConfiguration真实对话中Agent 需要在每轮之后动态调整转写行为例如每轮更新agent_context、中途切换语言引导、调整打断延迟。插件提供两级update_optionsSTT.update_options(...)插件级可更新buffer_size_seconds、end_of_turn_confidence_threshold、min_turn_silence、max_turn_silence、prompt、agent_context、keyterms_prompt、language_codes、vad_threshold、continuous_partials、interruption_delay。调用后会同步更新自身_opts并通过弱引用集合self._streams广播给所有活跃的SpeechStream。SpeechStream.update_options(...)流级除了更新本地配置还会构造一条{type: UpdateConfiguration, ...}消息放入_config_update_queue由独立的send_config_task协程立即通过活跃 WebSocket 发送给服务端不重连。源码中update_options的实现遵循先校验、后变更原则任何非法值如非 U3 Pro 模型使用language_codes、agent_context超长都会在修改_opts之前抛出ValueError保证配置对象不会处于半更新状态。测试 test_plugin_assemblyai_stt.py 验证了以下动态行为vad_threshold可在构造后通过update_options(vad_threshold0.7)更新且不影响其他已设置的选项局部更新agent_context支持最近一轮覆盖语义连续两次update_options后以最后一次为准通过stt.update_options(agent_context...)会同时把更新传播到已激活的 stream并在其队列中产生UpdateConfiguration消息。此外U3 Pro 家族下chat-context 自动透传默认开启框架收到 assistant 回复ConversationItemAddedEvent时_push_conversation_item会自动把回复文本写入agent_context用于偏置下一次用户输入的转写超过 1750 字符时保留尾部因为回复结尾通常是向用户提出的问题偏置价值最高。若要手动管理可通过AgentSession的stt_context_options{forward_chat_context: ...}关闭。底层原理WebSocket 会话与事件流连接建立_connect_ws每个SpeechStream启动时会向{base_url}/v3/ws发起一次 WebSocket 连接将上述全部配置sample_rate、encoding、speech_model、静音窗口、language_detection、language_codes、prompt、agent_context、vad_threshold、speaker_labels、voice_focus、mode等以 URL query 参数形式发送请求头携带Authorization。连接完成后_run会并行启动三个协程send_task从self._input_ch消费框架送来的音频帧经AudioByteStream按buffer_size_seconds分帧后以二进制帧发送并在发送首帧前锚定流的时间零点self.start_time供后续时间戳换算recv_task循环接收服务端 JSON 消息并交给_process_stream_event处理带 5 秒超时与心跳监测——15 秒无消息时打印告警并区分上游无音频到达与下游卡住两种故障send_config_task独立发送UpdateConfiguration等控制消息保证调参消息不被音频流阻塞。会话生命周期_process_stream_event处理服务端各类消息服务端消息插件行为Begin记录session_id与expires_atUnix 时间戳。SpeechStream.session_id属性可在排查问题时提供给 AssemblyAI 支持团队。SpeechStarted将消息中的流内相对时间戳timestamp毫秒换算为墙上时钟self.start_time timestamp_ms/1000发出START_OF_SPEECH事件并携带精确的speech_start_time。测试验证了timestamp0是合法的流起始不会被误判为缺字段缺省timestamp时回退为消息到达时间。Turn含words/utterance/transcript/end_of_turn依次产生三类事件见下。Termination会话结束记录audio_duration_seconds与session_duration_seconds日志。三级转录事件一次说话轮次中插件按以下顺序对外发出stt.SpeechEventINTERIM_TRANSCRIPT中间结果由累积的words时间戳生成逐词带时间TimedString与置信度PREFLIGHT_TRANSCRIPT预飞行结果基于分块的utterance字段按_last_preflight_start_time过滤出属于当前 utterance 的词便于框架提前启动 LLM 生成预生成FINAL_TRANSCRIPT最终结果当end_of_turn为真时发出使用累积transcript若format_turns开启则要求turn_is_formatted才发最终结果。每轮结束时还会发出END_OF_SPEECH与RECOGNITION_USAGE携带audio_duration供用量统计。另外服务端返回的end_of_turn_confidence会被放入SpeechData.metadata在 U3 Pro 上该值会随 partial 逐渐逼近 1.0调用方可以对它设置阈值在最终结果到来前触发抢先式/预生成式LLM 调用进一步压低端到端延迟。常见问题与调试建议报错AssemblyAI API key is required说明既未设置ASSEMBLYAI_API_KEY环境变量也未传api_key参数按上文两种方式补齐即可。ValueError: ... only supported with the u3-rt-pro, u3-rt-pro-beta-1, universal-3-5-pro, universal-3-6-pro models说明把 U3 Pro 专属参数如voice_focus、mode、agent_context、language_codes用在了旧模型上请切换模型或将参数移除。想降低延迟优先考虑modemin_latency、调低interruption_delay、保持min_turn_silence默认的 100ms 窗口需要注意设置了mode时插件不会主动注入静音默认值。会议室/远场嘈杂环境使用voice_focusfar-field并配合voice_focus_threshold0.0–1.0调节抑制强度。欧盟数据合规将base_url切换为wss://streaming.eu.assemblyai.com。排查服务端问题通过stream.session_id拿到会话 ID连同Begin日志中的expires_at一起提供给 AssemblyAI 支持。结语livekit-plugins-assemblyai把 AssemblyAI 成熟的流式识别能力封装成符合 livekit-agents 规范的 STT 插件安装一条命令、鉴权一个环境变量、接入一行assemblyai.STT()。在此基础上model选型、语言引导language_codes、Voice Focus 降噪、mode延迟/精度预设、agent_context上下文偏置以及运行期update_options动态调参构成了一个面向真实语音交互的完整调优工具箱。文中涉及的参数默认值、模型家族边界、事件流转与校验逻辑均可直接对照仓库源码 stt.py 与测试 test_plugin_assemblyai_stt.py 逐一验证是集成与排障时最可靠的参考依据。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考