RAG 配置

1. 页面概览

RAG 配置页（路由 /admin/rag）是 AIP 管理后台面向管理员的 RAG（检索增强生成）链路配置台。它包含三块能力：通道配置（metadata/knowledge/history/fewshot 四通道的启用开关与权重，启用通道权重合计应约等于 100%，可自动归一化）、索引重建（按数据源或全量重建元数据向量索引，展示 data_source/items/indexed/failed/degraded/collection 真实字段 + 前端秒表等待反馈）、检索测试（内嵌 RagRetrievePage 复用检索交互）。用于调整 RAG 多路召回权重、维护索引与调试检索链路。所有请求走 aipClient（/aip-api/v1 → AIP 18080），后端未就绪时优雅提示不白屏。

一句话总结：本页是 RAG 链路的「通道权重 + 索引维护 + 检索调试」控制台，四通道加权融合的入口在此配置。

2. 访问入口

• 路由与菜单：path /admin/rag、name AdminRag、路由 title「RAG 配置」，位于 AIP 管理后台侧边栏（菜单项「RAG 配置」）；源码 action/web/src/views/RagConfigPage.vue。
• 认证与权限：父路由 /admin 配置 requiresAuth: true, requiresAdmin: true；通道查询 GET /rag/channels 为 protected 登录组，通道保存 PUT /rag/channels 与索引重建 POST /rag/index/rebuild 为 admin 组。
• 端口与 API 前缀：AIP 后端 18080，前端 baseURL /aip-api/v1（Vite 将 /aip-api 重写为 /api）。

3. 界面布局

+--------------------------------------------------------------+
| RAG 配置                                      [刷新]           |
| 通道配置（启用通道权重合计 X%）：                                 |
|   表格：通道(label+name)|说明|启用(switch)|权重（%）[清零]        |
|   提示：权重精度 0.05（对应 5%）… [自动归一化] [保存配置]         |
| 索引重建：数据源[select]（可选，为空则重建全部） [重建索引]        |
|   结果 chip：data_source | items | indexed | failed | degraded | collection |
|   （重建中按钮显示 spinner + 已用 Ns，防重复点击）                |
| 检索测试（调试 RAG 链路）：内嵌 RagRetrievePage（embedded 模式） |
+--------------------------------------------------------------+

各板块职责：

• 通道配置：四通道启用开关与权重输入（%），启用通道权重合计实时显示在标题旁；提供「自动归一化」「保存配置」。
• 索引重建：选择数据源（可选）后重建元数据向量索引，结果按后端真实字段展示 data_source / items / indexed / failed / degraded / collection（failed>0 与 degraded 高亮警示）；重建为同步请求，按钮期间显示 spinner + 已用秒数。
• 检索测试：内嵌 RagRetrievePage（embedded 模式），复用检索交互调试 RAG 链路。

4. 交互元素

次要控件：通道行内「清零」按钮；重建结果区 message 展示；内嵌检索测试页的交互见 RagRetrievePage。

重建无进度条（后端缺口，非前端遗漏）：重建端点 POST /rag/index/rebuild 是同步接口——后端在同一请求内完成「清空索引 → 全量向量化 → 写入索引状态」后直接 ok(c, result) 返回结果对象（nlq/rag_handler.go:147-171），不返回 task_id、不提供进度查询，故无法做服务端进度条；前端仅以秒表给出等待时长反馈（重操作期间请勿重复点击）。平台虽已具备通用任务查询端点 GET /api/v1/tasks/:id（platform/task/rest.go:27-31，接线于 server/server.go:1001），但重建未任务化——真正进度条需后端先把重建改造为异步任务。

5. 后端关联

5.1 端点表

5.2 关键机制

• 四通道加权融合：metadata（元数据通道，表结构/字段元数据检索）、knowledge（知识库通道，知识库文档向量检索）、history（历史会话通道，相似历史问题-回答检索）、fewshot（Few-shot 示例通道，示例问题-SQL 对检索）；后端多路召回后 min-max 归一化加权融合重排（默认权重约 0.40/0.25/0.20/0.15）。
• 权重语义：前端按百分比输入（0-100，step 5），保存时换算为 0-1 小数（weight = 百分比/100，保留两位）；停用通道 weight 写 0。
• 保存前归一化提示：启用权重合计与 100% 差超过 0.5% 时弹 confirm，确认后先归一化再保存；「自动归一化」按启用通道等比缩放到 100%，末位通道吸收取整漂移。
• 索引重建语义：空 body（或仅有空白）视为未提供数据源 → 全量重建；后端手动读 body 避免空 body 被解析为 data_source_id=0 误触发全量（rag_handler.go:149-159）；通道配置存 rag_channel_configs 表，无记录时返回默认值。
• 重建响应字段（已按代码修正）：RebuildMetadataIndex 返回 {data_source, items, indexed, failed, degraded, collection}（nlq/rag.go:1286-1293），其中 items 为待索引项数、indexed 为成功入库数、failed = items - indexed、degraded 表示 embedding 不可用而降级、collection 为向量集合名；无 item_count 字段，此前前端误读 item_count 恒为空，本批已改为真实字段。
• 同步无任务化（后端缺口）：RebuildIndex handler 直接返回结果，无 task_id（rag_handler.go:147-171）；进度条需后端先异步任务化（平台已有 GET /api/v1/tasks/:id，platform/task/rest.go:27-31，接线 server/server.go:1001）。

6. 权限与安全

• 通道与索引写操作（PUT /rag/channels、POST /rag/index/rebuild）挂 admin 组，仅管理员可调；通道查询与检索为 protected 登录组。
• 重建索引为重操作：未选数据源即全量重建，操作前建议确认范围；重建为同步长请求，按钮期间禁用并显示已用秒数，避免重复点击。
• 检索测试结果仅面向登录用户，不携带跨权限敏感列。

7. 常见问题与排错

• 现象：通道表格显示「暂无通道配置（后端可能未就绪）。」。原因：GET /rag/channels 失败或后端未启动。处理：确认 AIP 服务存活，点「刷新」重试；失败时会回退为默认四通道各 25% 并弹错误提示。
• 现象：保存配置时提示权重合计与 100% 不符的确认框反复弹出。原因：启用通道权重合计偏差超过 0.5%。处理：点确认先归一化，或手动调整权重到合计约 100% 后再保存。
• 现象：重建索引提示失败或结果为空。原因：数据源未就绪、连接失败或索引写入异常。处理：确认所选数据源可连通（可先建索引再核对 indexed/failed），查看后端日志中 RebuildMetadataIndex 报错。
• 现象：重建耗时很长且界面只有秒表、没有进度条。原因：重建端点为同步接口，后端无 task_id/进度查询（rag_handler.go:147-171）。处理：耐心等待或缩小到单个数据源；真正进度条需后端将重建改造为异步任务（后端缺口）。
• 现象：点「自动归一化」提示「至少启用一个通道后才能归一化」。原因：所有通道均被停用。处理：至少启用一个通道后再归一化。

8. 已知缺陷与边界