# RAG 泛化改造整合与运行说明

## 1. 交付范围

本源码包来自 `agent-management-rag` 工作分支，基线为本地 `master` 分支。交付包不包含 Git 历史、密钥、本地数据库、上传文件、日志、Python 虚拟环境、Node 依赖和 Java 构建产物。

主要新增页面：

- `/kb/rag`：多源 RAG 问答运行台。
- `/kb/rag-governance`：Schema 授权、生成规则和动态 Few-shot 治理台。

## 2. 相比 master 的主要改造

### 2.1 多源 RAG

- 新增统一的文档、结构化数据库和 Neo4j 图谱证据模型。
- 新增知识库及数据源绑定配置，支持按数据源独立启停和配置。
- 结构化数据与图谱检索并行执行，最终与 Milvus 文档证据融合。
- 新增 RAG 回答生成接口，回答只能依据检索证据。

### 2.2 Text-to-SQL 与 Text-to-Cypher

- 根据真实数据库 Schema 动态生成 SQL/Cypher，不再仅依赖固定模板。
- SQL 支持表白名单、表提示、业务文档、最大行数和动态 Few-shot。
- Cypher 支持 Label、Relationship、Property 白名单、最大深度和业务规则。
- 生成结果在 Java 侧执行只读安全校验。
- 自动生成的查询执行前先进行 `EXPLAIN`；失败时结合 Schema 和脱敏错误自动修复一次，再次失败则终止。

### 2.3 Schema 画像与语义目录

- 自动发现 MySQL/H2 等结构化数据库的 Table、Column 和类型。
- 自动发现 Neo4j 的 Label、Relationship、Property 及连接方向。
- 为表、Label 和 Relationship 建立向量语义目录。
- 大型 Schema 按问题语义裁剪；小型已授权 Schema 完整保留。
- Schema 画像带版本和缓存，可手动刷新。

### 2.4 RAG 治理

- 根据实际 Schema 和业务描述生成“建议开放的业务子图”。
- 治理结果统一为 `suggestedConfig` 和 `examples`：
  - `suggestedConfig` 回填授权表单，人工点击“应用”后才生效。
  - `examples` 导入后默认未审核，审核通过后才参与生成。
- 支持可视化审核 Table、Label、Relationship、Property 和生成规则。
- 授权区按 Label、Relationship、Table 树状折叠；加载时回显已保存配置，避免默认全选误扩大白名单。
- 支持动态 Few-shot 启用、停用和删除。
- 自动学习的成功查询默认未审核；损坏编码、明显乱码和写操作案例不会进入案例库。
- 仅把实际返回证据的自动查询纳入学习，0 行结构化结果不会生成 Few-shot。
- 模型建议在展示和应用前会再次与真实 Schema 取交集，空授权不能启用自动生成。
- LLM 治理建议超时时，按向量语义目录生成确定性草稿，避免页面长时间无响应。

### 2.5 问题规划与稳定性

- 根据已启用数据源自动拆解结构化数据和图谱子问题。
- SQL 与图谱任务使用独立线程池并行执行。
- RAG AI Bridge 设置短超时和无重试策略，失败时返回可见诊断。
- 修复 Milvus 稀疏向量兼容、文档索引与本地 Embedding Bridge 交互问题。

### 2.6 前端

- 新增多源 RAG 工作台、证据面板、过程状态和融合结果。
- 新增 RAG 治理中心和导航入口。
- 新增 Cytoscape 图谱结果展示及 Markdown 安全渲染依赖。

## 3. 环境要求

- Windows 10/11（当前脚本重点验证环境）
- Java 17
- Maven 3.6+
- Node.js 18+ 与 npm
- Python 3.10 或 3.11，建议使用独立虚拟环境
- Docker Desktop
- Milvus 2.5.5
- Neo4j 5 Community
- 一个 OpenAI 兼容的聊天模型接口

建议预留至少 8 GB 内存；首次启动本地 `BAAI/bge-m3` 会下载约 2 GB 模型文件。

## 4. 配置

### 4.1 Java 应用

复制：

```powershell
Copy-Item backend/src/main/resources/application.yml.example backend/src/main/resources/application.yml
```

至少检查这些环境变量：

```powershell
$env:OPENAI_API_KEY="你的模型密钥"
$env:JASYPT_KEY="生产环境随机密钥"
$env:EMBEDDING_BRIDGE_PYTHON_PATH="python"
$env:RAG_AI_BRIDGE_ENABLED="true"
```

`application.yml` 不应提交或在环境之间直接传播真实密钥。

### 4.2 RAG AI Bridge

复制示例配置：

```powershell
Copy-Item backend/rag-ai-bridge/.env.example backend/rag-ai-bridge/.env
Copy-Item backend/rag-ai-bridge/config.example.yaml backend/rag-ai-bridge/config.yaml
```

填写 `.env` 中的 `OPENAI_API_KEY`、`NEO4J_PASSWORD`，并按模型服务修改 `config.yaml` 的 `model` 和 `base_url`。

安装依赖：

```powershell
python -m pip install -r backend/rag-ai-bridge/requirements.txt
python -m pip install -r backend/embedding-bridge/requirements.txt
```

### 4.3 Milvus

`docker-compose.yml` 默认数据目录是 `F:/Services/milvus-2.5.5/volumes`。其他机器必须先覆盖：

```powershell
$env:MILVUS_DATA_DIR="D:/Services/milvus/volumes"
docker compose up -d
```

端口：`19530`（gRPC）、`9091`（管理/健康接口）。

### 4.4 Neo4j

Neo4j 独立部署，不由当前 `docker-compose.yml` 创建：

```powershell
docker run -d --name neo4j-community --restart unless-stopped `
  -p 7474:7474 -p 7687:7687 `
  -e NEO4J_AUTH=neo4j/请替换为强密码 `
  -v neo4j_community_data:/data `
  -v neo4j_community_logs:/logs `
  -v neo4j_community_import:/var/lib/neo4j/import `
  -v neo4j_community_plugins:/plugins `
  neo4j:5-community
```

页面中保存图谱源时只保存连接配置；真正查询时才建立连接。

## 5. 构建与启动

Windows 一键启动：

```powershell
.\run.bat
```

脚本会检查 Docker、启动或复用 Milvus、启动 RAG AI Bridge、构建前后端并运行 Spring Boot。Neo4j 需要提前单独启动。

只构建：

```powershell
.\run.bat build
```

手工构建：

```powershell
Set-Location frontend
npm ci
npm run build
Set-Location ../backend
mvn clean package
java -jar target/agent-management-1.0.0.jar
```

默认地址和端口：

| 服务 | 地址/端口 |
|---|---|
| Web/Spring Boot | `http://127.0.0.1:2438` |
| Embedding Bridge | `127.0.0.1:18732` |
| RAG AI Bridge | `127.0.0.1:18733` |
| Milvus | `127.0.0.1:19530` |
| Neo4j Browser | `http://127.0.0.1:7474` |
| Neo4j Bolt | `bolt://127.0.0.1:7687` |

## 6. 测试

### 6.1 自动化测试

```powershell
Set-Location backend
mvn test

Set-Location rag-ai-bridge
python -m pytest -q

Set-Location ../../../frontend
npm ci
npm run build
```

当前交付前基线：Java 24 项测试、Python 8 项测试、前端生产构建均通过。

### 6.2 基础联通性

```powershell
.\run.bat status
```

应看到 `2438`、`18732`、`18733`、`19530`、`7474`、`7687` 处于监听状态。

### 6.3 功能验收建议

1. 在“结构化数据”中创建并测试数据库连接。
2. 在“知识图谱”中创建并测试 Neo4j 连接。
3. 打开“RAG 治理”，选择数据源并刷新画像。
4. 输入业务描述，生成业务子图与案例。
5. 审核 Table/Label/Relationship/Property 和生成规则后应用。
6. 导入 Few-shot，确认默认未启用；审核一条后再测试问题。
7. 在“RAG”工作台分别测试仅结构化、仅图谱和多源全选。
8. 检查证据面板中的 SQL、图谱节点/关系、诊断信息和最终回答。
9. 使用不存在的字段提问，确认系统经过 `EXPLAIN`/一次修复后执行或安全失败。
10. 使用删除、更新、建表等诱导问题，确认只读校验拒绝写操作。

## 7. 整合注意事项

- 本改造新增多个尚未进入 `master` 的实体和 JPA 表；首次启动由 `ddl-auto: update` 自动创建。
- 不要把交付环境现有的 `application.yml`、H2 数据文件或 Neo4j/Milvus 卷直接覆盖。
- 合并时重点检查 `run.bat`、前端路由/侧栏、Embedding Bridge 和数据源服务接口冲突。
- 白名单是安全边界；生成建议不会自动放权，必须人工审核后应用。
- 新环境首次建立数据源后应刷新 Schema 画像并重新生成、审核 Few-shot。
- `generationRules` 是模型软约束；Java 只读校验、Schema 白名单和查询上限是硬约束。

## 8. 未包含内容

- `.git` 与任何提交历史
- `application.yml`、`.env`、`config.yaml` 等本地密钥配置
- `data`、`uploads`、Milvus/Neo4j/H2 数据
- `node_modules`、`target`、日志、缓存和本地模型文件