hkjarral/AVA-AI-Voice-Agent-for-Asterisk 来源：https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk 版本许可 Python Docker Asterisk 在 DeepWiki 上询问 (https://deepwiki.com/hkjarral/Asterisk-AI-Voice-Agent) Discord (https://discord.gg/ysg8fphxUe) 最强大、最灵活的开源 AI 语音代理，适用于 Asterisk/FreePBX。采用模块化流水线架构，可自由组合 STT、LLM 和 TTS 提供商，并包含6 个经过企业部署验证的生产级黄金基线。 快速开始 · 功能特性 · 路线图 · 演示 · 文档 · 社区 — ## 📖 目录 - 🚀 快速开始 - 🎉 最新更新 - 🌟 为什么选择 Asterisk AI 语音代理？ - ✨ 功能特性 - 🎥 演示 - 🛠️ AI 驱动动作 - 🩺 代理 CLI 工具 - ⚙️ 配置 - 🏗️ 项目架构 - 📊 环境要求 - 🗺️ 文档 - 🤝 贡献指南 - 💬 社区 - 📝 许可证 — ## 🚀 快速开始 两分钟内启动管理 UI。如需完整的首次成功通话演练（拨号计划 + 传输模式选择 + 验证），请参阅： - 安装指南 - 传输模式兼容性 ### 1. 运行预检检查（必需） bash # 克隆仓库 git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git cd AVA-AI-Voice-Agent-for-Asterisk # 运行预检并自动修复（创建 .env，生成 JWT_SECRET） sudo ./preflight.sh --apply-fixes > 重要提示： 预检会创建 .env 文件并生成安全的 JWT_SECRET。务必先运行此步骤！ ### 2. 启动管理 UI bash # 启动管理 UI 容器 docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui ### 3. 访问仪表盘 在浏览器中打开： - 本地： http://localhost:3003 - 远程服务器： http://<服务器IP>:3003 默认登录： 首次启动时，一次性管理员密码会打印到容器日志中。使用以下命令获取： bash docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password 首次登录后必须更改密码。生产环境中请通过防火墙、VPN 或反向代理限制端口 3003。 跟随设置向导配置您的提供商并进行测试通话。 > ⚠️ 安全性： 管理 UI 在网络上可访问。生产环境中请通过防火墙、VPN 或反向代理限制端口 3003。 ### 4. 验证安装 > GPU 用户： 如果您拥有 NVIDIA GPU 用于本地 AI 推理，请在构建前参阅 docs/LOCAL_ONLY_SETUP.md 了解 GPU compose 覆盖层（docker-compose.gpu.yml）。 bash # 启动 ai_engine（健康检查所需） docker compose -p asterisk-ai-voice-agent up -d --build ai_engine # 检查 ai_engine 健康状态 curl http://localhost:15000/health # 预期输出：{"status":"healthy"}（"degraded" 也可能表示某个子系统不健康） # 查看日志中的错误 docker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20 ### 5. 连接 Asterisk 向导将为您生成 Asterisk 服务器所需的拨号计划配置。传输模式的选择取决于配置（并非严格的“流水线 vs 完整代理”）。请使用经过验证的矩阵： - docs/Transport-Mode-Compatibility.md — ## 🔧 高级设置（命令行） 适用于偏好命令行或需要无头设置的用户。 ### 选项 A：交互式 CLI bash ./install.sh agent setup > 注意：旧命令 agent init、agent quickstart、agent doctor、agent troubleshoot 和 agent demo 仍保留为隐藏的兼容性别名。新工作流应使用 docs/CLI_TOOLS_GUIDE.md 中记录的可见命令。 ### 选项 B：手动设置 bash # 配置环境 cp .env.example .env # 编辑 .env 文件，填入您的 API 密钥 # 启动服务 docker compose -p asterisk-ai-voice-agent up -d ### 配置 Asterisk 拨号计划 将其添加到您的 FreePBX（extensions_custom.conf）： asterisk [from-ai-agent] exten => s,1,NoOp(Asterisk AI Voice Agent) ; AI_AGENT 通过 slug 选择一个由运维管理的代理。 same => n,Set(AI_AGENT=sales-agent) ; 可选：为此通话覆盖代理已配置的提供商/流水线。 ; same => n,Set(AI_PROVIDER=google_live) same => n,Stasis(asterisk-ai-voice-agent) same => n,Hangup() 说明： - 使用 AI_AGENT 选择由运维管理的代理。除非故意设置 AI_PROVIDER 作为每次通话的覆盖，否则该代理配置的目标具有权威性。 - 使用 agent dialplan --agent <slug> 生成当前代码片段。 - 有关通道变量优先级及示例，请参阅 docs/FreePBX-Integration-Guide.md。 ### 测试您的代理 健康检查： bash agent check 查看日志： bash docker compose -p asterisk-ai-voice-agent logs -f ai_engine — ## 🎉 最新更新 v7.3.3 — 本地 AI 稳定性优化 🧠 v7.3.3 是一个仅针对本地 AI 的稳定性发布版本。未新增提供商，云提供商通话路径保持不变。 - 通话按会话隔离 — 代理提示语和对话状态不再修改共享的本地 AI 服务器配置，也不会跨重复使用的 WebSocket 连接泄漏。AI Engine 和 Local AI Server 应同时升级；旧的无作用域开关暂时保持兼容。 - 打断功能丢弃中断的输出 — 延迟的 LLM/TTS 工作被隔离，中断的交换消息从弱模型历史中移除，替换轮次专注于呼叫者刚刚说的内容。 - 告别语恰好执行一次 — 本地 hangup_call 使用选定的 Kokoro/Piper 等告别语（不经过第二次 LLM 重写），排空部分 AudioSocket 或 RTP 尾部，记录 agent_hangup，然后断开连接。 - CPU/GPU 部署更安全 — 依赖固定、CUDA/cuDNN 验证、可选的 llama.cpp 架构目标以及幂等预检检查，减少了首次构建和重新运行的失败。 - 社区 GPU 证据 — Tesla V100S 测试通过了 Faster-Whisper CUDA float16、Llama 3.1 8B Q4_K_M、Kokoro、AudioSocket、ExternalMedia、打断、终端挂断、并发会话隔离和重启恢复。请参阅本地 AI 社区测试矩阵和未发布变更日志以获取完整范围。 v7.3.2 — 稳定性发布 🛡️ v7.3.2 是一个仅针对稳定性的补丁版本，基于监督下的 AudioSocket 和 ExternalMedia 验证周期构建。 - 未新增提供商 — 范围限于可靠性、部署安全性、文档和面向贡献者的 CI。 - Grok ExternalMedia 修复 — 干净的打断、取消输出隔离、命名实例运行时继承、完整替换轮次以及通过 xAI force_message 的精确无活动通知。 - AudioSocket 和模块化流水线加固 — 终端播放、流水线生产者所有权、通话检测回波以及无活动宽限回退均通过针对性测试和监督通话覆盖。 - 更新器和提供商故障恢复加固 — 更安全的所有权、回滚/暂存处理、就绪验证以及可选的拨号计划重定向。 - PR 质量门禁扩展 — 管理后台/前端检查以及 CLI 交叉编译现在在合并前运行。发布证据和剩余门禁在 v7.3.2 验证矩阵中跟踪。 v7.3.1 — 静默看门狗与安全通话结束 ☎️ AVA 现在保护静默通话，并在断开连接前完成每条终端消息。 - 默认 30 秒入站无活动保护 — AVA 询问“您还在吗？”，等待 15 秒回复，然后播放可配置的最终警告并结束通话。出站代理仍为可选。 - 代理保持其配置的语音 — 签到和最终警告由活动的 Google Live、OpenAI Realtime、Grok、Deepgram、ElevenLabs、本地完整代理或流水线语音合成。 - 传输安全挂断 — 看门狗和 hangup_call 告别语在 ARI 断开呼叫者之前排空 AudioSocket 或 ExternalMedia/RTP 流缓冲区以及 ARI 文件播放。固定的睡眠不再截断长句子。 - Deepgram 和 ElevenLabs 生命周期修复 — Deepgram 控制帧不再分割问候语，ElevenLabs 响应完成和托管静音处理使 AVA 的看门狗保持权威。 - 全局和每代理控制 — 在 高级设置 → 语音活动检测 → 呼叫者无活动下配置默认值，然后可选地为每个代理覆盖。通话历史将看门狗结束标记为 无输入超时。请参阅呼叫者无活动配置、ElevenLabs 设置以及完整 v7.3.1 变更日志。 v7.3.0 — 每代理语音 🎙️ 语音现在属于代理。 配置一个提供商，创建多个共享该提供商的代理——每个代理拥有自己的语音。 - 代理表单中的提供商感知语音选择器：OpenAI 的 10 个 GA 语音下拉列表、Grok 的建议+自定义克隆 ID、Google Live 的 30 个预建语音、Deepgram 的 Aura 模型——控件会根据代理选择的 AI Engine 自适应调整。 - 默认安全 — 提供商级别的语音成为默认语音；没有语音的代理行为与以前完全相同。无法识别的值（OpenAI/Google/Deepgram 目录已验证）会记录警告并回退——错误的语音值永远不会导致通话失败。 - 可观察 — 每次通话都会记录解析后的语音及其来源，通话历史显示“语音：marin（来自代理）”。 - 代理语音更改立即生效，无需重启引擎。感谢 @foytech 提出此功能 (#497)。完整指南：docs/VOICE_SELECTION.md。 v7.2.0 — 实时状态仪表盘 📡 管理 UI 的实时系统状态——推送而非轮询。 - 实时状态中心 — 一个 /api/live-status 快照端点加上 SSE 流（/api/live-status/stream），将 AI Engine 健康状态、本地 AI 连接、活动会话、音频目录、平台检查和 Asterisk ARI 汇总为一个标准化的状态反馈。 - 推送优先 — ai_engine 和 local_ai_server 将自己的就绪状态推送到管理 UI（POST /api/live-status/publish，使用 LIVE_STATUS_PUSH_TOKEN 验证），因此仪表盘在重启后亚秒内收敛，而不是等待错开的轮询。旧的 /api/system/* 探测作为回退/补充保留。 - 可配置 — LIVE_STATUS_POLL_INTERVAL_SECONDS（默认 30 秒，最小 2 秒）和 LIVE_STATUS_INITIAL_PROBE_TIMEOUT_SECONDS（默认 2 秒），从 .env 实时读取。完整说明见 CHANGELOG.md。 v7.1.1 — 仪表盘可靠性与管理 UI 改进 🛠️ 专注于管理 UI 的质量发布——无通话路径更改。 - 仪表盘可靠性 — Asterisk 状态指示灯不再因短暂的 ARI 波动而闪烁：它读取引擎权威的、由重连监督的 ARI 状态并应用迟滞。仪表盘每 5 秒轮询的系统端点不再阻塞管理事件循环，最重的端点有 TTL 缓存，轮询在出错时后退，失败轮询在错误横幅中显示，单个错误轮询不再将卡片闪烁为“Loading…”。 - 不再出现“Loading configuration…”闪烁 — 约 11 个配置页面现在从配置文档的共享 stale-while-revalidate 缓存中获取种子，因此重新访问设置页面是即时的。 - 无障碍性（WCAG AA） — 表单标签与输入程序化关联、焦点陷阱模态框、导航地标 + “跳到内容”链接、纯图标按钮的可访问名称、拓扑上的非颜色状态提示、可见的深色模式切换状态以及浅色模式对比度修复。调试用的 console.log（包括一个向浏览器控制台泄漏认证令牌的）已被移除。 - 提示编辑器 — 输入时，已配置的工具名称根据其在通话中的状态（启用/全局/未启用）进行颜色编码。 - 修复 (#436) — 规范的 google_live: { type: full } 提供商现在可以再次编辑和保存。完整说明见 CHANGELOG.md。 v7.0.0 — 代理版本 🎯 迄今为止最大的版本：从管理 UI 管理您的 AI 代理，无需修改配置文件。 - 🤖 代理标签页 — 在 UI 中创建、编辑和管理代理。从模板开始（接待员、非工作时间、预约预订等），设置提示语和提供商，并复制一个可粘贴的拨号计划代码片段。（语音在提供商级别配置，而非每代理。） - 📊 多代理仪表盘 — 实时 KPI（活动代理、活动通话、已路由通话、转接）、每代理统计和路由分解一目了然。 - ☎️ 新的 AI_AGENT 拨号计划变量 — 按名称将通话路由到代理。您现有的 AI_CONTEXT 拨号计划保持不变。 - 🔄 自动迁移 — 首次启动时，您现有的上下文将迁移到本地代理数据库。无需任何操作，回滚只需一个命令。 - 🔒 安全强化 — 不再使用 admin/admin：生成一次性管理员密码，首次登录必须更改。配置导出默认不再捆绑您的 .env。 ⚠️ 重要版本——从 6.x 升级前请阅读升级说明。 v6.5.4 (2026-05-25) — OpenAI Realtime GA 清理覆盖所有代码路径 对 v6.5.3 热修复的跟进。v6.5.3 仅翻转了 config/ai-agent.yaml；v6.5.4 将代码库其余部分同步： - Pydantic 默认值 在 src/config.py 中现在默认为 api_version: ga + model: gpt-realtime（因此新向导安装正确）。 - 管理 UI “添加提供商”模板 OpenAI Realtime 不再填充已弃用的预览模型。 - 模型下拉列表 移除了 5 个已弃用的预览选项，新增 3 个 GA 模型——gpt-realtime-1.5（最佳音频输入/输出质量）、gpt-realtime-2（推理语音模型，GPT-5 级别）和 gpt-realtime-mini（成本优化）——与现有的 gpt-realtime 并列。 - 运营商 YAML 中的旧预览值 现在在表单上方呈现为“自定义（旧版——将无法连接）”的 optgroup，并带有黄色警告横幅，以便在未静默替换运营商配置的情况下显示损坏状态。 - 引擎 在配置中检测到 api_version: beta 时发出一次性警告（每个提供商生命周期仅一次，而非每次重连尝试）。 - 文档：完全重写 docs/Provider-OpenAI-Setup.md 模型部分，并修复 docs/TROUBLESHOOTING_GUIDE.md。 v6.5.3 热修复 (2026-05-25) — OpenAI Realtime 恢复 OpenAI 于 2026-05-12 弃用了 Realtime Beta API，并于 2026-05-07 移除了 gpt-4o-realtime-preview-2024-12-17 模型。已发布的 config/ai-agent.yaml 仍固定为 api_version: beta + 该预览模型，因此每个使用 OpenAI Realtime 的运营商都会遇到 error.code: beta_api_shape_disabled，WebSocket 立即关闭。 两行配置翻转——无需代码更改。提供商的 GA 线路协议路径自 v6.0.0 起已存在；v6.5.3 只是使其成为默认值： - api_version: ga（原为 beta） - model: gpt-realtime（原为 gpt-4o-realtime-preview-2024-12-17） 如果您有明确固定 api_version: beta 的 ai-agent.local.yaml，请移除覆盖或将其更改为 ga。参考：OpenAI 弃用 (https://developers.openai.com/api/docs/deprecations)，gpt-realtime (https://platform.openai.com/docs/models/gpt-realtime)。 v6.5.2 (2026-05-24) — xAI Grok + 多实例完整代理提供商 ### 🆕 xAI Grok 语音代理实时提供商（新增，v6.5.2） - 第五个完整代理实时提供商——结构上与 OpenAI Realtime 和 Google Live 并行，从第一天起基于多实例基础构建 - μ-law @ 8 kHz 呼叫者输入，无需输入重采样