展示自托管语音AI代理 兼容Asterisk/FreePBX
速览
该项目提供自托管的语音AI代理，可集成到Asterisk和FreePBX电话系统中，实现智能语音交互。开发者可通过开源方式部署，保留数据隐私。该工具适合需要定制化语音助手的用户。
AI 深度解读
背景
在开源电话系统领域，Asterisk 和 FreePBX 是广泛使用的企业级通信平台。它们支持传统的 IVR（交互式语音应答）和呼叫路由，但在自然语言理解和 AI 驱动的语音交互方面能力有限。随着大型语言模型（LLM）和语音 AI 技术的成熟，将智能语音代理集成到电话系统中成为提升客户服务、自动化流程和降低运营成本的重要方向。然而，大多数现成的 AI 语音代理方案依赖公有云服务，存在数据隐私、延迟、成本和对供应商的依赖等问题。自托管的开源方案可以有效解决这些痛点，但此前缺乏一个功能全面、架构灵活且经过企业验证的成熟项目。
AVA（Asterisk AI Voice Agent）正是在这一背景下诞生。它是一个基于 Asterisk/FreePBX 的开源 AI 语音代理，采用模块化管道架构，允许用户自由组合不同的语音转文字（STT）、大语言模型（LLM）和文字转语音（TTS）提供商，并提供了多个经过企业部署验证的生产级基线配置。
核心内容
AVA 是一个为 Asterisk/FreePBX 设计的自托管 AI 语音代理，拥有强大的模块化管道架构，支持混合搭配 STT、LLM 和 TTS 提供商，并提供 6 个经过企业部署验证的生产级黄金基线。项目提供了详细的快速启动指南、功能介绍、演示、AI 驱动的动作、CLI 工具、配置说明、项目架构、依赖要求、文档、贡献指南和社区支持。
快速启动：用户可以在 2 分钟内启动管理界面。首先克隆仓库：
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
接着启动管理界面容器：
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui
在浏览器中打开 http://localhost:3003（本地）或 http://<server-ip>:3003（远程）。首次启动时，一次性管理员密码会打印到容器日志中，可通过以下命令获取：
docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password
首次登录后必须修改密码。生产环境中需要通过防火墙、VPN 或反向代理限制端口 3003 的访问。
之后，用户可以按照设置向导配置提供商并进行测试呼叫。
GPU 用户注意事项：如果拥有 NVIDIA GPU 并希望进行本地 AI 推理，可以参考 docs/LOCAL_ONLY_SETUP.md 中的 GPU 叠加配置（docker-compose.gpu.yml）。
启动 AI 引擎（健康检查必需）：
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine
检查 AI 引擎健康状态：
curl http://localhost:15000/health
预期返回 {"status":"healthy"}（如果子系统不健康也可能返回 "degraded"）。
生成拨号方案配置：设置向导会为 Asterisk 服务器生成所需的拨号方案配置。传输选择依赖于配置（不是严格的“管道 vs 完整代理”）。推荐使用经过验证的矩阵。
CLI 工具：对于偏好命令行或需要无头设置的用户，可使用：
./install.sh
agent setup
注意：旧命令 agent init、agent quickstart、agent doctor、agent troubleshoot 和 agent demo 作为隐藏兼容别名保留。新工作流应使用 docs/CLI_TOOLS_GUIDE.md 中记录的可见命令。
标准配置：复制 .env.example 为 .env，编辑 API 密钥，然后启动所有服务：
docker compose -p asterisk-ai-voice-agent up -d
FreePBX 集成：在 FreePBX 的 extensions_custom.conf 中添加以下内容：
[from-ai-agent]
exten => s,1,NoOp(Asterisk AI Voice Agent)
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。
健康检查：agent check
查看日志：docker compose -p asterisk-ai-voice-agent logs -f ai_engine
版本更新说明：
-
v7.3.3 (本地 AI 稳定版)：仅限本地 AI 的稳定版本，未添加新提供商，云提供商呼叫路径不变。关键修复：会话隔离（代理提示和对话状态不再变异共享的本地 AI 服务器配置或跨重用 WebSocket 连接泄露）；打断功能（中断输出被隔离，被中断的交换从弱模型历史中移除，替换回合专注于呼叫者刚刚说的话）；告别语恰好执行一次（本地
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、打断、终端挂断、并发会话隔离和重启恢复）。 -
v7.3.2 (稳定版修复)：仅修复的补丁版本，基于有监督的 AudioSocket 和 ExternalMedia 验证周期。无新提供商，范围限于可靠性、部署安全性、文档和面向贡献者的 CI。修复了 Grok ExternalMedia（干净打断、取消输出隔离、命名实例运行时继承、完整替换回合、通过 xAI
force_message的精确不活动通知）；硬化了 AudioSocket 和模块化管道（终端播放、管道生产者所有权、对话检测回波、不活动宽容回归）；硬化了更新器和提供商故障恢复（更安全的所有权、回退/stash 处理、就绪验证、可选的拨号方案重定向）；扩展了 PR 质量门控（管理后端/前端检查和 CLI 交叉编译在合并前运行）。 -
v7.3.1 (静默监控与安全通话结束)：AVA 现在保护静默呼叫并在断开连接前完成每条终端消息。默认提供 30 秒入站不活动保护（AVA 询问“您还在吗？”，等待 15 秒回复，然后说出可配置的最终警告并结束通话。出站代理保持选择性加入）。代理保持其配置的语音（检查和不活动最终警告由活动的 Google Live、OpenAI Realtime、Grok、Deepgram、ElevenLabs、本地完整代理或管道语音合成）。传输安全挂断（监控和
hangup_call告别语排空 AudioSocket 或 ExternalMedia/RTP 流缓冲区以及 ARI 文件播放，然后 ARI 断开呼叫者。修复的睡眠不再截断长句）。Deepgram 和 ElevenLabs 生命周期修复（Deepgram 控制帧不再分割问候语；ElevenLabs 响应完成和托管静默处理保持 AVA 的监控权威）。全局和每代理控制（在“高级设置”→“语音活动检测”→“呼叫者不活动”中配置默认值，可选择为每个代理覆盖）。通话历史将监控结束标记为“无输入超时”。 -
v7.3.0 (每代理语音)：语音现在属于代理。配置一个提供商，创建多个共享它的代理——每个代理有自己的语音。代理表单中的提供商感知语音选择器：OpenAI 的 10 个 GA