在 TEN Framework 中接入 Oracle TTS:oracle_tts_python 扩展的配置、原理与实战指南

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

在 TEN Framework 中接入 Oracle TTS:oracle_tts_python 扩展的配置、原理与实战指南

TEN Framework 的 oracle_tts_python 扩展为会话式语音 AI Agent 提供了一条接入 Oracle Cloud Infrastructure(OCI)Speech 文本转语音(TTS)服务的标准通道。它以标准的 TTS2 接口对接 TEN 运行时,通过 OCI API 密钥完成认证,将文本合成为 PCM 音频流并回传给 Agent 管线,同时内置了重试、取消、WAV 头剥离等工程化处理。读完本文,你将掌握该扩展的完整配置方式、环境变量用法、底层实现原理与测试验证方法,能够直接在自己的语音 Agent 图(graph)中部署并调优 Oracle TTS 能力。

扩展定位:TEN Framework 语音 Agent 中的 Oracle 语音出口

oracle_tts_python 是 TEN Framework 生态中针对 Oracle Cloud Infrastructure(OCI)Speech TTS 服务的官方扩展实现,位于仓库的 ai_agents/agents/ten_packages/extension/oracle_tts_python 目录。从 manifest.json 可以看到,它声明为 extension 类型,版本 0.1.3,依赖 ten_runtime_python(0.11)与 ten_ai_base(0.7)两个系统包,并通过 import_uri: ../../system/ten_ai_base/api/tts-interface.json 复用了 TEN 标准的 TTS 接口定义。

在会话式语音 Agent 的典型链路(ASR → LLM → TTS → 播放/上行)中,该扩展处于 TTS 输出环节:上游 LLM 产生文本后,扩展将文本发送至 OCI Speech 服务,合成音频后以标准 TTS 消息(tts_audio_start / tts_audio_data / tts_audio_end)回传,供播放器或 WebSocket 上行通道消费。

该扩展的代码结构非常精简,由四个核心模块构成:

文件 职责
addon.py 通过 register_addon_as_extension("oracle_tts_python") 注册 Addon,负责实例化扩展
extension.py OracleTTSExtension,继承 AsyncTTS2BaseExtension,实现 TTS 请求处理、音频流回传、取消与指标上报
config.py OracleTTSConfig(pydantic 模型),负责参数校验、敏感信息脱敏
oracle_tts.py OracleTTS 客户端,封装 OCI Python SDK,完成认证、合成请求、WAV 剥离、重试与取消

配置详解:参数、默认值与环境变量

完整参数表

扩展的全部配置位于扩展的 property 中,README.md 给出了完整参数清单:

参数 类型 必填 默认值 说明
tenancy string 是 OCI tenancy OCID
user string 是 OCI user OCID
fingerprint string 是 API key 指纹
key_file string 是 Base64 编码的 PEM 私钥字符串
compartment_id string 是 OCI compartment OCID
region string 否 us-phoenix-1 OCI 区域标识符
model_name string 否 TTS_2_NATURAL TTS 模型(TTS_1_STANDARD 或 TTS_2_NATURAL)
voice_id string 否 Annabelle 音色标识符
language_code string 否 en-US 合成语言代码
sample_rate int 否 16000 音频采样率(Hz)
output_format string 否 PCM 音频输出格式

必填项的校验逻辑位于 config.py 的 validate_params():缺失 tenancy、user、fingerprint、key_file、compartment_id 中任意一项(或值为空字符串)都会抛出 ValueError,并明确指出缺失项,例如 Missing required OCI parameters: fingerprint。对应测试见 tests/test_config.py,覆盖了"全缺失报错""部分缺失精确报告缺失字段""空字符串视为缺失"等场景。

环境变量

README 建议通过环境变量注入 OCI 凭据,避免把密钥写死在配置文件中:

  • OCI_TENANCY
  • OCI_USER
  • OCI_FINGERPRINT
  • OCI_KEY_FILE_BASE64
  • OCI_COMPARTMENT_ID
  • OCI_REGION(可选,默认 us-phoenix-1)

扩展自带的默认配置 property.json 展示了环境变量在 property 中的引用语法(TEN Framework 的 ${env:VAR} 模板语法,| 后为默认值):

{
  "dump": false,
  "dump_path": "/tmp",
  "params": {
    "tenancy": "${env:OCI_TENANCY}",
    "user": "${env:OCI_USER}",
    "fingerprint": "${env:OCI_FINGERPRINT}",
    "key_file": "${env:OCI_KEY_FILE_BASE64}",
    "compartment_id": "${env:OCI_COMPARTMENT_ID}",
    "region": "${env:OCI_REGION|us-phoenix-1}",
    "model_name": "TTS_2_NATURAL",
    "voice_id": "Annabelle",
    "language_code": "en-US",
    "sample_rate": 16000,
    "output_format": "PCM"
  }
}

region 一项使用了 ${env:OCI_REGION|us-phoenix-1} 带默认值的写法:未设置环境变量时自动回落到 us-phoenix-1。该回落逻辑在源码中也有一致实现——oracle_tts.py 的 _initialize_client() 中 params.get("region") or "us-phoenix-1",并且 tests/test_tts_client.py 的 test_empty_region_falls_back_to_default 与 test_explicit_region_used 分别验证了空 region 回落与显式 region(如 eu-frankfurt-1)生效。

两个补充配置项

除 README 参数表外,源码还提供了两个与调试相关的配置(同样在 manifest 的 api.property 中声明):

  • dump(bool,默认 false):开启后把每次合成返回的原始 PCM 落盘,便于离线排查音频质量问题;
  • dump_path(string,默认 /tmp):PCM 转储目录,文件名格式为 oracle_tts_dump_<request_id>.pcm(见 extension.py)。

测试配置 tests/configs/property_basic_audio_setting1.json 与 tests/configs/property_dump.json 均演示了 dump: true 的用法,后者将转储目录指向 ./tests/dump_output/。

敏感信息脱敏

由于配置中包含密钥,OracleTTSConfig.to_json() 提供了 sensitive_handling 开关:开启后会对 fingerprint、key_file、tenancy、user 四个敏感字段调用 ten_ai_base.utils.encrypt 进行加密后再输出(config.py)。扩展初始化时会以 sensitive_handling=True 的方式打印配置日志,避免明文密钥进入日志;tests/test_config.py 的 test_to_json_is_valid_json_with_masking 验证了脱敏后敏感字段不再等于原始值,而非敏感字段(如 voice_id)保持原样。

安装与加载:Addon 注册机制

该扩展在 TEN Framework 中作为 Python Addon 加载,入口是 addon.py:

from ten_runtime import (
    Addon,
    register_addon_as_extension,
    TenEnv,
)

@register_addon_as_extension("oracle_tts_python")
class OracleTTSExtensionAddon(Addon):

    def on_create_instance(self, ten_env: TenEnv, name: str, context) -> None:
        from .extension import OracleTTSExtension
        ten_env.log_info("OracleTTSExtensionAddon on_create_instance")
        ten_env.on_create_instance_done(OracleTTSExtension(name), context)

register_addon_as_extension("oracle_tts_python") 将 Addon 注册为名为 oracle_tts_python 的扩展,运行时按需通过 on_create_instance 创建 OracleTTSExtension 实例。因此,在你的 Agent 应用 property(如 agents/xxx/property.json 的 addon 或 graph 定义)中,以扩展名 oracle_tts_python 引用该模块,并为其提供上文所述的 params 配置即可。

依赖方面,pyproject.toml 声明 Python 要求 >=3.10,依赖 oci>=2.181.0 与 pydantic>=2.13.4;requirements.txt 与之一致。

工作原理:从文本到 PCM 音频流的完整链路

初始化:配置校验与密钥落地

扩展 on_init(extension.py)按以下顺序完成初始化:

  1. 通过 ten_env.get_property_to_json("") 读取全部 property,若为空直接报错;
  2. 用 OracleTTSConfig.model_validate_json() 解析为 pydantic 模型,并调用 validate_params() 校验必填项;
  3. 对 base64 的 key_file 解码,写入 tempfile.mkstemp(suffix=".pem", prefix="oci_key_") 生成的临时文件,并 chmod 0o600 收紧权限,随后把配置中的 key_file 替换为临时文件路径;
  4. 构造 OracleTTS 客户端(内部完成 oci.config.validate_config 与 AIServiceSpeechClient 创建)。

临时 PEM 文件的生命周期由扩展管理:on_stop 时若临时文件仍存在则删除,同时调用 client.clean() 释放客户端并 flush 所有 PCM 写入器(extension.py)。这种"运行时临时落盘、退出即清理"的设计,既满足了 OCI SDK 对密钥文件路径的要求,又避免密钥常驻磁盘。

合成请求:模型、语音与音频设置

OracleTTS._build_model_details()(oracle_tts.py)根据 model_name 构造不同的 OCI 模型详情:

  • TTS_1_STANDARD → TtsOracleTts1StandardModelDetails(model_name, voice_id)
  • TTS_2_NATURAL → TtsOracleTts2NaturalModelDetails(model_name, voice_id, language_code)

源码用白名单 _KNOWN_MODELS = {"TTS_1_STANDARD", "TTS_2_NATURAL"} 拦截未知模型名并抛出 ValueError。_build_speech_settings() 则构造 TtsOracleSpeechSettings,固定 text_type="TEXT",透传 sample_rate_in_hz 与 output_format(oracle_tts.py)。

最终请求通过 client.synthesize_speech() 发起,请求体 SynthesizeSpeechDetails 包含 text、is_stream_enabled=True、compartment_id,以及 model_family="ORACLE" 的配置(oracle_tts.py)。

WAV 头剥离:保证纯 PCM 输出

OCI 流式合成返回的音频带 WAV/RIFF 封装,而 TTS2 接口需要裸 PCM。_strip_wav_header()(oracle_tts.py)专门处理这一环节,并覆盖了两类易错场景:

  1. data chunk 大小准确、尾部存在元数据块(如 LIST、fact、id3 、INFO、PEAK、bext、JUNK、cue ):按声明的 chunk_size 截取 PCM,排除尾部非音频数据,防止播放"爆音";
  2. data chunk 大小过小(流式占位):改用 data 头之后全部剩余字节,防止截断。

同时保证返回的 PCM 字节数为偶数(16-bit PCM 单样本 2 字节),奇数时裁掉最后一个字节。该函数是 tests/test_oracle_tts.py 中单测最密集的部分,覆盖了非 RIFF 直通、短输入直通、错误 WAVE 标识直通、标准 WAV 提取、奇数长度修剪、data 大小为 0 时使用剩余字节、尾部元数据剔除、超大声明大小使用剩余字节等 9 个用例。

音频流回传与指标

OracleTTS.get()(oracle_tts.py)以异步生成器逐块(每块 4096 字节)产出 (audio_chunk, event, ttfb_ms) 三元组,事件类型包括:

  • EVENT_TTS_RESPONSE:携带音频数据块,首块附带 TTFB(首包延迟)毫秒值,后续块为 None;
  • EVENT_TTS_REQUEST_END:本次合成结束;
  • EVENT_TTS_ERROR:一般错误;
  • EVENT_TTS_INVALID_KEY_ERROR:认证失败(HTTP 401/403 或错误信息含 auth/credentials 等关键词),扩展会将其升级为 FATAL_ERROR 并终止会话。

扩展侧(extension.py)收到 EVENT_TTS_RESPONSE 后累计 total_audio_bytes,通过 send_tts_audio_start / send_tts_audio_data / send_tts_audio_end 回传,并在首次收到音频时上报 send_tts_ttfbf_metrics(附带 voice_id 与 model_name 元数据)。请求结束时,_calculate_audio_duration_ms() 依据"字节数 /(采样率 × 2 字节 × 单声道)"换算总音频时长(毫秒),随 send_tts_audio_end 一起上报,供上层统计与对齐使用。

重试与取消

OCI SDK 调用是同步阻塞的,get() 通过 run_in_executor 放到线程池执行,并每 100ms 轮询一次取消标志,从而在不阻塞事件循环的前提下实现可取消(oracle_tts.py)。

重试策略(最多 3 次,退避间隔 1s → 2s)针对两类错误:

  • OCI ServiceError:HTTP 429/500/502/503 视为可重试;401/403 直接判定为密钥错误;
  • 通用异常:错误信息含 timeout、connection、socket 视为可重试。

取消入口 cancel_tts()(extension.py)先置位 _flush_requested,再调用 client.cancel(),最后以 TTSAudioEndReason.INTERRUPTED 结束当前请求;生成器内会检测取消标志并提前跳出音频分块循环。对应测试见 tests/test_tts_client.py 的 test_cancel_sets_flag、test_get_cancel_stops_iteration(验证取消后返回的音频块数少于完整分块数)。

测试与验证:如何确认扩展可用

仓库为该扩展提供了完整的测试套件(tests):

测试配置样例分布在 tests/configs 目录:property_basic_audio_setting1.json / property_basic_audio_setting2.json 为正常配置(含 dump 开启的变体),property_invalid.json 为字段值非法(如 region: us-phoenix-1、model_name: TTS_2_NATURAL 但凭据为 invalid)的失败用例,property_miss_required.json 则把所有必填项置空以触发校验报错。安装依赖后,可在扩展目录下运行测试(测试通过 mock 与隔离配置完成,不要求真实 OCI 账号)。

常见问题与排查思路

  1. 初始化报 Missing required OCI parameters: ...:说明 property 未注入或环境变量未设置。检查 OCI_TENANCY、OCI_USER、OCI_FINGERPRINT、OCI_KEY_FILE_BASE64、OCI_COMPARTMENT_ID 是否都已正确导出,且 property 中使用了 ${env:...} 模板语法。
  2. Invalid key / 401 / 403 错误:扩展会以 EVENT_TTS_INVALID_KEY_ERROR 上报并终止。请核对 user/tenancy OCID、API key 指纹,以及 OCI_KEY_FILE_BASE64 是否为 PEM 私钥原文的 base64 编码(而非文件路径)。
  3. 音频有爆音或首尾异常:打开 dump: true 并设置 dump_path,用工具查看落盘的 oracle_tts_dump_<request_id>.pcm 是否为干净的 16-bit 单声道 PCM;该扩展的 WAV 剥离逻辑已针对流式场景做了专门处理(见上文"WAV 头剥离")。
  4. Unknown TTS model:model_name 仅支持 TTS_1_STANDARD 与 TTS_2_NATURAL 两个取值,请勿传入其他字符串。
  5. 采样率不匹配:sample_rate 需与下游播放器/上行通道一致,默认 16000 Hz;扩展的音频时长换算(_calculate_audio_duration_ms)也以此值为基准。

小结

oracle_tts_python 以约 200 行核心代码完成了 OCI Speech TTS 与 TEN Framework 标准 TTS2 接口的对接:base64 密钥的临时落盘与生命周期管理、pydantic 配置校验与敏感脱敏、双模型/双格式的参数构建、流式 WAV 头剥离、三级重试、可取消的异步产流以及完整的音频指标上报。对开发者而言,只需准备好 OCI 凭据环境变量,在 Agent 的扩展配置中填入 params,即可把 Oracle 的神经网络语音(TTS_2_NATURAL)接入自己的会话式语音 Agent。若需进一步验证或二次开发,可重点研读 extension.py、oracle_tts.py 与 tests 下的测试用例,它们完整呈现了该扩展的契约与行为边界。

登录后查看全文
ten-framework