295 lines
9.2 KiB
Markdown
295 lines
9.2 KiB
Markdown
# AI Robot Core
|
||
|
||
AI中台业务的能力支撑，提供智能客服、RAG知识库检索、LLM对话等核心能力。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ai-robot-core/
|
||
├── ai-service/ # Python 后端服务
|
||
│ ├── app/ # FastAPI 应用
|
||
│ ├── tests/ # 测试用例
|
||
│ ├── Dockerfile # 后端镜像
|
||
│ └── pyproject.toml # Python 依赖
|
||
├── ai-service-admin/ # Vue 前端管理界面
|
||
│ ├── src/ # Vue 源码
|
||
│ ├── Dockerfile # 前端镜像
|
||
│ ├── nginx.conf # Nginx 配置
|
||
│ └── package.json # Node 依赖
|
||
├── docker-compose.yaml # 容器编排
|
||
├── .env.example # 环境变量示例
|
||
└── README.md
|
||
```
|
||
|
||
## 功能特性
|
||
|
||
- **多租户支持**: 通过 X-Tenant-Id 头实现租户隔离
|
||
- **RAG 知识库**: 基于 Qdrant 的向量检索增强生成
|
||
- **LLM 集成**: 支持 OpenAI、DeepSeek、Ollama 等多种 LLM 提供商
|
||
- **SSE 流式输出**: 支持 Server-Sent Events 实时响应
|
||
- **置信度评估**: 自动评估回复质量，低置信度时建议转人工
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Docker 20.10+
|
||
- Docker Compose 2.0+
|
||
|
||
### 部署步骤
|
||
|
||
#### 1. 克隆代码
|
||
|
||
```bash
|
||
git clone http://49.232.209.156:3005/MerCry/ai-robot-core.git
|
||
cd ai-robot-core
|
||
```
|
||
|
||
#### 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件，配置 LLM API：
|
||
|
||
```env
|
||
# OpenAI 配置
|
||
AI_SERVICE_LLM_PROVIDER=openai
|
||
AI_SERVICE_LLM_API_KEY=your-openai-api-key
|
||
AI_SERVICE_LLM_BASE_URL=https://api.openai.com/v1
|
||
AI_SERVICE_LLM_MODEL=gpt-4o-mini
|
||
|
||
# 或使用 DeepSeek
|
||
# AI_SERVICE_LLM_PROVIDER=deepseek
|
||
# AI_SERVICE_LLM_API_KEY=your-deepseek-api-key
|
||
# AI_SERVICE_LLM_MODEL=deepseek-chat
|
||
```
|
||
|
||
#### 3. 启动服务
|
||
|
||
```bash
|
||
# Docker Compose V2 (推荐，Docker 内置)
|
||
docker compose up -d --build
|
||
|
||
# 或 Docker Compose V1 (旧版，需要单独安装)
|
||
docker-compose up -d --build
|
||
```
|
||
|
||
#### 4. 拉取嵌入模型
|
||
|
||
服务启动后，需要在 Ollama 容器中拉取嵌入模型。推荐使用 `nomic-embed-text-v2-moe`，对中文支持更好：
|
||
|
||
```bash
|
||
# 进入 Ollama 容器拉取模型
|
||
docker exec -it ai-ollama ollama pull toshk0/nomic-embed-text-v2-moe:Q6_K
|
||
```
|
||
|
||
**可选模型**：
|
||
|
||
| 模型 | 维度 | 说明 |
|
||
|------|------|------|
|
||
| `toshk0/nomic-embed-text-v2-moe:Q6_K` | 768 | 推荐，中文支持好，支持任务前缀 |
|
||
| `nomic-embed-text:v1.5` | 768 | 原版，支持任务前缀和 Matryoshka |
|
||
| `bge-large-zh` | 1024 | 中文专用，效果最好 |
|
||
|
||
#### 5. 配置嵌入模型
|
||
|
||
访问前端管理界面，进入 **嵌入模型配置** 页面：
|
||
|
||
1. 选择提供者：**Nomic Embed (优化版)**
|
||
2. 配置参数：
|
||
- **API 地址**：`http://ollama:11434`（Docker 环境）或 `http://localhost:11434`（本地开发）
|
||
- **模型名称**：`toshk0/nomic-embed-text-v2-moe:Q6_K`
|
||
- **向量维度**：`768`
|
||
- **Matryoshka 截断**：`true`
|
||
3. 点击 **保存配置**
|
||
|
||
> **注意**:
|
||
> - 使用 Nomic Embed (优化版) provider 可启用完整的 RAG 优化功能：任务前缀、Matryoshka 多向量、两阶段检索。
|
||
> - 嵌入模型配置会持久化保存到 `ai-service/config/embedding_config.json`，服务重启后自动加载。
|
||
> - **重要**: 切换嵌入模型后，需要删除现有知识库并重新上传文档，因为不同模型生成的向量不兼容。
|
||
|
||
#### 6. 验证服务
|
||
|
||
```bash
|
||
# 检查服务状态
|
||
docker compose ps
|
||
|
||
# 查看后端日志，找到自动生成的 API Key
|
||
docker compose logs -f ai-service | grep "Default API Key"
|
||
```
|
||
|
||
> **重要**: 后端首次启动时会自动生成一个默认 API Key，请从日志中复制该 Key，用于前端配置。
|
||
|
||
#### 7. 配置前端 API Key
|
||
|
||
```bash
|
||
# 创建前端环境变量文件
|
||
cd ai-service-admin
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `ai-service-admin/.env`，将 `VITE_APP_API_KEY` 设置为后端日志中的 API Key：
|
||
|
||
```env
|
||
VITE_APP_BASE_API=/api
|
||
VITE_APP_API_KEY=<从后端日志复制的API Key>
|
||
```
|
||
|
||
然后重新构建前端：
|
||
|
||
```bash
|
||
cd ..
|
||
docker compose up -d --build ai-service-admin
|
||
```
|
||
|
||
#### 7. 访问服务
|
||
|
||
| 服务 | 地址 | 说明 |
|
||
|------|------|------|
|
||
| 前端管理界面 | http://服务器IP:8181 | Vue 管理后台 |
|
||
| 后端 API | http://服务器IP:8182 | FastAPI 服务（Java渠道侧调用） |
|
||
| API 文档 | http://服务器IP:8182/docs | Swagger UI |
|
||
| Qdrant 控制台 | http://服务器IP:6333/dashboard | 向量数据库管理 |
|
||
| Ollama API | http://服务器IP:11434 | 嵌入模型服务 |
|
||
|
||
> **端口说明**:
|
||
> - `8181`: 前端管理界面，内部代理后端 API
|
||
> - `8182`: 后端 API，供 Java 渠道侧直接调用
|
||
|
||
## 服务架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 用户访问 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ai-service-admin (端口8181) │
|
||
│ - Nginx 静态文件服务 │
|
||
│ - 反向代理 /api/* → ai-service:8080 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ai-service (端口8080) │
|
||
│ - FastAPI 后端服务 │
|
||
│ - RAG / LLM / 知识库管理 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||
│ PostgreSQL │ │ Qdrant │ │ Ollama │
|
||
│ (端口5432) │ │ (端口6333) │ │ (端口11434) │
|
||
│ - 会话存储 │ │ - 向量存储 │ │ - nomic-embed │
|
||
│ - 知识库元数据 │ │ - 文档索引 │ │ - 嵌入模型 │
|
||
└──────────────────┘ └──────────────────┘ └──────────────────┘
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
docker compose up -d
|
||
|
||
# 重新构建并启动
|
||
docker compose up -d --build
|
||
|
||
# 查看服务状态
|
||
docker compose ps
|
||
|
||
# 查看日志
|
||
docker compose logs -f ai-service
|
||
docker compose logs -f ai-service-admin
|
||
|
||
# 重启服务
|
||
docker compose restart ai-service
|
||
|
||
# 停止所有服务
|
||
docker compose down
|
||
|
||
# 停止并删除数据卷（清空数据）
|
||
docker compose down -v
|
||
```
|
||
|
||
## 宿主机 Nginx 配置（可选）
|
||
|
||
如果需要通过宿主机 Nginx 统一管理入口（配置域名、SSL证书），可参考 `deploy/nginx.conf.example`：
|
||
|
||
```bash
|
||
# 复制配置文件
|
||
sudo cp deploy/nginx.conf.example /etc/nginx/conf.d/ai-service.conf
|
||
|
||
# 修改配置中的域名
|
||
sudo vim /etc/nginx/conf.d/ai-service.conf
|
||
|
||
# 测试配置
|
||
sudo nginx -t
|
||
|
||
# 重载 Nginx
|
||
sudo nginx -s reload
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
### 后端开发
|
||
|
||
```bash
|
||
cd ai-service
|
||
|
||
# 创建虚拟环境
|
||
python -m venv .venv
|
||
source .venv/bin/activate # Linux/Mac
|
||
# .venv\Scripts\activate # Windows
|
||
|
||
# 安装依赖
|
||
pip install -e ".[dev]"
|
||
|
||
# 启动开发服务器
|
||
uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
cd ai-service-admin
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
## API 接口
|
||
|
||
### 核心接口
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/ai/chat` | POST | AI 对话接口 |
|
||
| `/admin/kb` | GET/POST | 知识库管理 |
|
||
| `/admin/rag/experiments/run` | POST | RAG 实验室 |
|
||
| `/admin/llm/config` | GET/PUT | LLM 配置 |
|
||
| `/admin/embedding/config` | GET/PUT | 嵌入模型配置 |
|
||
|
||
详细 API 文档请访问 http://服务器IP:8080/docs
|
||
|
||
## 环境变量说明
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| `AI_SERVICE_LLM_PROVIDER` | openai | LLM 提供商 |
|
||
| `AI_SERVICE_LLM_API_KEY` | - | API 密钥 |
|
||
| `AI_SERVICE_LLM_BASE_URL` | https://api.openai.com/v1 | API 地址 |
|
||
| `AI_SERVICE_LLM_MODEL` | gpt-4o-mini | 模型名称 |
|
||
| `AI_SERVICE_DATABASE_URL` | postgresql+asyncpg://... | 数据库连接 |
|
||
| `AI_SERVICE_QDRANT_URL` | http://qdrant:6333 | Qdrant 地址 |
|
||
| `AI_SERVICE_LOG_LEVEL` | INFO | 日志级别 |
|
||
|
||
## License
|
||
|
||
MIT
|