目录

• [欢迎来到 TEN][welcome-to-ten]
• [代理示例][agent-examples-section]
• [通过代理示例快速入门][quick-start]
  • [本地主机][localhost-section]
  • [Codespaces][codespaces-section]
• [代理示例自托管][agent-examples-self-hosting]
  • [使用 Docker 部署][deploying-with-docker]
  • [使用其他云服务部署][deploying-with-other-cloud-services]
• [敬请期待][stay-tuned]
• [TEN 生态系统][ten-ecosystem-anchor]
• [问题][questions]
• [贡献][contributing]
  • [代码贡献者][code-contributors]
  • [贡献指南][contribution-guidelines]
  • [许可证][license-section]

欢迎来到 TEN

TEN 是一个用于实时多模态对话式 AI 的开源框架。

[TEN 生态系统][ten-ecosystem-anchor] 包括 [TEN 框架][ten-framework], [代理示例][agent-examples-repo], [VAD][ten-vad], [轮次检测][ten-turn-detection] 和 [Portal][ten-portal]。

社区频道	目的
[![在 X 上关注][follow-on-x-badge]][follow-on-x]	在 X 上关注 TEN 框架，获取最新动态和公告
[![Discord TEN 社区][discord-badge]][discord-invite]	加入我们的 Discord 社区，与开发者交流
![在 LinkedIn 上关注][linkedin-badge]	在 LinkedIn 上关注 TEN 框架，获取最新动态和公告
[![Hugging Face Space][hugging-face-badge]][hugging-face]	加入我们的 Hugging Face 社区，探索我们的空间和模型
[![微信][wechat-badge]][wechat-discussion]	加入我们的微信群，参与中文社区讨论

代理示例

![图片][voice-assistant-image]

多功能语音助手 — 这款低延迟、高质量的实时助手支持 RTC 和 [WebSocket][websocket-example] 连接，您还可以通过 [Memory][memory-example], [VAD][voice-assistant-vad-example], [Turn Detection][voice-assistant-turn-detection-example] 等扩展功能对其进行扩展。

更多详情请参阅 [示例代码][voice-assistant-example]。

![分隔线][divider-light] ![分隔线][divider-dark]

![图片][doodler-image]

涂鸦板 — 一款能够将口头或键入的提示转化为简单手绘草图的涂鸦板，配有蜡笔调色板和实时绘图功能。

[示例代码][doodler-example]

![分隔线][divider-light] ![分隔线][divider-dark]

![图片][speaker-diarization-image]

说话人辨识 — 实时说话人辨识功能可以检测并标记不同的说话人；“谁喜欢什么”游戏展示了其交互式应用场景。

[示例代码][speechmatics-diarization-example]

![分隔线][divider-light] ![分隔线][divider-dark]

![图片][lip-sync-image]

唇同步虚拟形象 — 支持多家虚拟形象供应商，主角是 Kei，一个由 MotionSync 提供唇同步技术的动漫角色；同时也支持来自 Trulience、HeyGen 和 Tavus 的逼真虚拟形象。

有关不同 Live2D 角色的 [示例代码][voice-assistant-live2d-example] 请参阅。

![分隔线][divider-light] ![分隔线][divider-dark]

![图片][sip-call-image]

SIP 通话 — 一个基于 TEN 的 SIP 扩展模块，可用于实现电话通话功能。

[示例代码][voice-assistant-sip-example]

![分隔线][divider-light] ![分隔线][divider-dark]

![图片][transcription-image]

转录 — 一款将音频转录为文本的工具。

[示例代码][transcription-example]

![分隔线][divider-light] ![分隔线][divider-dark]

![图片][esp32-image]

ESP32-S3 Korvo V3 — 在 Espressif ESP32-S3 Korvo V3 开发板上运行 TEN 代理示例，以实现 LLM 驱动的通信与硬件的集成。

更多详情请参阅 [集成指南][esp32-guide]。

通过代理示例快速入门

本地主机

步骤 ⓵ - 先决条件

类别	要求
密钥	• Agora App ID 和 App Certificate • OpenAI API 密钥 • Deepgram ASR • ElevenLabs TTS
安装	• Docker / Docker Compose • Node.js (LTS) v18
最低系统要求	• CPU >= 2 核 • 内存 >= 4 GB

![分隔线][divider-light] ![分隔线][divider-dark]

步骤 ⓶ - 在虚拟机中构建代理示例

1. 克隆仓库，进入 ai_agents 目录，并从 .env.example 文件创建 .env 文件

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

2. 在 .env 文件中设置 Agora App ID 和 App Certificate

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# Deepgram（用于语音转文字）
DEEPGRAM_API_KEY=

# OpenAI（用于语言模型）
OPENAI_API_KEY=

# ElevenLabs（用于文本到语音）
ELEVENLABS_TTS_KEY=

3. 启动代理开发容器

docker compose up -d

4. 进入容器

docker exec -it ten_agent_dev bash

5. 使用默认示例构建代理（约 5–8 分钟）

请查看 agents/examples 文件夹以获取更多示例。可以从以下默认示例开始：

# 使用串联的语音助手
cd agents/examples/voice-assistant

# 或者使用实时语音到语音的语音助手
cd agents/examples/voice-assistant-realtime

6. 启动 Web 服务器

如果你修改了任何本地源代码，请运行 task build。这一步对于编译型语言（例如 TypeScript 或 Go）是必需的，而对于 Python 则不需要。

task install
task run

7. 访问代理

一旦代理示例运行起来，你就可以访问以下界面：

localhost:49483	localhost:3000

• TMAN 设计器：localhost:49483
• 代理示例 UI：localhost:3000

![分隔线][divider-light] ![分隔线][divider-dark]

步骤 ③ - 自定义你的代理示例

1. 打开 localhost:49483。
2. 右键点击 STT、LLM 和 TTS 扩展。
3. 打开它们的属性并输入相应的 API 密钥。
4. 提交更改后，你现在可以在 localhost:3000 看到更新后的代理示例。

![分隔线][divider-light] ![分隔线][divider-dark]

在不使用 Docker 的情况下从 TEN 管理器运行转录应用（测试版）

TEN 还提供了一个转录应用，你可以直接从 TEN 管理器运行，无需使用 Docker。

更多详情请参阅 快速入门指南。

![分隔线][divider-light] ![分隔线][divider-dark]

Codespaces

GitHub 为每个仓库提供免费的 Codespaces。你可以在 Codespaces 中运行代理示例，而无需使用 Docker。Codespaces 的启动速度通常比本地 Docker 环境更快。

更多详情请参阅 此指南。

代理示例的自托管

使用 Docker 部署

一旦你自定义好你的代理（无论是通过 TMAN 设计器还是直接编辑 property.json），你就可以为你的服务创建一个发布版的 Docker 镜像来部署它。

以 Docker 镜像形式发布

注意：以下命令需要在任何 Docker 容器之外执行。

构建镜像

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

运行

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

![分隔线][divider-light] ![分隔线][divider-dark]

使用其他云服务部署

如果你想将 TEN 托管在诸如 Vercel 或 Netlify 等平台上，可以将部署分为两部分。

1. 将 TEN 后端运行在任何支持容器的平台上（如带有 Docker 的虚拟机、Fly.io、Render、ECS、Cloud Run 等）。使用示例 Docker 镜像而不做任何修改，并暴露该服务的 8080 端口。

2. 只将前端部署到 Vercel 或 Netlify。将项目根目录指向 ai_agents/agents/examples/<example>/frontend，运行 pnpm install（或 bun install），然后运行 pnpm build（或 bun run build），并保持默认的 .next 输出目录。

3. 在你的托管仪表板中配置环境变量，使 AGENT_SERVER_URL 指向后端 URL，并添加 UI 所需的任何 NEXT_PUBLIC_* 键（例如，你需要暴露给浏览器的 Agora 凭证）。

4. 确保你的后端能够接受来自前端来源的请求——可以通过开放 CORS 或使用内置的代理中间件来实现。

通过这种设置，后端负责处理长时间运行的工作进程，而托管的前端则简单地将 API 流量转发到后端。

敬请关注

获取新版本和更新的即时通知。你的支持将帮助我们不断成长并改进 TEN！

TEN 生态系统

项目	预览
️TEN 框架 用于对话式 AI 代理的开源框架。
TEN VAD 低延迟、轻量级且高性能的流式语音活动检测器 (VAD)。
️ TEN 轮次检测 TEN 轮次检测实现了全双工对话通信。
TEN 代理示例 TEN 驱动的应用场景。
TEN 门户 TEN 框架的官方网站，包含文档和博客。

问答

TEN 框架可在这些由 AI 驱动的问答平台上使用。它们可以帮助你快速准确地找到答案，支持多种语言，涵盖从基础设置到高级实现细节的各个方面。

服务	链接
DeepWiki	![Ask DeepWiki][deepwiki-badge]
ReadmeX	![ReadmeX][readmex-badge]

贡献

我们欢迎任何形式的开源协作！无论你是修复 bug、添加功能、改进文档，还是分享想法，你的贡献都有助于推动个性化 AI 工具的发展。请查看我们的 GitHub Issues 和 Projects，寻找参与贡献的方式，展示你的技能。让我们一起打造令人惊叹的成果！

[!提示]

欢迎各种形式的贡献 🙏

加入我们，共同让 TEN 更加完善！每一次贡献都至关重要，无论是代码还是文档。请在社交媒体上分享你的 TEN 代理项目，激励他人！

与 TEN 的维护者之一 @elliotchen200 在 𝕏 上，或 @cyfyifanchen 在 GitHub 上联系，以获取项目更新、讨论及合作机会。

![分隔线][divider-light] ![分隔线][divider-dark]

代码贡献者

[][contributors]

贡献指南

欢迎贡献！请先阅读 贡献指南。

![分隔线][divider-light] ![分隔线][divider-dark]

许可证

1. 整个 TEN 框架（除下面明确列出的文件夹外）根据 Apache 许可证 2.0 版本发布，并附加了一些限制。详细信息请参阅位于 TEN 框架根目录下的 LICENSE 文件。

2. packages 目录中的组件根据 Apache 许可证 2.0 版本发布。详细信息请参阅每个包根目录下的 LICENSE 文件。

3. TEN 框架所使用的第三方库已在列表中详细列出并说明。更多信息请参阅 third_party 文件夹。

TEN Framework 快速上手指南

TEN 是一个用于实时多模态对话式 AI 的开源框架。本指南将帮助你快速在本地运行官方的 Agent 示例（如语音助手）。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

系统要求

• CPU: >= 2 核
• 内存: >= 4 GB
• 操作系统: Linux, macOS, 或 Windows (需安装 Docker Desktop)

前置依赖

1. 容器工具: Docker 和 Docker Compose
   • 国内用户建议: 配置 Docker 镜像加速器（如阿里云、腾讯云或 DaoCloud 加速器）以加快拉取速度。
2. 运行时环境: Node.js (LTS v18 版本)
3. API 密钥: 你需要准备以下服务的密钥：
   • Agora (声网): App ID 和 App Certificate (获取链接)
   • OpenAI: API Key (获取链接)
   • Deepgram: API Key (用于语音转文字) (获取链接)
   • ElevenLabs: API Key (用于文字转语音) (获取链接)

安装步骤

1. 克隆项目并配置环境变量

首先克隆仓库，进入 ai_agents 目录，并基于模板创建 .env 文件。

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

2. 填写 API 密钥

使用文本编辑器打开 .env 文件，填入你在“环境准备”阶段获取的密钥：

AGORA_APP_ID=你的_Agora_App_ID
AGORA_APP_CERTIFICATE=你的_Agora_App_Certificate

# Deepgram (语音转文字必填)
DEEPGRAM_API_KEY=你的_Deepgram_Key

# OpenAI (大语言模型必填)
OPENAI_API_KEY=你的_OpenAI_Key

# ElevenLabs (文字转语音必填)
ELEVENLABS_TTS_KEY=你的_ElevenLabs_Key

3. 启动开发容器

使用 Docker Compose 启动后端服务容器：

docker compose up -d

4. 进入容器并构建示例

进入名为 ten_agent_dev 的容器内部：

docker exec -it ten_agent_dev bash

在容器内，选择一个示例项目进行构建。这里以“链式语音助手”为例：

# 进入示例目录
cd agents/examples/voice-assistant

# 安装依赖并运行 (如果是首次运行或修改了代码)
task install
task run

注：构建过程可能需要 5-8 分钟，具体取决于网络状况。

基本使用

当终端显示服务启动成功后，你可以通过浏览器访问以下界面：

1. TEN Manager (配置中心)

   • 地址：http://localhost:49483
   • 操作: 在此页面右键点击 STT (语音识别)、LLM (大模型) 和 TTS (语音合成) 组件，打开属性面板确认 API Key 已正确加载。如有变动可在此提交更新。

2. Agent Examples UI (交互界面)

   • 地址：http://localhost:3000
   • 操作: 点击页面上的麦克风图标或输入框，即可开始与 AI 进行实时语音或文字对话。

替代方案：无 Docker 运行 (Beta)

如果你不想使用 Docker，TEN 也支持通过 TEN Manager 直接运行转录应用，具体可参考官方提供的 TEN Manager 快速指南。

替代方案：GitHub Codespaces

如果本地环境配置困难，你可以直接使用 GitHub Codespaces 在线运行，无需本地安装 Docker：