30c7bda389
- Removed multiple failed document entries from `documents.json`. - Added a new document entry with updated metadata and changed the index name to `regulations_dense_1024_v2`. - Updated architecture documentation to reflect changes in the Milvus collection name. - Adjusted requirements by removing the sqlalchemy dependency. - Modified test cases to align with new document structure and naming conventions. - Introduced a new test file for Milvus vector index runtime recovery and error handling. - Updated assertions in various test files to ensure compatibility with the new schema.
429 lines
9.2 KiB
Markdown
429 lines
9.2 KiB
Markdown
# 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 dev.sh
|
||
./dev.sh setup
|
||
```
|
||
|
||
脚本自动完成：
|
||
- 创建虚拟环境
|
||
- 安装依赖（使用阿里云镜像）
|
||
- 检查各服务连接状态
|
||
|
||
### 方式B：手动安装
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
|
||
# 安装依赖
|
||
pip install -r backend/requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 四、配置解析与 embedding
|
||
|
||
当前主链路不再依赖本地 BGE-M3 模型文件，必须配置：
|
||
|
||
```env
|
||
ALIBABA_ACCESS_KEY_ID=your_aliyun_access_key_id
|
||
ALIBABA_ACCESS_KEY_SECRET=your_aliyun_access_key_secret
|
||
EMBEDDING_API_KEY=your_embedding_api_key_here
|
||
EMBEDDING_MODEL=text-embedding-v3
|
||
EMBEDDING_DIM=1024
|
||
PARSER_BACKEND=aliyun
|
||
CHUNK_BACKEND=aliyun
|
||
PARSER_FAILURE_MODE=fail
|
||
```
|
||
|
||
---
|
||
|
||
## 五、启动服务
|
||
|
||
### 统一命令入口（推荐）
|
||
|
||
```bash
|
||
# 赋予脚本执行权限
|
||
chmod +x dev.sh
|
||
|
||
# 启动所有服务（API + 前端）
|
||
./dev.sh start
|
||
|
||
# 查看服务状态
|
||
./dev.sh status
|
||
|
||
# 重启所有服务
|
||
./dev.sh restart
|
||
|
||
# 停止所有服务
|
||
./dev.sh stop
|
||
```
|
||
|
||
### 单独启动（可选）
|
||
|
||
```bash
|
||
# 仅启动API服务（前台运行，可调试）
|
||
./dev.sh start api --foreground
|
||
|
||
# 仅启动API服务（后台运行）
|
||
./dev.sh start api
|
||
|
||
# 仅停止API服务
|
||
./dev.sh stop api
|
||
|
||
# 仅启动前端服务（Vite 开发模式）
|
||
./dev.sh start frontend --mode dev
|
||
|
||
# 仅启动前端服务（静态构建模式）
|
||
./dev.sh start frontend --mode static
|
||
```
|
||
|
||
---
|
||
|
||
## 六、服务访问地址
|
||
|
||
启动成功后访问：
|
||
|
||
| 服务 | 地址 |
|
||
|------|------|
|
||
| **API服务** | http://localhost:8000 |
|
||
| **API文档** | http://localhost:8000/docs |
|
||
| **健康检查** | http://localhost:8000/health |
|
||
| **前端测试页面** | http://localhost:5173 |
|
||
|
||
> 注意：前端默认通过 `http://localhost:5173` 访问，自动代理到 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>"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 八、脚本命令速查表
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| **启动所有服务** | `./dev.sh start` |
|
||
| **停止所有服务** | `./dev.sh stop` |
|
||
| **重启所有服务** | `./dev.sh restart` |
|
||
| **查看服务状态** | `./dev.sh status` |
|
||
| 查看API日志 | `tail -f logs/api.log` |
|
||
| 查看前端日志 | `tail -f logs/frontend.log` |
|
||
| 环境初始化 | `./dev.sh setup` |
|
||
| 前台调试 API | `./dev.sh start api --foreground` |
|
||
| 静态模式启动前端 | `./dev.sh start frontend --mode static` |
|
||
| 重启Docker | `cd docker && docker-compose restart` |
|
||
| 下载嵌入模型 | `./download_model.sh` |
|
||
|
||
---
|
||
|
||
## 九、Linux / Windows 命令对照表
|
||
|
||
| 操作 | Linux / macOS | Windows |
|
||
|------|---------------|---------|
|
||
| 环境初始化 | `./dev.sh setup` | `dev.bat setup` |
|
||
| 启动所有服务 | `./dev.sh start` | `dev.bat start` |
|
||
| 停止所有服务 | `./dev.sh stop` | `dev.bat stop` |
|
||
| 重启所有服务 | `./dev.sh restart` | `dev.bat restart` |
|
||
| 查看服务状态 | `./dev.sh status` | `dev.bat status` |
|
||
| 前台调试 API | `./dev.sh start api --foreground` | `dev.bat start api --foreground` |
|
||
| 后台启动 API | `./dev.sh start api` | `dev.bat start api` |
|
||
| 启动前端开发模式 | `./dev.sh start frontend --mode dev` | `dev.bat start frontend --mode dev` |
|
||
| 启动前端静态模式 | `./dev.sh start frontend --mode static` | `dev.bat start frontend --mode static` |
|
||
| 查看 API 日志 | `./dev.sh logs api --follow` | `dev.bat logs api --follow` |
|
||
| 查看前端日志 | `./dev.sh logs frontend --follow` | `dev.bat logs frontend --follow` |
|
||
|
||
> Linux / macOS 首次使用前建议先执行：`chmod +x dev.sh`
|
||
|
||
---
|
||
|
||
## 十、服务状态检查
|
||
|
||
运行状态检查脚本：
|
||
|
||
```bash
|
||
./dev.sh status
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
========================================
|
||
AI+合规智能中枢 - 服务状态
|
||
========================================
|
||
|
||
API服务:
|
||
状态: 运行中 ✓
|
||
PID: 12345
|
||
健康检查: 正常 ✓
|
||
地址: http://localhost:8000
|
||
|
||
前端服务:
|
||
状态: 运行中 ✓
|
||
PID: 12346
|
||
地址: http://localhost:5173
|
||
|
||
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
|
||
当前版本无需下载本地 BGE-M3 模型；请改为确认 `EMBEDDING_API_KEY` 与阿里云文档解析凭据已配置。
|
||
```
|
||
|
||
### 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
|
||
```
|
||
|
||
---
|
||
|
||
## 十二、目录结构
|
||
|
||
```text
|
||
Demo-glm/
|
||
├── backend/
|
||
│ ├── app/ # FastAPI 后端代码
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ └── main.py # 后端启动入口
|
||
├── frontend/ # Vite React 前端
|
||
├── docker/ # Docker 配置
|
||
│ └── docker-compose.yml
|
||
├── logs/ # 运行日志
|
||
├── tests/ # 根级测试脚本
|
||
├── .env # 环境配置
|
||
├── .env.example # 配置模板
|
||
├── pyproject.toml # 根级 Python 项目配置
|
||
├── dev.sh # Linux/macOS 统一入口
|
||
├── dev.bat # Windows 统一入口
|
||
└── 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到项目仓库
|