Asterisk AI语音代理 v3.0 这是一个开源的AI语音代理，通过Asterisk REST接口(ARI)与Asterisk/FreePBX集成。它采用生产就绪的双容器架构，具有混合ARI呼叫控制、SessionStore状态管理、ExternalMedia RTP集成，用于可靠的实时音频捕获，以及基于文件的TTS回放，确保稳健的对话处理。

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

这个项目旨在成为Asterisk最强大、最灵活、最易用的开源AI语音代理。以下是其特点：

• Asterisk原生：无需外部电话供应商。直接与您现有的Asterisk/FreePBX安装配合工作。 

• 真正开源：整个项目都是开源的(MIT许可)，为您提供完全的透明度和控制权。 

• 混合AI：在云端和本地AI提供商之间无缝切换，让您体验两者的最佳优势。 

• 生产就绪：这不仅是个演示，而是经过实战检验的生产就绪解决方案。 成本效益高：使用本地AI，您可以拥有可预测的成本，无需按分钟付费。

✨ 功能 

模块化AI提供商：轻松在云端和本地AI提供商之间切换

✅ Deepgram语音代理：完全实现，提供强大的基于云的解决方案。

✅ OpenAI实时功能：开箱即用——只需在.env文件中设置OPENAI_API_KEY并选择OpenAI模板/提供商。

✅ 本地AI服务器：专用容器运行本地模型(Vosk用于STT，Llama用于LLM，Piper用于TTS)，确保完全控制和隐私。

高性能架构：精简的ai-engine用于呼叫控制，独立的local-ai-server用于繁重的AI处理，确保稳定性和可扩展性。

混合ARI架构：使用ARI进行呼叫控制，采用"接听来电→创建混合桥→添加来电者→创建ExternalMedia并添加到桥"流程。

SessionStore状态管理：集中化、类型化的存储，用于所有呼叫会话状态，替代传统基于字典的状态管理。

实时通信：通过ARI指令的基于文件的回放，从Asterisk捕获ExternalMedia RTP上游；engine↔AI服务器使用WebSocket通信。

基于Docker的部署：使用Docker Compose进行简单的两服务编排。

可定制：在简单的YAML文件中配置问候语、AI角色和语音个性。

🚀 快速入门 按照这3个步骤获取工作正常的代理。

克隆并安装

git clone https://github.com/hkjarral/Asterisk-AI-Voice-Agent.git

cd Asterisk-AI-Voice-Agent

./install.sh

在提示时选择配置模板。安装程序将设置媒体路径符号链接，并可选择启动服务。

验证健康状况 curl http://127.0.0.1:15000/health 预期看到"audiosocket_listening": true。

FreePBX拨号计划(AudioSocket优先)：添加docs/FreePBX-Integration-Guide.md中的上下文(from-ai-agent等)，然后将测试呼叫路由到该上下文。 Hello World测试(可选，本地AI)：

python3 tests/test_local_ai_server_protocol.py # 在local-ai-server运行的情况下 应报告3/3测试通过。

OpenAI实时快速入门(仅云端) 如果您希望开箱即用OpenAI实时功能：

在./install.sh期间，在提示时选择OpenAI模板(它会将config/ai-agent.openai-agent.yaml写入config/ai-agent.yaml)。

在.env中添加您的API密钥：

echo "OPENAI_API_KEY=sk-..." >> .env

仅启动引擎(无需本地模型)：

docker-compose up -d ai-engine

按FreePBX指南中的说明路由测试呼叫。

先决条件

Asterisk 18+或FreePBX 15+，启用ARI。

已安装Docker和Docker Compose。

Git用于克隆存储库。

先决条件检查 验证必需的Asterisk模块已加载：

asterisk -rx "module show like res_ari_applications"

asterisk -rx "module show like app_audiosocket"

预期两者都显示Status: Running。如果Asterisk < 18，请升级或在FreePBX Distro上运行：asterisk-switch-version(又名asterisk-version-switch)以选择18+。

示例输出：

Module Description Use Count Status Support Level res_ari_applications.so RESTful API module - Stasis application 0 Running core 1 modules loaded

Module Description Use Count Status Support Level app_audiosocket.so AudioSocket Application 20 Running extended 1 modules loaded

Docker快速安装

Ubuntu(便捷脚本)：

curl -fsSL https://get.docker.com  | sudo sh sudo usermod -aG docker $USER && newgrp docker docker --version && docker compose version

CentOS/Rocky/Alma(仓库方法)：

sudo dnf -y install dnf-plugins-coresudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo dnf install -y docker-ce docker-ce-cli containerd.io sudo systemctl enable --now docker docker --version && docker compose version

安装 克隆存储库：

git clone https://github.com/hkjarral/Asterisk-AI-Voice-Agent.git

cd Asterisk-AI-Voice-Agent

运行安装程序(推荐)：

./install.sh

安装程序将：

验证Docker，检测Compose(docker-compose vs docker compose)。 运行Asterisk模块预检。 复制.env.example到.env(如果需要)并提示输入ARI和API密钥。 让您选择config/下的配置模板并写入config/ai-agent.yaml。 如果您选择本地/混合配置文件，会提供下载本地模型的选项。 可选择构建并启动堆栈。

如果您更喜欢手动设置，请按照下面的配置部分中的步骤操作。

启动服务(如果您没有让安装程序执行此操作)：

docker-compose up --build -d

这将启动ai-engine和local-ai-server。如果您只想使用像Deepgram这样的云提供商，可以只启动引擎：docker-compose up -d ai-engine。

⚙️ 配置 

系统通过config/ai-agent.yaml和.env文件进行配置(用于机密信息)。

规范的角色和问候语 代理问候语和角色的规范来源位于config/ai-agent.yaml的llm块中： llm.initial_greeting llm.prompt

运行时的优先级规则： 提供商或管道特定的覆盖(例如，providers.openai_realtime.instructions或providers.deepgram.greeting)如果明确设置 YAML中的llm.prompt和llm.initial_greeting 环境变量AI_ROLE和GREETING作为默认值

这确保所有提供商和管道保持一致，除非您有意按提供商/管道覆盖它们。

安装程序行为(GREETING/AI_ROLE) ./install.sh提示输入问候语和AI角色，并将它们写入.env。它还通过yq(Linux优先)更新config/ai-agent.yaml llm.*，或在无法安装yq时作为后备附加YAML llm块。 重新运行是幂等的：提示会从现有.env预填。 YAML中的${VAR}占位符继续受支持；加载器在运行时展开这些变量。

ai-agent.yaml关键设置：

default_provider: openai_realtime(整体后备；通过active_pipeline默认使用管道) asterisk: ARI连接详情。 providers: 每个AI提供商的特定配置。

完整的逐选项参考(包括推荐范围和影响)，请参见docs/Configuration-Reference.md。对于实用预设，请参见docs/Tuning-Recipes.md。

必需的.env变量： ASTERISK_ARI_USERNAME和ASTERISK_ARI_PASSWORD DEEPGRAM_API_KEY(如果使用Deepgram)

可选本地AI调优(通过环境变量设置) LOCAL_LLM_MODEL_PATH: 装入容器的替代GGUF文件的绝对路径。

LOCAL_LLM_MAX_TOKENS: 限制响应令牌数量(默认48，以获得更快回复)。

LOCAL_LLM_TEMPERATURE, LOCAL_LLM_TOP_P, LOCAL_LLM_REPEAT_PENALTY: TinyLlama运行时的采样控制。 LOCAL_LLM_THREADS, LOCAL_LLM_CONTEXT, LOCAL_LLM_BATCH: 高级性能调节；默认自动检测CPU核心并优先考虑延迟。 LOCAL_STT_MODEL_PATH, LOCAL_TTS_MODEL_PATH: 如果您在models/下预加载替代模型，则覆盖默认Vosk/Piper模型。

🏗️ 项目架构 

应用程序分为两个Docker容器，以提高性能和可扩展性

ai-engine: 轻量级服务，通过ARI连接到Asterisk，管理呼叫生命周期，并与AI提供商通信。 local-ai-server: 专用的强大服务，预加载并运行本地STT、LLM和TTS模型，通过WebSocket接口提供服务。

这种分离确保资源密集型AI模型不会影响ai-engine的实时呼叫处理性能。系统使用ExternalMedia RTP进行可靠的音频捕获，并使用基于文件的TTS回放进行稳健的对话处理。流式TTS计划作为未来的增强功能。

🎯 当前开发状态

✅ 生产就绪: 双向对话系统完美运行！

✅ 实时音频处理: 带SSRC映射的ExternalMedia RTP

✅ 状态管理: 基于SessionStore的集中状态管理

✅ TTS闸控: AI响应期间完美防止反馈

✅ 本地AI集成: Vosk STT、TinyLlama LLM、Piper TTS

✅ 对话流程: 完整的STT → LLM → TTS管道工作正常

✅ 架构验证: 重构代码库，关注点分离清晰

✅ 可观测性: ConversationCoordinator驱动/health + /metrics(Prometheus友好)