h
hkjarral/AVA-AI-Voice-Agent-for-Asterisk
An open-source AI Voice Agent that integrates with Asterisk/FreePBX using Audiosocket/RTP technology
PythonMIT创建于 2025/9/5更新于 昨天
README
由 Gemini 翻译整理
这是目前最强大、最灵活的开源 Asterisk/FreePBX AI 语音代理项目。它采用了模块化流水线架构，允许用户自由组合 STT（语音转文字）、LLM（大语言模型）和 TTS（文字转语音）供应商，并附带了 6 个经过企业级部署验证的黄金基准配置（golden baselines）。
快速开始 • 特性 • 路线图 • 演示 • 文档 • 社区
📖 目录
- 🚀 快速开始
- 🎉 新功能
- 🌟 为什么选择 Asterisk AI Voice Agent？
- ✨ 特性
- 🎥 演示
- 🛠️ AI 驱动的操作
- 🩺 代理 CLI 工具
- ⚙️ 配置
- 🏗️ 项目架构
- 📊 要求
- 🗺️ 文档
- 🤝 贡献
- 💬 社区
- 📝 许可协议
🚀 快速开始
只需 2 分钟即可运行 管理 UI (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. 启动管理 UI
# 启动管理 UI 容器
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui
3. 访问仪表板
在浏览器中打开：
- 本地：
http://localhost:3003 - 远程服务器：
http://<服务器IP>:3003
默认登录信息： admin / admin
按照 设置向导 配置你的服务提供商并进行测试通话。
⚠️ 安全警告： 管理 UI 可通过网络访问。请立即更改默认密码，并在生产环境中使用防火墙、VPN 或反向代理来限制 3003 端口的访问。
4. 验证安装
GPU 用户： 如果你有 NVIDIA GPU 用于本地 AI 推理，在构建前请查阅 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"}
# 查看错误日志
docker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20
5. 连接 Asterisk
向导将为你生成 Asterisk 服务器所需的拨号方案（dialplan）配置。
传输方式的选择取决于配置（并非严格的“流水线”与“全代理”之分）。请参考以下文档中的验证矩阵：
🔧 高级设置 (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为可选。如果未设置，引擎将遵循正常的优先级（上下文提供商 → 默认提供商）。AI_CONTEXT为可选。使用它可以更改问候语/角色，而无需更改默认提供商/流水线。- 有关通道变量优先级和示例，请参阅
docs/FreePBX-Integration-Guide.md。
测试你的代理
健康检查：
agent