Paragraph Semantic 分块策略

1. 适用场景与策略选择

1.1 P 策略要解决什么问题

Paragraph Semantic Chunking（下文简称 P 策略）面向 DOCX 等具有清晰章节结构的文档。其核心目标是：让分块边界尽可能对齐文档原生的语义边界（标题、段落、表格行），而不是仅由 token 长度计数决定切点。

P 策略主要解决以下四类问题：

1. 表格语境断裂：大表被拆分后，首尾切片容易脱离前置说明、后置解释或中间桥接文字，召回时无法独立理解。
2. 层级信息利用不足：仅看相邻段落的方法无法利用父标题路径、同级条款之间的关系。
3. 细碎章节尺寸失衡：规章、标准、合同等文档常包含大量 100~300 token 的细碎条款，若不合并则块过短、语义稀薄；若仅按相邻长度合并又会跨主题污染。
4. 长块二次拆分破坏结构：章节过长时，常规字符切分会忽略表格行边界和标题层级。

P 策略仅对 native 抽取引擎生成的 .blocks.jsonl 结构化产物有效；对非结构化输入会自动降级为 R 策略（见 §8）。

1.2 P / R / V 三种策略对比

1.3 怎么选

1.4 P 策略的代价

• 必须搭配 native 引擎：在 LIGHTRAG_PARSER 中显式声明，例如 docx:native-P；否则即使写了 P，也会因为缺少 .blocks.jsonl 退化到 R。
• 仅支持 DOCX：其他格式没有 .blocks.jsonl 产物。
• 算法路径多、阈值多：调试时需要先确认输入 sidecar 是否正确，再看各阶段输出。

2. 工作原理总览

P 策略以 native parser 在 fixlevel=0 模式下产生的 .blocks.jsonl 为输入，每个 type == "content" 行被视为一个标题级基础块，然后在该基础上执行表格切片、长块拆分和层级合并：

DOCX
  ↓  native parser (fixlevel=0)
.blocks.jsonl + sidecar (.tables.json / .equations.json / .drawings.json / .blocks.assets/)
  ↓  Stage B：超大表格按行边界切片并赋予 first/middle/last 角色
  ↓  Stage B.1：连续大表之间桥接文字双向重叠
  ↓  Stage C：锚点驱动的长文本块再切分
  ↓  Stage D：层级感知的双相位合并
  ↓  Stage E：[part n] 行级来源追溯编号
最终 chunk 列表

P 策略的关键不变量：

1. 章节边界不会重叠：不同 .blocks.jsonl 内容行之间的文本绝不会被复制到对方块里，避免“张冠李戴”。
2. 章节内长正文可重叠：同一个内容行内拆分的多个片段允许按 chunk_overlap_token_size 保留 R 风格 overlap，减少长正文中途切断。
3. 表格之间桥接文字可双向重叠：唯一的跨段落复制场景，专门服务连续大表的上下文保留。
4. 表格行不互相重叠：行级切片本身是非重叠的，与 R 的 overlap 概念不同。

3. 输入与输出

3.1 输入

chunking_by_paragraph_semantic() 接收以下输入：

P 策略不接收 split_by_character / split_by_character_only，因为正常路径由标题和段落结构驱动。

3.2 .blocks.jsonl 约定

P 策略只处理 type == "content" 行。每个内容行通常包含：

• content：该标题下的正文文本，可能包含普通段落、<table ... /> 标签、<equation ... /> 公式、<drawing ... /> 图形。
• heading：当前标题。
• parent_headings：父级标题链。
• level：标题级别（19，对应原始 outline level 08）。
• positions：原始段落定位（用于追溯）。

native parser 的 fixlevel=0 模式保证「一条标题下的正文作为一个基础块」，不在解析阶段做 token 阈值拆分。表格保持完整插入到 content 中。

3.3 输出

最终输出为有序 chunk 列表，每个元素：

{
    "tokens": int,                    # 真实 token 数（合并后会复测）
    "content": str,                   # 块文本（可能包含 <table> 标签）
    "chunk_order_index": int,         # 块顺序索引
    "heading": str,                   # 拆分后追加 [part n] 后缀
    "parent_headings": list[str],     # 父级标题链，不追加后缀
    "level": int,                     # 标题层级
}

实现内部还会临时使用 paragraphs、table_chunk_role、uuid、uuid_end、type 等字段辅助拆分和合并，但不会进入最终输出。

3.4 [part n] 后缀规则

• 同一个原始 .blocks.jsonl 内容行被拆成多个片段时，所有片段的 heading 字段追加 [part 1]、[part 2] …
• 未发生拆分的内容行保持原 heading 不变。
• parent_headings 不追加后缀。
• 编号在每个原始内容行内独立重置。
• 旧的 [表格片段N] 后缀已统一由 [part n] 替代。

4. 关键阈值

P 策略的阈值不是固定常量，而是按 chunk_token_size（记为 N）动态推导：

比例约束关系：table_max < target_ideal < target_max、table_ideal < table_max。这些比例源自审计模式经验值（大块 8000、小表 5000、理想表 3000、表格尾块 1600），现按 chunk_token_size 等比缩放。

5. Stage A：标题级基础块

标题识别由 native parser 完成，P chunker 自身不扫描 docx body、也不判断标题样式。

native parser 在 fixlevel=0 模式下：

1. 读取 styles.xml，按 <w:basedOn> 建立样式继承链，回溯有效 <w:outlineLvl>。
2. 遍历 document.xml 段落，沿继承链解析大纲级别；原始 outline level 08 映射为内部 level 19。
3. 维护 current_heading_stack，遇新标题时清理不浅于当前 level 的旧标题，计算 parent_headings。
4. 将表格、公式、图形分别提取为单行标签（<table id="..." format="json">...</table> 等），写入对应 sidecar。
5. 所有可识别标题均触发基础块边界，不执行 token 阈值拆分。

P chunker 直接读取 .blocks.jsonl，每个 content 行作为后续 Stage B/C 的独立处理单元。这意味着 [part n] 编号按每个原始 content 行独立重置。

6. Stage B：超大表格行边界切片

Stage B 只处理 token 数超过 table_max 的表格。其目标不是单纯拆表，而是在行边界优先拆分的基础上保留表格边界上下文。

6.1 行边界优先切片

• format="json"：按 JSON 顶层行数组切片。
• format="html"：按 <tr>...</tr> 行切片。
• 未显式标注但内容可嗅探为 JSON / HTML 的表格同样按上述规则处理。

切片前预扣 <table {attrs}></table> 外壳 token 开销，使重新包裹后的切片尽量不超过 table_max。每个切片重新包裹为合法的 <table> 标签，便于下游解析。

6.2 行级递归二次切片

若某个行子集重新包裹后仍超过 table_max，则在该行子集内继续细分。只有切片已经收敛到单行、且该单行自身超过限制时，才退化为字符级切分。该机制使可被行边界表达的表格内容尽量保留合法表格结构。

6.3 末片回吞

若表格末片 token 数低于 table_min_last，且与前一切片合并后不超过 table_max，则将末片回吞至前一切片，减少无效短表格块。

6.4 表格切片角色与物理粘连

每个表格切片被赋予内部字段 table_chunk_role，并按角色决定与周围段落的粘连方式：

table_chunk_role 是内部字段，最终输出不会保留，但在 Stage D 中继续作为合并约束使用（见 §9.1）。

7. Stage B.1：连续大表桥接文字双向重叠

当同一原始内容行中出现「大表 A、短桥接文字、大表 B」的模式，且两张表均被拆分时，桥接文字按上下文预算进行双向分配：

1. 将桥接文字按 token 编码。
2. 计算左侧预算 prev_budget = min(chunk_overlap_token_size, target_max - 左侧末切片当前 token 数)。
3. 计算右侧预算 next_budget = min(chunk_overlap_token_size, target_max - 右侧首切片当前 token 数)。
4. 若桥接文字长度同时不超过两侧预算：左右两个表格边界块都包含完整桥接文字。
5. 若桥接文字较长：前缀进入左侧末切片块，后缀进入右侧首切片块；超出两侧预算的中间段独立成为普通文本块。

单侧预算还会被限制到不超过 chunk_token_size / 2，避免桥接文字主导整个块。

这与普通相邻 chunk overlap 的差异：

• 普通 overlap 按前后顺序复制字符或 token，与边界类型无关。
• B.1 机制以表格切片角色为触发条件，把桥接文字同时作为左表后文上下文和右表前文上下文，避免桥接说明只归属一侧表格或被单独切散后难以召回。

8. Stage C：锚点驱动的长文本块再切分

Stage C 处理 Stage B 后仍超过 target_max 的内容块。

8.1 短段落锚点

把内容按段落恢复，选择满足以下条件的段落作为候选锚点：

• 段落不是表格（不以 <table 开头）。
• 段落文本长度不超过 max_anchor_candidate_length（100 字符）。
• 段落不是该块的第一个段落（避免递归无法收敛）。

8.2 均衡选锚

根据目标子块数量计算理想切分位置，从候选锚点中选择距离理想位置最近的锚点。被选中的锚点晋升为后续子块的新 heading，原 heading 写入该子块的 parent_headings。

8.3 无锚点降级

若不存在合格锚点：

1. 表格优先：若块内仍存在超限表格，优先调用 Stage B 的行边界切片。
2. 贪心打包：其余文本按段落贪心打包到接近 target_max。
3. 递归字符切分：单一过长普通文本段落降级到 R 策略（chunking_by_recursive_character），使用 chunk_overlap_token_size 保持相邻文本片段的连续性。

无锚点 fallback 路径保证算法不会丢弃内容，并尽量遵守用户配置的块大小上限。

9. Stage D：层级感知的双相位合并

Stage D 解决细碎章节场景下「块过碎」和「跨主题污染」的矛盾。核心思想是自深层级向浅层级处理，先合并同级小块，再允许浅层块吸收深层块，同时引入尺寸约束、表格切片角色约束和标题路径约束。

9.1 D.0 合并约束（每次合并都要满足）

1. 尺寸约束：合并后的真实文本 token 数不超过 target_max；已达到 target_ideal 的块原则上不继续参与普通同级合并。
2. 角色约束：middle 表格切片锁定独立；first、last 按方向参与合并，防止表格边界上下文被错误吞并。
3. 层级约束：同级合并在相同 level 之间发生；跨级吸收只允许浅层吸收深层，禁止深层反向吸收浅层。
4. 父标题路径一致性约束：相邻块的 parent_headings 一致，或处于同一父标题路径所限定的连续范围内。这是避免跨主题污染的关键。

9.2 D.1 Phase A：同级合并

针对当前 level 的相邻块，若两者均低于 target_ideal，且满足上述约束，则合并为一个块。

表格切片角色的方向规则：

9.3 D.2 尾部整批吸收

若一个已达到 target_ideal 的块后面紧跟一串同级小块，且该串小块总 token 数低于 small_tail_threshold、合并后真实 token 数不超过 target_max，则一次性吸收该串小块。遇到 middle 表格切片时停止。

9.4 D.3 Phase B：跨级吸收

对于 Phase A 后仍未饱和的小块，尝试跨级合并，但仅允许浅层吸收深层：

• 当前块比后一块更浅时，当前块可向后吸收后一块。
• 当前块比前一块更深时，前一浅层块可吸收当前块。
• 反方向合并被禁止。
• 跨级阶段允许 last 角色向后吸收；middle 仍不参与合并。

9.5 D.4 合并后真实 token 复测

由于合并时会插入换行连接符，逐块 token 数相加可能低估合并结果。每次提交合并前，都要对拼接后的真实文本重新计算 token 数，确认不超过 target_max 后再提交。

合并后保留主块的 heading。如果多个 part 片段被合并，最终 heading 保留主块的 part 后缀，不会额外拼接多个 part 标签。

10. Fallback 与降级路径

P 策略有多层降级保护：

重要：整体 fallback 后不再具备标题层级、表格角色和桥接文字双向重叠能力；但能保证文档仍产生检索块，不因结构化 sidecar 缺失而被静默丢弃。

11. 配置项

配置语法、优先级链、addon_params["chunker"] 运行时改值等详见 FileProcessingConfiguration-zh.md §3。

启用 P 的典型 LIGHTRAG_PARSER 写法：

LIGHTRAG_PARSER=docx:native-P,*:legacy-R
CHUNK_P_SIZE=2000
CHUNK_P_OVERLAP_SIZE=100

或在单文件覆盖：

my-proposal.[native-P].docx

12. 分块效果检验

12.1 检查 sidecar 是否生成

确认 native parser 是否成功产生 .blocks.jsonl：

ls -l INPUT/__parsed__/<doc>.docx.parsed/<doc>.blocks.jsonl

若文件不存在或为空，P 策略会整体降级为 R，不会获得 P 的任何收益。常见原因：

• 未配置 LIGHTRAG_PARSER=docx:native-...。
• 解析失败（看 pipeline_status 错误条目）。
• 文档不是 DOCX（其他格式不支持 P）。

12.2 检查 blocks.jsonl 内容

每行一个 JSON，过滤 type == "content" 后查看 heading / level / parent_headings 是否符合预期：

jq -c 'select(.type=="content") | {level, heading, parent_headings}' \
   INPUT/__parsed__/<doc>.docx.parsed/<doc>.blocks.jsonl | head

若 heading 大量为空或 level 异常，说明 native parser 没正确识别标题样式 —— 此时 P 策略的层级合并和锚点提升都会失效。

12.3 检查最终 chunks

查看 text_chunks 存储中的 chunk 元数据：

jq '.[] | {heading, level, tokens, parent_headings}' \
   rag_storage/kv_store_text_chunks.json | head -30

应观察到：

• 大表前后块的 heading 通常对应 [part 1] / [part n]（说明 Stage B 拆分发生）。
• 细碎条款被合并到接近 target_ideal 的块（说明 Stage D 生效）。
• parent_headings 在不同章节切换处发生跳变，同章节内保持稳定。

12.4 块尺寸分布检验

理想分布：大多数 chunk 落在 [target_ideal, target_max] 区间（即 N=2000 时约 1500~2000 token）；明显偏小的块通常是 middle 表格切片（锁定独立）或紧靠章节边界的尾块。

若出现大量低于 small_tail_threshold 的尾块，可能是：

• 父标题路径一致性约束过严（不同 parent_headings 的相邻小块无法合并）。
• 大量 middle 表格切片堆积（表格本身就很大）。

13. 错误调试

13.1 P 没生效，输出与 R 一致

按以下顺序排查：

1. full_docs[doc_id].process_options 是否包含 P？
2. full_docs[doc_id].parse_format 是否为 lightrag？若为 raw，说明走的是 legacy 路径，P 会自动降级到 R。
3. lightrag_document_path 指向的 .blocks.jsonl 是否存在、是否非空？
4. 日志中是否有 paragraph_semantic ... fallback to recursive_character 字样？

13.2 表格被切散、前后说明分离

• 检查表格是否真的被识别为 <table format="json"> 或 <table format="html">（看 .blocks.jsonl）。未识别格式的表格只能走字符切分，无法启动 Stage B 的角色机制。
• 检查表格 token 数是否真的超过 table_max。低于阈值的表格保持完整，不会触发首/中/末切片。
• 若是连续大表，确认两张表之间的桥接文字是否在同一 content 行内 —— 跨 content 行的桥接不参与 B.1 双向重叠。

13.3 细碎条款没有被合并

• 检查相邻条款的 parent_headings 是否一致：父标题路径一致性约束会阻止跨主题合并。
• 检查 level 是否一致：同级合并要求相同 level，跨级吸收只允许浅吸深。
• 检查中间是否插入了 middle 表格切片：会阻断尾部整批吸收。

13.4 出现单个超过 target_max 的块

正常情况下 Stage D 的真实 token 复测会拒绝超限合并，但以下场景仍可能出现超限块：

• 单行表格自身超过 target_max，无锚点可拆，最终走 R 字符切分但单 chunk 仍超限。
• enforce_chunk_token_limit_before_embedding 在 embedding 前会做最后的硬切分，下游不会真把超限 chunk 嵌入向量库。

13.5 [part n] 后缀异常

• 同一原始 content 行拆出多片但只看到一个 [part 1]：检查是否在 Stage D 中被合并 —— 合并后保留主块的 part 后缀，不拼接多个。
• 出现旧式 [表格片段N] 后缀：说明使用了旧版 chunker 输出的数据，新版统一为 [part n]，需要重新分块。

13.6 日志关键字

P 策略相关日志关键字（用于 grep 排查）：

• paragraph_semantic — 模块入口
• fallback to recursive_character — 整体或单段落降级
• table_chunk_role — 表格角色相关
• bridge — Stage B.1 桥接文字处理
• anchor — Stage C 锚点选择