TEN Framework 集成 Deepgram Aura 流式 TTS:deepgram_tts 扩展的配置、接口与原理详解

原创2026-09-23 18:04:071,447 阅读
文章标签:人工智能大模型语音音频多模态AI Agent实时分析后端插件系统Web框架开发者工具低代码MCP Clients工作流自动化跨平台

TEN Framework 集成 Deepgram Aura 流式 TTS:deepgram_tts 扩展的配置、接口与原理详解

Deepgram TTS Extension 是 TEN Framework 中基于 Deepgram Aura 流式 API 实现的 Text-to-Speech(TTS)扩展,通过 WebSocket 以线性16(Linear16)PCM 格式实时返回音频流。本文以该扩展的 README 为核心骨架,结合其源码与测试,完整讲解配置参数、支持的音色与采样率、标准 TTS 数据接口、TTFB 指标上报、音频 dump 调试以及测试运行方式,帮助你在 TEN 框架的语音 Agent 图(graph)中快速接入低延迟流式语音合成能力。

功能特性

从 README 和源码实现来看,该扩展的核心能力包括:

  • 实时流式 TTS:通过 WebSocket 连接 Deepgram Aura 服务,边合成边返回音频,无需等待整段文本全部合成完毕;
  • 多种音色模型:完整支持 Deepgram Aura-2 系列共 12 个音色(见下文列表);
  • 可配置采样率:支持 8000、16000、24000、48000 Hz 四种输出采样率;
  • Linear16 PCM 音频输出:16-bit、单声道(mono)裸 PCM 数据,便于下游直接播放或转发;
  • TTFB(Time to First Byte)指标上报:记录从发送文本到收到第一段音频的时间,随 metrics 数据输出;
  • 音频 dump 能力:开启后可将合成音频以 .pcm 文件落盘,方便离线调试与质量检查。

工作原理:Speak + Flush 流式协议

扩展的核心是 deepgram_tts.py 中的 DeepgramTTSClient。它维护一条复用的 WebSocket 连接,每次调用 get(text) 时依次发送两条 JSON 控制消息:

  1. {"type": "Speak", "text": text} —— 告诉 Deepgram 开始合成指定文本;
  2. {"type": "Flush"} —— 指示服务端在合成完当前文本后立即冲刷输出并返回 Flushed 消息。

随后客户端循环接收消息:二进制消息即为音频分片(bytes),JSON 文本消息则根据 type 字段区分 Flushed(结束)、Warning(警告)、Error(错误)。收到 Flushed 后本次请求结束,连接保持复用,下一次 get() 可以继续发送新文本。

连接并非一成不变,源码实现了三层保障:

  • 预连接(preheat):on_init 阶段调用 client.start() 提前建立 WebSocket 连接,减少首包延迟;
  • 按需重连:_ensure_connection() 在连接不存在时建立连接,_reconnect() 在出错或取消后重建连接;
  • 超时保护:接收音频时使用 WS_RECV_TIMEOUT = 8.0 秒(deepgram_tts.py)的等待上限,超时后标记需要重连并向上层抛出错误事件。

此外,cancel() 会发送 Flush 并排空(drain)直到收到 Flushed,保证连接处于干净状态,可供下一次请求继续使用——这对应 README 中 tts_flush 输入的处理逻辑。

配置详解

扩展配置通过 TEN 框架的 property 机制注入,在 property.json 中给出默认值,并在 manifest.json 中声明了 schema(api 部分)。扩展在 on_init 时通过 ten_env.get_property_to_json("") 读取全部配置,并交给 pydantic 模型 DeepgramTTSConfig(config.py)解析校验。

属性一览

Property 类型 默认值 说明
params.api_key string 必填 Deepgram API key,支持 ${env:DEEPGRAM_API_KEY} 环境变量引用
params.model string aura-2-thalia-en 使用的音色模型
params.encoding string linear16 音频编码格式
params.sample_rate int 24000 输出采样率(Hz),取值范围见下文
params.base_url string wss://api.deepgram.com/v1/speak WebSocket 端点
params.<deepgram_query_param> scalar 可选 额外透传给 Deepgram 的 WebSocket 查询参数
dump bool false 是否开启音频落盘
dump_path string /tmp dump 文件输出目录

参数归一化与透传

config.py 中的 update_params() 方法实现了一套“已知键归一化、未知键透传”的规则(config.py):

  • api_key、base_url、model、encoding、sample_rate 这五个扩展自有的键会被从 params 中取出,赋值到配置模型对应的属性上(同时从 params 中删除,避免重复);
  • params 中剩余的标量键值对(如 container、punctuate、smart_format 等 Deepgram 支持的 WebSocket 查询参数)会原样保留;
  • 在 deepgram_tts.py 的 _build_ws_url() 中,这些透传参数会同 model、encoding、sample_rate 一起通过 urlencode 拼接到 WebSocket 查询字符串上;而 api_key、base_url 永远不会进入查询串——API key 是通过 Authorization: Token <api_key> 请求头发送的(deepgram_tts.py)。

另外,配置对象在日志输出时会调用 to_str(sensitive_handling=True) 对 api_key 做脱敏加密处理(config.py),避免密钥明文出现在日志中。

配置示例

README 给出的标准配置如下,可直接复制使用:

{
  "params": {
    "api_key": "${env:DEEPGRAM_API_KEY}",
    "model": "aura-2-thalia-en",
    "encoding": "linear16",
    "sample_rate": 24000,
    "container": "none"
  },
  "dump": false,
  "dump_path": "/tmp"
}

其中 container: "none" 就是一个典型的透传参数:Deepgram 默认会在某些场景下返回带容器格式的数据,显式传 "none" 可确保拿到的是裸 Linear16 PCM 流,与扩展下游 pcm_frame 输出格式保持一致。

on_init 阶段会做两项硬性校验(extension.py):配置为空或为 {} 时直接报错“Configuration is empty”;api_key 为空时抛出 ValueError("API key is required")。初始化失败会通过 send_tts_error 上报 FATAL_ERROR 级别的 ModuleError,其中 vendor 字段固定为 "deepgram"。

可用音色模型

Deepgram Aura-2 系列共 12 个英语音色,女声/男声各 6 个:

  • 女声:aura-2-thalia-en(默认)、aura-2-luna-en、aura-2-stella-en、aura-2-athena-en、aura-2-hera-en
  • 男声:aura-2-orion-en、aura-2-arcas-en、aura-2-perseus-en、aura-2-angus-en、aura-2-orpheus-en、aura-2-helios-en、aura-2-zeus-en

通过修改 params.model 即可切换音色,无需改动代码或重启重建连接(新配置在下次建立 WebSocket 连接时生效)。

支持的采样率

采样率 说明
8000 Hz 窄带电话场景
16000 Hz 常见语音识别/通话场景
24000 Hz 推荐值(默认)
48000 Hz 高保真场景

采样率由 params.sample_rate 控制,同时会影响音频时长计算。在 extension.py 的 _calculate_audio_duration_ms() 中,音频时长按“16-bit(2 字节/采样)× 单声道”计算:duration_ms = total_audio_bytes / (sample_rate × 2 × 1) × 1000。

标准 TTS 数据接口

该扩展实现的是 TEN 标准 TTS 接口(AsyncTTS2BaseExtension,声明于 manifest.json 引用的 ten_ai_base 的 tts-interface.json),在图中与其他 TEN 扩展通过命名数据(named data)通信:

输入数据(Data)

  • tts_text_input —— 待合成文本,携带 request_id、text、text_input_end 等字段;其中 text_input_end=True 表示该请求文本已全部送入,收到合成结束事件后即可完成请求;
  • tts_flush —— 冲刷/打断当前请求:cancel_tts() 会向客户端发送 Flush 并最终以 INTERRUPTED 原因结束请求。

输出数据(Data)

  • tts_audio_start —— 音频生成开始(在收到首个音频分片、TTFB 统计完成时发送);
  • tts_audio_end —— 音频生成完成,携带 request_event_interval_ms(流式耗时)与 request_total_audio_duration_ms(音频总时长)等元数据;
  • metrics —— 性能指标,核心字段为嵌套在 metrics 对象中的 ttfb(毫秒)以及 model 等附加信息;
  • error —— 错误信息,按 ModuleError 结构上报(含 module=TTS、code、vendor_info)。

输出音频(AudioFrame)

  • pcm_frame —— 16-bit、单声道 PCM 音频数据,采样率与 params.sample_rate 一致。

TTFB 指标与错误处理

TTFB 上报流程

TTFB 的统计在客户端与扩展层协作完成(deepgram_tts.py):

  1. 发送 Speak 前记录 _sent_ts = datetime.now();
  2. 收到第一段二进制音频分片时,计算 ttfb_ms = (now - _sent_ts) × 1000;
  3. 以 EVENT_TTS_TTFB_METRIC 事件抛给扩展层;
  4. 扩展层收到后发送 tts_audio_start 与 metrics 数据(ttfb 字段 + model 元数据),随后正常转发音频分片。

扩展层的测试 test_metrics.py 用 mock 模拟了“延迟 0.2s 后先发 TTFB 指标、再发音频分片、最后发 END”的完整时序,并断言 metrics 数据中嵌套的 ttfb 值正确、音频帧与 tts_audio_end 均已收到——可作为理解该数据结构的直接参考。

错误处理策略

  • 连接层错误:DeepgramTTSConnectionException 携带 HTTP 状态码;401 视为 FATAL_ERROR,其余为 NON_FATAL_ERROR,错误详情通过 vendor_info(vendor=deepgram, code, message)上报;
  • 流式过程中的错误:Deepgram 返回 Error 消息时标记需要重连;若错误发生在非末段文本(text_input_end=False),仅记录 warning 继续流式;若发生在末段,则以 ERROR 原因结束请求;
  • 超时/异常:8 秒未收到数据即上报 EVENT_TTS_ERROR 并触发重连,保证连接状态自愈。

音频 dump 调试

当 dump 设为 true 时,扩展会为每个请求创建 PCMWriter,把收到的每个音频分片按顺序写入 {dump_path}/deepgram_dump_{request_id}.pcm(extension.py)。要点:

  • 文件为裸 PCM 格式,可用支持 raw PCM 的播放器或 Audacity(按 16-bit、单声道、对应采样率导入)试听;
  • 新请求开始时自动清理旧请求的 dump writer;
  • 扩展停止(on_stop)时会 flush 所有未写完的 dump 文件。

测试目录 tests/configs/property_dump.json 展示了开启 dump 的配置(输出到 ./tests/keep_dump_output/);而 tests/configs/property_invalid.json、tests/configs/property_miss_required.json 则分别覆盖了非法配置与缺少必填项(api_key)的失败路径。

运行测试

扩展自带基于 ExtensionTester 的单元测试(位于 tests 目录,覆盖基础合成、错误消息、指标、参数透传、鲁棒性、状态机等场景)。按 README 说明运行:

cd deepgram_tts
tman -y install --standalone
./tests/bin/start

tman -y install --standalone 会以 standalone 模式安装扩展及其依赖(ten_runtime_python 0.11、ten_ai_base 0.7,见 manifest.json),./tests/bin/start 启动测试套件。测试通过 mock 掉 DeepgramTTSClient 的方式运行,无需真实 API key 即可验证扩展层逻辑;需要真实联调时则通过环境变量注入密钥。

环境变量与依赖

  • DEEPGRAM_API_KEY —— Deepgram API key,配置中通过 ${env:DEEPGRAM_API_KEY} 引用。
  • 运行依赖(requirements.txt):websockets>=14.0(Python >= 3.10,见 pyproject.toml)。

许可证

Apache License, Version 2.0。

登录后查看全文
ten-framework