AVA-AI-Voice-Agent-for-Asterisk

给老式电话交换机装上大模型大脑，打电话也能自然对话

开源 unknown 自动化工作流

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1238

维护状态活跃

是否开源是

定价模式 unknown

项目预览

项目数据

分类自动化工作流

开发团队hkjarral

所属国家

官网地址https://operator.agent6789.com

GitHubhttps://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk

定价模式unknown

价格说明定价信息待确认

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型

GitHub 星标★ 1238

30天Star增速

HF 下载量

上线时间2025-09-05 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-12

浏览次数0

项目介绍

AVA 是一个开源的 AI 语音代理项目，目标是把大模型驱动的实时语音对话能力接入 Asterisk/FreePBX 这类传统电话交换机。它通过 Audiosocket、RTP 和 WebSocket 技术桥接电话语音流与 AI 服务，让企业无需更换现有 PBX 系统，就能为呼入/呼出电话加上智能语音应答、自然语言对话、意图理解和自动转接等能力。核心解决的是传统 IVR 只能按数字键、体验僵硬的问题，用语音识别+大模型+语音合成替代固定按键菜单。项目用 Python 编写，提供与 Asterisk 对接的完整链路，适合做智能客服、电话机器人、语音外呼等场景，部署在自有服务器上，数据可控。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：进阶约 15 分钟部署方式：Docker 6 步

环境要求

Linux 服务器并具备 sudo 权限（预检脚本需 sudo 运行）
已安装 Docker 与 docker compose（命令基于 docker compose）
已有一套 Asterisk/FreePBX 环境，并准备 ARI 用户名与密码
至少一个 AI 服务商的 API Key（OpenAI、Deepgram、Google、ElevenLabs、xAI 等）
如需本地推理，需具备 NVIDIA GPU 环境

安装与启动步骤

1运行预检脚本

这是官方标注必做的第一步，会自动创建 .env 文件并生成安全的 JWT_SECRET；不加 --apply-fixes 只做检查不修复。
```
sudo ./preflight.sh --apply-fixes
```
2填写密钥与账号

在生成的 .env 中填入所用服务商 API Key 及 Asterisk ARI 账号；该文件不入版本库。
3选择配置基线

从 7 个 golden 基线中挑一个，如 config/ai-agent.golden-openai.yaml（<2 秒响应，官方推荐快速开始）。
4运行交互式向导

CLI 用户可用向导完成服务商可视化配置；agent quickstart 作为向后兼容命令仍可继续使用。
```
agent init
```
5获取登录密码

Admin UI 启动后，从 admin_ui 容器日志里取一次性登录密码，compose 项目名固定为 asterisk-ai-voice-agent。
```
docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password
```
6验证首次通话

按官方 Installation Guide 完成拨号方案与传输方式选择并验证；GPU 用户构建前先看本地部署文档的 GPU compose overlay。

关键配置

配置项	必填	说明	示例
`OPENAI_API_KEY`	是	OpenAI Realtime 等基线所需的服务商密钥	`sk-your-key-here`
`DEEPGRAM_API_KEY`	否	使用 Deepgram Voice Agent 基线时填写	`your-key-here`
`ASTERISK_ARI_USERNAME`	是	Asterisk ARI 连接用户名	`asterisk`
`ASTERISK_ARI_PASSWORD`	是	Asterisk ARI 连接密码	`your-password`
`JWT_SECRET`	是	Admin UI 鉴权密钥，由预检脚本自动生成	`由 preflight.sh 自动生成`

如何确认成功

打开 Admin UI 的 Dashboard，确认容器状态与 Asterisk 连接指示灯正常，并能从日志中取到一次性密码。

常见问题

Q：可以跳过预检脚本直接启动吗？

A：不建议。README 将预检标明为 Required，它负责创建 .env 并生成 JWT_SECRET，跳过会导致后续配置缺失。

Q：忘记 Admin UI 登录密码怎么办？

A：执行 docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password 重新读取容器日志里的一次性密码。

Q：不知道该选哪个基线配置？

A：想快速上手选 OpenAI Realtime；重视音质选 ElevenLabs；重视音频隐私与成本选 Local Hybrid（本地 STT/TTS + 云端 LLM）。

Q：想用本地模型推理需要额外做什么？

A：需具备 NVIDIA GPU，并在构建前参考 docs/LOCAL_ONLY_SETUP.md 中的 docker-compose.gpu.yml 覆盖配置。

注意事项

配置分三层：ai-agent.yaml 为上游基线，ai-agent.local.yaml 存放运维覆盖（不入库），.env 存放密钥（不入库）
Admin UI 与 CLI 的写入都会落到 ai-agent.local.yaml，升级上游时不会冲突
WebSocket 传输为可选且需鉴权的模式，使用前需先确认服务商、编解码与拓扑是否匹配
AVA Core 保持 MIT 许可、免费且可独立完整运行；AVA Operator 是早期预览的多实例商业管理组件

核心亮点

直接对接 Asterisk/FreePBX，不用替换现有电话系统，改造成本低
同时支持 Audiosocket、RTP、WebSocket 多种语音流接入方式，适配灵活
Python 实现，便于二次开发和接入各家 ASR/LLM/TTS 服务

不足之处

依赖 Asterisk 环境，非电话场景用户上手门槛较高
实时语音链路涉及音频编解码与延迟调优，部署配置较复杂

适用场景

企业呼叫中心用 AI 语音客服替代传统按键 IVR
基于 FreePBX 的外呼营销或回访电话机器人
自建 PBX 的团队为电话系统增加自然语言对话能力

替代项目

Asterisk、FreeSWITCH、Vocode

上一篇：AVA

下一篇：loom