AIRegulation-Demo-Test-Backend/README.md

# 车辆法规智能检索系统 - 后端 API

基于 FastAPI + LangGraph + Milvus + 千问大模型 的法规检索与合规分析后端服务。

## 目录

- [技术栈](#技术栈)
- [服务依赖](#服务依赖)
- [快速开始](#快速开始)
- [环境配置](#环境配置)
- [API 接口文档](#api-接口文档)
- [项目结构](#项目结构)
- [核心模块详解](#核心模块详解)
- [工作流设计](#工作流设计)
- [数据模型](#数据模型)

## 技术栈

| 组件 | 技术选型 | 说明 |
|------|----------|------|
| Web框架 | FastAPI | 高性能异步 API 框架 |
| AI框架 | LangGraph | 状态图工作流编排 |
| LLM | 千问 Qwen-Max | 阿里云 DashScope API |
| Embedding | text-embedding-v3 | DashScope 文本向量服务 |
| 向量数据库 | Milvus | 开源高性能向量检索引擎 |
| 关系数据库 | PostgreSQL | 数据持久化存储 |
| 缓存 | Redis | 会话缓存与任务队列 |
| 图数据库 | Neo4j | 法规关系图谱存储 |
| 消息队列 | RabbitMQ | 异步任务处理 |

## 服务依赖

需要启动以下基础服务：

| 服务 | 端口 | 用户/密码 |
|------|------|-----------|
| PostgreSQL | 5432 | postgresql/postgresql123456 |
| Redis | 6379 | redis@123 |
| Milvus | 19530, 9091 | - |
| MinIO | 9000, 9001 | minioadmin/minioadmin |
| Neo4j | 7474, 7687 | neo4j/neo4j123 |
| RabbitMQ | 5672, 15672 | admin/admin@123 |

## 快速开始

### 1. 安装依赖

```bash
cd backend
uv pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件，配置各项服务参数
```

### 3. 启动服务

```bash
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 4. 访问 API 文档

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 环境配置

`.env` 文件配置项：

```bash
# DashScope API（LLM 与 Embedding）
DASHSCOPE_API_KEY=your_api_key_here
LLM_MODEL=qwen-max
EMBEDDING_MODEL=text-embedding-v3
EMBEDDING_DIM=1536

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgresql
POSTGRES_PASSWORD=postgresql123456
POSTGRES_DB=mydb

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=redis@123

# Milvus
MILVUS_HOST=localhost
MILVUS_PORT=19530

# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=neo4j123

# RabbitMQ
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USER=admin
RABBITMQ_PASSWORD=admin@123

# 检索配置
VECTOR_TOP_K=10
BM25_TOP_K=10
FINAL_TOP_K=5

# 分块配置
CHUNK_SIZE=800
CHUNK_OVERLAP=50

# 服务配置
API_HOST=0.0.0.0
API_PORT=8000
```

## API 接口文档

### 1. 文档管理 `/api/docs`

| 接口 | 方法 | 说明 |
|------|------|------|
| `/upload` | POST | 上传法规文档 (PDF/DOCX/TXT) |
| `/list` | GET | 获取已索引文档列表 |
| `/parse/{doc_id}` | POST | 解析文档并分块 |
| `/embed/{doc_id}` | POST | 向量化并存入 Milvus |
| `/delete/{doc_id}` | DELETE | 删除文档 |

**上传文档响应示例：**
```json
{
  "doc_id": "doc-001",
  "filename": "道路交通安全法.pdf",
  "size": 102400,
  "status": "uploaded"
}
```

### 2. RAG 问答 `/api/rag`

| 接口 | 方法 | 说明 |
|------|------|------|
| `/chat` | POST | SSE 流式问答 |
| `/quick-questions` | GET | 获取预设快捷问题 |

**请求参数：**
```json
{
  "query": "电动自行车需要上牌照吗？",
  "top_k": 5
}
```

**SSE 事件流格式：**
```json
{"type": "retrieving"}
{"type": "retrieved", "docs": [...]}
{"type": "generating", "text": "正在生成答案..."}
{"type": "chunk", "text": "答案片段..."}
{"type": "done"}
```

### 3. 合规分析 `/api/compliance`

| 接口 | 方法 | 说明 |
|------|------|------|
| `/analyze` | POST | 上传设计方案进行分析 |
| `/result/{task_id}` | GET | 获取分析结果 |
| `/chat/{segment_id}` | POST | 针对特定段落进行合规对话 |

**分析结果响应示例：**
```json
{
  "task_id": "task-xxx",
  "dashboard": {
    "score": 78,
    "high_risk_count": 2,
    "medium_risk_count": 1,
    "low_risk_count": 0,
    "need_fix_segments": 3,
    "status": "warning",
    "status_label": "需优化"
  },
  "segments": [
    {
      "id": 1,
      "intent": "车身结构设计",
      "content": "...",
      "risk_level": "high",
      "regulations": [...]
    }
  ],
  "priority_actions": [...]
}
```

### 4. 系统状态 `/api/status`

| 接口 | 方法 | 说明 |
|------|------|------|
| `/stats` | GET | 系统统计数据 |
| `/config` | GET | 当前配置信息 |
| `/milvus/health` | GET | Milvus 健康检查 |

**统计数据响应：**
```json
{
  "docs": 5,
  "chunks": 510,
  "vectors": 510,
  "segments": 0
}
```

## 项目结构

```
backend/
├── app/
│   ├── main.py                 # FastAPI 应用入口
│   ├── core/
│   │   └── config.py           # Pydantic Settings 配置管理
│   ├── api/
│   │   ├── __init__.py         # API 路由聚合
│   │   └── routes/
│   │       ├── docs.py         # 文档管理接口
│   │       ├── rag.py          # RAG 问答接口
│   │       ├── compliance.py   # 合规分析接口
│   │       └── status.py       # 系统状态接口
│   ├── schemas/
│   │   ├── doc.py              # 文档相关数据模型
│   │   ├── rag.py              # RAG 问答数据模型
│   │   └── compliance.py       # 合规分析数据模型
│   ├── services/
│   │   ├── llm.py              # LLM 服务封装
│   │   ├── embedding.py        # Embedding 服务封装
│   │   ├── milvus.py           # Milvus 向量库服务
│   │   ├── document.py         # 文档解析服务
│   │   └── mock_data.py        # Mock 数据（开发测试）
│   ├── workflows/
│   │   ├── rag_workflow.py     # RAG 工作流
│   │   └── compliance_workflow.py  # 合规分析工作流
│   └── utils/
│       ├── chunking.py         # 文本分块工具
│       └── logger.py           # 日志工具
├── data/
│   ├── raw/                    # 原始上传文件
│   └── parsed/                 # 解析后文件
├── tests/                      # 测试目录
├── .env                        # 环境变量配置
├── .env.example                # 环境变量示例
├── requirements.txt            # Python 依赖
├── pyproject.toml              # 项目配置
└── main.py                     # 入口脚本
```

## 核心模块详解

### 配置管理 (`app/core/config.py`)

使用 Pydantic Settings 管理配置，自动从 `.env` 文件加载：

```python
class Settings(BaseSettings):
    dashscope_api_key: str = ""
    milvus_host: str = "localhost"
    milvus_port: int = 19530
    llm_model: str = "qwen-max"
    embedding_model: str = "text-embedding-v3"
    embedding_dim: int = 1536
    # ...
    
    class Config:
        env_file = ".env"
```

### 服务层 (`app/services/`)

#### LLM 服务 (`llm.py`)
- 封装 DashScope API 调用
- 支持流式输出
- 提供对话补全功能

#### Embedding 服务 (`embedding.py`)
- 文本向量化
- 批量嵌入支持
- 维度配置 (1536)

#### Milvus 服务 (`milvus.py`)
- Collection 创建与管理
- 向量插入与检索
- 混合检索 (向量 + BM25)

#### Mock 数据服务 (`mock_data.py`)
- 预设法规文档数据
- 预设问答数据
- 预设合规分析结果
- 用于开发测试阶段

## 工作流设计

### RAG 工作流 (`rag_workflow.py`)

基于 LangGraph 构建的状态图工作流：

```
[用户查询] -> [检索向量库] -> [BM25补充] -> [结果融合] -> [LLM生成] -> [输出答案]
```

### 合规分析工作流 (`compliance_workflow.py`)

```
[上传文档] -> [解析文档] -> [AI语义分段] -> [法规匹配] -> [风险评分] -> [生成建议]
```

状态节点：
- `parse`: 解析文档提取文本
- `segment`: AI 识别语义段落
- `match`: 向量检索匹配法规
- `score`: 计算风险等级
- `suggest`: 生成优先修改建议

## 数据模型

### 文档模型 (`schemas/doc.py`)

| 模型 | 字段 | 说明 |
|------|------|------|
| DocumentUploadResponse | doc_id, filename, size, status | 上传响应 |
| DocumentInfo | id, name, chunks, status, created_at | 文档信息 |
| DocumentListResponse | docs | 文档列表 |
| ParseResponse | doc_id, chunks, status | 解析响应 |
| EmbedResponse | doc_id, vectors, status | 嵌入响应 |

### RAG 模型 (`schemas/rag.py`)

| 模型 | 字段 | 说明 |
|------|------|------|
| RagChatRequest | query, top_k | 问答请求 |
| RetrievedDoc | id, doc_name, clause_id, score, content, preview | 检索文档 |
| QuickQuestion | id, question, category | 快捷问题 |
| QuickQuestionsResponse | questions | 快捷问题列表 |

### 合规模型 (`schemas/compliance.py`)

| 模型 | 字段 | 说明 |
|------|------|------|
| Regulation | id, name, clause, score, match_keyword, category, full_content | 法规条目 |
| ComplianceSegment | id, index, intent, content, risk_level, regulations | 语义段落 |
| RiskDashboard | score, high_risk_count, medium_risk_count, low_risk_count, status | 风险仪表盘 |
| PriorityAction | regulation, issue, suggestion, severity | 优先建议 |
| ComplianceResult | task_id, dashboard, segments, priority_actions | 分析结果 |

### 风险等级枚举

```python
class RiskLevel(str, Enum):
    high = "high"      # 高风险：需立即修改
    medium = "medium"  # 中风险：建议优化
    low = "low"        # 低风险：基本合规
```

### 合规状态枚举

```python
class ComplianceStatus(str, Enum):
    pass_status = "pass"    # 合规通过
    warning = "warning"     # 需要优化
    fail = "fail"           # 不合规
```

## 开发说明

### Mock 模式

当依赖服务未安装或 API Key 未配置时，系统自动使用 Mock 数据模式，返回预设的测试数据，便于前端开发调试。

### SSE 流式输出

使用 `sse-starlette` 库实现 Server-Sent Events 流式响应，适用于：
- RAG 问答实时输出
- 合规对话实时响应

### CORS 配置

已配置允许所有来源的跨域请求，生产环境需根据实际需求调整。

```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

## 测试

```bash
pytest tests/
```

## 许可证

MIT