RAG 配置

1. 页面概览

RAG 配置页（路由 /admin/rag）是 AIP 管理后台面向管理员的 RAG（检索增强生成）链路配置台。它包含三块能力：通道配置（metadata/knowledge/history/fewshot 四通道的启用开关与权重，启用通道权重合计应约等于 100%，可自动归一化）、索引重建（按数据源或全量重建元数据向量索引，展示 indexed/item_count）、检索测试（内嵌 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]（可选，为空则重建全部） [重建索引]        |
|   结果：indexed | item_count | message                          |
| 检索测试（调试 RAG 链路）：内嵌 RagRetrievePage（embedded 模式） |
+--------------------------------------------------------------+

各板块职责：

• 通道配置：四通道启用开关与权重输入（%），启用通道权重合计实时显示在标题旁；提供「自动归一化」「保存配置」。
• 索引重建：选择数据源（可选）后重建元数据向量索引，展示 indexed / item_count / message。
• 检索测试：内嵌 RagRetrievePage（embedded 模式），复用检索交互调试 RAG 链路。

4. 交互元素

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

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_channel_configs 表，无记录时返回默认值。

6. 权限与安全

• 通道与索引写操作（PUT /rag/channels、POST /rag/index/rebuild）挂 admin 组，仅管理员可调；通道查询与检索为 protected 登录组。
• 重建索引为重操作：未选数据源即全量重建，操作前建议确认范围；保存配置有归一化 confirm，无其他二次确认。
• 检索测试结果仅面向登录用户，不携带跨权限敏感列。

7. 常见问题与排错

• 现象：通道表格显示「暂无通道配置（后端可能未就绪）。」。原因：GET /rag/channels 失败或后端未启动。处理：确认 AIP 服务存活，点「刷新」重试；失败时会回退为默认四通道各 25% 并弹错误提示。
• 现象：保存配置时提示权重合计与 100% 不符的确认框反复弹出。原因：启用通道权重合计偏差超过 0.5%。处理：点确认先归一化，或手动调整权重到合计约 100% 后再保存。
• 现象：重建索引提示失败或结果为空。原因：数据源未就绪、连接失败或索引写入异常。处理：确认所选数据源可连通（可先建索引再查 item_count），查看后端日志中 RebuildMetadataIndex 报错。
• 现象：点「自动归一化」提示「至少启用一个通道后才能归一化」。原因：所有通道均被停用。处理：至少启用一个通道后再归一化。

8. 已知缺陷与边界