---

📖 目次

• 🚀 クイックスタート
• 🎉 新機能
• 🌟 なぜAsterisk AI音声エージェントなのか？
• ✨ 機能
• 🎥 デモ
• 🛠️ AI駆動アクション
• 🩺 エージェントCLIツール
• ⚙️ 設定
• 🏗️ プロジェクトアーキテクチャ
• 📊 必要条件
• 🗺️ ドキュメント
• 🤝 貢献
• 💬 コミュニティ
• 📝 ライセンス

---

🚀 クイックスタート

管理UIを2分で起動しましょう。

完全な初回通話成功までの手順（ダイヤルプラン + トランスポート選択 + 検証）については、以下をご参照ください：

• インストールガイド
• トランスポート互換性

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://<server-ip>:3003

デフォルトログイン: admin / admin

セットアップウィザードに従ってプロバイダーを設定し、テスト通話をかけてみてください。

⚠️ セキュリティ： 管理UIはネットワーク上でアクセス可能です。デフォルトパスワードを直ちに変更し、本番環境ではファイアウォール、VPN、またはリバースプロキシを使用してポート3003へのアクセスを制限してください。

4. インストールの確認

GPUユーザー： 地方でのAI推論にNVIDIA GPUをお持ちの場合、ビルド前にGPU用のComposeオーバーレイ（docker-compose.gpu.yml）を適用するための手順は、docs/LOCAL_ONLY_SETUP.md をご参照ください。

# 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サーバー用の必要なダイヤルプラン設定を生成します。

トランスポートの選択は構成依存であり、「パイプライン対フルエージェント」という単純な区分ではありません。有効なマトリックスについては以下をご参照ください：

• docs/Transport-Mode-Compatibility.md

---

🔧 高度なセットアップ（CLI）

コマンドラインを好むユーザー、またはヘッドレスでのセットアップが必要な場合にご利用ください。

オプション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 check

ログの確認：

docker compose -p asterisk-ai-voice-agent logs -f ai_engine

---

🎉 v6.4.1の新機能

最新の更新内容

⚡ CPU遅延最適化 — ストリーミングLLM→TTSオーバーラップ（v6.4.1）

• 文単位のストリーミング: LLMトークンは文の区切りで分割され、各文が即座に合成・再生されます。これにより、全体の応答を待つ必要がなくなり、パイプライン構成では体感遅延が3〜10秒から2秒未満へ短縮されます。
• パイプラインフィラーオーディオ: LLMが思考を始める前に、エージェント自身の声で「少々お待ちください」などの即時応答フレーズが再生されます。フレーズは管理UIでカスタマイズ可能です。
• CPU推奨モデルとしてQwen 2.5-1.5B Instruct: 新しい940MBのモデルはCPU上で約15〜30トークン/秒の処理速度を実現します（Phi-3は約0.8トークン/秒）。セットアップウィザードでは「⚡ CPU推奨」バッジが自動的に表示されます。
• PCMからµ-lawへの直接変換: 全5つのTTSバックエンドで一時的なWAVファイルのやり取りが不要になり、応答ごとに10〜50ミリ秒の時間短縮が可能になりました。
• プレフライトの強化: Buildx検出、RAM/ディスク/ネットワークチェック、GPUインストールは--apply-fixesオプションに限定され、すべてのランタイムポートが検証済みです。

📞 已参与转接流媒体与筛选（v6.4.0）

• 三种筛选模式：basic_tts（来电者ID播报）、ai_briefing（实验性AI对话摘要）、caller_recording（录制来电者自报姓名/事由）
• 流媒体传输：ExternalMedia RTP助手消除了转接提示音对外部共享存储的依赖
• 供应商无关工具引导：动态向LLM提供商暴露已配置的转接目标，防止出现幻觉扩展名
• 在线坐席UI：重新设计了紧凑布局，并支持自动轮询以检查坐席可用性

🗣️ 俄语语音后端（v6.4.0）

• Sherpa离线STT：基于VAD门控的离线转换器模式，采用Silero VAD、可配置阈值、预滚动填充及调试诊断功能。设置SHERPA_MODEL_TYPE=offline即可启用。
• T-one STT：原生俄语电信ASR，使用流式CTC流水线结合束搜索/贪婪解码。需添加--build-arg INCLUDE_TONE=true参数。
• Silero TTS：多语言TTS（俄语、英语、德语、西班牙语、法语、乌克兰语），提供原生8kHz电信输出和多种发音人选择。需添加--build-arg INCLUDE_SILERO=true参数。

🎧 管理员UI（v6.4.0）

• 全屏面板：系统拓扑、通话统计和通话历史可切换最大化/最小化，并支持Esc键操作
• 对话时间戳：通话记录UI中每条消息均显示时间戳，并对LLM负载进行净化处理
• HTTP工具通配符：JSONPath [*]数组提取现可在输出变量中正确工作

之前在v6.3.2中的内容

• Microsoft Azure语音服务STT与TTS管道适配器
• MiniMax LLM M2.7通过OpenAI兼容API
• 管理员UI中的通话录音回放
• Azure SSRF防范措施、PII日志记录规范

完整发布说明请参阅CHANGELOG.md。

以前的版本

v6.3.1 - 本地AI服务器与安全机制

• 后端启用/重建流程、模型生命周期用户体验、GPU操作便捷性、CPU优先入门流程
• 结构化的本地工具网关、挂断安全机制、工具调用解析稳健性
• agent check --local / --remote CLI验证命令

v6.1.1 - 呼叫中心配置与在线坐席转接

• 呼叫中心配置覆盖文件（ai-agent.local.yaml）、在线坐席转接工具
• ViciDial兼容性、Admin UI中的Asterisk配置发现功能
• OpenAI Realtime GA API、邮件系统全面升级、NAT/GPU支持

v5.3.1 - 阶段性工具与稳定性

• 呼叫前HTTP查询、呼叫中HTTP工具以及呼叫后Webhook（里程碑24）
• Deepgram Voice Agent语言配置
• ExternalMedia RTP问候语截断修复

v4.4.3 - 跨平台支持

• 🌍 预检脚本：系统兼容性检查工具，带自动修复模式。
• 🔧 管理员UI修复：模型页面、提供商页面、仪表盘改进。
• 🛠️ 开发者体验：代码拆分、ESLint + Prettier集成。

v4.4.2 - 本地AI增强

• 🎤 新STT后端：Kroko ASR、Sherpa-ONNX。
• 🔊 Kokoro TTS：高质量神经网络TTS。
• 🔄 模型管理：可通过仪表盘动态切换后端。
• 📚 文档：新增LOCAL_ONLY_SETUP.md指南。

v4.4.1 - 管理员UI

• 🖥️ 管理员UI：现代化Web界面（http://localhost:3003）。
• 🎙️ ElevenLabs对话式AI：优质音质提供商。
• 🎵 背景音乐：AI通话期间播放环境音乐。

v4.3 - 完整工具支持与文档更新

• 🔧 完整工具支持：适用于所有类型的管道。
• 📚 文档全面更新：结构重新组织。
• 💬 Discord社区：官方服务器整合。

v4.2 - Google Live API与增强安装

• 🤖 Google Live API：Gemini 2.0 Flash集成。
• 🚀 交互式安装：agent init向导（同时保留agent quickstart以保持向后兼容性）。

v4.1 - 工具调用与Agent CLI

• 🔧 工具调用系统：转接电话、发送邮件。
• 🩺 Agent CLI工具：doctor、troubleshoot、demo。

---

🌟 为什么选择Asterisk AI语音代理？

特性	优势
Asterisk原生	直接与您现有的Asterisk/FreePBX配合使用——无需外部电信运营商。
真正的开源	MIT许可证，完全透明且可控。
模块化架构	可选择云端、本地或混合部署——根据需要灵活搭配不同提供商。
生产就绪	经过实战检验的基础配置，以通话历史为先的调试方式。
经济高效	本地混合部署的成本约为0.001–0.003美元/分钟（仅LLM费用）。
隐私优先	在使用云端智能的同时，将音频数据保留在本地。

---

✨ 功能

6种黄金基准配置

1. OpenAI实时（推荐快速入门）

   • 现代云端AI，实现自然流畅的对话（响应时间小于2秒）。
   • 配置文件：config/ai-agent.golden-openai.yaml
   • 最适合：企业级部署、快速搭建。

2. Deepgram Voice Agent（企业级云服务）

   • 先进的思考阶段，适用于复杂推理任务（响应时间小于3秒）。
   • 配置文件：config/ai-agent.golden-deepgram.yaml
   • 最适合：Deepgram生态系统、高级功能。

3. Google Live API（多模态AI）

   • Gemini Live（Flash）具备多模态能力（响应时间小于2秒）。
   • 配置文件：config/ai-agent.golden-google-live.yaml
   • 最适合：Google生态系统、高级AI功能。

4. ElevenLabs Agent（优质音质）

   • ElevenLabs对话式AI，提供高品质语音（响应时间小于2秒）。
   • 配置文件：config/ai-agent.golden-elevenlabs.yaml
   • 最适合：注重音质、追求自然对话体验。

5. 本地混合（隐私导向）

   • 本地STT/TTS结合云端LLM（OpenAI），音频全程本地保存。
   • 配置文件：config/ai-agent.golden-local-hybrid.yaml
   • 最适合：保护音频隐私、控制成本、满足合规要求。

6. Telnyx AI推理（经济高效多模型）

   • 本地STT/TTS结合Telnyx LLM，支持53+种模型（GPT-4o、Claude、Llama等）。
   • OpenAI兼容API，价格极具竞争力。
   • 配置文件：config/ai-agent.golden-telnyx.yaml
   • 最适合：模型灵活性、成本优化、多供应商接入。

其他LLM提供商

• MiniMax LLM（高性能、高性价比）
  • 本地STT/TTS结合MiniMax M2.7 LLM，具备更强的推理与编码能力。
  • OpenAI兼容API，支持工具调用功能。
  • 模型包括：MiniMax-M2.7（默认，最新旗舰版）、MiniMax-M2.7-highspeed（低延迟版）、MiniMax-M2.5、MiniMax-M2.5-highspeed。
  • 激活方法：在.env文件中设置MINIMAX_API_KEY，然后在config/ai-agent.yaml中配置providers.minimax_llm（确保minimax_llm部分的enabled: true）。
  • 最适合：长上下文对话、高性价比高性能LLM。

完全本地（可选）

AVA 还支持完全本地模式（100% 本地部署，不使用云 API）。支持三种拓扑结构：

拓扑	延迟	适用场景
仅 CPU	5-15秒/轮次	隐私保护、测试
GPU（同一台机器）	0.5-2秒/轮次	本地生产环境
分体式服务器（远程 GPU）	1-3秒/轮次	PBX 部署在 VPS 上 + GPU 专用机

GPU 设置使用带有 CUDA 支持的 docker-compose.gpu.yml 覆盖层与 llama.cpp 结合。社区验证：RTX 4090 可实现约 1.0 秒的端到端延迟。

• 查看：docs/LOCAL_ONLY_SETUP.md（所有本地拓扑的官方指南）
• 硬件建议：docs/HARDWARE_REQUIREMENTS.md

🏠 自托管 LLM 与 Ollama（无需 API 密钥）

使用 Ollama 运行您自己的本地 LLM——非常适合注重隐私的部署场景：

# 在 ai-agent.yaml 中
active_pipeline: local_hybrid
pipelines:
  local_hybrid:
    stt: local_stt
    llm: ollama_llm
    tts: local_tts

功能：

• 无需 API 密钥——完全自托管于您的网络中
• 工具调用支持，适用于兼容模型（Llama 3.2、Mistral、Qwen）
• 本地 Vosk STT + 您的 Ollama LLM + 本地 Piper TTS
• 完全隐私——所有处理均在本地完成

要求：

• Mac Mini、游戏 PC 或已安装 Ollama 的服务器
• 8GB+ 内存（推荐 16GB+ 以运行更大模型）
• 请参阅 docs/OLLAMA_SETUP.md 获取设置指南

推荐模型：

模型	大小	工具调用
llama3.2	2GB	✅ 是
mistral	4GB	✅ 是
qwen2.5	4.7GB	✅ 是

技术特性

• 工具调用系统：AI 驱动的操作（转接、发送邮件）适用于任何提供商。
• Agent CLI 工具：包括 setup、check、rca、update、version 等命令（旧别名：init、doctor、troubleshoot）。
• 模块化管道系统：独立选择 STT、LLM 和 TTS 提供商。
• 双传输支持：AudioSocket（默认配置在 config/ai-agent.yaml 中）和 ExternalMedia RTP（两者均支持——详见传输矩阵）。
• 流媒体优先下游：尽可能采用流媒体播放，并自动回退至文件播放以提高可靠性。
• 高性能架构：分离 ai_engine 和 local_ai_server 容器。
• 可观测性：内置通话历史记录用于逐通调试，以及可选的 /metrics 数据抓取。
• 状态管理：SessionStore 提供集中式、类型化的通话状态管理。
• 打断支持：可配置门控的中断处理机制。

🖥️ 管理 UI

现代化的 Web 界面，用于配置和系统管理。

快速入门：

docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui
# 访问地址：http://localhost:3003
# 默认登录：admin / admin（请立即修改！）

主要功能：

• 设置向导：可视化提供商配置。
• 仪表盘：实时系统指标、容器状态及 Asterisk 连接指示。
• Asterisk 设置：ARI 状态实时显示、模块检查清单、带指导修复命令的配置审计。
• 实时日志：基于 WebSocket 的日志流。
• YAML 编辑器：基于 Monaco 的编辑器，具备验证功能。

---

🎥 演示视频

📞 现场试用！（仅限美国）

只需一个电话，即可体验我们已投入生产的配置：

拨打：(925) 736-6718

• 按 5 → Google Live API（多模态 AI，结合 Gemini 2.0）
• 按 6 → Deepgram Voice Agent（企业级云端服务，包含 Think 阶段）
• 按 7 → OpenAI Realtime API（现代云端 AI，最自然）
• 按 8 → 本地混合管道（注重隐私，音频全程本地处理）
• 按 9 → ElevenLabs Agent（圣诞老人语音，配有背景音乐）
• 按 10 → 完全本地管道（100% 本地部署，基于 CPU）

---

🛠️ AI 驱动的操作

您的 AI 代理可通过工具调用执行真实的电话操作。

统一呼叫转接

来电者：“请帮我转接到销售团队”
客服：“我马上为您转接至销售团队。”
[转接至销售队列，并播放队列音乐]

支持的目标：

• 分机：直接 SIP/PJSIP 端点转接。
• 队列：ACD 队列转接，并播报等待位置。
• 振铃组：多个座席同时振铃。

呼叫控制与语音信箱

• 取消转接：“其实，取消刚才的转接吧”（在振铃过程中）。
• 挂断电话：以礼貌告别结束通话。
• 语音信箱：将呼叫转至语音信箱。

邮件集成

• 自动通话摘要：管理员会收到完整的通话记录和元数据。
• 来电者请求通话记录：“请把这次通话的记录发给我。”

工具	描述	状态
transfer	转接至分机、队列或振铃组	✅
cancel_transfer	取消正在进行的转接（振铃期间）	✅
hangup_call	优雅地结束通话并致以告别	✅
leave_voicemail	将呼叫者转至语音信箱	✅
send_email_summary	自动将通话摘要发送给管理员	⚙️ 默认关闭
request_transcript	来电者主动请求发送通话记录	⚙️ 默认关闭

HTTP 工具（呼叫前/中/后）示例

# 在 ai-agent.yaml 中
tools:
  pre_call_lookup:
    kind: generic_http_lookup
    phase: pre_call
    enabled: true
    is_global: false
  post_call_webhook:
    kind: generic_webhook
    phase: post_call
    enabled: true
    is_global: false

in_call_tools:
  intent_router:
    kind: in_call_http_lookup
    enabled: true
    is_global: false

contexts:
  default:
    pre_call_tools:
      - pre_call_lookup
    tools:
      - intent_router
      - hangup_call
    post_call_tools:
      - post_call_webhook

---

🩺 Agent CLI 工具

专为运维和部署设计的生产就绪 CLI。

安装：

curl -sSL https://raw.githubusercontent.com/hkjarral/Asterisk-AI-Voice-Agent/main/scripts/install-cli.sh | bash

命令：

agent setup               # 交互式设置向导（推荐）
agent check               # 标准诊断报告（寻求帮助时可分享此输出）
agent check --local       # 验证本机上的本地 AI 服务器（STT、LLM、TTS）
agent check --remote <ip> # 验证远程 GPU 机器上的本地 AI 服务器
agent update              # 拉取最新代码并根据需要重建/重启
agent rca --call <call_id> # 通话后根本原因分析（使用通话历史查找 call_id）
agent version             # 版本信息

---

⚙ 配置

三文件配置

• config/ai-agent.yaml - 黄金基准配置（已加入 Git 跟踪，由上游维护）。
• config/ai-agent.local.yaml - 运维人员覆盖配置（被 .gitignore 忽略）。启动时，此处的所有键值会与基础文件进行深度合并；所有 Admin UI 和 CLI 的写入操作都会保存到这里，因此上游更新不会产生冲突。
• .env - 秘密信息和 API 密钥（被 .gitignore 忽略）。

.env 示例：

OPENAI_API_KEY=sk-your-key-here
DEEPGRAM_API_KEY=your-key-here
ASTERISK_ARI_USERNAME=asterisk
ASTERISK_ARI_PASSWORD=your-password

可选：指标监控（自建 Prometheus）

引擎在 http://<engine-host>:15000/metrics 暴露 Prometheus 格式的指标。 每次通话的调试可通过 Admin UI → Call History 进行。

---

🏗 项目架构

采用双容器架构以提升性能和可扩展性：

1. ai_engine（轻量级编排器）：通过 ARI 连接 Asterisk，管理通话生命周期。
2. local_ai_server（可选）：运行本地 STT/LLM/TTS 模型（Vosk、Faster Whisper、Whisper.cpp、Sherpa、Kroko、Piper、Kokoro、MeloTTS、llama.cpp）。

graph LR
    A[Asterisk Server] <-->|ARI, RTP| B[ai_engine]
    B <-->|API| C[AI Provider]
    B <-->|WS| D[local_ai_server]
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#bfb,stroke:#333,stroke-width:2px
    style D fill:#fbf,stroke:#333,stroke-width:2px

---

📊 系统要求

平台要求

要求	详情
架构	仅支持 x86_64 (AMD64)
操作系统	带有 systemd 的 Linux
支持的发行版	Ubuntu 20.04+、Debian 11+、RHEL/Rocky/Alma 8+、Fedora 38+、Sangoma Linux

注意： 目前不支持 ARM64（Apple Silicon、Raspberry Pi）。完整兼容性矩阵请参阅 Supported Platforms。

最低系统要求

类型	CPU	内存	GPU	磁盘
云端（OpenAI/Deepgram）	2 核以上	4GB	无	1GB
本地混合（云端 LLM）	4 核以上	8GB+	无	2GB
全本地（CPU）	4 核以上（2020 年及以上型号）	8-16GB	无	5GB
全本地（GPU）	4 核以上	8-16GB	RTX 3060+	10GB

软件要求

• Docker + Docker Compose v2
• 启用了 ARI 的 Asterisk 18+
• FreePBX（推荐）或原生 Asterisk

预检自动化

preflight.sh 脚本负责初始设置：

• 根据 .env.example 文件填充 .env，并结合您的设置；
• 提示您输入 Asterisk 配置目录的位置；
• 设置 ASTERISK_UID/ASTERISK_GID 以匹配主机权限（解决媒体访问问题）；
• 重复运行预检脚本通常可以解决权限问题。

---

🗺 文档

入门指南

• 文档索引
• FreePBX 集成指南
• 安装指南

配置与运维

• 配置参考
• 传输模式兼容性
• 调优方案
• 支持平台
• 本地配置文件
• 监控指南

开发与社区

• 路线图 - 下一步计划、里程碑及参与方式
• 开发者文档
• 架构深度解析
• 贡献指南
• 里程碑历史 - 已完成的 1-24 个里程碑

---

🤝 贡献方式

您无需具备编程知识。 我们的 AI 助手 AVA 会为您编写代码——只需描述您想构建的内容即可。

🚀 三步开始贡献

git clone -b develop https://github.com/hkjarral/Asterisk-AI-Voice-Agent.git
cd Asterisk-AI-Voice-Agent
./scripts/setup-contributor.sh

然后在 Windsurf 中打开项目，并输入：“我想贡献”

📖 指南

指南	适用人群
运营人员贡献指南	第一次贡献者（无需 GitHub 经验）
贡献指南	完整的贡献指南和工作流程
编码规范	所有贡献的代码标准
路线图	下一步要做的工作（13+ 项适合初学者的任务）

🔧 构建新功能

领域	指南	模板
完整代理提供者	指南	模板
流水线适配器（STT/LLM/TTS）	指南	模板
通话前钩子	指南	模板
通话中钩子	指南	模板
通话后钩子	指南	模板

👩‍💻 针对开发者

• 开发者入职指南 - 项目概述及首批任务
• 开发者快速入门 - 搭建开发环境
• 开发者文档 - 完整的贡献者文档

贡献者

hkjarral 架构、代码	Abhishek Telnyx LLM 提供商	turgutguvercin NumPy 重采样器	Scarjit 代码	egorky Azure STT/TTS 提供商
alemstrom 文档 — PBX 设置	gcsuri 代码 — Google 日历	octo-patch MiniMax LLM 提供商	neilruaro-camb CAMB AI TTS 提供商	aoi-dev-0411 转录搜索、健康徽章

完整贡献者列表请参阅 CONTRIBUTORS.md，关于我们如何认可贡献，请查看 表彰计划。

---

💬 社区

• Discord 服务器 - 支持与讨论
• GitHub Issues - 错误报告
• GitHub Discussions - 通用交流

---

📝 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

---

💖 支持本项目

Asterisk AI 语音代理是 免费且开源 的。如果它为您节省了成本，不妨考虑支持开发：

您的支持将用于：

• 🐛 更快地修复错误和响应问题
• ✨ 新的提供商集成和功能
• 📚 更完善的文档和教程

如果您觉得本项目有用，请为它点亮一颗星 ⭐️！

星标历史

AVA-AI-Voice-Agent-for-Asterisk 快速上手指南

AVA 是一款专为 Asterisk/FreePBX 设计的开源 AI 语音代理工具。它采用模块化架构，支持灵活组合 STT（语音转文本）、LLM（大语言模型）和 TTS（文本转语音）提供商，并提供多种经过企业级验证的配置方案。

环境准备

在开始之前，请确保您的服务器满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+/Debian 11+)
• 电话系统: Asterisk 18+ 或 FreePBX
• Python: 3.11+
• 容器环境: Docker 和 Docker Compose
• 硬件资源:
  • CPU 模式: 至少 2 核 CPU，4GB 内存（推荐使用 Qwen 2.5-1.5B 等轻量模型）。
  • GPU 模式 (可选): 如需本地运行大型模型，需配备 NVIDIA GPU 并安装 NVIDIA Container Toolkit。
• 网络: 服务器需能访问外部 API（如 OpenAI, Google, Deepgram 等），若在国内部署，建议配置科学上网或替换为国内兼容的 API 端点。

安装步骤

1. 克隆项目并运行预检脚本

预检脚本会自动创建 .env 配置文件并生成安全的 JWT_SECRET，这是启动前的必要步骤。

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

# 运行预检脚本（自动修复环境并生成配置）
sudo ./preflight.sh --apply-fixes

注意: 如果您拥有 NVIDIA GPU 并希望进行本地 AI 推理，请在构建前参考 docs/LOCAL_ONLY_SETUP.md 启用 GPU 覆盖配置 (docker-compose.gpu.yml)。

2. 启动管理后台 (Admin UI)

使用 Docker Compose 启动管理界面容器：

docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui

3. 启动 AI 引擎

AI 引擎是核心服务，必须运行才能处理呼叫逻辑：

docker compose -p asterisk-ai-voice-agent up -d --build ai_engine

4. 验证安装

检查 AI 引擎健康状态：

curl http://localhost:15000/health
# 预期输出：{"status":"healthy"}

查看日志确认无报错：

docker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20

基本使用

1. 访问管理后台

在浏览器中打开以下地址：

• 本地访问: http://localhost:3003
• 远程访问: http://<服务器 IP>:3003

默认登录凭据:

• 用户名: admin
• 密码: admin

⚠️ 安全警告: 首次登录后请立即修改默认密码。在生产环境中，请通过防火墙、VPN 或反向代理限制对 3003 端口的访问。

2. 配置向导

登录后的 Setup Wizard 将引导您完成以下操作：

1. 选择并配置您的服务提供商（如 OpenAI, Google, Azure 或本地模型）。
2. 生成适用于您 Asterisk 环境的拨号计划（Dialplan）配置。
3. 进行测试呼叫验证。

3. 集成 Asterisk

根据向导生成的配置，将其添加到您的 FreePBX (extensions_custom.conf) 或 Asterisk 拨号计划中。以下是一个基础示例：

[from-ai-agent]
exten => s,1,NoOp(Asterisk AI Voice Agent)
; 可选：指定特定的提供商或上下文
; same => n,Set(AI_PROVIDER=google_live)
; same => n,Set(AI_CONTEXT=sales-agent)
same => n,Stasis(asterisk-ai-voice-agent)
same => n,Hangup()

配置完成后，重载 Asterisk 配置即可生效：

asterisk -rx "core reload"

4. 发起测试呼叫

拨打您配置了上述拨号计划的分机号码，即可与 AI 语音代理进行对话。您可以在管理后台的 Call History 或 Live Agents 面板中实时监控呼叫状态和日志。