人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本指南以 TEN-framework 仓库中ai_agents/agents/examples/voice-assistant-sip-twilio/server/目录为核心讲解该示例中独立 Twilio 服务器的定位、源码结构、配置方式与调用方式。读完本文你将掌握如何安装并启动这个 FastAPI 独立进程、如何通过环境变量注入 Twilio 凭证、它暴露了哪些 HTTP 端点、以及它如何与负责 WebSocket 音频流处理的main_python扩展分工协作共同构成完整的 SIP/Twilio 语音助手呼叫链路。一、这是什么从 main_python 扩展迁移出的独立 Twilio 服务器在voice-assistant-sip-twilio示例中整体语音助理由多个组件协作完成STT → LLM → TTS 实时对话管线、WebSocket 音频流转发、Twilio 呼叫管理。而server/目录下的这份 README 描述的是一个独立运行的 Twilio 服务器应用它从ten_packages/extension/main_python中迁移而来核心职责是基于FastAPI提供 REST API支持外呼outbound calls、接听来电receiving calls与状态回调status callbacks明确不做WebSocket 与音频处理——这两部分由main_python扩展负责详见后文职责分工一节。换句话说该服务器扮演的是呼叫管理 配置下发 进程守护的角色而不是语音数据通道本身。这种拆分让服务器代码可以脱离 TEN 框架的运行时独立测试与部署也使得呼叫控制与音频 AI 处理两条关注点清晰解耦。二、项目结构与源码模块解析按 server/README.md 的描述目录结构如下server/ ├── __init__.py # Package initialization ├── main.py # Main entry file ├── config.py # Configuration model ├── twilio_server.py # Twilio server logic ├── run_server.py # Startup script ├── requirements.txt # Python dependencies └── README.md # Documentation结合当前仓库实际文件核对该目录下实际存在__init__.py、main.py、twilio_server.py、requirements.txt 与 README.md。可以推断文档中提到的config.py配置模型与run_server.py启动脚本在实际代码中已分别合并进twilio_server.pyTwilioServerConfigpydantic 模型与main.py含argparse与asyncio.run(main())入口因此阅读源码时以这两个文件为准文件职责__init__.py包初始化声明main.py命令行入口解析--tenapp-dir/--port参数、读取环境变量、配置日志、启动服务器twilio_server.py核心实现TwilioServerConfig配置模型、TwilioServerFastAPI 应用、tenapp 子进程管理requirements.txt依赖清单fastapi、uvicorn[standard]、twilio、pydanticrequirements.txt 中特别注释了两点WebSocket 功能由main_python扩展处理音频处理所用的audioop属于 Python 标准库无需额外安装。三、安装与运行1. 安装依赖README 给出的方式是使用tman# 在项目根目录执行 tman run build若使用仓库自带的 Taskfile 工作流见 Taskfile.yml则等效的安装命令为在示例目录执行cd agents/examples/voice-assistant-sip-twilio task install该任务会依次执行tman install、Python 依赖安装脚本tenapp/scripts/install_python_deps.sh以及前端bun install。2. 配置环境变量按 server/README.md 的说明设置以下环境变量export TWILIO_ACCOUNT_SIDyour_twilio_account_sid export TWILIO_AUTH_TOKENyour_twilio_auth_token export TWILIO_FROM_NUMBER1234567890 export TWILIO_HTTP_PORT8000 export TWILIO_GREETINGHello, I am your AI assistant.对照 twilio_server.py 的main()函数实际被该独立服务器读取的环境变量还包括环境变量读取代码位置默认值说明TWILIO_ACCOUNT_SIDmain()空字符串Twilio 账户 SIDTWILIO_AUTH_TOKENmain()空字符串Twilio 认证令牌TWILIO_FROM_NUMBERmain()空字符串呼出使用的 Twilio 电话号码TWILIO_HTTP_PORTmain()8080独立服务器监听端口README 示例写作 8000源码默认 8080前端默认也指向 8080见 frontend/app/api.tsTWILIO_PUBLIC_SERVER_URLmain()空字符串公网服务器地址不含协议如your-domain.com:9000用于拼接 WebSocket 媒体流地址与 webhook 地址TWILIO_USE_HTTPSmain()false字符串比较webhook 使用https还是httpTWILIO_USE_WSSmain()false媒体流使用wss还是ws需要说明的是README 示例中的TWILIO_GREETING并未被独立服务器的TwilioServerConfig解析源码配置模型中无此字段它来自原main_python扩展的配置体系用于设置 AI 助手的开场问候语真正生效位置在 tenapp 一侧的 LLM/agent 配置中。3. 启动服务器README 给出两种启动方式# 使用 tman 运行 tman run twilio-server # 或直接运行 python3 server/run_server.py结合仓库实际代码可运行的等效命令为见 Taskfile.yml 的run-api-server任务# 进入 server 目录指定 tenapp 路径 cd server python3 main.py --tenapp-dir ../tenapp # 或直接 task run-api-servermain.py 支持两个命令行参数--tenapp-dirtenapp 目录路径默认取../tenapp相对于 server 目录--portTwilio 服务器端口默认8080。启动后日志会同时输出到标准输出与/tmp/twilio_server.log。四、配置模型TwilioServerConfig 源码级解读TwilioServer的全部配置都封装在 pydantic 的TwilioServerConfig中见 twilio_server.pyclass TwilioServerConfig(BaseModel): # Twilio configuration twilio_account_sid: str Field(default, descriptionTwilio Account SID) twilio_auth_token: str Field(default, descriptionTwilio Auth Token) twilio_from_number: str Field(default, descriptionTwilio phone number to call from) # Server configuration twilio_server_port: int Field(default8080, descriptionPort for server (process management)) # Tenapp configuration tenapp_dir: str Field(default, descriptionPath to tenapp directory) # Public server URL configuration twilio_public_server_url: str Field( default, descriptionPublic server URL without protocol (e.g., your-domain.com:9000) - used for both media stream and webhooks, ) # Protocol configuration twilio_use_https: bool Field(defaultTrue, descriptionUse HTTPS for webhooks (True) or HTTP (False)) twilio_use_wss: bool Field(defaultTrue, descriptionUse WSS for media stream (True) or WS (False))几个值得注意的源码细节twilio_public_server_url是不含协议前缀的地址服务器会依据twilio_use_wss/twilio_use_https动态拼接wss:///ws://与https:///http:///api/config端点会从twilio_public_server_url中解析出 tenapp 端口取冒号后的数字解析失败回退到9000并据此返回tenapp_urlhttp://localhost:{tenapp_port}是否启用媒体流与 webhook 完全取决于是否配置了twilio_public_server_url为空时media_stream_enabled与webhook_enabled均为false。五、API 端点详解独立服务器自身提供的端点端口 8080该服务器在 twilio_server.py 的_setup_routes()中只注册了两个路由GET /health健康检查返回{status: healthy, server_time: ...}GET /api/config返回服务器配置与 tenapp 服务器信息包括twilio_from_number、server_port、tenapp_port、tenapp_url、public_server_url、use_https、use_wss、media_stream_enabled、media_ws_url、webhook_enabled、webhook_url等字段供前端获取运行时配置。呼叫管理 API位于 tenapp 的 main_python 扩展端口 9000server/README.md 列出的呼叫管理端点如下POST /api/calls— 创建外呼GET /api/calls— 列出所有呼叫GET /api/calls/{call_sid}— 获取呼叫信息DELETE /api/calls/{call_sid}— 停止呼叫POST /webhook/status— Twilio 状态回调GET /health— 健康检查这些端点的真正实现位于 tenapp 侧的 ten_packages/extension/main_python/server.pyTwilioCallServer类。从源码可见其具体行为创建外呼POST /api/call注意实现中的路径为单数/api/call读取 JSON 请求体中的phone_number必填与message默认Hello from Twilio!若配置了twilio_public_server_url会构造ConnectStream urlwss://.../media/Stream/Connect形式的 TwiML 并附加say(Stream Started)同时设置status_callback指向协议://{public_server_url}/webhook/status并订阅initiated / ringing / answered / completed四个事件随后通过 Twilio SDK 创建呼叫并把会话信息记录到active_call_sessions字典结束呼叫DELETE /api/call/{call_sid}调用twilio_client.calls(sid).update(statuscompleted)并在会话中标记ended_at查询/列表基于内存字典active_call_sessions返回会话状态状态回调GET/POST /webhook/status兼容两种请求方式解析CallSid、CallStatus、CallDuration、Direction表单参数并更新会话媒体流 WebSocket/media接收 Twilio 媒体流消息处理start记录streamSid、callSid并触发on_websocket_connected通知扩展、media将音频 payload 转发给 TEN 框架、stop等事件。GET /health在该实现中额外返回active_calls计数便于监控当前活跃呼叫数。前端如何消费这些 APIfrontend/app/api.ts 展示了双服务器架构的消费方式前端通过NEXT_PUBLIC_TWILIO_SERVER_URL默认http://localhost:8080请求独立服务器的/api/config而呼叫管理类请求/api/call、/api/calls、/health则默认发往NEXT_PUBLIC_TENAPP_SERVER_URL默认http://localhost:9000的 tenapp 服务器。六、进程管理与生命周期独立服务器如何守护 tenapp独立服务器最重要的隐藏功能是tenapp 子进程管理见 twilio_server.py 的_start_tenapp_process/_monitor_tenapp_process/_stop_tenapp_process启动时通过subprocess.Popen([./scripts/start.sh], cwdtenapp_dir, preexec_fnos.setsid)拉起 tenapptenapp/scripts/start.sh 内部设置PYTHONPATH、LD_LIBRARY_PATH、NODE_PATH后执行bin/main若未显式指定--tenapp-dir回退到 server 目录的上一级下的tenapp/启动一个守护线程每秒轮询子进程状态一旦 tenapp 退出服务器会记录退出码并向自身发送SIGTERM优雅关闭服务器收到SIGINT/SIGTERM时会先向 tenapp 进程组发送SIGTERM等待 10 秒后仍不退则升级为SIGKILL最后清理资源退出。这种进程守护设计意味着独立服务器与 tenapp 可以作为一个整体被拉起任一方异常退出另一方也会随之关闭避免留下孤儿进程或半死不活的服务。七、与原版代码的差异README 要点继承server/README.md 明确列出了该独立服务器相对原main_python扩展代码的五点差异独立运行完全独立无外部框架依赖配置管理改用环境变量进行配置而非扩展的 property 配置日志系统使用 Python 标准库loggingmain.py中输出到 stdout 与/tmp/twilio_server.logtwilio_server.py中按%(asctime)s - %(name)s - %(levelname)s - %(message)s格式输出到流处理器模块化设计代码结构更清晰、更易维护关注点分离WebSocket 与音频处理保留在main_python扩展中服务器只提供呼叫管理的 HTTP API。八、运行注意事项与排错要点结合 README 的 Notes 与源码实现实际部署时需注意确保 Twilio 账户配置正确TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN、TWILIO_FROM_NUMBER三者缺一不可tenapp 侧的 server.py 在缺失时会直接报错退出确保防火墙放行相关端口独立服务器默认 8080TWILIO_HTTP_PORT可改tenapp 默认 9000前端 3000公网可达性Twilio 需要能回调你的服务器。本地开发可用仓库提供的 start-with-ngrok.sh 与 ngrok.yml将本地 9000 端口映射为公网 HTTP 隧道支持 WebSocket并把得到的公网地址填入TWILIO_PUBLIC_SERVER_URL该脚本依赖NGROK_AUTHTOKEN环境变量未设置时仅给出警告WebSocket 与音频处理不在本服务器本服务器只提供呼叫管理的 HTTP API 端点媒体流由main_python扩展承载排查语音问题时应在 tenapp 侧日志中定位状态回调仅在配置公网地址后生效twilio_public_server_url为空时不会设置status_callbackTwilio 也就不会回传呼叫状态事件。九、延伸阅读示例整体说明与完整环境变量清单含 Deepgram、OpenAI、ElevenLabs 等 AI 服务凭证README.mdtenapp 图配置property.json中预定义图voice_assistant串起 STT/LLM/TTS/main_control 节点property.json呼叫与媒体流核心实现ten_packages/extension/main_python/server.py独立服务器入口与配置实现main.py、twilio_server.py一键启动编排ngrok 前端 tenapp 独立服务器Taskfile.ymlDocker 化部署构建与运行命令见示例根目录 READMEDockerfile赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework Voice Assistant SIP Plivo Server独立 HTTP 服务架构与实战部署指南TEN Framework Voice Assistant SIP Plivo Server独立 HTTP 服务架构与实战部署指南 导读 本文围绕 TEN f人工智能AI Agent多模态语音AI 应用TEN Framework 语音助手中枢main_python 扩展的架构解析与实战指南TEN Framework 语音助手中枢main_python 扩展的架构解析与实战指南 在 TEN Framework 的 Live2D 语音助手示例 v人工智能AI Agent多模态语音AI 应用如何用环境变量把 Immich 拆分为独立的 API 与微服务容器如何用环境变量把 Immich 拆分为独立的 API 与微服务容器 默认情况下Immich 的 immich server 容器内部同时运行两类 worker后端前端移动开发音视频计算机视觉创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考