Echo 智能语音 AI-Agent 开放平台

项目简介

Echo是一个基于Python(FastAPI)后端和React前端的智能语音AI-Agent开放平台，支持语音全流程交互、意图识别、工具调用等功能��系统可集成MCP服务和各类HTTP API，实现丰富的技能服务。

主要特性

语音全流程交互：支持语音输入、意图识别、语音合成输出
多种工具集成：
- MCP服务集成（支持区块链、Web3等复杂场景）
- HTTP工具支持（Dify平台、Coze平台、通用HTTP API）
意图识别与确认：使用大语言模型(LLM)解析用户意图并生成确认提示
安全认证：JWT身份验证与权限管理
多轮对话管理：会话状态跟踪与上下文保持
日志与监控：详细操作记录，便于审计与排查

技术栈

后端：Python 3.9+, FastAPI, SQLAlchemy, Alembic, Pydantic
前端：React, Material UI, Web Speech API
数据库：MySQL
AI服务：兼容OpenAI API的LLM服务
认证：JWT
部署：Uvicorn, PM2

项目结构

project/
├── backend/               # 后端服务
│   ├── alembic/           # 数据库迁移
│   ├── app/               # 应用主目录
│   │   ├── clients/       # 第三方客户端封装
│   │   ├── controllers/   # 控制器
│   │   ├── models/        # 数据库模型
│   │   ├── routers/       # API路由
│   │   ├── schemas/       # 数据验证模型
│   │   ├── services/      # 业务逻辑
│   │   ├── utils/         # 工具函数
│   │   ├── config.py      # 配置管理
│   │   └── main.py        # 应用入口
│   ├── logs/              # 日志文件
│   ├── scripts/           # 辅助脚本
│   ├── tests/             # 测试代码
│   ├── .env.example       # 环境变量示例
│   └── requirements.txt   # 依赖包列表
├── frontend/              # 前端项目
│   ├── public/            # 静态资源
│   ├── src/               # 源代码
│   │   ├── components/    # UI组件
│   │   ├── contexts/      # React上下文
│   │   ├── hooks/         # 自定义钩子
│   │   ├── pages/         # 页面组件
│   │   ├── services/      # API服务
│   │   ├── styles/        # 样式文件
│   │   └── utils/         # 工具函数
│   └── package.json       # 依赖配置
├── MCP_Client/            # MCP客户端（Python）
│   ├── config/            # MCP配置
│   └── src/               # MCP客户端源码
├── docs/                  # 项目文档
├── logs/                  # 项目日志
└── .env.example           # 环境变量示例

安装与配置

依赖环境

Python 3.9+
Node.js 16+
MySQL 5.7+
(推荐)虚拟环境管理工具：venv, uv等

后端安装与配置

git clone <repo_url>
cd project/backend

创建并激活虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate  # Windows

安装依赖

pip install -r requirements.txt

配置环境变量

cp .env.example .env
# 编辑.env文件，设置数据库连接、API密钥等

配置环境变量

# 编辑.env文件，设置必要的配置项
vim .env

主要配置项包括：数据库连接、LLM API密钥、JWT密钥等。详细配置说明请参考：后端开发文档

数据库迁移

cd backend
alembic upgrade head

前端安装与配置

cd project/frontend

安装依赖

npm install

配置环境变量

cp .env.example .env
# 编辑.env文件，设置API路径等

MCP_Client 配置

cd project/MCP_Client

创建并激活虚拟环境

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate  # Windows

安装依赖

pip install openai python-dotenv
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

启动服务

启动后端服务

cd backend
# 开发模式（自动重载）
uvicorn app.main:app --reload --host 0.0.0.0 --port 3000

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 3000

使用PM2启动（生产环境推荐）

# 安装PM2 (需要Node.js)
npm install -g pm2

# 使用项目根目录的启动脚本
cd project
pm2 start ecosystem.config.js
# 或使用start-pm2.sh脚本
./start-pm2.sh

启动前端服务

# 开发模式（Mock数据，无需后端）
./start-frontend.sh start dev

# 生产模式（自动检测后端进程）
./start-frontend.sh start prod

# 查看状态和日志
./start-frontend.sh status
./start-frontend.sh logs

# 停止服务
./start-frontend.sh stop

# 查看帮助
./start-frontend.sh help

核心特性： 智能后端检测、自动端口分配、多模式启动、实时监控

直接启动MCP_Client（可选）

cd MCP_Client
# 启动并连接到指定MCP服务器
python src/mcp/client/main.py <path_to_server_script>

核心API接口

系统提供完整的RESTful API接口，支持意图解析、工具执行、用户认证等功能。

API基础路径: http://localhost:3000/api/v1
API文档: http://localhost:3000/docs (Swagger UI)
认证方式: JWT Bearer Token

详细的API接口说明请参考：前后端对接与API规范

支持的工具类型

系统支持两种主要类型的工具：

1. MCP工具

MCP (Model Context Protocol) 工具是基于自定义协议的脚本工具，能够执行区块链相关操作和其他复杂任务。

要求配置 server_name 字段，指向对应的MCP服务器
支持完整的参数传递和结果解析
集成了多种MCP服务器，如Playwright、MiniMax API、地图API和Web3区块链API

2. HTTP工具

HTTP工具允许系统调用外部HTTP API来执行操作。目前支持以下平台类型：

a. Dify

调用Dify平台上的AI应用
支持conversation_id管理
响应通过LLM总结，生成适合语音播报的内容

b. Coze

调用Coze平台上的机器人
要求在配置中提供bot_id
响应同样经过LLM总结处理

c. 通用HTTP

支持配置和调用任意HTTP API
支持GET, POST, PUT, PATCH, DELETE等多种HTTP方法
灵活配置头信息、认证方式（Bearer、ApiKey、Basic）
支持响应结果路径提取（使用result_path字段）
支持URL参数格式化和有效载荷配置
对响应结果进行LLM总结处理，生成简洁易懂的语音反馈

统一API架构

本项目采用了统一的API架构，提高了代码可维护性和一致性：

统一API入口
- 所有API请求通过统一的路由处理
- 标准化的请求/响应格式
- 版本化API设计 (如 /api/v1/...)

标准响应格式

{
  "status": "success|error|waiting",
  "data": { /* 响应数据 */ },
  "message": "操作结果描述",
  "timestamp": "2023-04-19T12:34:56.789Z"
}

开发指南

详细的开发指南请参考：

后端开发文档 - 后端开发者专用
前后端对接与API规范 - 前端开发者必读
前端开发文档 - 前端开发指南

测试与调试

运行测试

cd backend
pytest

API调试

Swagger UI: http://localhost:3000/docs
ReDoc: http://localhost:3000/redoc

贡献指南

Fork本仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送分支 (git push origin feature/amazing-feature)
创建Pull Request

更新日志

2025-05-14

实现通用HTTP API工具支持，包括多种HTTP方法、认证方式和结果处理
完善Dify和Coze平台工具的LLM结果总结功能
添加单元测试覆盖工具执行服务

2025-04-30

实现意图识别和工具执行的核心功能
完成MCP客户端集成，支持多种操作
添加基础认证系统

文档导航

前后端对接与API规范 - API接口详细说明和调用示例
后端开发文档 - 后端架构、服务和开发指南
前端开发文档 - 前端组件和开发规范

文档更新时间：2025-05-14

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
.trae/rules		.trae/rules
.venv		.venv
MCPTEST		MCPTEST
MCP_Client		MCP_Client
MCP_server		MCP_server
backend		backend
docs		docs
logs		logs
.gitignore		.gitignore
README.md		README.md
echo_ai_console.py		echo_ai_console.py
package-lock.json		package-lock.json
package.json		package.json
start-backend.sh		start-backend.sh
start-pm2.sh		start-pm2.sh
test-ci-clean.md		test-ci-clean.md
uv.lock		uv.lock

Sonny-cy/Demo_Echo_Backend

Folders and files

Latest commit

History

Repository files navigation