343 lines
13 KiB
Markdown
343 lines
13 KiB
Markdown
# Essence Report: SuperBizAgent-java — RAG 切片流程
|
||
|
||
> **Lens:** mechanical
|
||
> **Design analyzed:** 四层递进式文档分块算法——标题→章节→段落→句子边界的逐级切割策略
|
||
> **Files examined:** 3 (`DocumentChunkService.java`, `DocumentChunkConfig.java`, `DocumentChunk.java`)
|
||
> **Pattern:** Hierarchical Splitter with Sentence-Boundary-Aware Overlap
|
||
> **Status:** complete
|
||
|
||
---
|
||
|
||
## Phase 2: Deep Dive
|
||
|
||
### 核心文件
|
||
|
||
| # | 文件 | 行数 | 角色 |
|
||
|---|------|------|------|
|
||
| 1 | `service/DocumentChunkService.java` | 229 | 分块引擎本身 |
|
||
| 2 | `config/DocumentChunkConfig.java` | 32 | 参数契约 `maxSize=800, overlap=100` |
|
||
| 3 | `dto/DocumentChunk.java` | 59 | 分块数据载体 |
|
||
|
||
### 完整调用链
|
||
|
||
```
|
||
VectorIndexService.indexSingleFile()
|
||
└─ chunkService.chunkDocument(content, filePath) [L35]
|
||
│
|
||
├─ splitByHeadings(content) [L44]
|
||
│ ├─ 正则: ^(#{1,6})\s+(.+)$ [L65]
|
||
│ ├─ 迭代 matcher.find() 找到每个标题位置
|
||
│ ├─ 标题之间的内容 → Section(title, content, startIndex)
|
||
│ └─ → List<Section>
|
||
│
|
||
└─ for each Section:
|
||
└─ chunkSection(section, globalChunkIndex) [L49]
|
||
│
|
||
├─ if content.length() ≤ maxSize (800):
|
||
│ └─ 直接作为一个分块 [L110-119]
|
||
│
|
||
├─ else (需要进一步切割):
|
||
│ ├─ splitByParagraphs(content) [L124]
|
||
│ │ └─ content.split("\n\n+") [L178]
|
||
│ │
|
||
│ ├─ for each paragraph: [L130-167]
|
||
│ │ ├─ 当前缓冲区 + 新段落 ≤ maxSize? → 继续追加
|
||
│ │ └─ 当前缓冲区 + 新段落 > maxSize? → 触发切分:
|
||
│ │ ├─ 保存当前分块
|
||
│ │ ├─ getOverlapText(当前分块内容) [L147]
|
||
│ │ │ ├─ 取末尾 overlap(100) 字符
|
||
│ │ │ ├─ 在重叠文本中找最后一个句子终止符
|
||
│ │ │ │ max(lastIndexOf('。'), lastIndexOf('？'), lastIndexOf('！'))
|
||
│ │ │ ├─ if 句子边界 > overlapSize/2 (50字符):
|
||
│ │ │ │ └─ 从句子边界后截取（保证新块以完整句开头）
|
||
│ │ │ └─ else:
|
||
│ │ │ └─ 直接用 overlap 末尾截取
|
||
│ │ └─ 新缓冲区 = 重叠文本 + 当前段落
|
||
│ │
|
||
│ └─ 最后一个分块: 保存缓冲区剩余内容
|
||
│
|
||
└─ → List<DocumentChunk>
|
||
```
|
||
|
||
### 算法的四层递进结构
|
||
|
||
```
|
||
第1层：标题分割
|
||
输入："# CPU高负载\n内容...\n## 排查步骤\n内容..."
|
||
输出：Section("CPU高负载", "内容..."), Section("排查步骤", "内容...")
|
||
作用：保持文档结构，同一主题的内容不被拆散
|
||
|
||
第2层：容量判断
|
||
if section.length() ≤ 800: 整个章节 = 一个分块
|
||
else: 进入段落级切割
|
||
作用：短章节保持完整，不破坏语义
|
||
|
||
第3层：段落边界切割
|
||
输入：超长章节的全部段落
|
||
算法：逐个追加段落到缓冲区，超过 maxSize 时触发一次切分
|
||
作用：不在段落中间截断
|
||
|
||
第4层：重叠窗口 + 句子边界对齐
|
||
输入：即将被切断的分块末尾
|
||
算法：取末尾100字符 → 找最近的。？！ → 从该位置之后截取作为下一块的"种子"
|
||
作用：相邻分块在语义上是"连续"的，检索时召回更完整
|
||
```
|
||
|
||
### 架构图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
DOC[/"原始文档"/] --> L1{"第1层: splitByHeadings()"}
|
||
|
||
L1 --> S1["Section 1<br/>title: CPU高负载<br/>content: ..."]
|
||
L1 --> S2["Section 2<br/>title: 排查步骤<br/>content: ..."]
|
||
L1 --> S3["Section N"]
|
||
|
||
S1 --> L2{"第2层: 容量判断"}
|
||
S2 --> L2
|
||
S3 --> L2
|
||
|
||
L2 -->|"≤800字符"| CHUNK["作为1个分块<br/>继承 title"]
|
||
L2 -->|">800字符"| L3{"第3层: splitByParagraphs()<br/>在段落边界切分"}
|
||
|
||
L3 --> BUF["逐段追加到缓冲区"]
|
||
BUF --> CHECK{"buf + para<br/>> maxSize?"}
|
||
CHECK -->|否| APPEND["追加段落<br/>继续累积"]
|
||
CHECK -->|是| L4{"第4层: getOverlapText()<br/>句子边界校准"}
|
||
|
||
APPEND --> CHECK
|
||
|
||
L4 --> FIND["在重叠区末尾100字符<br/>找最近的 。？！"]
|
||
FIND --> EVAL{"句子边界位置<br/>> overlapSize/2?"}
|
||
EVAL -->|是| ALIGN["从句号后截取<br/>保证新块以完整句开头"]
|
||
EVAL -->|否| RAW["退回原始截取<br/>直接用末尾100字符"]
|
||
|
||
ALIGN --> SEED["种子 + 当前段落<br/>→ 新缓冲区"]
|
||
RAW --> SEED
|
||
SEED --> CHECK
|
||
|
||
CHUNK --> RESULT[/"List<DocumentChunk><br/>每个携带: content + title + startIndex + endIndex + chunkIndex"/]
|
||
```
|
||
|
||
### 关键代码证据
|
||
|
||
#### 第1层——标题正则
|
||
|
||
```java
|
||
// DocumentChunkService.java:65
|
||
Pattern headingPattern = Pattern.compile("^(#{1,6})\\s+(.+)$", Pattern.MULTILINE);
|
||
```
|
||
|
||
支持 H1-H6，`MULTILINE` 模式让 `^` 匹配行首而非仅字符串首。
|
||
|
||
#### 第2层——容量判断（短路）
|
||
|
||
```java
|
||
// DocumentChunkService.java:110-119
|
||
if (content.length() <= chunkConfig.getMaxSize()) {
|
||
DocumentChunk chunk = new DocumentChunk(content, startIndex, endIndex, chunkIndex);
|
||
chunk.setTitle(title);
|
||
chunks.add(chunk);
|
||
return chunks; // 直接返回，不进入段落切割
|
||
}
|
||
```
|
||
|
||
#### 第3层——段落级触发切分
|
||
|
||
```java
|
||
// DocumentChunkService.java:132-148
|
||
if (currentChunk.length() > 0 &&
|
||
currentChunk.length() + paragraph.length() > chunkConfig.getMaxSize()) {
|
||
// 触发切分：保存当前块
|
||
String overlap = getOverlapText(chunkContent); // 提取重叠文本
|
||
currentChunk = new StringBuilder(overlap); // 新块以重叠文本开头
|
||
currentStartIndex = currentStartIndex + chunkContent.length() - overlap.length();
|
||
}
|
||
currentChunk.append(paragraph).append("\n\n"); // 继续追加
|
||
```
|
||
|
||
#### 第4层——句子边界检测（核心巧思）
|
||
|
||
```java
|
||
// DocumentChunkService.java:193-213
|
||
private String getOverlapText(String text) {
|
||
int overlapSize = Math.min(chunkConfig.getOverlap(), text.length());
|
||
String overlap = text.substring(text.length() - overlapSize);
|
||
|
||
// 在重叠文本中找最近的句子终止符
|
||
int lastSentenceEnd = Math.max(
|
||
overlap.lastIndexOf('。'),
|
||
Math.max(overlap.lastIndexOf('？'), overlap.lastIndexOf('！'))
|
||
);
|
||
|
||
// 质量阈值：只有句子边界在重叠区后半段才采用
|
||
if (lastSentenceEnd > overlapSize / 2) {
|
||
return overlap.substring(lastSentenceEnd + 1).trim();
|
||
}
|
||
return overlap.trim(); // 退回普通重叠
|
||
}
|
||
```
|
||
|
||
`overlapSize / 2` 条件是一个**质量阈值**。如果最近的句子边界在重叠区的前半段（即离截断点太远），说明分块点本身就接近句子边界，不需要特殊处理。只有句子边界明显位于重叠区后半段时才调整——避免把半个句子作为新块的"种子"。
|
||
|
||
### 数据流契约
|
||
|
||
```
|
||
chunkDocument(content, filePath)
|
||
│
|
||
│ IN: String content — 原始文档全文
|
||
│ String filePath — 仅用于日志
|
||
│
|
||
│ INNER CLASS: Section
|
||
│ String title — 所在标题（可为 null）
|
||
│ String content — 标题下的所有文本
|
||
│ int startIndex — 在原文档中的字符偏移
|
||
│
|
||
│ OUT: List<DocumentChunk>
|
||
│ String content — 分块文本
|
||
│ int startIndex — 在原文档中的起始位置
|
||
│ int endIndex — 在原文档中的结束位置
|
||
│ int chunkIndex — 分块序号 (0, 1, 2, ...)
|
||
│ String title — 所属章节标题（继承自 Section）
|
||
│
|
||
└─ 消费者: VectorIndexService.indexSingleFile():142
|
||
→ 遍历 chunks → embeddingService.generateEmbedding(chunk.content)
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 3: Extract Pattern
|
||
|
||
### 模式名：Hierarchical Splitter with Sentence-Boundary-Aware Overlap
|
||
|
||
**一句话：** 从粗到细逐级切割——先按文档结构（标题）分章，再按语义边界（段落）分块，最后在切分点用句子终止符校准重叠窗口。
|
||
|
||
### 问题
|
||
|
||
固定长度切割的典型失败场景：
|
||
|
||
```
|
||
切在句子中间： "CPU使用率达到 95%，建议" | "立即重启相关服务"
|
||
↑ 检索"CPU问题"时召回这块——后半句完全脱离上下文，LLM 误判
|
||
|
||
切在段落中间："## 排查步骤\n1. 查看监控\n2. 检" | "查日志\n3. 重启服务"
|
||
↑ 步骤 2 被切断，Agent 拿着残缺的排查步骤执行操作
|
||
```
|
||
|
||
### 替代方案对比
|
||
|
||
| 方案 | 切分依据 | 优势 | 劣势 |
|
||
|------|----------|------|------|
|
||
| **固定字符切割**（最简陋） | maxSize，不关心内容 | 实现简单 | 句子截断、丢失语义 |
|
||
| **递归字符切割**（LangChain RecursiveTextSplitter） | `\n\n` → `\n` → ` ` → `` | 通用性好 | 不理解 Markdown 结构 |
|
||
| **语义切割**（用 LLM 判断切点） | LLM 标注切分位置 | 理论上最优 | 慢、贵、不可预测 |
|
||
| **本项目：层级式+句子校准** | 标题→段落→句子终止符 | 快速 + 保留文档结构 | 仅支持 Markdown，非标题文档退化为段落切割 |
|
||
|
||
### 为什么标题分割放在第一步？
|
||
|
||
```java
|
||
// DocumentChunkService.java:43-44
|
||
// 1. 首先尝试按标题分割（Markdown格式）
|
||
List<Section> sections = splitByHeadings(content);
|
||
```
|
||
|
||
看本项目的知识库文档就懂了：
|
||
|
||
```markdown
|
||
# CPU高负载问题排查 ← 一个独立主题
|
||
## 问题现象
|
||
...
|
||
## 排查步骤 ← 这些步骤必须完整才能被 Agent 执行
|
||
1. 使用 top 命令确认 CPU 使用率最高的进程
|
||
2. 检查对应服务的日志
|
||
3. ...
|
||
## 解决方案
|
||
...
|
||
|
||
# 内存高负载问题排查 ← 另一个独立主题
|
||
...
|
||
```
|
||
|
||
如果把「CPU 排查步骤」和「内存排查步骤」混在一个分块里，Agent 查询"CPU 高"时会召回包含内存排查步骤的分块——噪声干扰判断。
|
||
|
||
标题优先分割 = **用文档作者自己标注的结构来界定语义边界**，比任何算法都准确。
|
||
|
||
---
|
||
|
||
## Phase 4: Migrate
|
||
|
||
### 可迁移性
|
||
|
||
这个切分策略**直接可用**于任何需要为 Markdown 文档建 RAG 的项目。三个参数全部可配置：
|
||
|
||
```yaml
|
||
# application.yml — 按文档类型调整
|
||
document:
|
||
chunk:
|
||
max-size: 800 # 短文档(API文档)可设500，长文档(周报)可设1200
|
||
overlap: 100 # 800的12.5%，保持比例即可
|
||
```
|
||
|
||
### Steal-it 示例（17 行）
|
||
|
||
```java
|
||
/**
|
||
* 四层递进分块：标题 → 章节 → 段落 → 句子校准
|
||
* 依赖：maxSize / overlap 两个参数
|
||
*/
|
||
public List<Chunk> chunk(String doc) {
|
||
List<Chunk> result = new ArrayList<>();
|
||
int globalIdx = 0;
|
||
|
||
// 第1层：按标题分章
|
||
for (Section sec : splitByHeadings(doc)) {
|
||
if (sec.content.length() <= maxSize) {
|
||
// 第2层：短章节直接作为一个分块
|
||
result.add(new Chunk(sec.content, sec.title, globalIdx++));
|
||
} else {
|
||
// 第3层：超长章节在段落边界切分
|
||
String overlap = "";
|
||
for (String para : sec.content.split("\n\n+")) {
|
||
String candidate = overlap + para;
|
||
if (candidate.length() > maxSize && !overlap.isEmpty()) {
|
||
result.add(new Chunk(overlap, sec.title, globalIdx++));
|
||
overlap = tailOverlap(overlap); // 第4层：句子校准
|
||
}
|
||
overlap = (overlap.isEmpty() ? "" : overlap + "\n\n") + para;
|
||
}
|
||
if (!overlap.isEmpty()) result.add(new Chunk(overlap, sec.title, globalIdx++));
|
||
}
|
||
}
|
||
return result;
|
||
}
|
||
```
|
||
|
||
### 落地陷阱
|
||
|
||
| 陷阱 | 原因 | 规避 |
|
||
|------|------|------|
|
||
| **非 Markdown 文档退化为单块** | `splitByHeadings()` 找不到标题时整个文档作为一个 Section | L93-96：返回一个 Section，后续段落切割仍生效 |
|
||
| **代码块内的 `#` 被误识别为标题** | 正则不区分代码块和正文 | 未规避——可加反引号检测 `` ``` `` |
|
||
| **overlap=0 时句子校准无效** | `getOverlapText` 第一行 `Math.min(0, length)=0` 返回空串 | L194：直接返回空字符串，跳过校准 |
|
||
| **单段落超过 maxSize 不做切割** | `splitByParagraphs` 后每个段落作为一个单位 | L132 条件要求 `currentChunk.length() > 0`，首段落即使超长也会被单独保存为一块 |
|
||
|
||
---
|
||
|
||
### Self-review
|
||
|
||
- [x] 设计真实——每层切割均有代码行号证据
|
||
- [x] 深度足够——追溯到正则、条件分支、句子校准的数学逻辑
|
||
- [x] 迁移示例 17 行——提取了四层递进的核心骨架
|
||
- [x] 陷阱具体到代码行——非 Markdown 退化为单块(L93)、单段落超长不切割(L132)
|
||
|
||
```
|
||
Essence Report: SuperBizAgent-java — RAG 切片流程
|
||
Lens: mechanical
|
||
Design analyzed: 四层递进式文档分块算法
|
||
Files examined: 3
|
||
Pattern: Hierarchical Splitter with Sentence-Boundary-Aware Overlap
|
||
Migration: 17-line steal-it skeleton
|
||
HTML generated: no
|
||
Status: complete
|
||
```
|