TEN Framework 实战指南：从 Agent Examples 快速启动到 Docker 自托管部署实时多模态语音助手-港品优选

TEN Framework 实战指南：从 Agent Examples 快速启动到 Docker 自托管部署实时多模态语音助手

【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework

导读

TEN 是一个开源的实时多模态对话 AI 框架，本文以仓库根目录 README.md 为骨架，围绕其官方提供的 Agent Examples（语音助手、Doodler、说话人分离、SIP 通话等）展开。你将掌握三条主线：一是在本地通过 Docker 一键拉起开发环境并运行语音助手示例；二是用 TMAN Designer 可视化替换 STT/LLM/TTS 扩展完成自定义；三是将定制好的 Agent 打成 Docker 镜像自托管，或拆分为后端 + 前端部署到 Vercel/Netlify 等云平台。全文结合仓库内 docker-compose.yml、.env.example、property.json 等源码级证据，让每一步都有实可查。

TEN Framework 是什么

TEN 是一个面向实时多模态对话 AI 的开源框架（open-source framework for real-time multimodal conversational AI），其核心能力是把实时语音链路中的 ASR（语音识别）、LLM（大语言模型）、TTS（语音合成）、RTC（实时音视频）等组件以可编排的图（graph）形式组织起来，并在此基础上提供可视化设计器与完整的示例生态。

围绕 TEN 形成了一个生态（TEN Ecosystem），在仓库 README 中明确了以下组成：

项目	定位
TEN Framework	对话式 AI Agent 的开源框架（即本仓库）
TEN VAD	低延迟、轻量、高性能的流式语音活动检测器（VAD）
TEN Turn Detection	实现全双工对话的端点检测能力
TEN Agent Examples	基于 TEN 构建的各类真实用例
TEN Portal	TEN 官方站点，含文档与博客

Agent Examples：仓库内置的真实用例

README 的 Agent Examples 一节列举了仓库 ai_agents/agents/examples 目录下的代表性示例，它们既是学习 TEN 的最佳入口，也是快速开始的默认模板：

Multi-Purpose Voice Assistant（多用途语音助手）：低延迟、高质量的实时助手，同时支持 RTC 与 WebSocket 连接，可扩展 Memory、VAD、Turn Detection 等能力，示例代码见 voice-assistant。
Doodler：将语音或文字提示词转化为手绘简笔画的白板应用，带蜡笔调色板与实时绘制能力，代码见 doodler。
Speaker Diarization：实时说话人分离，自动检测并标记不同说话人，代码见 speaker-diarization。
Lip Sync Avatars：支持多家数字人供应商的唇形同步 Avatar，主角色是带 MotionSync 唇形同步的动漫角色 Kei，同时支持 Trulience、HeyGen、Tavus 的写实 Avatar，代码见 voice-assistant-live2d。
SIP Call：通过 SIP 扩展让 TEN 驱动的 Agent 支持电话呼叫，代码见 voice-assistant-sip-twilio。
Transcription：将音频转写为文字的转录工具，代码见 transcription。
ESP32-S3 Korvo V3：在乐鑫 ESP32-S3 Korvo V3 开发板上运行 TEN Agent 示例，把 LLM 对话能力与硬件结合，集成指南见 esp32-client。

本地快速开始：用 Docker 一键拉起开发环境

README 的 Localhost 快速开始共分三步（⓵ 前置条件 → ⓶ 在 VM 中构建 → ⓷ 自定义），下面逐条展开并补充仓库源码细节。

Step ⓵ 前置条件

类别	要求
密钥	Agora App ID 与 App Certificate；OpenAI API key；Deepgram ASR；ElevenLabs TTS
安装	Docker / Docker Compose；Node.js（LTS）v18
最低系统要求	CPU ≥ 2 核；内存 ≥ 4 GB

需要说明的是：README 标注 Node.js LTS v18，而仓库内实际运行依赖更多样——voice-assistant/Taskfile.yml 中前端使用bun install与bun run dev（Bun 运行时），playground/package.json 声明"node": ">=20"并基于 Next.js 16、React 19；voice-assistant/Dockerfile 在最终镜像中安装的是 Node.js 20 与 Bun。因此建议以仓库实际要求为准：Node.js 20+ 配合 Bun。

Step ⓶ 在 VM 中构建 agent 开发容器

1. 克隆仓库并准备环境变量文件

cd ai_agents cp ./.env.example ./.env

仓库中的 .env.example 是完整的配置模板，涵盖日志、服务端口、前端、RTC、LLM、STT、TTS、工具与数据库等全部可配置项。

2. 在`.env`中填入 Agora 与各模型服务密钥

AGORA_APP_ID= AGORA_APP_CERTIFICATE= # Deepgram（语音转文字，STT） DEEPGRAM_API_KEY= # OpenAI（大语言模型，LLM） OPENAI_API_KEY= # ElevenLabs（文字转语音，TTS） ELEVENLABS_TTS_KEY=

这只是最精简的一组。结合 .env.example 可以看到，.env实际承载了完整的多供应商配置矩阵：

服务与端口：LOG_PATH=/tmp/ten_agent、LOG_STDOUT=true、GRAPH_DESIGNER_SERVER_PORT=49483（TMAN Designer 端口）、SERVER_PORT=8080（API Server 端口）、WORKERS_MAX=100、WORKER_QUIT_TIMEOUT_SECONDS=60。
前端：AGENT_SERVER_URL=http://localhost:8080、TEN_DEV_SERVER_URL=http://localhost:49483、NEXT_PUBLIC_EDIT_GRAPH_MODE=true。
LLM 供应商：OpenAI（OPENAI_API_BASE、OPENAI_API_KEY、OPENAI_MODEL=gpt-4o、OPENAI_PROXY_URL）、Grok、Gemini、Anthropic、Azure OpenAI、Qwen、DeepSeek、Stepfun、AWS Bedrock、LiteLLM 等。
STT 供应商：Deepgram、xAI、Azure ASR、Oracle OCI 等。
TTS 供应商：Azure TTS、Cartesia、Cosy、Speechmatics、ElevenLabs、Mistral、Qwen3、Fish.audio、MiniMax、字节跳动、Dubverse、Gradium、Inworld 等。
工具与数据库：WeatherAPI、Querit、Bing 搜索、Firestore、阿里云 AnalyticDB 向量库等。

3. 启动 agent 开发容器

docker compose up -d

对应的 docker-compose.yml 定义了名为ten_agent_dev的服务，其关键配置为：

镜像：ghcr.io/ten-framework/ten_agent_build:0.7.14，平台固定为linux/amd64；
端口映射：${GRAPH_DESIGNER_SERVER_PORT}:${GRAPH_DESIGNER_SERVER_PORT}（默认 49483）、3000:3000（前端 UI）以及8000-9001:8000-9001（扩展调试端口段）；
卷挂载：将./（整个 ai_agents 目录）挂载到容器/app，另有.vscode、pylint 配置与升级工具目录；
环境变量：通过env_file: .env注入，即上一步配置的密钥全部生效；
网络：ten_agent_network桥接网络。

4. 进入容器

docker exec -it ten_agent_dev bash

5. 构建默认 agent 示例（约 5～8 分钟）

# 使用链式（pipeline）语音助手 cd agents/examples/voice-assistant # 或使用实时端到端的 speech-to-speech 语音助手 cd agents/examples/voice-assistant-realtime

agents/examples下还提供大量其他示例，构建前可先浏览目录选择目标。

6. 启动 Web 服务

task install task run

这里需要区分两个命令的职责（见 voice-assistant/Taskfile.yml）：

task install：仅在首次启动、或修改了依赖与 Go 源码后需要执行。它内部依次执行：install-tenapp（tman install安装 TEN 应用依赖）、install-tenapp-python-deps（安装 Python 依赖）、install-frontend（在 playground 下执行bun install）、build-api-server（在 server 下执行go mod tidy && go mod download && go build -o bin/api main.go编译 Go API Server）。纯 Python 源码改动无需重新 install。
task run：并行拉起三个进程——run-gd-server（tman designer，TMAN Designer 服务，端口 49483）、run-frontend（bun run dev，Next.js 前端，端口 3000）、run-api-server（./bin/api -tenapp_dir=...，Go API Server，端口 8080）。

7. 访问 Agent

服务启动后可通过两个入口访问：

localhost:49483	localhost:3000
TMAN Designer（可视化图编辑器）	Agent Examples UI（示例交互界面）

即 README 给出的两个访问地址：TMAN Designer localhost:49483 与 Agent Examples UI localhost:3000。

Step ⓷ 自定义你的 agent 示例

打开 localhost:49483（TMAN Designer）；
右键点击 STT、LLM、TTS 等扩展节点；
打开它们的属性面板，填入对应的 API Key；
提交修改，随后刷新 localhost:3000 即可看到更新后的 Agent 表现。

这个可视化编辑的底层其实对应每个示例应用的 property.json。以默认的 voice-assistant 为例，其predefined_graphs定义了一个名为voice_assistant的图（auto_start: true），图中编排了五个扩展节点，且各节点属性直接通过${env:XXX}语法引用.env中的变量：

agora_rtc：RTC 入口，使用AGORA_APP_ID、AGORA_APP_CERTIFICATE，信道名ten_agent_test，订阅/发布音频并发布数据；
stt：deepgram_asr_python扩展，模型nova-3、语言en-US，密钥来自DEEPGRAM_API_KEY；
llm：openai_llm2_python扩展，base_url指向 OpenAI，模型来自OPENAI_MODEL，还配置了frequency_penalty、max_tokens、max_memory_length与问候语greeting；
tts：elevenlabs_tts2_python扩展，输出 PCM 16k 音频流，密钥来自ELEVENLABS_TTS_KEY；
main_control：main_python主控扩展，负责对话流程编排。

在 Designer 中右键修改扩展属性，本质上就是在改这份图的节点配置——修改会落到扩展属性上并被图执行引擎读取。

不借助 Docker 运行 transcriber 应用（Beta）

TEN 还提供了一款 transcriber（转写器）应用，可以不使用 Docker、直接通过 TEN Manager 运行。这是官方文档中标注为 Beta 的实验性路径，适合希望绕开容器环境的开发者。

Codespaces：免 Docker 的云端开发

GitHub 为每个仓库提供免费的 Codespaces。你可以在 Codespaces 中直接运行 Agent Examples，无需本地 Docker，且启动速度通常比本地 Docker 环境更快。点击仓库页面的 Codespaces 按钮即可创建云端开发环境，具体步骤参考官方开发环境搭建指南。

Agent Examples 自托管部署

完成自定义（通过 TMAN Designer 修改，或直接编辑property.json）之后，就可以把 Agent 发布为服务镜像进行部署。

方式一：Docker 镜像部署

注意：以下命令需要在任何 Docker 容器之外执行（即宿主机上）。

构建镜像

cd ai_agents docker build -f agents/examples/<example-name>/Dockerfile -t example-app .

其中<example-name>替换为具体示例目录名（如voice-assistant）。以 voice-assistant/Dockerfile 为例，它采用两阶段构建：

builder 阶段：基于ghcr.io/ten-framework/ten_agent_build:0.7.14，通过ARG USE_AGENT=agents/examples/voice-assistant指定示例，显式拷贝该示例的tenapp（go.mod、main.go、manifest、property.json 等）与main_python扩展，随后执行task install && task release完成依赖安装与产物打包，并在 playground 中执行NEXT_PUBLIC_EDIT_GRAPH_MODE=false bun run build构建前端；
运行阶段：基于ubuntu:22.04，安装音频/构建运行库（libasound2、gstreamer、Python3、Node.js 20、Bun、Task 等），把.release/产物、server/bin/api、Python 库与构建好的前端拷贝进最终镜像，EXPOSE 8080 3000，入口为task run-prod（对应 Taskfile.docker.yml）。

运行

docker run --rm -it --env-file .env -p 3000:3000 example-app

--env-file .env会把先前配置的全部密钥注入容器；-p 3000:3000暴露前端端口。由于 Dockerfile 同时EXPOSE 8080，后端 API 服务（端口 8080）也在容器内一并运行。

方式二：拆分前后端部署到云平台

当希望把 TEN 托管到 Vercel、Netlify 等平台时，可以按 README 的做法把部署拆成两半：

后端：运行在任何支持容器的平台（带 Docker 的 VM、Fly.io、Render、ECS、Cloud Run 等）。直接使用上述示例 Docker 镜像，无需修改，只需把该服务的8080 端口暴露出去。
前端：仅将前端部署到 Vercel 或 Netlify。项目根目录指向ai_agents/agents/examples/<example>/frontend，执行pnpm install（或bun install）后执行pnpm build（或bun run build），保留默认的.next输出目录。
环境变量：在托管平台控制台配置环境变量，令AGENT_SERVER_URL指向后端地址，并补充 UI 所需的NEXT_PUBLIC_*键（例如暴露给浏览器侧的 Agora 凭据）。
跨域：确保后端接受来自前端 origin 的请求——要么开放 CORS，要么使用内置的代理中间件。

这套架构下，后端承载长驻的 worker 进程，托管的静态前端只负责把 API 流量转发到后端。关于后端 worker 的参数（如WORKERS_MAX=100、WORKER_QUIT_TIMEOUT_SECONDS=60）均可在 .env.example 中调整。

仓库源码路径速查

以下是本文涉及的关键文件，便于继续深入阅读：

编排入口与图定义：ai_agents/agents/examples/voice-assistant/tenapp/property.json
开发容器定义：ai_agents/docker-compose.yml
全量环境变量模板：ai_agents/.env.example
构建/运行/发布任务编排：ai_agents/agents/examples/voice-assistant/Taskfile.yml
生产镜像多阶段构建：ai_agents/agents/examples/voice-assistant/Dockerfile
Go API Server：ai_agents/server
前端 Playground：ai_agents/playground

开源协议说明

整个 TEN 框架（除下文明确列出的目录外）依据 Apache License 2.0 发布，并附带额外限制条款，详见仓库根目录 LICENSE。
packages 目录内的组件均以 Apache License 2.0 发布，各组件根目录下自带LICENSE文件。
框架使用的第三方库清单与详细说明见 third_party 目录。

【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址: https://gitcode.com/TEN-framework/ten-framework

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析