TEN Framework 实时语音助手实战：基于 Voice-to-Voice 模型的极低延迟语音对话 Agent 搭建指南

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载实时语音助手Realtime Voice Assistant是 TEN-framework 中面向「语音到语音voice-to-voice」模型的端到端示例应用用户说话的声音经由 Agora RTC 采集后直接送入 GPT Realtime、Gemini 2.0 Flash、GLM 等原生语音模型生成语音回复全程不经过「ASR → LLM → TTS」三段式流水线从而获得极低的端到端延迟。本文以 ai_agents/agents/examples/voice-assistant-realtime/README.md 为骨架结合仓库内完整的图配置graph、主控扩展源码与打包脚本带你从环境准备、本地运行、配置调优到 Docker 发布完整搭建一个可复制的实时语音对话 Agent。核心特性极低延迟语音交互采用语音直连语音speech-to-speech的对话模式跳过多阶段流水线最大限度压缩交互延迟多模型供应商支持兼容 OpenAI GPT Realtime、Azure Voice AI、Gemini 2.0 Flash、GLM、StepFun 等主流 voice-to-voice 模型通过环境变量即可切换模块化可定制基于 TEN 的图graph机制组合扩展extension可用 TMAN Designer 可视化替换组件工具调用Function Calling内置天气查询工具演示实时语音场景下的工具调用闭环。前置条件与环境变量必备环境变量Agora 账号用于音频流的实时收发从 Agora 控制台获取凭证。AGORA_APP_ID— 你的 Agora App ID必填Voice-to-Voice 模型供应商五选一OpenAIOPENAI_API_KEY— 用于 GPT RealtimeAzureAZURE_AI_FOUNDRY_API_KEY与AZURE_AI_FOUNDRY_BASE_URI— 用于 Azure Voice AIGeminiGEMINI_API_KEY— 用于 Gemini 2.0 FlashGLMGLM_API_KEY— 用于 GLM 语音模型StepFunSTEPFUN_API_KEY— 用于 StepFun 语音模型。可选环境变量AGORA_APP_CERTIFICATE— Agora App Certificate可选多用于鉴权场景WEATHERAPI_API_KEY— 天气工具weather tool的 API Key可选。在仓库中tenapp/property.json通过${env:VAR}语法把上述变量注入图配置。注意AGORA_APP_CERTIFICATE与WEATHERAPI_API_KEY的写法是${env:VAR|}竖线表示「缺省为空字符串」即不配置也不会导致启动失败。安装与本地运行将环境变量写入.env文件示例位于 ai_agents/.env.exampleTaskfile 通过dotenv: [../../../.env]自动加载# Agora音频流收发必需 AGORA_APP_IDyour_agora_app_id_here AGORA_APP_CERTIFICATEyour_agora_certificate_here # Voice-to-Voice 模型供应商五选一 OPENAI_API_KEYyour_openai_api_key_here # OR AZURE_AI_FOUNDRY_API_KEYyour_azure_api_key_here AZURE_AI_FOUNDRY_BASE_URIyour_azure_base_uri_here # OR GEMINI_API_KEYyour_gemini_api_key_here # OR GLM_API_KEYyour_glm_api_key_here # OR STEPFUN_API_KEYyour_stepfun_api_key_here # 可选 WEATHERAPI_API_KEYyour_weather_api_key_here说明示例中的.env位于仓库ai_agents/目录下与Taskfile.yml中的dotenv: [../../../.env]相对路径一致。安装依赖cd ai_agents/agents/examples/voice-assistant-realtime task install该命令会依次完成详见 Taskfile.ymlinstall-tenapp在tenapp/目录下执行tman install按 tenapp/manifest.json 拉取依赖扩展agora_rtc、openai_mllm_python、azure_mllm_python、gemini_mllm_python、glm_mllm_python、stepfun_mllm_python、message_collector2、weatherapi_tool_python、streamid_adapter 等install-tenapp-python-deps执行 tenapp/scripts/install_python_deps.sh 安装 Python 依赖install-frontend在ai_agents/playground下用bun install安装前端依赖build-api-server在ai_agents/server下执行go mod tidy go mod download go build -o bin/api main.go构建 API 服务。运行实时语音助手cd ai_agents/agents/examples/voice-assistant-realtime task runtask run会并行启动三个进程run-gd-server在tenapp/下执行tman designer启动 TMAN Designer 开发服务器run-frontend在ai_agents/playground下执行bun run dev启动前端run-api-server运行./bin/api -tenapp_dir{{.PWD}}/tenapp启动 API 服务。启动完成后实时语音助手即具备全部能力音频收发、语音对话、转写、工具调用。访问应用服务地址前端Frontendhttp://localhost:3000API 服务API Serverhttp://localhost:8080TMAN Designerhttp://localhost:49483配置详解理解实时语音助手的图结构实时语音助手的核心配置位于 tenapp/property.json。与 README 中简化的两节点示例不同仓库内实际生效的predefined_graphs由6 个扩展节点及其连接关系组成节点名称addon扩展组职责agora_rtcagora_rtcdefault通过 Agora RTC 收发实时音频帧与用户上下线事件main_controlmain_pythoncontrol主控逻辑事件分发、问候语、转写转发、工具调用路由message_collectormessage_collector2transcriber收集并展示用户/助手转写消息weatherapi_tool_pythonweatherapi_tool_pythondefault天气查询工具工具调用示例streamid_adapterstreamid_adapter-音频流 ID 适配将 RTC 音频帧转发给 v2vv2vopenai_mllm_python-Voice-to-Voice 模型扩展默认 GPT Realtime核心节点配置参数agora_rtc节点{ name: agora_rtc, addon: agora_rtc, extension_group: default, property: { app_id: ${env:AGORA_APP_ID}, app_certificate: ${env:AGORA_APP_CERTIFICATE|}, channel: ten_agent_test, stream_id: 1234, remote_stream_id: 123, subscribe_audio: true, publish_audio: true, publish_data: true, enable_agora_asr: false } }参数类型默认值说明app_idstring-Agora App ID取自AGORA_APP_ID必填app_certificatestring空Agora App Certificate取自AGORA_APP_CERTIFICATE可选channelstringten_agent_testRTC 频道名需与客户端前端加入的频道一致stream_idint1234本地音频发布流 IDremote_stream_idint123远端音频订阅流 IDsubscribe_audiobooltrue是否订阅远端音频publish_audiobooltrue是否发布本地音频publish_databooltrue是否发布数据通道enable_agora_asrboolfalse是否启用 Agora 自带 ASR实时语音场景通常关闭交由 v2v 模型处理v2v节点Voice-to-Voice 模型默认 OpenAI GPT Realtime{ name: v2v, addon: openai_mllm_python, property: { api_key: ${env:OPENAI_API_KEY}, temperature: 0.9, model: gpt-realtime, max_tokens: 2048, voice: alloy, language: en, vad_type: semantic_vad, vad_eagerness: auto, vad_threshold: 0.5, vad_prefix_padding_ms: 300, vad_silence_duration_ms: 500 } }参数类型默认值说明api_keystring-模型供应商 API Key取自OPENAI_API_KEY必填temperaturefloat0.9采样温度控制回复随机性modelstringgpt-realtimeRealtime 模型名max_tokensint2048单次回复最大 token 数voicestringalloy语音音色GPT Realtime 内置音色languagestringen对话语言vad_typestringsemantic_vadVAD 类型semantic_vad表示由模型语义判断何时应插话/停止vad_eagernessstringauto插话积极性auto/low/medium/high越高越容易打断vad_thresholdfloat0.5VAD 检测阈值vad_prefix_padding_msint300VAD 触发前保留的音频前缀长度毫秒vad_silence_duration_msint500判定为静音结束说话所需的静音时长毫秒这些 VAD 默认值同样定义在扩展的 property.json 中是 openai_mllm_python 扩展的标准默认配置可直接照抄到自定义图中。完整环境变量参数表参数类型默认值说明AGORA_APP_IDstring-Agora App ID必填AGORA_APP_CERTIFICATEstring-Agora App Certificate可选OPENAI_API_KEYstring-OpenAI API Key使用 GPT Realtime 时必填AZURE_AI_FOUNDRY_API_KEYstring-Azure AI Foundry API Key使用 Azure Voice AI 时必填AZURE_AI_FOUNDRY_BASE_URIstring-Azure AI Foundry Base URI使用 Azure Voice AI 时必填GEMINI_API_KEYstring-Gemini API Key使用 Gemini 2.0 Flash 时必填GLM_API_KEYstring-GLM API Key使用 GLM 语音模型时必填STEPFUN_API_KEYstring-StepFun API Key使用 StepFun 语音模型时必填WEATHERAPI_API_KEYstring-天气工具 API Key可选图连接connections数据如何流动property.json中的connections定义了各扩展之间的消息通道是理解实时语音链路的关键agora_rtc → streamid_adapter → v2vagora_rtc将采集到的pcm_frame音频帧发给streamid_adapter再由其转发给v2v模型扩展上行语音v2v → agora_rtcv2v生成的语音pcm_frame直接回流到agora_rtc发布下行语音v2v → main_control模型产生的mllm_server_input_transcript用户输入转写、mllm_server_output_transcript助手输出转写、mllm_server_session_ready会话就绪、mllm_server_interrupted被打断、mllm_server_function_call函数调用等数据事件全部汇聚到主控agora_rtc → main_control用户加入/离开on_user_joined/on_user_left命令事件weatherapi_tool_python → main_control工具注册命令tool_registermessage_collector → agora_rtc转写消息通过数据通道data返回前端展示。源码级原理主控扩展如何驱动实时对话实时语音助手的大脑是main_python扩展其源码位于 tenapp/ten_packages/extension/main_python。整个主控采用事件驱动的事件队列event-driven asyncio.Queue架构agent/events.py 定义了 8 种语义化 Agent 事件UserJoinedEvent、UserLeftEvent、ToolRegisterEvent、SessionReadyEvent、ServerInterruptEvent、InputTranscriptEvent、OutputTranscriptEvent、FunctionCallEventagent/agent.py 中的Agent类把底层 Cmd/Data 统一转换为上述事件并放入event_queue同时维护tool_registry工具名 → 来源扩展的映射负责工具注册与函数调用结果的回传extension.py 中的MainControlExtension._consume_agent_events()是核心事件循环通过 Python 3.10 的match语法分发事件。关键行为解读问候语逻辑_greeting_if_ready只有当_rtc_user_count 1首位用户加入、配置了greeting、且收到SessionReadyEventsession_ready True三个条件同时满足时才会向 v2v 发送say {greeting} to me消息并触发_send_create_response()生成回复。问候语通过main_control节点的greeting属性配置默认 TEN Agent connected. How can I help you today?其 Pydantic 模型定义在 config.py。打断机制ServerInterruptEvent→_interrupt当模型检测到用户插话语义 VAD 判定时主控向agora_rtc发送flush命令清空正在播放的语音缓冲实现实时打断。工具调用闭环weatherapi_tool_python通过tool_register命令注册工具 → 主控以DATA_MLLM_IN_REGISTER_TOOL数据转发给 v2v → 模型发起mllm_server_function_call→ 主控根据tool_registry找到工具来源扩展并发送tool_call命令 → 拿到LLMToolResult后通过DATA_MLLM_IN_FUNCTION_CALL_OUTPUT回传给模型模型据此组织口语化回复。转写回显InputTranscriptEvent/OutputTranscriptEvent会被封装为message数据发送给message_collector最终经agora_rtc的数据通道展示在 Web 前端方便调试与观察对话过程。定制你的实时语音助手实时语音助手采用模块化设计可以借助TMAN Designer可视化替换组件。访问 http://localhost:49483 即可在浏览器中拖拽编排扩展节点、修改参数并实时预览图结构。常见的定制方向包括更换模型供应商把v2v节点的 addon 从openai_mllm_python换成gemini_mllm_python、glm_mllm_python、azure_mllm_python或stepfun_mllm_python这些扩展均已在 tenapp/manifest.json 的依赖中声明并同步替换api_key对应的环境变量与model名称调整 VAD 行为修改vad_eagerness、vad_threshold、vad_prefix_padding_ms、vad_silence_duration_ms以适配不同打断灵敏度需求增加新工具参照weatherapi_tool_python的注册模式接入仓库中其他工具扩展如bingsearch_tool_python、vision_tool_python等见 ai_agents/agents/ten_packages/extension 目录。发布为 Docker 镜像注意以下命令需要在 Docker 容器之外执行。构建镜像在ai_agents目录下执行cd ai_agents docker build -f agents/examples/voice-assistant-realtime/Dockerfile -t voice-assistant-realtime-app .镜像采用两阶段构建Dockerfilebuilder 阶段基于ghcr.io/ten-framework/ten_agent_build:0.7.14依次执行task install、task release打包 tenapp 运行产物并用bun run build产出前端静态文件运行阶段基于ubuntu:22.04安装 Node.js 20、Bun、Task 等运行时依赖最终以task -t Taskfile.docker.yml run-prod作为入口生产模式启动脚本见 Taskfile.docker.yml。运行容器docker run --rm -it --env-file .env -p 8080:8080 -p 3000:3000 voice-assistant-realtime-app访问前端http://localhost:3000API 服务http://localhost:8080容器内已通过EXPOSE 8080 3000声明端口运行时用--env-file .env把 Agora 与模型供应商的凭证注入容器。参考资源示例完整配置ai_agents/agents/examples/voice-assistant-realtime/tenapp/property.json依赖清单ai_agents/agents/examples/voice-assistant-realtime/tenapp/manifest.json主控扩展源码ai_agents/agents/examples/voice-assistant-realtime/tenapp/ten_packages/extension/main_pythonopenai_mllm_python 扩展默认参数ai_agents/agents/ten_packages/extension/openai_mllm_python/property.json全部可用扩展清单ai_agents/agents/ten_packages/extension任务编排脚本Taskfile.yml 与 Taskfile.docker.yml赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐如何用TEN-framework构建低延迟实时语音助手详细教程如何用TEN framework构建低延迟实时语音助手详细教程 想要构建一个能够实时对话、响应迅速的语音AI助手吗TEN framework作为开源对话语音人工智能AI Agent多模态语音AI 应用NeMo Voice Agent 实战指南基于 NeMo STT/TTS 与 HuggingFace LLM 搭建本地语音对话 AgentNeMo Voice Agent 实战指南基于 NeMo STT/TTS 与 HuggingFace LLM 搭建本地语音对话 Agent 本篇技术指南以 N人工智能语音音频大模型深度学习Mastra xAI Grok 实时语音集成指南使用 mastra/voice-xai-realtime 构建低延迟双向语音 AgentMastra xAI Grok 实时语音集成指南使用 mastra/voice xai realtime 构建低延迟双向语音 Agent mastra/v人工智能Agent 框架AI AgentRAG后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考