RAG 检索测试

1. 页面概览

RAG 检索测试页是 LightAIP 的检索链路调试入口，路由为 /rag-test。它向 RAG 引擎发起一次自然语言检索请求（POST /rag/retrieve），把"多路召回 + 融合重排"的结果可视化：按检索通道分组的文档列表（每条含 score/source/content）、命中的通道徽标、结果分页条，以及五段检索上下文的 Tab 展示。

页面支持限定数据源与调整 top_k（召回条数），便于验证不同配置下的召回效果。该组件还支持 embedded 模式：作为子组件嵌入「RAG 配置」管理页复用检索交互（隐藏页头）。一句话总结：RAG 检索测试页是验证"问题 → 召回 → 上下文"链路的调试台。

2. 访问入口

2.1 路由与菜单

2.2 认证与权限

meta 配置 requiresAuth: true；请求经 action/web/src/api/aipClient.js（baseURL /aip-api/v1）附 localStorage.aip_token，401 由响应拦截器清 Token 并跳 /login。普通登录用户可访问。

2.3 端口与 API 前缀

AIP 后端默认端口 18080，API 前缀 /aip-api，实际请求路径 /aip-api/v1/rag/retrieve、/aip-api/v1/datasources。

3. 界面布局

+--------------------------------------------------+
| RAG 检索测试                                      |
+--------------------------------------------------+
| [操作结果提示 alert（有消息时显示，可关闭）]          |
+--------------------------------------------------+
| 检索请求（card）                                   |
|  问题 [textarea]   数据源（可选）[全部数据源▾]       |
|  top_k（召回条数）[10]   [发起检索]                 |
+--------------------------------------------------+
| 检索结果（card，有结果时）                          |
|  本次命中的通道：[元数据][知识库][历史会话][示例]     |
|  分页条：第 X/Y 页·共 N 条  每页[20▾] [上一页][下一页] |
|  按 channel 分组：通道 Tag + N 条文档               |
|    每条：score / source / content                  |
|  contexts 五段 Tab：表结构Schema|字段同义词|知识上下文|历史会话|Few-shot示例 |
+--------------------------------------------------+

各板块职责：

• 检索请求：问题为必填，数据源可选限定范围，top_k 控制召回条数上限，点「发起检索」执行。
• 检索结果：展示命中的通道徽标、分页条（页大小可选 + 上下页 + 计数）、按 channel 分组的文档（score 四位小数、source 来源、content 正文），以及五段检索上下文（table_schemas / column_synonyms / knowledge_context / history_context / fewshot_examples）的 Tab 视图。
• embedded 模式：作为子组件嵌入 RagConfigPage 时隐藏页头，复用同一套检索交互。

4. 交互元素

5. 后端关联

5.1 端点表

5.2 关键机制

• 多路召回：RAG 引擎按四个通道并行召回——metadata（元数据/表结构）、knowledge（知识库）、history（历史会话）、fewshot（示例），再融合重排。响应含 documents、contexts、channels_used、latency_ms。
• 跨用户隔离：检索请求把当前用户显式注入 RAG 上下文（WithRAGUser），history/few-shot 通道按 user_id 过滤；无有效身份时 fail-closed 返回空通道，防止检索结果跨用户泄漏。
• top_k 语义：top_k 是融合后文档数上限（缺省 10）；data_source_id 为空表示不限定范围，后端先解析为数据源名称再检索，数据源不存在返回 404。
• 分页语义：POST /rag/retrieve 一次返回全部结果（documents 数量受 top_k 上限约束），接口无分页参数，故结果分页为前端渲染分页（对已取回的 documents 切片展示），不改变接口返回与既有 score/source/channel 展示。
• 防御式取值：前端 unwrap 兼容 {code,data} 与直接对象两种外层结构；后端未就绪或未返回文档时提示"检索完成，但未返回文档"而不白屏。

6. 权限与安全

• 认证为 JWT（aip_token），/rag/retrieve 挂 protected 登录组，未登录一律 401。
• RAG 上下文按当前登录用户过滤，历史/示例通道不泄漏他人会话内容。
• 通道写操作（PUT /rag/channels）与索引重建（POST /rag/index/rebuild）挂 admin 管理组，本页只读不暴露。

7. 常见问题与排错

问题 1：检索返回"未检索到相关文档"

现象：提示检索完成但无文档，通道徽标为空。

原因：多为向量索引为空、知识库/元数据未构建，或问题过偏。

处理：确认已导入数据源元数据/知识文档并重建索引；先不限定数据源、调大 top_k 再试。

问题 2：数据源下拉框为空

现象：下拉只有「全部数据源」。

原因：GET /datasources 失败（后端未就绪）或尚无数据源。

处理：确认后端 18080 存活并已有数据源；下拉框为空不影响全局检索。

问题 3：检索报 401 被踢回登录页

现象：点「发起检索」后整体跳转 /login。

原因：aip_token 失效，响应拦截器清除 Token 并跳转登录。

处理：重新登录；检查后端时钟/密钥配置导致的 Token 快速过期。

问题 4：某些上下文 Tab 显示"（该上下文为空）"

现象：如「历史会话」Tab 为空。

原因：当前用户无历史会话，或该通道未启用/权重为 0。

处理：先去「智能查询」产生会话历史，或到 RAG 配置检查通道启用状态。

8. 已知缺陷与边界