realtime-phone-agents-course
neural-maze/realtime-phone-agents-course加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下这样的场景：用户拨打一个房产中介热线，电话那头不是按键菜单，而是一个温柔的女声"Tara"，实时询问你想要的房源条件——"您想要马德里哪个区域的房子？预算上限是多少？"——然后在对话中动态调整搜索条件，最终帮你找到最匹配的那一套。这不是科幻电影，而是 The Neural Maze 团队在 GitHub 上开源的真实可运行项目。
图1：系统整体架构图（来源：项目 README）
这个项目的发起人是 Miguel Otero Pedrido（网名 Michaelis Trofficus）和 Jesús Copado，两位西班牙资深 ML/AI 工程师。他们在运营 "The Neural Maze" 技术博客（Substack 订阅通讯）时发现，市场上关于实时语音 Agent 的教程要么过于浅显（只是简单的 Web Demo），要么需要购买昂贵的商业服务。为了让更多开发者真正掌握从零到生产的端到端能力，他们决定把整个技术链条做成一套免费的开源课程。
课程采用"周课制"：每周发布一篇深度 Substack 文章 + 代码增量推送 + YouTube 直播答疑。目前已更新 5 个章节（Week 0-4），从基础的 WebRTC 语音通信讲到生产级多 Avatar 呼叫中心。
整个系统的数据流向可以概括为：用户电话 → Twilio → WebRTC 流 → STT 语音识别 → LLM 对话 → TTS 语音合成 → WebRTC 流 → Twilio → 用户听筒。每一步都有多个可替换实现，形成了极强的高低成本组合能力。
项目支持三种 STT 后端，开发难度和成本逐级递增：
代码位于 src/realtime_phone_agents/stt/ 目录，抽象出统一 Base 类，方便切换不同实现。
这是整个系统的"大脑"。LLM 选用 GPT-4o-mini（通过 OpenAI API），配合 LangChain 实现工具调用（Tool Calling）模式。当用户说"我要找 90 万欧元以下、萨拉曼卡区的公寓"时，LLM 会识别出这是一个检索工具调用请求，触发 Superlinked 检索引擎。
Superlinked 是这个项目最特别的技术选择。与传统的纯向量检索（只支持语义相似性）不同，Superlinked 将文本描述、房价数字、区域类别等不同类型的数据统一建模到同一个向量空间，允许在查询时动态调整各维度的权重。这意味着 Agent 可以在对话中实时组合价格区间、地理位置、房屋面积等多个筛选条件，一次查询返回精准结果，而不是多次调用+重排。
检索结果由 Qdrant Cloud（向量数据库）存储和查询。
同样支持三种后端：
图2：项目核心依赖技术栈 Logo（来源：项目 README）
项目采用标准的 Python 包结构，入口点为 src/realtime_phone_agents：
src/realtime_phone_agents/
├── agent/ # Agent 核心逻辑
│ ├── fastrtc_agent.py # FastRTC Agent 主类，管道编排
│ ├── stream.py # 音频流处理
│ └── tools/ # Agent 工具集（房产搜索等）
├── api/ # FastAPI 服务
│ ├── main.py # Uvicorn 入口，注册路由
│ ├── models.py # Pydantic 请求/响应模型
│ └── routes/ # 路由模块
├── avatars/ # 多 Avatar 系统（Week 4 新增）
│ ├── base.py # Avatar 基类，生成系统 prompt
│ ├── registry.py # Avatar 注册与获取
│ └── definitions/ # YAML 定义各 Avatar 角色
├── stt/ # 语音识别模块
│ ├── local/ # Moonshine 本地实现
│ ├── groq/ # Groq Whisper API
│ └── runpod/ # Faster Whisper 自托管
├── tts/ # 语音合成模块
│ ├── local/ # Kokoro 本地实现
│ ├── togetherai/ # Together AI Orpheus API
│ └── runpod/ # Orpheus 3B 自托管
├── infrastructure/
│ └── superlinked/ # Superlinked 检索引擎封装
└── observability/ # Week 4 新增：可观测性
├── opik_utils.py # Opik 追踪工具
└── prompt_versioning.py # Prompt 版本管理
值得注意的是 Agent 的管道设计：FastRTC 负责音频流分发，音频帧到达后立即交给 STT 模块转写为文本，文本送入 LangChain LLM，LLM 的响应经过 TTS 模块生成音频帧，最后通过 WebRTC 推回。整个管道用 asyncio 驱动，实现了真正的端到端流式处理，而非批量处理。
make start-gradio-application
这条命令会启动一个本地 Gradio Web 界面，打开浏览器就能和 Agent 对话，完全不需要配置 ngrok 或 Twilio。适合在没有电话的情况下先验证语音对话效果。
生产级部署需要完成以下步骤：
.env 文件（参考 .env.example），填入 Twilio、Groq、OpenAI、Qdrant 等凭证docker-compose up -d，这会同时启动 FastAPI 应用和 Qdrant 向量数据库make create-faster-whisper-pod 和 make create-orpheus-poddocker-compose 中 API 服务资源配置：4 核 CPU + 4GB 内存，不需要 GPU（STT/TTS 可以走 API）。Qdrant 容器单独运行，负责向量存储。
Week 4 支持将整个呼叫中心部署到 RunPod，直接获得公网域名，无需 ngrok：
make create-call-center-pod # 一键部署 FastAPI 到 RunPod
make ingest-properties # 将房产数据导入 Qdrant Cloud
Week 4 引入的多 Avatar 系统是这个项目最有意思的设计。不同于单一固定角色，项目允许定义多个"虚拟员工"，每个 Avatar 有：
avatars/definitions/prompt_versioning.py 实现 prompt 的版本追踪和回滚通过 Opik（Comet 的开源可观测性平台），每一次 Agent 对话都被完整记录：STT 耗时、LLM 响应时间、工具调用延迟、TTS 生成耗时——形成完整的性能画像。
图3：The Neural Maze 团队头像（来源：GitHub）
尽管项目整体质量很高，仍有几个不可忽视的现实问题：
1. 延迟瓶颈：端到端延迟（从用户说话到听到回复）受 STT+LLM+TTS 三个环节影响，即使用 Groq 的低延迟 API，真实通话中用户仍能感受到明显等待（通常 2-5 秒）。这是所有实时语音 Agent 的共性问题。
2. Twilio 成本：Twilio 的电话号码和通话费用不便宜（Inbound 约 0.01 美元/分钟起，Outbound 更高）。课程演示用的小规模还好，生产规模电话营销/客服需要认真核算成本。
3. 中文支持：项目默认的语言模型是 GPT-4o-mini（英文为主），房产数据是西班牙马德里房源。对于中文场景，需要替换中文 STT 模型、中文 LLM 和中文 TTS，技术上可行但工作量不小。
4. 复杂对话理解：Superlinked 的多条件检索能力很强，但当用户的表述模糊或包含隐含意图时（如"我想要安静一点但不要太偏"），LLM 的意图识别能力仍是瓶颈。
截至分析时，该项目已获得：
增长趋势得分（Growth Trend Score）达到 57.3，属于快速上升期的优质项目，尤其在 AI 语音 Agent 和 RAG 检索结合这一细分领域具有代表性。
Realtime Phone Agents Course 不是一个玩具级别的 Demo，而是一个真正的端到端生产就绪课程项目。它覆盖了从 Twilio 电话接入、WebRTC 音频流、语音识别、LLM 对话、向量检索、多 Avatar 管理到完整可观测性的完整技术链条。最难得的是，它把所有步骤都做成了可运行的代码，而不是停留在 PPT 架构图层面。
对于想进入 AI 语音交互领域的开发者，这个项目是最好的实践起点之一。对于已经有相关经验的工程师，它的 Superlinked 检索引擎和多 Avatar 架构也值得借鉴。唯一需要注意的是，中文场景需要额外适配工作。
一句话推荐：如果你想知道怎么把 GPT-4o + Whisper + Twilio + Superlinked 组合成一个真正能接电话的 AI Agent，这个项目是目前为止 GitHub 上最完整、最可运行的参考答案。