AIRegulation-DocAnalysis/QUICK_DEPLOY.md

# AI+合规智能中枢 - 快速部署指南

## 系统要求

- Python 3.10+
- Docker & Docker Compose
- 8GB+ 内存（推荐16GB）
- 20GB+ 磁盘空间

---

## 一、环境准备

### 1. 克隆项目

```bash
git clone <project_url>
cd Demo-glm
```

### 2. 配置环境变量

```bash
# 复制配置模板
cp .env.example .env

# 编辑配置文件，填入API密钥
vim .env
```

**必填配置项**：

```env
# LLM配置（使用统一API代理）
LLM_PROVIDER=qwen
LLM_MODEL=qwen3.5-plus

# API密钥（通过 new-api.fletcher0516.online 代理）
QWEN_API_KEY=your_api_key_here
DEEPSEEK_API_KEY=your_api_key_here
QWEN_BASE_URL=https://new-api.fletcher0516.online/v1
DEEPSEEK_BASE_URL=https://new-api.fletcher0516.online/v1
```

---

## 二、启动基础设施

### 1. 启动Docker服务

```bash
cd docker
docker-compose up -d
```

等待服务启动完成（约30秒）。

### 2. 验证服务状态

```bash
docker ps
```

确认以下容器运行正常：
- `milvus` - 向量数据库
- `minio` - 对象存储
- `redis` - 缓存服务
- `postgres` - 关系数据库

---

## 三、安装Python依赖

### 方式A：使用快速启动脚本（推荐）

```bash
chmod +x quick_start.sh
./quick_start.sh
```

脚本自动完成：
- 创建虚拟环境
- 安装依赖（使用阿里云镜像）
- 检查各服务连接状态

### 方式B：手动安装

```bash
# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

---

## 四、下载嵌入模型

BGE-M3模型约2GB，首次使用需下载。

### 方式A：自动下载（联网环境）

首次启动API时自动下载到 `~/.cache/huggingface/`

### 方式B：手动下载（离线环境）

```bash
# 从ModelScope下载
python -c "from modelscope import snapshot_download; snapshot_download('Xorbits/bge-m3', cache_dir='~/.cache/modelscope')"
```

---

## 五、启动服务

### 整合启动脚本（推荐）

```bash
# 赋予脚本执行权限
chmod +x start_all.sh stop_all.sh restart_all.sh status.sh

# 启动所有服务（API + 前端）
./start_all.sh

# 查看服务状态
./status.sh

# 重启所有服务
./restart_all.sh

# 停止所有服务
./stop_all.sh
```

### 单独启动（可选）

```bash
# 仅启动API服务（前台运行，可调试）
./start_api.sh

# 仅启动API服务（后台运行）
./start_api_background.sh

# 仅停止API服务
./stop_api.sh

# 仅启动前端服务
./start_frontend.sh
```

---

## 六、服务访问地址

启动成功后访问：

| 服务 | 地址 |
|------|------|
| **API服务** | http://localhost:8000 |
| **API文档** | http://localhost:8000/docs |
| **健康检查** | http://localhost:8000/health |
| **前端测试页面** | http://localhost:3000 |

> 注意：前端测试页面通过 `http://localhost:3000` 访问，自动连接到API服务。

---

## 七、功能测试

### 1. 上传文档测试

```bash
curl -X POST http://localhost:8000/api/v1/documents/upload \
  -F "file=@test.pdf" \
  -F "doc_name=测试文档"
```

文档上传后会自动存储到MinIO对象存储（bucket: upload-files）。

### 2. 下载文档测试

```bash
# 下载已上传的文档
curl -O http://localhost:8000/api/v1/documents/download/{doc_id}
```

### 3. 检索测试

```bash
curl -X POST http://localhost:8000/api/v1/knowledge/search \
  -H "Content-Type: application/json" \
  -d '{"query": "机动车安全", "top_k": 10}'
```

### 3. 智能问答测试

```bash
curl -X POST http://localhost:8000/api/v1/agent/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "机动车安全技术检验有哪些要求？"}'
```

### 4. 多轮对话测试

```bash
curl -X POST http://localhost:8000/api/v1/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "什么是机动车安全技术检验？"}'

# 返回 session_id，继续对话
curl -X POST http://localhost:8000/api/v1/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "检验周期是多久？", "session_id": "<session_id>"}'
```

---

## 八、脚本命令速查表

| 操作 | 命令 |
|------|------|
| **启动所有服务** | `./start_all.sh` |
| **停止所有服务** | `./stop_all.sh` |
| **重启所有服务** | `./restart_all.sh` |
| **查看服务状态** | `./status.sh` |
| 查看API日志 | `tail -f logs/api.log` |
| 查看前端日志 | `tail -f logs/frontend.log` |
| 环境初始化 | `./quick_start.sh` |
| 重启Docker | `cd docker && docker-compose restart` |
| 下载嵌入模型 | `./download_model.sh` |

---

## 九、服务状态检查

运行状态检查脚本：

```bash
./status.sh
```

输出示例：
```
========================================
  AI+合规智能中枢 - 服务状态
========================================

API服务:
  状态:   运行中 ✓
  PID:    12345
  健康检查: 正常 ✓
  地址:    http://localhost:8000

前端服务:
  状态:   运行中 ✓
  PID:    12346
  地址:    http://localhost:3000

Docker服务:
  milvus:  运行中 ✓
  minio:   运行中 ✓
  redis:   运行中 ✓
  postgres: 运行中 ✓

========================================
  所有服务正常运行 ✓
========================================
```

---

## 十、常见问题

### Q1: Milvus连接失败

```bash
# 检查Milvus状态
docker logs milvus

# 重启Milvus
docker restart milvus

# 等待30秒后再启动服务
```

### Q2: 模型下载慢/失败

使用ModelScope镜像：

```bash
export HF_ENDPOINT=https://hf-mirror.com
```

或手动下载：
```bash
python -c "from modelscope import snapshot_download; snapshot_download('Xorbits/bge-m3')"
```

### Q3: LLM调用失败

检查 `.env` 中API密钥配置：

```bash
# 验证配置
cat .env | grep API_KEY

# 确保base_url正确
cat .env | grep BASE_URL
```

### Q4: 端口被占用

修改 `.env` 中的端口配置：

```env
API_PORT=8001
FRONTEND_PORT=3001
```

### Q5: 服务无法停止

强制清理：

```bash
# 查找并停止所有相关进程
pkill -f uvicorn
pkill -f http.server

# 清理PID文件
rm -f logs/*.pid
```

---

## 十一、目录结构

```
Demo-glm/
├── src/
│   ├── api/              # FastAPI接口
│   │   ├── main.py       # API入口
│   │   └── routes/
│   │       ├── documents.py    # 文档上传
│   │       ├── knowledge.py    # 知识检索
│   │       └── agent.py        # 智能问答
│   ├── services/         # 核心服务
│   │   ├── llm/          # LLM调用（Qwen/DeepSeek）
│   │   ├── rag/          # RAG检索
│   │   ├── agent/        # 问答Agent
│   │   ├── parser/       # 文档解析
│   │   ├── embedding/    # 向量嵌入（BGE-M3）
│   │   └── storage/      # Milvus存储
│   └── config/           # 配置管理
├── frontend/             # 前端测试页面
│   └── index.html        # 测试界面
├── docker/               # Docker配置
│   └── docker-compose.yml
├── logs/                 # 运行日志
│   ├── api.log
│   └── frontend.log
├── tests/                # 测试脚本
├── .env                  # 环境配置
├── .env.example          # 配置模板
├── requirements.txt      # Python依赖
├── quick_start.sh        # 环境初始化脚本
├── start_all.sh          # 整合启动脚本
├── stop_all.sh           # 整合停止脚本
├── restart_all.sh        # 重启脚本
├── status.sh             # 状态检查脚本
├── start_api.sh          # 单独启动API
├── start_frontend.sh     # 单独启动前端
└── QUICK_DEPLOY.md       # 本文档
```

---

## 十二、API接口清单

| 接口 | 路径 | 方法 | 功能 |
|------|------|------|------|
| 上传文档 | `/api/v1/documents/upload` | POST | 上传PDF/DOCX |
| 下载文档 | `/api/v1/documents/download/{doc_id}` | GET | 下载原文PDF/DOCX |
| 文档列表 | `/api/v1/documents/list` | GET | 列出已上传文档 |
| 检索知识 | `/api/v1/knowledge/search` | POST | 向量检索 |
| 单次问答 | `/api/v1/agent/ask` | POST | 智能问答 |
| 多轮对话 | `/api/v1/agent/chat` | POST | 会话对话 |
| 会话信息 | `/api/v1/agent/session/{id}` | GET | 获取会话 |
| 删除会话 | `/api/v1/agent/session/{id}` | DELETE | 删除会话 |
| Prompt模板 | `/api/v1/agent/templates` | GET | 模板列表 |
| 可用模型 | `/api/v1/agent/models` | GET | LLM模型列表 |

---

## 十三、支持的LLM模型

通过统一API代理 `https://new-api.fletcher0516.online/v1` 支持：

**Qwen系列**：
- `qwen3.5-plus` (推荐)
- `qwen3-plus`
- `qwen-max`
- `qwen-turbo`
- `qwen-long`

**Qwen VL系列**（多模态）：
- `qwen3-vl-plus`
- `qwen-vl-max`

**DeepSeek系列**：
- `deepseek-v3.2` (推荐)
- `deepseek-v3`
- `deepseek-chat`
- `deepseek-coder`

---

## 技术支持

- API文档：http://localhost:8000/docs
- 问题反馈：提交Issue到项目仓库