人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本指南以 TEN Framework 仓库中的soniox_asr_python扩展为对象完整讲解其配置参数、四种holding_mode语义、asr_result输出结构、WebSocket 底层通信、错误分级与指数退避重连机制并结合 manifest.json、config.py、extension.py 等源码给出可验证的实现细节。读完本文你将能够在 TEN 应用图中接入 Soniox 实时 ASR为语音 Agent 提供多语言实时转写并掌握结果缓冲策略、调试手段与迁移方法。扩展是什么soniox_asr_python是 TEN Framework 官方仓库中内置的一个Python 实时语音识别ASR扩展它通过 WebSocket 连接 Soniox 的实时转写服务Real-time STT API把进入 TEN 图的AudioFrame音频帧实时转换为文本结果再以标准的asr_result数据消息输出给下游扩展如 LLM 扩展。该扩展位于 ai_agents/agents/ten_packages/extension/soniox_asr_python在 manifest.json 中声明为type: extension、name: soniox_asr_python当前版本 0.6.0依赖ten_runtime_python0.11与ten_ai_base0.7两个系统包。它的核心能力可概括为基于 Soniox WebSocket API 的实时流式识别支持逐 token 输出多语言识别与语言自动识别内置 ISO 语言码到 Soniox 语言码的映射表可配置的音频参数采样率、声道、采样位宽遵循 TEN 标准 ASR 接口继承AsyncASRBaseExtension可无缝接入现有语音 Agent 图内置错误分级、指数退避重连与音频转储调试能力。扩展的入口在 addon.py通过register_addon_as_extension(soniox_asr_python)注册on_create_instance中实例化SonioxASRExtension定义于 extension.py。安装与依赖扩展的依赖在 requirements.txt 与 pyproject.toml 中声明依赖版本要求用途pydantic2.0.0配置模型SonioxASRConfig的校验与序列化websockets11.0.0与 Soniox 服务端的 WebSocket 通信aiofilespyproject 要求 25.1.0音频转储文件的异步写入pysbd0.3.4句子边界检测sentence_terminator缓冲模式依赖说明README 中标注的 Python 版本要求为 3.8而当前仓库 pyproject.toml 实际声明为requires-python 3.10以仓库源码为准。扩展对输入音频的格式有固定要求定义于 extension.py采样率16000 Hzinput_audio_sample_rate()返回 16000声道数1单声道采样位宽2 字节16-bit PCMpcm_s16le音频缓冲策略ASRBufferConfigModeKeep(byte_limit1024 * 1024 * 10)即最多缓存 10 MB 音频。配置参数配置通过扩展的property.json注入完整字段由 config.py 中的SonioxASRConfigpydanticBaseModel定义。参数分为两层扩展自身参数url、sample_rate、dump等直接位于配置根节点与Soniox 会话参数api_key、model、language_hints等位于params对象内会被原样序列化为 WebSocket 的 start request。必填参数参数位置说明api_keyparamsSoniox API 密钥。缺失时扩展会在start_connection阶段直接抛出致命错误Missing required api_key并断开连接可选参数参数位置默认值说明url根节点wss://stt-rt.soniox.com/transcribe-websocketSoniox 实时转写 WebSocket 地址modelparamsstt-rt-preview使用的 ASR 模型config.update()会为未提供的会话参数补默认值language_hintsparams[en]识别主语言README 所列默认值测试配置中常显式给出sample_rate根节点16000音频采样率Hz同时会被写入会话参数holding_mode根节点false识别结果的缓冲/发射策略详见下文dump根节点false是否开启音频转储调试dump_path根节点.音频转储文件输出目录SonioxASRConfig.update()config.py会把根节点上的特殊参数抽取到配置字段并为params补全如下默认值仅当未显式提供时{ max_non_final_tokens_duration_ms: 360, model: stt-rt-preview, enable_language_identification: true, audio_format: pcm_s16le, num_channels: 1, sample_rate: 16000 }仓库测试目录给出了两份可直接参考的完整配置英文 tests/configs/property_en.json 与中文 tests/configs/property_zh.json{ params: { api_key: ${env:SONIOX_ASR_API_KEY}, url: wss://stt-rt.soniox.com/transcribe-websocket, model: stt-rt-v4, language_hints: [en], sample_rate: 16000 } }可以看到api_key支持${env:VAR}形式从环境变量注入如SONIOX_ASR_API_KEYmodel在测试配置中使用stt-rt-v4。此外还有一份用于验证参数校验逻辑的非法配置 tests/configs/property_invalid.json对应测试文件为 tests/test_invalid_params.py。扩展级进阶参数除了 README 列出的参数源码还暴露了以下扩展级配置同样通过配置根节点注入可用于精细化控制 finalize 与连接行为参数默认值说明finalize_modedefaultfinalize 触发方式default发送{type: finalize}消息、ignore忽略 finalize要求开启 endpoint detection、mute_pkg发送静音包代替、close关闭连接触发mute_pkg_duration_ms800mute_pkg模式下发送的静音包时长default_finalize_send_silencefalse是否在 finalize 前先发送一段静音以降低转写延迟对应 Soniox 文档的 trailing silence 技巧default_finalize_silence_duration_ms800上述静音包的时长enable_keepalivetrue是否开启 keepalive 心跳WebSocket 层每 15 秒无音频时发送{type: keepalive}finalize_reconnect_modeimmediatefinalize-by-close 后的重连策略immediate立即重连on_audio在有新音频时重连dump_rotate_on_finalizefalse每次 finalize 时轮转滚动转储文件这些配置的实际消费逻辑可在 extension.py 的on_data与_real_finalize*系列方法中看到例如asr_finalize数据消息携带可选的silence_duration_ms属性时会被透传给 Soniox 的 finalize 请求以降低最终化延迟。holding_mode识别结果缓冲策略holding_mode是本扩展最核心的行为开关决定“何时把识别结果发射给下游”。README 定义了四种取值HoldingMode枚举位于 config.py。取值语义false默认结果产生即发射不做任何缓冲。非 final token 与 final token 混合时按“混合批次”输出finalize持有 final token直到会话 finalize 时一次性 flush等价于旧版finalize_holding: trueendpointing_only持有 final token直到收到 endpoint 信号或会话结束片段边界完全跟随 endpointing。要求enable_endpoint_detection: true否则实际生效模式回退为falsesentence_terminator持有 vendor 的is_final片段直到检测到完整句子边界后才发射。英文边界通过pySBDpysbd0.3.4识别处理.与Mr.等缩写歧义中文及强终止符簇。……、!!!、...等由本地规则判断sentence_terminator的行为细节来自 README 与 text_utils.py 的实现每次发射只包含累积的 vendor-final 缓冲中“最后一个完整句子边界”之前的 token边界之后的尾随 token 继续保持延迟仅逗号如不算句子结束尾随的纯标点 token如。会先与延迟文本合并再评估边界数字场景有专门处理12.Hello中12.被视为句子边界而12.5是小数、需继续等待见_digit_period_boundary_decisiontext_utils.py语言支持限定于中文族zh/cmn/yue/wuu与英文族其他语言自动跳过该模式supports_language返回 false 时直接透传会话结束fin时未形成完整句子的延迟 token 会被强制以 final 身份 flush_flush_deferred_vendor_final_tokensextension.py。实际生效模式的判定在_effective_holding_mode()extension.py当配置为endpointing_only但params中没有开启enable_endpoint_detection时静默回退为false并在初始化日志中打印effective holding_mode。对应的边界行为测试见 tests/test_sentence_end_punctuation.py 与 tests/test_finalize.py。输出数据格式扩展实现的是 TEN 标准 ASR 接口下游扩展可直接按标准方式消费。单个片段输出为asr_result数据消息结构如下README 原文{ id: unique_result_id, text: recognized text, final: true, start_ms: 1000, duration_ms: 500, language: en, words: [ { word: hello, start_ms: 1000, duration_ms: 200, stable: true } ], metadata: { session_id: session_identifier } }字段说明id结果唯一标识兼容旧接口时逐片段生成text识别文本final是否为最终结果false表示中间结果start_ms/duration_ms相对音频时间线的起止毫秒。实现上通过_adjust_timestamp()extension.py结合audio_timeline与断线重连前的累计时长校准保证时间戳跨重连仍连续language识别语言ISO 码经map_language_code映射后的 Soniox 语言码如en-US、zh-CNwords词级明细stable表示该词是否已稳定等于结果是否 finalmetadata扩展附加信息例如平均置信度{asr_info: {confidence: 0.97}}见_calculate_average_confidenceextension.py。除逐片段asr_result外扩展还会发送asr_results批量结果数据消息Data.create(asr_results)payload 为ASRResults(results[...])供下游一次处理整批结果_send_asr_results_dataextension.pyasr_translation_result翻译结果数据消息当会话开启翻译时包含source_text、source_language、language等字段ASRTranslationResultextension.py。在sentence_terminator模式下翻译只随 final 片段发射避免中间结果触发翻译事件。底层实现WebSocket 客户端与协议交互会话建立与 token 解析扩展在start_connectionextension.py中把config.params序列化为 JSON 作为start request随 WebSocket 连接建立后立即发送。服务端初始化消息的完整字段说明见仓库附带的 API_REFERENCE.md{ api_key: SONIOX_API_KEY|SONIOX_TEMPORARY_API_KEY, model: stt-rt-preview, audio_format: auto, num_channels: 1, sample_rate: 16000, language_hints: [zh, en], context: , enable_speaker_diarization: false, enable_language_identification: false, enable_non_final_tokens: true, max_non_final_tokens_duration_ms: 360, enable_endpoint_detection: false, holding_mode: false, client_reference_id: }其中api_key、model、audio_format为必填其余可选holding_mode可为false、finalize或endpointing_only服务端侧使用endpointing_only时需开启enable_endpoint_detection。注意扩展自身的holding_modesentence_terminator是 TEN 层的缓冲策略与会话参数中透传的holding_mode是两回事。WebSocket 客户端实现在 websocket.py 的SonioxWebsocketClient采用单连接内recv/send双任务竞争asyncio.wait_work方法的事件驱动模型通过事件回调把消息派发给扩展事件触发时机回调参数OPEN连接建立、start request 已发送连接耗时msTRANSCRIPT收到转写/翻译 token 批次tokens、final_audio_proc_ms、total_audio_proc_msFINISHED收到finished: true完成消息final_audio_proc_ms、total_audio_proc_msERROR收到error_code/error_message错误码、错误信息CLOSE连接关闭vendor 关闭码、原因EXCEPTION连接异常异常对象收到的 token 由_parse_tokenwebsocket.py按结构匹配为四种类型SonioxTranscriptToken转写词、SonioxTranslationToken翻译、SonioxFinTokenfin标记表示一次 finalize 操作结束、SonioxEndTokenend标记表示 endpoint 到达。成功转写响应示例来自 API_REFERENCE.md{ tokens: [ { text: Hello, start_ms: 600, end_ms: 760, confidence: 0.97, is_final: true, speaker: 1, language: en } ], final_audio_proc_ms: 760, total_audio_proc_ms: 880 }流结束时服务端返回{tokens: [], ..., finished: true}并关闭连接。单条流最长 65 分钟见 API_REFERENCE.md。keepalive 与手动 finalizekeepaliveenable_keepalive开启时客户端后台任务在连续 15 秒无音频数据时发送{type: keepalive}保持连接_keepalive_loopwebsocket.py。手动 finalizefinalize_mode: default下收到asr_finalize数据消息后发送{type: finalize}可携带trailing_silence_ms。Soniox 会把此前收到的所有音频标记为 final 并返回fin标记见 API_REFERENCE.md 的 Manual finalize 一节实现见websocket.finalize()websocket.py。扩展收到fin后调用_finalize_end()计算 finalize 延迟当前时间 -last_finalize_timestamp并发送asr_finalize_end消息供图内下游同步“转写已定稿”的语义。错误处理与断线重连错误分级Soniox 的错误响应格式为{tokens: [], error_code: 503, error_message: ...}error_code为标准 HTTP 状态码见 API_REFERENCE.md。扩展通过SonioxASRErrorFilterextension.py把 vendor 错误映射为 TEN 的模块错误码条件映射结果400 且消息含No audio received或Audio is too long非致命错误NON_FATAL_ERROR400 / 401 / 402其余情况致命错误FATAL_ERROR其他错误码非致命错误错误通过send_asr_error以ModuleErrorModuleErrorVendorInfovendor 标识、原始错误码与消息上报便于上层排查与告警。对应测试见 tests/test_vendor_error.py。指数退避重连连接意外关闭非主动 stop、关闭码非 0/1000时扩展记录 vendor 关闭信息并触发ReconnectManagerreconnect_manager.py执行指数退避重连基础延迟base_delay 0.5s每次失败翻倍上限max_delay 4.0sdelay min(0.5 * 2^(attempts-1), 4.0)重连成功OPEN事件后重置尝试计数mark_connection_successful重连失败会以FATAL_ERROR上报。重连期间的时间戳处理值得注意_handle_open会把重连前已发送的用户音频时长累加到sent_user_audio_duration_ms_before_last_reset并重置audio_timeline从而让新连接产出的start_ms与旧连接保持时间轴连续finalize_reconnect_mode: on_audio时新音频帧到达才触发重连_needs_reconnect标志见on_audio_frameextension.py。连接建立耗时也会通过send_connect_delay_metrics上报相关测试见 tests/test_connection_delay_metrics.py。音频转储调试设置dump: true时扩展会把送入 WebSocket 的原始音频以 16-bit PCM 格式落盘文件名为soniox_asr_in.pcm常量定义于 const.py输出目录由dump_path指定默认当前目录。实现见 dumper.py使用aiofiles异步写入避免阻塞事件循环开启dump_rotate_on_finalize时每次 finalize 前轮转文件新文件名形如soniox_asr_in_时间戳_随机hex.pcm轮转采用“先开新文件、成功后再关旧文件”的策略失败时保留旧文件句柄避免调试数据丢失音频帧在send_audio中同步写入转储extension.py因此转储内容与实际上送内容完全一致可用于复现识别问题。多语言支持扩展内置 ISO 语言码到 Soniox 语言码的映射表const.py覆盖 60 余种语言例如en → en-US、zh → zh-CN、ja → ja-JP、ko → ko-KR、fr → fr-FR、de → de-DE、es → es-ES、ar → ar-SA等。map_language_code()对未收录的 ISO 码原样返回is_supported_language()用于判断语言是否在支持列表内。语言相关测试见 tests/test_multilang.py。配合enable_language_identification默认开启与language_hints会话可自动识别语种并按 hint 优先转写。注意sentence_terminator缓冲模式的句子边界检测目前只覆盖中文与英文语族。迁移说明README 明确提示finalize_holding已移除。旧配置中的{finalize_holding: true}应迁移为{holding_mode: finalize}迁移可在配置/翻译层完成例如把finalize_holding: true映射为holding_mode: finalize扩展侧不再兼容旧字段。单元测试扩展自带完整的 pytest 测试套件覆盖配置校验、音频参数、finalize、多语言、vendor 错误、连接状态/延迟指标、句子边界、混合结果批次等场景。测试文件位于 tests运行方式README 原文cd tests ./bin/start实际入口脚本 tests/bin/start 会设置PYTHONPATH指向.ten/app下的ten_runtime_python与ten_ai_base与TEN_APP_BASE_DIR然后执行pytest -s tests/。测试基于AsyncExtensionTester驱动扩展实例api_key通过环境变量SONIOX_ASR_API_KEY注入见 tests/configs/property_en.json不依赖真实 Soniox 服务即可验证扩展内部逻辑。注意事项endpoint detection 不在标准 ASR 接口中README 明确指出{enable_endpoint_detection: true}这一能力不被支持因为该字段不包含在 TEN 标准 ASR 接口中。这意味着依赖服务端 endpoint 信号的endpointing_only模式需要上游自行透传该会话参数且仅在服务端支持时才有效。api_key属于敏感信息扩展日志输出配置时会走sensitive_handlingTrue对api_key加密后再打印config.to_str(sensitive_handlingTrue)config.py部署时应继续使用环境变量方式注入避免明文落盘。输入音频固定为 16 kHz / 单声道 / 16-bit PCM若上游图产出其他格式需要先经音频处理扩展如重采样再接入本扩展。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework Soniox 实时语音识别 WebSocket API 深度指南soniox_asr_python 扩展的协议解析与源码实现TEN Framework Soniox 实时语音识别 WebSocket API 深度指南soniox_asr_python 扩展的协议解析与源码实现 So人工智能AI Agent多模态语音AI 应用QMK 固件文档系统能力清单VitePress 时代的文档语法、排版特性与构建链路QMK 固件文档系统能力清单VitePress 时代的文档语法、排版特性与构建链路 本文围绕 docs/__capabilities.md https://l人工智能AI Agent多模态语音AI 应用ai-sdk/azure 演进全解析从 AI SDK 5 到 7 的 Azure OpenAI 提供方能力变迁与实战指南ai sdk/azure 演进全解析从 AI SDK 5 到 7 的 Azure OpenAI 提供方能力变迁与实战指南 本文以 packages/azur人工智能AI Agent多模态语音AI 应用上一篇解决 Soybean Admin 混合菜单折叠时图标文本层级冲突的 3 个实用技巧下一篇如何编写专业的JavaScript构造函数面向对象开发的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
