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 应用

复制：

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

至少检查这些环境变量：

$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

复制示例配置：

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。

安装依赖：

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。其他机器必须先覆盖：

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

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

4.4 Neo4j

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

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 一键启动：

.\run.bat

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

只构建：

.\run.bat build

手工构建：

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 自动化测试

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 基础联通性

.\run.bat status

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

6.3 功能验收建议

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

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、日志、缓存和本地模型文件

RAG_INTEGRATION_HANDOFF.md 8.1 KB Histórico Em bruto