ai-robot-core/README.md

# 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 多向量、两阶段检索。

#### 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