Gradium ASR 扩展实战指南：在 TEN 框架中接入低延迟流式语音识别

Gradium ASR 扩展实战指南在 TEN 框架中接入低延迟流式语音识别【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework导读本文围绕 TEN 框架TEN-framework官方仓库中提供的gradium_asr_python扩展完整讲解如何通过 Gradium AI API 为会话式语音 AI Agent 接入基于 WebSocket 的实时语音转文本ASR能力。读完本文你将掌握该扩展的配置方式、音频输入规格、TEN 应用图中的接线方法、输出消息格式以及底层 WebSocket 协议与错误处理机制并能直接照搬示例搭建一条可运行的实时转录链路。扩展概述为语音 Agent 提供低延迟转录gradium_asr_python是 TEN 框架下的一款 Python ASR 扩展位于仓库的 ai_agents/agents/ten_packages/extension/gradium_asr_python 目录。它使用 Gradium AI API 提供实时语音转文本转录服务核心传输通道为 WebSocket 流式传输从而获得低延迟的转录体验。从源码看该扩展以 extension.py 中的GradiumASRExtension类为核心实现继承自ten_ai_base的AsyncASRBaseExtension并借助ten_runtime_python与ten_ai_base两个系统级依赖完成与 TEN 运行时的对接。扩展通过 addon.py 中的register_addon_as_extension(gradium_asr_python)注册为 TEN 扩展应用图graph中通过addon字段引用即可加载。功能特性根据扩展文档与源码实现该扩展具备以下能力通过 WebSocket 实现实时语音识别start_connection/_receive_loop/_send_loop三个异步方法构成完整的数据通路支持多个区域美国us与欧洲eu由config.py中的get_websocket_url()按区域选择端点语音活动检测VAD集成接收服务端下发的vad类型消息可配置的音频格式PCM、WAV、Opus由input_format参数控制低延迟流式转录音频帧经 base64 编码后逐块推送同时输出中间结果与最终结果通过final字段区分。配置指南环境变量设置 API 密钥Gradium API 密钥通过环境变量注入避免明文写入配置文件。在运行 TEN 应用前执行export GRADIUM_API_KEYyour_api_key_here扩展的 property.json 中使用${env:GRADIUM_API_KEY|}语法引用该环境变量|后为空表示未设置时不提供默认值。属性配置property.json在扩展包目录下的property.json中配置参数。仓库自带的默认配置如下{ params: { api_key: ${env:GRADIUM_API_KEY|}, region: us, model_name: default, input_format: pcm, sample_rate: 24000, language: } }扩展在on_init阶段通过ten_env.get_property_to_json()读取全部属性并使用 pydantic 模型GradiumASRConfig进行校验见 config.py。若校验失败扩展会记录错误日志并通过标准 TEN 错误接口向上层发送ModuleErrorFATAL_ERROR。配置参数表参数类型默认值描述api_keystring-Gradium API 密钥必需支持${env:GRADIUM_API_KEY}环境变量引用regionstringusAPI 区域取值us美国或eu欧洲由 pydanticLiteral[eu, us]强约束model_namestringdefaultGradium ASR 模型名称随setup消息上报服务端input_formatstringpcm音频格式取值pcm、wav或opus同样受Literal约束sample_rateinteger24000音频采样率HzGradium 服务期望 24 kHzlanguagestring可选语言代码仅在非空时随setup消息发送除了上述参数config.py 中的 pydantic 模型还定义了三个对调用方透明的内部参数channels默认1声道数Gradium 期望单声道bits_per_sample默认16位深Gradium 期望 16 位dump/dump_path默认false//tmp是否转储音频以辅助调试。这些参数由update()方法从property.json的params对象中合并而来只要在params中声明对应键即可覆盖。to_json(sensitive_handlingTrue)方法会在日志输出时把api_key掩码为***避免敏感信息泄露对应on_init中KEYPOINT vendor_config日志。音频要求Gradium ASR 服务期望的音频规格如下这也是input_audio_sample_rate()、input_audio_channels()、input_audio_sample_width()三个方法向 TEN 运行时声明输入格式的依据见 extension.py采样率24,000 Hz24 kHz格式PCM或 WAV/Opus位深度16 位有符号整数bits_per_sample // 8即每采样 2 字节声道单声道1 个声道推荐块大小每块 1920 个采样点80ms对应 const.py 中的GRADIUM_FRAME_SIZE 1920扩展的缓冲策略为ASRBufferConfigModeDiscard()即对输入音频帧不做复杂缓存、直接流转以保障实时性。API 端点区域 URL区域WebSocket 端点美国uswss://us.api.gradium.ai/api/speech/asr欧洲euwss://eu.api.gradium.ai/api/speech/asr端点选择逻辑实现在 config.py 的get_websocket_url()中region eu时返回欧洲端点否则返回美国端点。使用示例在 TEN 应用图中配置扩展在 TEN 应用的 graph 配置中将 Gradium ASR 扩展声明为一个节点并注入必要参数{ nodes: [ { type: extension, name: gradium_asr, addon: gradium_asr_python, extension_group: gradium_asr_group, property: { params: { api_key: ${env:GRADIUM_API_KEY|}, region: us, model_name: default } } } ] }其中addon必须与 addon.py 中注册的名称gradium_asr_python一致。property.params中的字段结构由 manifest.json 的api.property.properties.params声明api_key、region、model_name、input_format、sample_rate、language。连接音频输入将上游音频源如麦克风采集扩展的pcm_frame输出连接到gradium_asr扩展{ connections: [ { extension_group: audio_input_group, extension: audio_input, audio_frame_out: [ { name: pcm_frame, dest: [ { extension_group: gradium_asr_group, extension: gradium_asr } ] } ] } ] }连接建立后扩展通过send_audio()接收AudioFrame用frame.lock_buf()取出裸字节放入AsyncQueue再由_send_loop()任务逐帧取出、base64 编码后封装为{type: audio, audio: base64}消息推送到 WebSocket。底层 WebSocket 协议结合 const.py 与 extension.py可梳理出完整的消息类型与握手流程消息类型type方向说明setup客户端 → 服务端携带model_name、input_format可选languageready服务端 → 客户端握手成功确认收到后扩展才启动收发任务audio客户端 → 服务端base64 编码的音频数据text服务端 → 客户端转录文本结果vad服务端 → 客户端语音活动检测事件end_of_stream客户端 → 服务端流结束信号对应stop_connection()连接建立流程扩展调用websockets.connect(url, additional_headers{x-api-key: api_key})建立连接API 密钥通过 HTTP 头x-api-key传递见start_connection()发送setup消息若配置了language则附加语言代码等待服务端返回ready消息确认后置connected True并同时启动_receive_loop与_send_loop两个异步任务若收到的不是ready抛出异常并走错误处理分支。断开流程stop_connection()依次执行发送end_of_stream消息 → 取消接收与发送任务 → 关闭 WebSocket → 复位connected状态。由于 Gradium 不需要按会话显式终结finalize()方法为空实现。输出格式扩展以标准 TEN ASR 格式输出转录结果_handle_text_message()将服务端下发的text消息解析后通过_handle_asr_result()向上游透出{ text: 转录的文本, final: true, start_ms: 0, duration_ms: 1000, language: zh }结果字段说明字段类型说明textstring转录的文本内容finalboolean是否为最终结果false表示中间部分结果可用于流式展示start_msinteger该片段相对开始时间毫秒取自服务端消息的start_msduration_msinteger持续时间毫秒由服务端end_ms - start_ms计算得出languagestring检测到的或配置的语言取自config.language错误处理扩展通过标准 TEN 错误接口ModuleErrorModuleErrorVendorInfo向上层报告错误vendor()返回gradium。主要错误场景与处理逻辑连接错误WebSocket 连接失败start_connection()中的连接或握手异常会发送FATAL_ERROR级别的ModuleError并附带vendor_info.code connection_error身份验证错误无效的 API 密钥API 密钥通过x-api-key请求头传递服务端拒绝时同样在start_connection()的异常分支被捕获上报转录错误处理失败_receive_loop()接收或解析消息异常时发送NON_FATAL_ERROR级别的ModuleErrorvendor_info.code receive_error并复位连接状态。此外on_init阶段的配置校验失败也会产生FATAL_ERROR错误。所有错误消息均携带module asr标识见MODULE_NAME_ASR便于上层按模块路由处理。依赖项扩展的依赖在 requirements.txt 与 pyproject.toml 中声明运行时依赖如下websockets14.0WebSocket 客户端库负责与 Gradium 服务的流式通信pydantic2.0.0配置模型校验GradiumASRConfigtyping-extensions4.5.0override等类型标注支持ten_runtime_python0.11TEN 运行时 Python 绑定见 manifest.json 中的系统依赖声明ten_ai_base0.7TEN AI 基础类AsyncASRBaseExtension、ASRBufferConfig、消息与错误类型等。扩展包版本为0.1.1见 manifest.json要求 Python3.10。许可证与支持本扩展与 TEN 框架采用相同许可证。如在使用中遇到问题可参考以下途径Gradium API 文档https://gradium.ai/api_docs.html确认服务端协议与配额TEN 框架官方文档仓库的 docs 目录以及框架根目录的 README.md获取应用图配置与调试方法查看仓库内其他语音示例如 ai_agents/agents/examples/voice-assistant中 ASR 扩展的接线方式作为集成参考。【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考