编程 TEN Framework 是什么：用 tman 跑通 transcriber_demo，再挂上 C++ VAD 插件

2026-10-08 00:03:53

TEN Framework 是什么：用 tman 跑通 transcriber_demo，再挂上 C++ VAD 插件

TEN = Transformative Extensions Network，声网（Agora）主导、社区共建的开源框架，面向实时多模态对话式 AI Agent（语音、视频、数据流、图像、文本）。

主仓库：TEN-framework/ten-framework，默认分支 main，License 为 Apache 2.0 with certain conditions，packages 目录内组件为 Apache 2.0。

官网/文档/博客：，中文文档。

生态里的几个独立项目：

TEN Framework：ten-framework
TEN Agent Examples：ai_agents/agents/examples
TEN VAD（低延迟流式语音活动检测）：ten-vad
TEN Turn Detection（全双工回合检测）：ten-turn-detection
TEN Portal：portal

架构概念

以下来自官方 concept_overview：

App（应用）：可作为独立进程运行，也可作为现有进程中的线程运行。
Graph（图）：编排扩展之间的数据流转。一个 App 可执行多个图（静态预定义或动态组装），每个图实例在应用内作为一个独立会话运行。支持四类主要数据流：命令、数据、视频帧、音频帧。
Extension Group（扩展组）：类似线程的机制，同一组内扩展在同一线程执行。开发者只需声明扩展所属组，不用直接管线程。同语言同组在同一线程。
Extension（扩展）：基本构建块，可用不同语言编写并在同一应用/服务里协作。例如 C++ 写 RTC 扩展（音视频性能），Python 写 AI 扩展。每个扩展有唯一 ID，结构为 app-uri/graph-name/group-name/extension-name。
TEN Runtime：为框架设计的运行平台，统一管理扩展生命周期、数据流向与线程，可无缝集成多语言扩展、处理各类数据流。
TEN 云商店：类似应用商店，用于共享/下载扩展。TEN Manager（tman）负责上传、共享、安装扩展并管理依赖。

快速开始：Agent Examples

预备条件：Agora App ID + App Certificate；OpenAI API key；Deepgram ASR；ElevenLabs TTS。需要装好 Docker / Docker Compose、Node.js (LTS) v18。最低 CPU >= 2 核、RAM >= 4 GB。

cd 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   # 或 voice-assistant-realtime，语音到语音
task install
task run

默认示例构建约 5–8 分钟。首次启动前、改依赖或 Go 源码后需要 task install，它会安装 TEN/Python/前端依赖并构建 Go API server；仅改 Python 源码不用重装。

访问 TMAN Designer：，Agent Examples UI：。

自定义：打开 49483，右键 STT/LLM/TTS 扩展，填对应 API key，提交后在 3000 看到更新。

自托管：

docker build -f agents/examples//Dockerfile -t example-app .
docker run --rm -it --env-file .env -p 3000:3000 example-app

拆分为前后端：后端跑在容器平台（VM+Docker、Fly.io、Render、ECS、Cloud Run），暴露 8080；前端部署到 Vercel/Netlify，根目录指向 ai_agents/agents/examples//frontend，执行 pnpm install && pnpm build，保留默认 .next 输出；在托管面板配置 AGENT_SERVER_URL 指向后端 URL，并加 UI 需要的 NEXT_PUBLIC_* 变量；后端需接受前端来源（开 CORS 或用内置代理中间件）。

用 tman 跑 transcriber_demo

系统要求：Linux x64/arm64、macOS Intel/Apple Silicon、Windows x64；需要 Python 3.10（仅支持 3.10）、Go 1.20+、Node.js/npm。

Windows 额外需要 GCC(MinGW)：

winget install BrechtSanders.WinLibs.POSIX.MSVCRT

Go 要显式设置 $env:CGO_ENABLED = "1"。

安装 TEN Manager (tman)：

# Linux
sudo add-apt-repository ppa:ten-framework/ten-framework && sudo apt update && sudo apt install tman
# macOS
brew install TEN-framework/ten-framework/tman
# Windows
winget install TEN-framework.tman
# 或用安装脚本，非交互形式：yes y | bash tools/tman/install_tman.sh
bash tools/tman/install_tman.sh

验证：tman --version。

创建并运行：

tman install app transcriber_demo && cd transcriber_demo
tman install          # 安装 TEN 包依赖
tman run install_deps # 安装 Python 和 npm 依赖，约 1-2 分钟
tman run build        # 约 30 秒
tman run start

配置 .env：示例用 Azure ASR extension，需填 AZURE_STT_KEY、AZURE_STT_REGION 等；也可从云商店换成 OpenAI Whisper、Google Speech 等。

访问，可实时语音转录、上传音频、看字幕。

这个 demo 的架构本身就是多语言扩展协作：Go WebSocket 服务器扩展（web_audio_control_go）、Python ASR 扩展（azure_asr_python）、TypeScript VTT 字幕与音频录制扩展（vtt_nodejs）。

启动输出示例：

[web_audio_control_go] Web server started on port 8001
[audio_file_player_python] AudioFilePlayerExtension on_start

C++ 插件进阶

安装 tgn（基于 Google GN 的 C/C++ 构建系统，仓库在 ten_gn）：

curl -fsSL https://raw.githubusercontent.com/TEN-framework/ten-framework/main/tools/tgn/install_tgn.sh | bash

从云商店装 C++ 扩展：

cd transcriber_demo && tman install extension webrtc_vad_cpp
tman run build           # 首次编译 C++ 约 1-3 分钟
tman run start_with_vad

输出：

[vad] WebRTC VAD initialized with mode 2

silence 状态为 true 表示当前音频无人声。

C++ 环境准备：Linux apt-get install gcc g++ 或 clang；macOS xcode-select --install；Windows 装 VS Build Tools 的「使用 C++ 的桌面开发」工作负载，并勾选 C++ Clang 工具。

常见问题

macOS 找不到 libpython3.10.dylib：

export DYLD_LIBRARY_PATH=/usr/local/opt/python@3.10/Frameworks/Python.framework/Versions/3.10/lib:$DYLD_LIBRARY_PATH

tman 下载慢：从 Releases 页手动下载对应平台二进制。
端口 8001 被占用：lsof -i :8001 或 netstat -ano | findstr :8001，改 property.json 里 web_audio_control_go 的端口号。
Go build 失败：

export GOPROXY=https://goproxy.cn,direct
go clean -modcache

然后重新 tman run build。

Python 依赖失败：

pip3 install --index-url https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

Azure 语音报错：检查 .env 的 AZURE_STT_KEY / AZURE_STT_REGION。
Windows 权限：以管理员身份运行 PowerShell。

Agent 示例清单

Multi-Purpose Voice Assistant：低延迟实时助手，支持 RTC 与 WebSocket，可扩展 Memory/VAD/Turn Detection。
Doodler：把语音或文字提示画成手绘草图。
Speaker Diarization：实时说话人分离。
Lip Sync Avatars：多头像厂商（Live2D Kei、Trulience/HeyGen/Tavus）。
SIP Call：通过 SIP 扩展打真实电话。
Transcription：音频转文字。
ESP32-S3 Korvo V3：在乐鑫 ESP32-S3 开发板跑 TEN agent 示例。