hkjarral/AVA-AI-Voice-Agent-for-Asterisk

这是目前最强大、最灵活的 Asterisk/FreePBX 开源 AI 语音助手。它采用模块化管道架构，允许你随意组合 STT、LLM 和 TTS 提供商，并内置了 6 种已通过生产环境验证的“黄金基准”配置，可直接用于企业部署。

快速入门 • 功能特性 • 路线图 • 演示 • 文档 • 社区

---

📖 目录

• 🚀 快速入门
• 🎉 v6.4.0 版本更新
• 🌟 为什么选择 Asterisk AI Voice Agent？
• ✨ 功能特性
• 🎥 演示
• 🛠️ AI 驱动的操作
• 🩺 Agent CLI 工具
• ⚙️ 配置
• 🏗️ 项目架构
• 📊 系统需求
• 🗺️ 文档
• 🤝 贡献
• 💬 社区
• 📝 许可证

---

🚀 快速入门

2 分钟内启动 Admin UI。

如需了解完整的首次通话成功指南（拨号方案 + 传输选择 + 验证），请参阅：

• 安装指南
• 传输兼容性说明

1. 运行预检（必须）

# 克隆仓库
git clone https://github.com/hkjarral/Asterisk-AI-Voice-Agent.git
cd Asterisk-AI-Voice-Agent

# 运行预检并自动修复（创建 .env 文件，生成 JWT_SECRET）
sudo ./preflight.sh --apply-fixes

重要： 预检脚本会创建 .env 文件并生成安全的 JWT_SECRET。请务必先运行此步骤！

2. 启动 Admin UI

# 启动 Admin UI 容器
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui

3. 访问控制面板

在浏览器中打开：

• 本地： http://localhost:3003
• 远程服务器： http://<your-server-ip>:3003

默认登录信息： admin / admin

按照设置向导配置你的提供商并进行测试通话。

⚠️ 安全警告： Admin UI 在网络上可见。请立即修改默认密码，并在生产环境中使用防火墙、VPN 或反向代理限制对 3003 端口的访问。

4. 验证安装

GPU 用户： 如果你有用于本地 AI 推理的 NVIDIA GPU，请在构建前参阅 docs/LOCAL_ONLY_SETUP.md 获取 GPU compose 覆盖文件 (docker-compose.gpu.yml)。

# 启动 ai_engine（健康检查所必需）
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine

# 检查 ai_engine 健康状态
curl http://localhost:15000/health
# 预期输出：{"status":"healthy"}

# 查看 ai_engine 日志以检查错误
docker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20

5. 连接 Asterisk

设置向导将为你的 Asterisk 服务器生成必要的拨号方案 (dialplan) 配置。

传输方式的选择取决于具体配置。请使用以下指南中的验证矩阵：

• docs/Transport-Mode-Compatibility.md

---

🔧 高级设置 (CLI)

适用于偏好命令行操作或需要无头 (headless) 设置的用户。

选项 A：交互式 CLI

./install.sh
agent setup

注意：旧版命令 agent init、agent doctor 和 agent troubleshoot 在 CLI v6.4.0 中作为隐藏别名保留。

选项 B：手动设置

# 配置环境变量
cp .env.example .env
# 使用你的 API 密钥编辑 .env 文件

# 启动服务
docker compose -p asterisk-ai-voice-agent up -d

配置 Asterisk 拨号方案

将以下内容添加到你的 FreePBX (extensions_custom.conf)：

[from-ai-agent]
exten => s,1,NoOp(Asterisk AI Voice Agent)
 ; 可选：按次通话覆盖：
 ; - AI_PROVIDER 选择提供商/管道（否则使用 ai-agent.yaml 中的 default_provider）
 ; - AI_CONTEXT 选择上下文/角色（否则使用默认上下文）
 same => n,Set(AI_PROVIDER=google_live)
 same => n,Set(AI_CONTEXT=sales-agent)
 same => n,Stasis(asterisk-ai-voice-agent)
 same => n,Hangup()

注意：

• AI_PROVIDER 是可选的。如果不设置，引擎将遵循正常优先级（上下文提供商 → default_provider）。
• AI_CONTEXT 是可选的。使用它可以更改问候语/角色，而无需更改默认提供商/管道。
• 有关通道变量优先级和示例，请参阅 docs/FreePBX-Integration-Guide.md。

测试你的 Agent

健康检查：

curl http://localhost:15000/health