用 TEN Framework 搭实时语音智能体：扩展图、TMAN Designer 可视化调参与打断实操

# Agora 控制台创建项目，拿 App ID 与 App Certificate
#   —— 负责实时音频传输（RTC 通道）
# OpenAI API Key      —— LLM 推理
# Deepgram API Key    —— 语音转写（STT，官方要求必配）
# ElevenLabs API Key  —— 语音合成（TTS）

这四家是官方默认示例的组合：Agora 承担浏览器与服务端之间的实时音频流，Deepgram 做转写，OpenAI 做推理，ElevenLabs 做合成。注册流程各家都是控制台自助，新账号普遍有免费额度——跑通演示够用，压测前先把各家的计费规则看清楚。

git clone https://github.com/TEN-framework/ten-framework.git
cd ten-framework/ai_agents
cp ./.env.example ./.env

# 编辑 .env，填入五项：
#   AGORA_APP_ID=...
#   AGORA_APP_CERTIFICATE=...
#   DEEPGRAM_API_KEY=...
#   OPENAI_API_KEY=...
#   ELEVENLABS_TTS_KEY=...

docker compose up -d
docker exec -it ten_agent_dev bash

# 容器内继续：
cd agents/examples/voice-assistant        # 链式语音助手
# 或 cd agents/examples/voice-assistant-realtime  # 语音到语音
task install    # 装 TEN、Python、前端依赖并构建 Go API 服务，约 5-8 分钟
task run
# 浏览器打开 http://localhost:3000 即语音助手界面

task install 只在初回启动、改依赖或改 Go 源码后需要重跑；纯 Python 层的改动不用重新安装。起来之后在 localhost:3000 授权麦克风，说一句话——听到回应就说明 RTC 通道、转写、推理、合成整条链路都通了。出问题时先看四把密钥是否都填了：官方示例对 Deepgram 与 OpenAI 是硬依赖，缺一个起不来。

# 浏览器打开 http://localhost:49483（TMAN Designer）
# 1) 找到 STT 扩展，右键 properties，
#    确认 Deepgram Key 已注入
# 2) LLM 扩展的 properties 里确认 OpenAI Key
#    与所用模型
# 3) TTS 扩展的 properties 里确认 ElevenLabs Key
#    与音色
# 4) 保存后回到 localhost:3000 验证效果

属性面板改的就是每个扩展的运行参数，保存即生效，不用重启容器。这是 TEN 与「一行 SDK 调用」框架的本质差异：你可以看着图调它。建议初回就把三个扩展的属性各打开看一遍——字段名、默认值、可选供应商一目了然，后面换东西心里有底。

# LLM 扩展属性面板：
#   model        —— 换推理模型（小模型延迟低，
#                   强模型回答好，按场景选）
#   prompt       —— 系统提示词，决定人设与语气
#
# 提示词示例（客服人设）：
# 「你是售后客服，回答保持三句以内，
#  涉及退款政策时引用知识库结论，
#  不确定就引导用户转人工。」

语音场景的提示词与文本场景不同：回复会被念出来，长句、列表、代码块都是灾难。写人设时明确「控制在几句以内、口语化、可以打断」，再按业务补充边界。扩展图的持久化在 property.json 里，动手改图前先 git 提交一版——画布上的误操作能随时回退。

# 在 TMAN Designer 的扩展市场按需挂载：
#   VAD            —— 静音检测，用户没说话
#                     就不调 STT，省成本
#   Turn Detection —— 判断用户是否说完，
#                     支持打断（barge-in）
#   Memory         —— 多轮对话记忆
# 挂上扩展、连线、保存，回 UI 逐个验证

没有打断检测的语音助手是灾难现场：用户插话它照播不误，体验直接崩掉。VAD 加 Turn Detection 是官方示例的标准组合——前者在本地判断有没有人说话，后者判断这句话说完了没有。多轮记忆扩展挂上后，助手才能记住前文，否则每轮都是失忆重启。

# 官方 Self-Hosting 文档：
#   Docker 部署 / 其他云服务部署两条路线
# 进阶示例（都在 agents/examples/ 下）：
#   speaker-diarization   说话人分离
#   唇形同步数字人          对接 Trulience、HeyGen、
#                          Tavus 等厂商
#   SIP call              接真实电话线路
#   ESP32-S3 Korvo V3     跑到硬件开发板上

对外的部署要点不在框架而在链路：扩展图跑通只是开始，真实延迟取决于你的服务器区域、供应商区域与用户网络三者的组合，上线前按目标用户分布实测。官方 Self-Hosting 文档覆盖 Docker 与主流云的部署路径，生产环境建议把 .env 换成密钥管理服务注入。延迟预算可以按段拆：RTC 传输几十毫秒、转写几百毫秒、推理几百到上千毫秒、合成几百毫秒——哪段超标就治哪段，逐段测量比笼统「感觉慢」有效得多。

进阶示例的选择也有讲究：说话人分离适合会议纪要场景；唇形同步数字人适合虚拟主播与展厅；SIP 电话把助手接进呼叫中心；ESP32 硬件端则是离线硬件原型的入口。这些示例与 voice-assistant 共享同一套扩展机制，先在主示例上把调参手感练出来，再迁移过去会顺很多。