docs: consolidate rag refactor issues

2026-07-05 01:40:08 +08:00
parent bf5286c8f4
commit 2609c5a5ab
15 changed files with 1167 additions and 0 deletions
@@ -0,0 +1,58 @@
+# RAG breadcrumb 未参与向量语义
+
+**状态**：待规划  
+**严重程度**：高  
+**发现时间**：2026-07-04  
+**范围**：向量化输入、检索相关性、知识库 metadata 使用
+
+---
+
+## 现象
+
+当前 chunk metadata 中保存了 `title` 和 `breadcrumb`，但向量化时主要使用 `chunk.getContent()`。这意味着标题层级、所属模块、章节路径没有进入 embedding 语义空间。
+
+当用户问题依赖章节语境时，例如“诊断流程里的验证步骤是什么”，如果 chunk 正文里没有重复出现完整标题语义，向量召回可能无法稳定命中正确片段。
+
+---
+
+## 当前实现
+
+- `DocumentChunkService` 会生成 `breadcrumb`。
+- `VectorIndexService` 会把 `breadcrumb` 写入 metadata。
+- `VectorEmbeddingService` 接收的 embedding 内容来自 chunk 正文。
+- `VectorSearchService` 只基于 query embedding 和 chunk embedding 做向量搜索。
+
+metadata 目前更像是展示和追踪字段，不是检索相关性的一部分。
+
+---
+
+## 影响
+
+- 标题语义丢失，尤其影响短段落、步骤列表、配置表格类 chunk。
+- 同名概念出现在不同章节时，缺少章节路径帮助 disambiguation。
+- 用户问的是“某个模块下的问题”，检索可能只看正文关键词，忽略模块归属。
+
+---
+
+## 建议修复
+
+构建面向 embedding 的增强文本：
+
+```text
+标题: {title}
+路径: {breadcrumb}
+正文:
+{content}
+```
+
+落库时仍保留原始 `content`，避免展示内容被污染。可以新增 `embeddingText` 构造逻辑，只用于向量化。
+
+后续还可以在 rerank 阶段把 `breadcrumb` 作为加权信号，例如同域、同章节、同文档优先。
+
+---
+
+## 相关文件
+
+- `src/main/java/com/superbiz/agent/service/DocumentChunkService.java`
+- `src/main/java/com/superbiz/agent/service/VectorIndexService.java`
+- `src/main/java/com/superbiz/agent/service/VectorEmbeddingService.java`