多彩编程 多彩编程MZPH · CODE BLOG
ARTICLE DETAIL

文章详情

深耕前端与后端开发技术的一线实战笔记与踩坑复盘。

OpenAvatarChat 双工模式端点检测指南:Smart Turn EOU 处理器实战详解

OpenAvatarChat 双工模式端点检测指南:Smart Turn EOU 处理器实战详解 数字人AI 应用语音多模态音视频后端【免费下载链接】OpenAvatarChat项目地址https://gitcode.com/gh_mirrors/op/OpenAvatarChat点击查看免费下载Smart Turn EOUEnd-of-Utterance是 OpenAvatarChat 在双工Duplex对话模式下的核心端点检测组件用于判断用户一句话是否说完从而决定何时结束当前语音流、把发言权交还给 AI。本文以官方文档 docs/reference/handlers/vad/smart-turn.md 为骨架结合处理器源码与真实双工配置文件完整讲解模型下载、参数配置、底层实现原理以及与双工 VAD 的协作机制读完即可在双工配置中正确启用并调优 Smart Turn EOU。一、双工模式为什么需要 Smart Turn EOU在 OpenAvatarChat 的普通半双工对话流程中通常依赖 VAD 的静音检测来切分语音。而在双工模式*_duplex.yaml下用户与 AI 可以同时说话系统需要一个更智能的“这句话是否已经说完”判定避免仅仅因为短暂停顿就把用户话语错误切断或长时间不结束导致响应延迟。为此双工配置引入了基于 ONNX 模型的Smart Turn端点检测当双工 VAD 检测到用户可能说完话时会打上EVT_EARLY_VAD_END事件Smart Turn EOU 处理器随即对缓冲区内的音频做一次“完成/未完成”二分类预测若判定完成则向 VAD 发出候选的STREAM_END信号从而在“不断言过早结束、不遗漏真实结束”之间取得平衡。从双工配置的注释可以看到分工关系config/chat_with_openai_compatible_bailian_cosyvoice_duplex.yaml语义轮次检测器的enable_completion_detection: false即“话语完成检测关闭依赖 VAD end_delay SmartTurnEOU 判断结束”。也就是说双工模式下“一句话是否说完”的判断职责正是交给 Smart Turn EOU。二、依赖模型下载Smart Turn EOU 需要 ONNX 格式的模型文件默认存放在仓库根目录下的models/smart_turn/。官方文档给出的下载命令为uv run scripts/download_models.py --handler smart_turn_eou执行后模型将下载到models/smart_turn/目录。该命令使用仓库自带的统一下载脚本 scripts/download_models.py在模型注册表中smart_turn_eou的描述是“Smart Turn v3 ONNX model for end-of-utterance detection”scripts/download_models.py模块与处理器名的映射表中vad/smart_turn_eou对应smart_turn_eouscripts/download_models.py下载函数将模型目录指向PROJECT_ROOT / models / smart_turnscripts/download_models.py。除了统一下载脚本仓库还提供了独立的 Shell 下载脚本 scripts/download_smart_turn_weights.sh其行为是从 HuggingFace 仓库pipecat-ai/smart-turn-v3下载模型到models/smart_turn/在国内网络环境下默认设置镜像export HF_ENDPOINThttps://hf-mirror.com下载完成后校验目录内的.onnx文件是否存在并检查可选的config.json、preprocessor_config.json。因此当uv run scripts/download_models.py --handler smart_turn_eou不可用或失败时可以直接执行bash scripts/download_smart_turn_weights.sh两种方式下载的都是 Smart Turn v3 系列的 ONNX 模型仓库源码与配置中引用的文件名是smart-turn-v3.1-cpu.onnx即 CPU 推理版本。三、配置参数详解3.1 官方文档给出的最小配置文档中的基础配置如下SmartTurnEOU: module: vad/smart_turn_eou/eou_handler_smart_turn threshold: 0.8 model_path: models/smart_turn/smart-turn-v3.1-cpu.onnx3.2 真实双工配置中的完整参数在仓库自带的双工配置中如 config/chat_with_openai_compatible_bailian_cosyvoice_duplex.yamlSmartTurnEOU 的完整段落为# Smart Turn EOU - 基于 ONNX 模型的端点检测 SmartTurnEOU: enabled: true module: vad/smart_turn_eou/eou_handler_smart_turn threshold: 0.8 max_buffer_seconds: 300.0 sample_rate: 16000 model_path: models/smart_turn/smart-turn-v3.1-cpu.onnx input_type_override: HUMAN_AUDIO: HUMAN_DUPLEX_AUDIO各参数含义如下表参数文档/配置中的值源码默认值eou_handler_smart_turn.py说明enabledtrue—是否启用该处理器双工配置中必须为 truemodulevad/smart_turn_eou/eou_handler_smart_turn—处理器实现模块路径指向 src/handlers/vad/smart_turn_eou/eou_handler_smart_turn.pythreshold0.80.5完成概率阈值模型输出概率大于该值才判定“话语完成”prediction 1阈值越高判定完成越严格、结束越保守max_buffer_seconds300.012.0音频缓冲区最大时长上限秒双工配置放宽到 300 秒以容纳长会话sample_rate1600016000音频采样率与 Whisper 特征提取器及 ONNX 模型输入要求一致model_pathmodels/smart_turn/smart-turn-v3.1-cpu.onnxmodels/smart_turn/smart-turn-v3.1-cpu.onnxONNX 模型文件路径相对路径会基于项目根目录解析input_type_overrideHUMAN_AUDIO: HUMAN_DUPLEX_AUDIO—将输入类型覆盖为双工音频与双工 VAD 输出的流类型对齐使用该处理器时threshold是文档明确要求用户关注的调参项默认源码值为0.5而双工配置中统一设置为0.8代表更严格的“说完”判定。可以推断threshold越低用户稍有停顿就可能被判定为结束响应更快但误切风险更高threshold越高则反之。四、源码级原理剖析处理器实现位于 src/handlers/vad/smart_turn_eou/eou_handler_smart_turn.py其运行依赖声明在 src/handlers/vad/smart_turn_eou/pyproject.tomlonnxruntime~1.20.1、transformers4.48.0并要求 Python3.11.7, 3.12。4.1 模型加载loadHandlerSmartTurnEOU.load完成两件事eou_handler_smart_turn.py解析模型路径若model_path不是绝对路径则通过DirectoryInfo.get_project_dir()拼接为项目根目录下的路径模型不存在时抛出FileNotFoundError错误信息提示执行bash scripts/download_smart_turn_weights.sh构建 ONNX 推理会话使用onnxruntime.InferenceSession显式指定providers[CPUExecutionProvider]CPU 推理并设置ORT_SEQUENTIAL顺序执行、inter_op_num_threads1、ORT_ENABLE_ALL图优化等级等会话选项初始化 Whisper 特征提取器WhisperFeatureExtractor(chunk_length8)即按 8 秒块提取特征——这解释了为什么模型输入固定为 8 秒音频窗口。4.2 端点预测_predict_eou_predict_eou是核心推理函数eou_handler_smart_turn.py流程如下音频定长化_truncate_audio_to_last_n_seconds将音频截断为最后 8 秒若不足 8 秒则在开头补零eou_handler_smart_turn.py——只保留“最近 8 秒”意味着预测更关注当前说话状态特征提取调用 Whisper 特征提取器sampling_rate16000、paddingmax_length、max_length8*16000、do_normalizeTrue输出形状为(1, features)ONNX 推理以{input_features: input_features}作为输入运行会话取outputs[0][0].item()得到sigmoid 概率阈值判定prediction 1 if probability threshold else 0返回{prediction: ..., probability: ...}。4.3 旁路监听式数据流get_handler_detail从处理器数据定义看SmartTurnEOU 采用“旁路监听”模式eou_handler_smart_turn.py输入HUMAN_AUDIO双工配置下经input_type_override变为HUMAN_DUPLEX_AUDIO消费模式为DEFAULT即“旁路监听不阻断数据流”优先级input_priority100属于低优先级不影响 ASR 正常处理输出为空——它不产生数据只通过信号Signal与外部协作。4.4 主处理循环handlehandle完整实现了文档描述的 EOU 协作逻辑eou_handler_smart_turn.py累积音频将收到的HUMAN_AUDIO音频非 float32 时按int16 / 32767.0归一化追加到会话上下文SmartTurnEOUContext的audio_buffer中并累加buffer_durationeou_handler_smart_turn.py新流重置当inputs.is_first_data为真新音频流开始时调用context.reset_buffer()清空缓冲响应早停事件当缓冲数据携带EventType.EVT_EARLY_VAD_END事件VAD 发出的“可能说完”信号且本流尚未发送过结束信号时取出缓冲音频执行_predict_eou完成则发信号若prediction 1构造ChatSignaltypeChatSignalType.STREAM_END、source_typeChatSignalSourceType.HANDLERrelated_streamcontext.current_stream_idsignal_data携带eou_prediction、eou_probability、eou_buffer_duration_ms缓冲时长毫秒三个字段通过context.emit_signal(signal)发出“候选 STREAM_END”信号并置end_signal_sent True未完成则等待若prediction 0打印“Utterance incomplete, waiting for next early_vad_end”等待 VAD 的下一次早停事件VAD 会按early_end_repeat_delay持续重复发送流结束清理当inputs.is_last_data为真VAD 正式结束流时记录日志并重置缓冲。五、与双工 VAD 的协作机制Smart Turn EOU 并不是孤立工作的它与双工 VADDuplexVADHandler位于 src/handlers/vad/silerovad/duplex_vad_handler.py构成“早停事件 候选结束信号”的双向协作事件发起方VAD双工 VAD 在检测到可能的语音结束时会向输出数据附加EventType.EVT_EARLY_VAD_END事件duplex_vad_handler.py同时其信号过滤规则注册了SignalFilterRule(ChatSignalType.STREAM_END, None, ChatDataType.HUMAN_DUPLEX_AUDIO)即“继续监听候选 STREAM_END 以配合 EOU 协作”duplex_vad_handler.py信号接收方VADVAD 的on_signal处理STREAM_END且signal.is_candidate为真的信号校验related_stream与当前流一致后置candidate_end_received Trueduplex_vad_handler.py从而在早停等待结束后确认“这句话确实说完了”正式结束该语音流。VAD 侧的end_delay、early_end_delay、early_end_repeat_delay等参数决定了早停事件何时触发、多久重复一次双工配置示例中分别为end_delay: 32000、early_end_delay: 5000、early_end_repeat_delay: 1000单位采样点这些参数与 SmartTurnEOU 的threshold共同决定端点检测的灵敏度。六、在双工配置中的实际落地仓库中共有 7 份*_duplex.yaml配置启用了 SmartTurnEOU例如config/chat_with_lam_duplex.yamlconfig/chat_with_lam_bailian_asr_duplex.yamlconfig/chat_with_openai_compatible_bailian_cosyvoice_duplex.yamlconfig/chat_with_openai_compatible_bailian_cosyvoice_musetalk_duplex.yamlconfig/chat_with_openai_compatible_bailian_cosyvoice_flashhead_duplex.yamlconfig/chat_with_openai_compatible_bailian_cosyvoice_flashhead_duplex_agent.yaml以 chat_with_openai_compatible_bailian_cosyvoice_duplex.yaml 为例启用 Smart Turn EOU 的完整链路包括以下相邻配置History 模块history.retention_mode: by_both等配置是双工打断检测所必需的双工 VADSileroVad使用vad/silerovad/duplex_vad_handler并设置end_delay、early_end_delay、early_end_repeat_delay等参数SmartTurnEOU如上文 3.2 节完整配置语义轮次检测器enable_interrupt_detection: true负责打断判断而enable_completion_detection: false明确把完成判断交给 SmartTurnEOU。启动时确保已按第二节完成模型下载然后使用对应配置文件运行即可例如通过uv run python src/demo.py --config config/chat_with_openai_compatible_bailian_cosyvoice_duplex.yaml方式启动具体启动方式以仓库 README.md 与 docs/getting-started/index.md 为准。七、运行与调优要点依赖前提需要 Python3.11.7 ~ 3.12以及onnxruntime~1.20.1、transformers4.48.0见 pyproject.toml推荐使用uv管理环境模型缺失排障启动时若模型路径不存在会抛出FileNotFoundError提示信息明确要求执行bash scripts/download_smart_turn_weights.sh日志观测推理时输出Smart Turn EOU: Prediction1 (Complete), Probability0.xxxx, Buffer duration...可通过日志中的Prediction/Probability/Buffer duration观察判定行为并据此微调threshold调参建议若出现“话还没说完就被抢答”适当调高threshold如0.85~0.9若出现“说完后响应明显延迟”可适当降低threshold同时配合 VAD 的end_delay、early_end_delay调整早停触发节奏。注意以上均为基于源码机制与参数语义的调优方向具体取值需结合实际对话场景验证。八、小结Smart Turn EOU 是 OpenAvatarChat 双工模式的“话语完成裁判”它以旁路监听方式累积双工音频收到 VAD 的早停事件后运行 Smart Turn ONNX 模型用 8 秒音频窗口输出完成概率并与threshold比较最终以候选STREAM_END信号驱动双工 VAD 精确收尾。通过文档中给出的模型下载命令与threshold、model_path等核心参数再配合源码中可追溯的推理与协作逻辑开发者可以快速在任意*_duplex.yaml配置中启用并按需调优该端点检测能力。更多处理器清单与目录索引可参见 docs/reference/handlers/vad/index.md英文版本见 docs/en/reference/handlers/vad/smart-turn.md。赞分享数字人AI 应用语音多模态音视频后端【免费下载链接】OpenAvatarChat项目地址https://gitcode.com/gh_mirrors/op/OpenAvatarChat点击查看免费下载相关推荐旧 Mac 升级 macOS 并连接 CarPlay 车机OpenCore Legacy Patcher 完整指南旧 Mac 升级 macOS 并连接 CarPlay 车机OpenCore Legacy Patcher 完整指南 把一台 2013 年的 MacBook 插操作系统固件驱动开发speech-to-speech 的 Smart Turn 端点检测怎么配置阈值与本地 ONNX 模型speech to speech 的 Smart Turn 端点检测怎么配置阈值与本地 ONNX 模型 在 speech to speech 的语音管线中S人工智能大模型语音音频AI 应用本地部署后端smart-turn智能对话中的转场检测smart turn智能对话中的转场检测 项目介绍 smart turn 是一个社区驱动、原生音频转场检测的开源模型。该模型致力于通过深度学习技术更精准地识上一篇Nativefier 性能优化团队会议记录讨论与决策下一篇Detectron高级功能测试时数据增强(TTA)提升检测精度创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表