人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载导读本文围绕 TEN Framework 开源仓库中的aws_asr_python扩展位于 ai_agents/agents/ten_packages/extension/aws_asr_python展开系统讲解如何通过该扩展接入 AWS Transcribe 流式转录 API为对话式语音 AI Agent 提供低延迟的实时语音转文本能力。读完本文你将掌握该扩展的完整配置项与默认值、异步生命周期方法、自动重连与指数退避策略、音频转储调试手段以及基于源码与测试用例的底层实现原理可直接在 TEN Framework 的语音场景中正确部署与排障。扩展定位为 TEN Framework 提供 AWS 实时 ASR 能力aws_asr_python是一个用 Python 编写的 ASR自动语音识别扩展其核心职责是把输入音频流实时转换为文本并作为 TEN Framework 图Graph中的一个标准 ASR 节点参与语音 Agent 的数据流。根据扩展说明见 docs/README.zh-CN.md它具备以下关键能力完全异步支持整体采用异步架构基于asyncio实现高性能、非阻塞的语音识别处理实时流式处理使用 AWS Transcribe 的流式 API 进行低延迟音频流转录音频转储可选的 PCM 音频录制功能用于调试和分析识别质量错误处理全面的错误处理与详细日志记录通过模块错误码、AWS 特定错误详情和优雅降级机制反馈问题多语言支持通过 AWS Transcribe 支持en-US、zh-CN等多种语言代码重连管理内置自动重连机制保障服务稳定性会话管理支持会话 ID 与音频时间线timeline管理。从清单文件 manifest.json 可以看到该扩展版本为0.2.3依赖ten_runtime_python0.11与ten_ai_base0.7两个系统包并通过api.interface引用asr-interface.json即遵循 TEN Framework 标准的 ASR 接口约定addon.py中使用register_addon_as_extension(aws_asr_python)将扩展注册到运行时因此它可以被 TEN Framework 的图配置直接实例化。配置指南必填项、可选项与完整示例扩展的配置通过 TEN Framework 的 property 机制注入在on_init阶段由AWSASRConfig.model_validate_json()完成解析与校验见 extension.py。配置主体是一个params对象内含认证信息与转录参数。必需参数paramsAWS Transcribe 配置对象包含认证信息和转录设置。在 config.py 中以下字段被声明为必填Pydantic 中无默认值的字段字段说明示例regionAWS 区域us-west-2access_key_idAWS 访问密钥 IDyour_aws_access_key_idsecret_access_keyAWS 秘密访问密钥your_aws_secret_access_keylanguage_code语言代码en-US、zh-CNmedia_sample_rate_hz音频采样率Hz16000media_encoding音频编码格式pcm扩展级可选参数dump是否启用音频转储默认falsedump_path转储音频文件路径默认扩展目录下的aws_asr_in.pcmlog_level日志级别默认INFOfinalize_mode完成模式可选disconnect或mute_pkg默认disconnectmute_pkg_duration_ms静音包持续时间毫秒默认800。AWS Transcribe 可选参数params 内以下字段在 config.py 中均为可选默认None并会在启动转录时透传给start_stream_transcription字段说明vocabulary_name自定义词汇表名称参考 AWS 文档 custom-vocabularysession_id会话 IDvocab_filter_method词汇过滤方法vocab_filter_name词汇过滤器名称show_speaker_label是否显示说话人标签enable_channel_identification是否启用声道识别number_of_channels声道数量enable_partial_results_stabilization是否启用部分结果稳定化partial_results_stability部分结果稳定性设置如HIGHlanguage_model_name语言模型名称完整配置示例文档给出的完整配置docs/README.zh-CN.md{ params: { region: us-west-2, access_key_id: your_aws_access_key_id, secret_access_key: your_aws_secret_access_key, language_code: en-US, media_sample_rate_hz: 16000, media_encoding: pcm, vocabulary_name: custom-vocabulary, show_speaker_label: true, enable_partial_results_stabilization: true, partial_results_stability: HIGH }, dump: false, log_level: INFO, finalize_mode: disconnect, mute_pkg_duration_ms: 800 }仓库自带的 property.json 演示了使用环境变量占位符注入敏感凭据的推荐做法{ params: { region: ${env:AWS_ASR_REGION|}, access_key_id: ${env:AWS_ASR_ACCESS_KEY_ID|}, secret_access_key: ${env:AWS_ASR_SECRET_ACCESS_KEY|}, language_code: en-US, media_sample_rate_hz: 16000, media_encoding: pcm } }即通过AWS_ASR_REGION、AWS_ASR_ACCESS_KEY_ID、AWS_ASR_SECRET_ACCESS_KEY三个环境变量提供配置值占位符中|后的空串为缺省值避免把密钥硬编码进配置。测试目录中的 property_zh.json 还给出了zh-CN语言代码的变体。凭据序列化保护值得注意的细节config.py通过encrypting_serializer(access_key_id, secret_access_key)实现见 utils.py为两个密钥字段注册了 Pydantic JSON 序列化器。当调用model_dump_json()输出配置日志时密钥只会显示为前缀***后缀的掩码形式仅取字符串前 1/5 与后 1/5 字符最长 5 字符防止密钥在日志中泄露同时不影响内部使用。核心 API 与异步生命周期该扩展实现了AsyncASRBaseExtension接口源自ten_ai_base.asr核心方法均以异步方式定义由 TEN 运行时在合适的时机回调方法职责on_init()读取并校验配置初始化 AWS ASR 客户端、音频转储器与重连管理器start_connection()建立与 AWS Transcribe 服务的连接并启动转录事件消费协程stop_connection()关闭与 ASR 服务的连接并停止音频转储send_audio()发送音频帧进行识别finalize()完成当前识别会话按finalize_mode分派is_connected()检查连接状态内部实现方法还包括_handle_transcript_event()处理转录事件_disconnect_aws()断开 AWS 连接_reconnect_aws()重新连接 AWS_handle_finalize_disconnect()处理“断开连接”完成模式_handle_finalize_mute_pkg()处理“静音包”完成模式。连接建立流程start_connection()extension.py的实际调用链如下使用TranscribeStreamingClient(**self.config.params.to_client_params())创建客户端。to_client_params()返回region与StaticCredentialResolver(access_key_id, secret_access_key)即使用静态凭据解析器完成认证调用client.start_stream_transcription(**self.config.params.to_transcription_params())建立转录流。to_transcription_params()会过滤掉region、密钥、log_level、finalize_mode、mute_pkg_duration_ms等客户端级字段仅把language_code、media_sample_rate_hz、media_encoding及所有可选转录参数透传给 AWS API连接成功后connected True并通知ReconnectManager.mark_connection_successful()重置重连计数通过asyncio.create_task(_handle_events())启动事件消费协程异步遍历stream.output_stream对TranscriptEvent调用_handle_transcript_event()若流被关闭异常则置connected False并触发_reconnect_aws()自动重连。音频发送与格式约束send_audio()接收AudioFrame取出缓冲区字节后若启用了dump将原始字节推入音频转储器依据采样率计算本次音频时长并记入audio_timelinelen(buf) / (sample_rate / 1000 * 2)即 16-bit 采样每样本 2 字节通过stream.input_stream.send_audio_event(audio_chunkbytes(buf))送入 AWS 转录流当流已关闭时会抛出IOError此时扩展将其视为需要重连的信号置connected False并调用_reconnect_aws()返回False。音频格式约束PCM1616 位 PCM、支持多种采样率如 16000 Hz、单声道。从时长计算公式可以看出扩展按 2 字节/样本的 16 位 PCM 单声道布局处理输入音频配置时需保证输入帧格式与media_encoding、media_sample_rate_hz一致。转录结果处理_handle_transcript_event()逐条遍历transcript.results对每个候选结果若结果非 partialis_partial False且之前有未完成的finalize计时则发送send_asr_finalize_end()通知会话结束提取alternatives[0]中的词级信息content、stable、start_time、end_time结合audio_timeline把 AWS 相对时间戳换算为全局音频时间线偏移构造ASRWord列表最终通过send_asr_result()向下游输出ASRResult包含text、final、start_ms、duration_ms、language与words等字段。is_connected()的实现同时检查self.stream非空、底层输入流未关闭且self.connected为真保证状态判断与实际可用性一致。finalize 完成模式disconnect 与 mute_pkgfinalize()根据finalize_mode选择会话收尾方式extension.pydisconnect默认调用_handle_finalize_disconnect()直接向流发送end_stream()结束转录等待 AWS 返回最终结果。这种模式适合“说完即断”的回合式交互能最快获得确定性的最终文本mute_pkg调用_handle_finalize_mute_pkg()不关闭流而是构造一段长度为mute_pkg_duration_ms * sample_rate / 1000 * 2字节的全零静音包发送给 AWS并通过audio_timeline.add_silence_audio()把这段静音计入时间线。静音包会促使 AWS 返回已识别内容的最终结果同时保持连接复用适合连续多轮对话场景。默认静音包时长 800ms 可在配置中调整。自动重连机制与指数退避扩展内置自动重连机制实现见 reconnect_manager.py关键策略与文档描述一致最多 5 次重连尝试max_attempts 5可在构造时调整指数退避基础延迟 300ms按delay base_delay * 2^(attempts-1)计算即依次为300ms、600ms、1.2s、2.4s、4.8s连接成功后自动重置计数器mark_connection_successful()会复位attempts详细日志每次重连前记录Attempting reconnection #N/5 after X seconds delay...达到上限后通过error_handler发送FATAL_ERROR模块错误。重连由_reconnect_aws()驱动先通过can_retry()判断是否还有重试额度再调用handle_reconnect(connection_funcself.start_connection, error_handlerself.send_asr_error)执行单次带延迟的重连尝试。整个链路保证了在网络抖动或 AWS 侧断流时语音服务可以自动恢复。开发与测试构建扩展作为 TEN Framework 构建系统的一部分进行构建无需额外的构建步骤文档说明见 docs/README.zh-CN.md。依赖声明在 requirements.txt 与 pyproject.toml 中amazon-transcribe0.6.4AWS Transcribe Python 客户端库pydantic2.13.4配置校验与数据模型typing_extensions4.15.0类型提示pytest8.3.4测试框架开发依赖。Python 版本要求3.10。测试运行单元测试pytest tests/测试目录提供了完整的可运行验证链路test_asr_result.py通过AsyncExtensionTester以单扩展测试模式加载aws_asr_python持续发送 16 位 PCM 音频帧320 字节/帧并校验下游asr_result数据包含id、text、final、start_ms、duration_ms、language、metadata字段以及session_id回传正确收到finaltrue结果后结束测试mock.py通过unittest.mock.patch替换TranscribeStreamingClient模拟流式转录的输入/输出流其中MockInputStream会在发送超过 100 个音频块后抛出IOError以模拟流关闭场景从而验证重连逻辑conftest.py以FakeApp在独立线程中启动一个最小化的 TEN 应用作为测试宿主为扩展测试提供运行时环境。使用方法安装扩展随 TEN Framework 自动安装配置设置 AWS 凭据推荐环境变量方式与 Transcribe 参数集成通过 TEN Framework 的 ASR 接口在图中使用该扩展监控检查日志进行调试与监控日志类别包含vendor厂商状态/错误与key_point关键节点配置两类便于过滤检索。故障排除常见问题连接失败检查 AWS 凭据是否正确、网络是否可达 AWS Transcribe 服务端点认证错误验证 AWS 访问密钥及 IAM 权限是否包含 Transcribe 流式转录所需的transcribe:StartStreamTranscription权限音频质量问题验证音频格式PCM16、单声道与采样率设置是否与media_sample_rate_hz、media_encoding一致性能问题调整缓冲区设置与语言模型language_model_name等参数日志问题配置适当的log_level如DEBUG以获取更详细的转录事件与重连日志。调试模式通过在配置中设置dump: true启用调试模式把送入 AWS 的原始音频录制为 PCM 文件默认路径aws_asr_in.pcm可通过dump_path修改。需要注意的是当dump_path不以.pcm结尾时扩展会将其视为目录并在其下创建aws_asr_in.pcm见 extension.py。录制的文件可用于离线回放、人工比对识别文本或与下游 TTS 输入对照排查链路问题。许可证此扩展是 TEN Framework 的一部分根据 Apache License, Version 2.0 授权。延伸阅读想深入了解本扩展所实现的 ASR 接口约定可查看ten_ai_base系统中的 asr-interface.jsonmanifest 中引用的接口定义想了解如何将该扩展编排进完整的语音 Agent 图可参考仓库中 ai_agents/agents/examples 下的 voice-assistant 系列示例。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework 的 AWS ASR Python 扩展基于 Amazon Transcribe 流式 API 的实时语音转文字实战指南TEN Framework 的 AWS ASR Python 扩展基于 Amazon Transcribe 流式 API 的实时语音转文字实战指南 AWS A人工智能AI Agent多模态语音AI 应用TEN Framework 集成 AWS Transcribe 流式语音识别aws_asr_python 扩展完整实战指南TEN Framework 集成 AWS Transcribe 流式语音识别aws_asr_python 扩展完整实战指南 导读 本文以 TEN Framew人工智能AI Agent多模态语音AI 应用Label Studio 如何用 Docker Compose 启动带 PostgreSQL 的完整部署Label Studio 如何用 Docker Compose 启动带 PostgreSQL 的完整部署 Label Studio 默认使用 SQLite 存人工智能AI Agent多模态语音AI 应用上一篇Open Agents 持久化睡眠Serverless 中跨部署存活的定时器下一篇高效免费GPU内存检测3个实用场景教你快速排查显卡硬件问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考