# RAG 前瞻性架构评审与新数据库接入方法

## 一、当前能力边界

现有系统已经具备多源检索、Schema 自动发现、白名单、动态 Few-shot、SQL/Cypher 只读校验、`EXPLAIN` 预检和一次修复。距离高准确率生产级 Text-to-SQL/Text-to-Cypher 仍有以下差距：

1. 仅有结构 Schema，缺少索引、约束、主外键、基数、典型属性值和业务术语等语义层。
2. 只按名称相似度选择 Schema 容易得到互不连接的 Label 和 Relationship。
3. 用户问题中的实体值尚未形成独立的实体链接链路，例如“爱达号”应先定位到 `Vessel.name` 或 `Mission.name`。
4. Few-shot 数量少时覆盖不足，数量多时需要语义召回、去重、质量评分和版本管理。
5. 白名单建议不能由模型直接生效，必须经过真实 Schema 对齐、查询预检和人工审核。
6. 缺少稳定评测集，无法量化生成正确率、执行正确率、答案一致性和回归变化。

## 二、本轮落地优化

### 0. 实体链接与增强元数据

- 从问题中抽取引号实体及“号、船、队、任务、阶段、事件、机构”等领域实体短语，要求模型把它们落到已授权的 `name/title/code` 等真实属性。
- SQL Schema Prompt 增加 JDBC 外键连接路径，避免模型猜测 JOIN。
- Neo4j 接入画像增加索引、约束、Label 节点规模。
- Few-shot 记录 Schema 版本；Schema 变化后自动取消审核并等待复审。

### 1. 拓扑感知业务子图

新的选择流程：

```text
业务意图/用户问题
  → 向量匹配 Label 与 Relationship 种子
  → 在已授权 Schema 内筛选
  → 按关系端点扩展相邻 Label
  → 形成连通业务子图
  → 再交给 Schema Linker 与 LLM
```

它解决了“选中了任务和队伍，却没有选中连接二者的关系”问题。白名单候选和运行时大型 Schema 裁剪共用同一拓扑选择逻辑。

### 2. 向量化 Few-shot 召回

已审核案例不再只按字面重合排序。系统优先对当前问题与候选问题做本地向量相似度排序，Embedding Bridge 不可用时才退回词法相似度。Prompt 仍只加入最相关的少量案例，避免案例过多稀释约束。

### 3. Few-shot 候选预检

治理生成的 SQL/Cypher 在进入待审核案例库前执行：

- SQL：只读检查与数据库 `EXPLAIN`。
- Cypher：写操作拦截、真实 Label/Relationship/Property 校验、最大深度检查和 Neo4j `EXPLAIN`。

导入接口返回通过和拒绝数量及拒绝原因。只有通过预检的案例才能进入人工审核阶段。

### 4. 图数据库接入成熟度评估

新增：

```http
GET /api/rag/capabilities/GRAPH/{sourceId}/readiness
```

返回 Label、关系模式、关系类型、Property、孤立 Label、语义目录覆盖、已审核 Few-shot 数量、成熟度评分和整改建议。

## 三、高准确率 Text-to-SQL 方法

推荐链路：

1. 发现表、字段、类型、备注、主键、外键、索引和方言。
2. 建立业务术语到表字段的语义目录。
3. 识别问题中的指标、维度、过滤条件、时间范围和排序要求。
4. 先生成逻辑查询计划，再生成 SQL。
5. 只向模型提供相关且授权的表及必要连接路径。
6. 召回同方言、同问题类型的已验证 Few-shot。
7. 静态校验表字段、只读操作、聚合和行数限制。
8. 执行 `EXPLAIN`；仅允许一次基于错误信息的修复。
9. 执行后检查结果形状和空结果，只有返回有效证据的查询才进入动态案例库。

后续应补充主外键发现、枚举值字典、时间字段识别和结果语义校验。

## 四、高准确率 Text-to-Cypher 方法

拿到一个新图数据库时，建议严格执行以下过程。

### 第一步：结构盘点

- 读取所有 Label、Relationship、方向和 Property 类型。
- 读取唯一约束、索引、全文索引和向量索引。
- 统计 Label 节点数、关系基数、孤立节点类型和高频路径。
- 识别名称、编码、状态、时间、坐标等实体关键属性。

### 第二步：语义画像

- 为 Label、Relationship、Property 建立业务说明和同义词。
- 将 Schema、说明和连接端点向量化。
- 对敏感属性建立禁止暴露策略。
- 将技术图谱拆成若干可解释的业务子图。

### 第三步：问法体系

至少覆盖五类基准问题：

1. 单节点查找。
2. 属性过滤与排序。
3. 聚合统计。
4. 一跳关系查询。
5. 多跳路径与因果链查询。

每类生成若干 Cypher，经过 Schema Validator 和 Neo4j `EXPLAIN` 后进入待审核案例库。

### 第四步：运行时生成

- 先做实体识别和实体值链接。
- 通过语义种子和关系端点形成连通子图。
- 从已审核案例中向量召回相同问法。
- 要求模型只返回查询，不返回解释。
- 校验 Label、关系、属性、方向、深度、返回形状和写操作。
- `EXPLAIN` 失败后最多修复一次。
- 查询成功后检查是否返回节点、关系或路径证据。

### 第五步：持续评测

为每个图数据库保存固定问题集，至少记录：

- Schema linking Recall@K。
- Cypher 语法通过率。
- `EXPLAIN` 一次通过率。
- 执行成功率。
- 结果集正确率。
- 路径/实体覆盖率。
- 平均耗时和 P95。
- 修复率、空结果率和越权拦截率。

## 五、智能白名单和 Few-shot 的安全原则

智能化不等于让模型直接修改生产权限。正确状态机应为：

```text
自动发现
  → 智能推荐
  → 真实 Schema 对齐
  → EXPLAIN 验证
  → 人工审核
  → 版本化发布
  → 监控与回滚
```

自动学习案例也必须是未审核状态。建议后续增加质量分、来源、Schema 版本、执行次数、最近成功时间和失效检测；Schema 变化后自动将受影响案例标记为待复审。

## 六、下一阶段优先级

1. 实体值链接与属性值字典。
2. Neo4j 索引、约束、基数和高频路径发现。
3. SQL 主外键和连接路径发现。
4. 白名单/Few-shot 版本、发布、回滚及 Schema 变更失效机制。
5. 固定评测集和自动回归看板。
6. 生成逻辑计划与结果语义校验。

批量执行评测可调用：

```http
POST /api/rag/evaluation/run
```

请求包含 `knowledgeBaseId` 与 `cases`；每个案例提供 `question`、可选 `expectedSource`。响应返回通过率、平均耗时、证据数和逐题诊断。