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低延迟、轻量、高性能的流式语音活动检测器VADTEN Turn Detection实现全双工对话的端点检测能力TEN Agent Examples基于 TEN 构建的各类真实用例TEN PortalTEN 官方站点含文档与博客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 CertificateOpenAI API keyDeepgram ASRElevenLabs TTS安装Docker / Docker ComposeNode.jsLTSv18最低系统要求CPU ≥ 2 核内存 ≥ 4 GB需要说明的是README 标注 Node.js LTS v18而仓库内实际运行依赖更多样——voice-assistant/Taskfile.yml 中前端使用bun install与bun run devBun 运行时playground/package.json 声明node: 20并基于 Next.js 16、React 19voice-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_STDOUTtrue、GRAPH_DESIGNER_SERVER_PORT49483TMAN Designer 端口、SERVER_PORT8080API Server 端口、WORKERS_MAX100、WORKER_QUIT_TIMEOUT_SECONDS60。前端AGENT_SERVER_URLhttp://localhost:8080、TEN_DEV_SERVER_URLhttp://localhost:49483、NEXT_PUBLIC_EDIT_GRAPH_MODEtrue。LLM 供应商OpenAIOPENAI_API_BASE、OPENAI_API_KEY、OPENAI_MODELgpt-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 bash5. 构建默认 agent 示例约 58 分钟# 使用链式pipeline语音助手 cd agents/examples/voice-assistant # 或使用实时端到端的 speech-to-speech 语音助手 cd agents/examples/voice-assistant-realtimeagents/examples下还提供大量其他示例构建前可先浏览目录选择目标。6. 启动 Web 服务task install task run这里需要区分两个命令的职责见 voice-assistant/Taskfile.ymltask install仅在首次启动、或修改了依赖与 Go 源码后需要执行。它内部依次执行install-tenapptman 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-servertman designerTMAN Designer 服务端口 49483、run-frontendbun run devNext.js 前端端口 3000、run-api-server./bin/api -tenapp_dir...Go API Server端口 8080。7. 访问 Agent服务启动后可通过两个入口访问localhost:49483localhost:3000TMAN Designer可视化图编辑器Agent Examples UI示例交互界面即 README 给出的两个访问地址TMAN Designer localhost:49483 与 Agent Examples UI localhost:3000。Step ⓷ 自定义你的 agent 示例打开 localhost:49483TMAN Designer右键点击 STT、LLM、TTS 等扩展节点打开它们的属性面板填入对应的 API Key提交修改随后刷新 localhost:3000 即可看到更新后的 Agent 表现。这个可视化编辑的底层其实对应每个示例应用的 property.json。以默认的 voice-assistant 为例其predefined_graphs定义了一个名为voice_assistant的图auto_start: true图中编排了五个扩展节点且各节点属性直接通过${env:XXX}语法引用.env中的变量agora_rtcRTC 入口使用AGORA_APP_ID、AGORA_APP_CERTIFICATE信道名ten_agent_test订阅/发布音频并发布数据sttdeepgram_asr_python扩展模型nova-3、语言en-US密钥来自DEEPGRAM_API_KEYllmopenai_llm2_python扩展base_url指向 OpenAI模型来自OPENAI_MODEL还配置了frequency_penalty、max_tokens、max_memory_length与问候语greetingttselevenlabs_tts2_python扩展输出 PCM 16k 音频流密钥来自ELEVENLABS_TTS_KEYmain_controlmain_python主控扩展负责对话流程编排。在 Designer 中右键修改扩展属性本质上就是在改这份图的节点配置——修改会落到扩展属性上并被图执行引擎读取。不借助 Docker 运行 transcriber 应用BetaTEN 还提供了一款 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_AGENTagents/examples/voice-assistant指定示例显式拷贝该示例的tenappgo.mod、main.go、manifest、property.json 等与main_python扩展随后执行task install task release完成依赖安装与产物打包并在 playground 中执行NEXT_PUBLIC_EDIT_GRAPH_MODEfalse 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_MAX100、WORKER_QUIT_TIMEOUT_SECONDS60均可在 .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/DockerfileGo API Serverai_agents/server前端 Playgroundai_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），仅供参考