AIRegulation/AIRegulation-DocAnalysis

Fork 0

Files

T

wangwei 52e67b0e7b Add LLM token

2026-07-02 22:03:39 +08:00

10 KiB

Raw Blame History

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

系统要求

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

一、环境准备

1. 克隆项目

git clone <project_url>
cd Demo-glm

2. 配置环境变量

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

# 编辑配置文件，填入API密钥
vim .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服务

cd docker
docker-compose up -d

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

2. 验证服务状态

docker ps

确认以下容器运行正常：

milvus - 向量数据库
minio - 对象存储
redis - 缓存服务
postgres - 关系数据库

三、安装Python依赖

方式A：使用统一初始化脚本（推荐）

chmod +x dev.sh
./dev.sh setup

脚本自动完成：

创建虚拟环境
安装依赖（使用阿里云镜像）
检查各服务连接状态

方式B：手动安装

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

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

四、配置解析与 embedding

当前主链路不再依赖本地 BGE-M3 模型文件，必须配置：

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

五、启动服务

统一命令入口（推荐）

# 赋予脚本执行权限
chmod +x dev.sh

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

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

# 重启所有服务
./dev.sh restart

# 停止所有服务
./dev.sh stop

单独启动（可选）

# 仅启动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. 上传文档测试

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

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

2. 下载文档测试

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

3. 检索测试

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

3. 智能问答测试

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

4. 多轮对话测试

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

十、服务状态检查

运行状态检查脚本：

./dev.sh status

输出示例：

========================================
  AI+合规智能中枢 - 服务状态
========================================

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

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

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

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

十一、常见问题

Q1: Milvus连接失败

# 检查Milvus状态
docker logs milvus

# 重启Milvus
docker restart milvus

# 等待30秒后再启动服务

Q2: 模型下载慢/失败

使用ModelScope镜像：

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

或手动下载：

当前版本无需下载本地 BGE-M3 模型；请改为确认 `EMBEDDING_API_KEY` 与阿里云文档解析凭据已配置。

Q3: LLM调用失败

检查 .env 中API密钥配置：

# 验证配置
cat .env | grep API_KEY

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

Q4: 端口被占用

修改 .env 中的端口配置：

API_PORT=8001
FRONTEND_PORT=3001

Q5: 服务无法停止

强制清理：

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

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

十二、目录结构

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/chat/stream`	POST	标准流式问答 (SSE)
Agentic 流式对话	`/api/v1/agent/agentic/stream`	POST	P0-1 多步推理 (SSE)：意图分析→查询分解→迭代检索→引文锚定→生成
会话信息	`/api/v1/agent/session/{id}`	GET	获取会话
删除会话	`/api/v1/agent/session/{id}`	DELETE	删除会话
会话历史	`/api/v1/agent/session/{id}/history`	GET	获取历史记录
会话列表	`/api/v1/agent/sessions`	GET	列出所有会话

Agentic 流式接口说明 (`/api/v1/agent/agentic/stream`)

请求体 (同 /agent/chat/stream)：

{ "query": "GB 18384 与 ECE R100 在电池安全上有哪些差异？", "session_id": null, "top_k": 5 }

额外 SSE 事件 (thinking)：

event: thinking
data: {"step": "intent_analysis", "status": "done", "intent_type": "compare", "requires_decomposition": true}

event: thinking
data: {"step": "query_planning", "status": "done", "sub_queries": ["GB 18384 电池安全要求", "ECE R100 电池安全要求"]}

event: thinking
data: {"step": "retrieving", "status": "done", "query": "GB 18384 电池安全要求", "index": 1, "total": 2, "found": 8}

event: thinking
data: {"step": "grounding_check", "status": "done", "sufficient": true, "confidence": 0.82, "reason": "检索置信度充足"}

意图类型：simple_qa（单跳）/ compare（对比）/ multi_hop（多跳）/ ambiguous（模糊）

十三、支持的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到项目仓库

10 KiB Raw Blame History Unescape Escape