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 高亮警示）。重建为异步任务：15s 窗口内完成直接出结果（旧字段 + task_id），超时返回 202 后前端经 GET /tasks/:id 每 1.5s 轮询并在卡片内展示 task_id/status/progress/进度条/message；按钮期间显示 spinner + 已用秒数。
• 检索测试：内嵌 RagRetrievePage（embedded 模式），复用检索交互调试 RAG 链路。

4. 交互元素

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

重建已任务化（D3，2026-09-17；原「无进度条」后端缺口闭环）：重建端点 POST /rag/index/rebuild 经平台异步任务系统执行（task_type=rag_index_rebuild，执行器 nlq.RAGRebuildRunner，实现 nlq/rag_task.go）——等待窗口 15s 内完成 → 200 返回原结果对象 + task_id；超时 → 202 {code:0,data:{task_id,status,type}}，任务在后台继续跑，前端经既有 GET /api/v1/tasks/:id（platform/task/rest.go:27-31，接线 server/server.go protected 组）轮询 progress/message，success 时 result 即原结果结构。任务管理器未装配或提交失败时后端降级为同步直执行（响应与改造前一致，无 task_id）。

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 恒为空，本批已改为真实字段。
• 任务化执行器与重启恢复：执行器无状态，数据源名只从 task.Payload.data_source_name 解析；注册点在 aip/server/server.go 的任务执行器注册块（早于 taskMgr.Restore），故进程重启后 queued 的重建任务可被重派继续执行。

6. 权限与安全

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

7. 常见问题与排错

• 现象：通道表格显示「暂无通道配置（后端可能未就绪）。」。原因：GET /rag/channels 失败或后端未启动。处理：确认 AIP 服务存活，点「刷新」重试；失败时会回退为默认四通道各 25% 并弹错误提示。
• 现象：保存配置时提示权重合计与 100% 不符的确认框反复弹出。原因：启用通道权重合计偏差超过 0.5%。处理：点确认先归一化，或手动调整权重到合计约 100% 后再保存。
• 现象：重建索引提示失败或结果为空。原因：数据源未就绪、连接失败或索引写入异常。处理：确认所选数据源可连通（可先建索引再核对 indexed/failed），查看后端日志中 RebuildMetadataIndex 报错。
• 现象：重建提交后界面显示「重建任务已受理，正在后台执行……」并出现进度条/status。说明：这是 15s 快路径超时后的正常分支（202），任务仍在服务端执行——进度条按 GET /tasks/:id 的 progress 推进，status=success 时展示结果 chips。处理：等待即可；若长时间停在 running，看 message 与 AIP 日志（embedding 慢或向量库慢）；若 failed 则按卡片报错排查数据源/embedding。
• 现象：点「自动归一化」提示「至少启用一个通道后才能归一化」。原因：所有通道均被停用。处理：至少启用一个通道后再归一化。

8. 已知缺陷与边界