LiveKit Agents × Speechmatics STT 插件实战语音转写、说话人识别与端点检测全配置指南【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读本文围绕livekit-plugins-speechmatics插件展开它是 LiveKit Agents 框架下接入 Speechmatics 实时语音转写STT能力的官方实现位于仓库 livekit-plugins/livekit-plugins-speechmatics。文章将带你掌握插件的安装与密钥配置、四种端点检测模式EXTERNAL/ADAPTIVE/SMART_TURN/FIXED的选型与代码用法、说话人分离Diarization与输出格式化宏的完整写法并结合源码讲解参数校验规则与底层流式处理原理读完即可在真实语音 Agent 中落地 Speechmatics 语音识别链路。一、插件概览与安装livekit-plugins-speechmatics是 LiveKit Agents 的 Speechmatics 集成插件提供 STT语音识别能力并顺带封装了 Speechmatics 的 TTS语音合成能力。从插件包的 pyproject.toml 可以看到其依赖约束livekit-agents1.8.0要求 LiveKit Agents 框架不低于 1.8.0speechmatics-voice[smart]0.2.8底层使用 Speechmatics 的 Voice SDK带smart扩展用于 SMART_TURN 等 ML 端点检测requires-python 3.10.0需要 Python 3.10 及以上版本。安装命令非常简单pip install livekit-plugins-speechmatics安装后插件会在导入时通过init.py 中的Plugin.register_plugin(SpeechmaticsPlugin())自动注册到 LiveKit Agents 的插件体系因此你只需要在代码中from livekit.plugins import speechmatics即可使用。注意如果使用默认的EXTERNAL端点检测模式且不显式传vad框架会自动加载livekit-plugins-silero作为外部 VAD详见下文第四节此时还需要额外安装该依赖。二、前置条件API Key 与端点配置使用前必须准备 Speechmatics 的 API Key插件支持三种提供方式源码见 stt.py 的STT.__init__环境变量SPEECHMATICS_API_KEY.env.local文件LiveKit Agents 会在启动时加载构造参数api_key...优先级最高。对应的默认 WebSocket 服务端点为wss://eu2.rt.speechmatics.com/v2也可以通过环境变量SPEECHMATICS_RT_URL或构造参数base_url...覆盖。若既没有 Key 也没有 URL构造时会直接抛出ValueErrorMissing Speechmatics API key Missing Speechmatics base URLTTS 模块同样复用SPEECHMATICS_API_KEY见 tts.py默认服务端点为https://preview.tts.speechmatics.com。三、核心概念TurnDetectionMode端点检测四种模式turn_detection_mode参数决定何时判定一句话说完了end-of-turn。插件在 stt.py 中定义了四种模式模式枚举值端点检测方式适用场景EXTERNAL默认externalSpeechmatics 自身不做端点检测由外部 VAD如 Silero或手动调用finalize()驱动与 LiveKit 的 Turn Detector 或自研 VAD 配合ADAPTIVEadaptiveSpeechmatics 使用自己的 VAD 结合语速控制结束希望服务端自行管理轮次边界SMART_TURNsmart_turnSpeechmatics 基于 ML 模型的端点检测需要更智能的停顿判断FIXEDfixed固定静音时长触发由end_of_utterance_silence_trigger决定对延迟敏感、规则明确的场景从实现上看插件在_prepare_config()中通过VoiceAgentConfigPreset.load(opts.turn_detection_mode.value)加载对应预设见 stt.py再把你显式传入的高级参数逐个覆盖到预设上因此你可以放心地预设兜底、参数精调。源码中还包含一条隐含规则只要显式传入了一个真实的vad对象turn_detection_mode就会被强制改回EXTERNALstt.py因为外部 VAD 已经接管了轮次边界服务端再自己做端点检测会造成重复或提前结束。四、Diarization多说话人识别与输出格式化Speechmatics STT 引擎支持输出会话中每位说话人的信息。开启方式speechmatics.STT(enable_diarizationTrue)默认即为开启源码中STTCapabilities.diarization的默认值是True见 stt.py。4.1 输出格式化宏开启说话人识别后转写文本可以通过格式化字符串嵌入说话人信息支持两个宏{speaker_id}—— 说话人标识如S1{text}—— 转写文本本身。插件会根据当前发言者是否为活跃说话人active选择不同的模板模板参数含义示例输出speaker_active_format活跃说话人的输出格式{speaker_id}{text}/{speaker_id}→S1Hello/S1speaker_passive_format背景/被动说话人的输出格式[Speaker {speaker_id}] {text}→[Speaker S1] Hello在 stt.py 的_send_frames()中可以看到实际替换逻辑以segment.get(is_active, True)判定活跃与否然后分别套用speaker_active_format或speaker_passive_format若两者都未设置则退化为纯文本{text}speaker_id缺失时兜底为UU。4.2 让 LLM 理解说话人格式由于格式化后的文本会作为提示词喂给 LLM你应该调整系统指令system instructions明确告知 LLM 该格式代表说话人例如Transcripts are annotated with speaker labels, e.g. [Speaker S1] ... means speaker S1 is talking.五、用法一与 LiveKit Turn Detection 配合默认EXTERNAL模式默认的EXTERNAL模式天然适合与 LiveKit 自身的轮次检测器搭配使用。要点如下为了让输出文本在语句末尾不附加多余内容避免干扰端点判断建议使用[Speaker S1] ...这类前缀式格式作为speaker_active_formatend_of_utterance_silence_trigger控制静音多久判定说话结束默认0.5秒必须同时配置 VAD 结束语音事件的监听示例中通过inference.VAD()与TurnDetector()完成通过min_endpointing_delay/max_endpointing_delay约束端点判定延迟区间。完整示例摘自插件 README.mdfrom livekit.agents import AgentSession, inference from livekit.agents.inference import TurnDetector from livekit.plugins import speechmatics agent AgentSession( sttspeechmatics.STT( end_of_utterance_silence_trigger0.2, speaker_active_format[Speaker {speaker_id}] {text}, speaker_passive_format[Speaker {speaker_id} *PASSIVE*] {text}, ), vadinference.VAD(), turn_detectionTurnDetector(), min_endpointing_delay0.3, max_endpointing_delay5.0, ... )5.1 Silero 自动加载与手动finalize()在EXTERNAL模式下如果构造时没有传vad参数NOT_GIVEN插件会自动加载 Silero VAD 来驱动finalize()stt.py若未安装livekit-plugins-silero会抛出带有明确提示的ImportError若你希望完全自己控制结束时机可显式传入vadNone关闭自动加载然后在自己的逻辑中调用stt.finalize()finalize()的作用是强制把 STT 缓冲中的词输出为最终段落final segments其内部会遍历所有活跃流并调用底层客户端的finalize()stt.py。5.2 底层流式处理链路从源码看SpeechStreamstt.py在_run()中并行启动了三条任务_process_audio()把输入音频帧同时推给外部 VAD 流和 STT 客户端确保 VAD 与转写看到的是同一份音频_process_vad()循环消费 VAD 事件一旦收到VADEventType.END_OF_SPEECH就调用client.finalize()stt.py_process_messages()消费服务端消息把ADD_PARTIAL_SEGMENT映射为INTERIM_TRANSCRIPT、把ADD_SEGMENT映射为FINAL_TRANSCRIPT、把START_OF_TURN/END_OF_TURN映射为START_OF_SPEECH/END_OF_SPEECH事件。这就是外部 VAD 驱动 Speechmatics 结束一轮发言的完整机制VAD 负责判断STT 引擎负责转写二者通过finalize()握手。六、用法二Speechmatics 服务端端点检测ADAPTIVE / SMART_TURN / FIXED若不想引入外部 VAD可以把端点检测完全委托给 Speechmatics设置turn_detection_mode为ADAPTIVE或SMART_TURN/FIXED并在AgentSession上配置turn_detectionstt让框架直接使用 STT 结果判断轮次结束。turn_detectionstt是 LiveKit Agents 内置的轮次检测模式之一其类型定义可见于 turn.py 中的TurnDetectionMode可选值包括stt、vad、realtime_llm、manual。完整示例摘自插件 README.mdfrom livekit.agents import AgentSession from livekit.plugins import speechmatics agent AgentSession( sttspeechmatics.STT( turn_detection_modespeechmatics.TurnDetectionMode.ADAPTIVE, speaker_active_format[Speaker {speaker_id}] {text}, speaker_passive_format[Speaker {speaker_id} *PASSIVE*] {text}, additional_vocab[ speechmatics.AdditionalVocabEntry( contentLiveKit, sounds_like[live kit], ), ], ), turn_detectionstt, ... )示例中还展示了additional_vocab自定义词典的用法通过AdditionalVocabEntry提高特定词在转写模型中的权重sounds_like用于给出读音提示适合产品名、人名、专业术语等容易转错的词。七、STT 高级参数全表STT构造器支持丰富的参数完整签名与说明见 stt.py 的STT.__init__这里按用途分组整理7.1 语言与领域参数说明默认值languageSTT 模型语言代码enoutput_locale输出区域如en-GB不设置domain领域提示用于优化转写不设置7.2 端点检测与延迟参数说明约束end_of_utterance_silence_trigger触发语句结束的静音时长秒必须 0且 2end_of_utterance_max_delay语句结束的最大等待时长必须大于end_of_utterance_silence_triggerend_of_turn_config端到端结束配置惩罚系数、最小结束延迟、强制结束行为等覆盖预设max_delay转写最大延迟秒降低可缩短部分结果到最终结果的时间但可能影响准确率必须在0.7 ~ 4.0之间vad_config客户端侧 VAD 配置silence_duration、threshold用于ADAPTIVE/SMART_TURN与EXTERNAL模式互斥7.3 说话人相关参数说明enable_diarization是否开启说话人分离默认Truespeaker_sensitivity分离灵敏度值越大越容易区分音色相近的说话人需在0.0 ~ 1.0之间max_speakers最多检测的说话人数需在2 ~ 100之间prefer_current_speaker为True时时间上相近的词组会加权归为同一说话人focus_speakers只关注这些说话人其他说话人按被动处理ignore_speakers忽略这些说话人默认任何双下划线包裹的标签如__ASSISTANT__都会被排除其语音不触发 VAD / 端点检测focus_mode非关注说话人的处理方式RETAIN保留为被动帧默认或IGNORE直接丢弃known_speakers已知说话人标签列表用于跨会话稳定归属7.4 输出与音频参数说明默认值include_partials是否在部分结果中输出词级片段说话人活动检测始终使用部分片段此开关只影响格式化文本输出不设置punctuation_overrides标点行为覆盖不设置operating_point准确率与延迟的权衡档位覆盖预设不设置sample_rate音频采样率Hz16000audio_encoding音频编码AudioEncoding.PCM_S16LE7.5 运行期动态能力除了构造参数STT实例还提供两个运行期方法stt.pyupdate_speakers(focus_speakers..., ignore_speakers..., focus_mode...)在转写进行中动态调整关注/忽略的说话人需要已开启 diarization会实时推送给所有活跃流get_speaker_ids()查询当前会话检测到的说话人列表建议在说话人至少说出 5 个词后调用以获得更稳定结果底层通过GET_SPEAKERS消息实现带 5 秒超时。7.6 参数校验规则插件在构造时会对参数做本地校验stt.py 的_validate_stt_options不满足约束会直接抛出ValueError避免把非法配置发给服务端end_of_utterance_silence_trigger必须介于 0 与 2 秒之间end_of_utterance_max_delay必须大于end_of_utterance_silence_triggermax_speakers必须在 2 ~ 100 之间max_delay必须在 0.7 ~ 4.0 秒之间低于 0.7 秒的延迟预算不被支持speaker_sensitivity必须介于 0.0 与 1.0 之间。另外vad_config启用状态下与turn_detection_modeEXTERNAL组合会被直接拒绝因为外部 VAD 已经接管了轮次边界两套 VAD 会互相干扰stt.py。7.7 兼容旧参数对于旧版本 API 中的参数插件保留了兼容迁移逻辑stt.py 的_check_deprecated_argsenable_partials会被迁移为include_partials、diarization_sensitivity会被迁移为speaker_sensitivity并打印警告日志end_of_utterance_mode、chunk_size、transcription_config等参数则被移除且无替代仅告警不再生效。八、附带能力Speechmatics TTS插件同时导出了 TTS 实现tts.py可用于语音合成可选音色sarah默认、theo、megan运行期可通过update_options(voice...)动态切换默认采样率16000单声道输出 PCM 音频请求通过 HTTP POST 到{base_url}/generate/{voice}?output_formatpcm_{sample_rate}完成URL 构造见 utils.py并附带 SDK 版本标识参数与 STT 共用SPEECHMATICS_API_KEY。需要说明的是该 TTS 的capabilities.streamingFalse即不支持流式合成属于一次性请求-返回模式在需要低延迟、流式语音的 Agent 中建议优先考虑其他流式 TTS 插件。九、选型建议与小结综合以上内容选择端点检测模式的参考路径如下已在使用 LiveKit 的 Turn Detector 或自研 VAD→ 保持默认EXTERNAL让外部 VAD 通过finalize()驱动 Speechmatics 结束轮次这也是与 LiveKit 生态集成度最高的方式想简化架构、由服务端管理轮次→ 使用ADAPTIVE简单 VAD或SMART_TURNML 端点检测并在AgentSession上配置turn_detectionstt对停顿规则有硬性要求→ 使用FIXEDend_of_utterance_silence_trigger精确控制多说话人场景客服、会议、访谈→ 务必开启enable_diarization用speaker_active_format/speaker_passive_format格式化输出并同步调整系统提示词让 LLM 理解说话人标签。无论选择哪种模式都建议用additional_vocab校正专有名词用max_speakers/focus_speakers/ignore_speakers约束说话人集合并参考本文第七节的校验规则提前规避非法参数。通过 插件源码 与 README 文档 可继续深入所有参数的细节行为。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考