RAG on 边个濑椰的博客

稀疏向量与 SPLADE 模型

Tue, 12 May 2026 16:17:17 +0800

参考网站

稀疏向量与 SPLADE 模型

在 RAG 系统里，dense vector 已经是最常见的召回方式。它把文本映射到连续向量空间中，适合捕捉语义相近的表达，例如“员工离职流程”和“人员退出手续”。但 dense vector 也有明显短板：它不一定擅长精确匹配实体、编号、术语、错误码、产品型号、表格字段名和代码片段。

这时 sparse vector 就有价值了。它更像一个“神经网络增强版倒排索引”：文本仍然被表示为词项维度上的稀疏权重，但这些权重不是 BM25 这类纯统计方法算出来的，而是由模型预测出来的。

简单说：

dense vector 负责语义相似。
BM25 负责原词匹配。
SPLADE sparse vector 负责神经词项扩展后的加权匹配。
Hybrid Search 则把 dense 和 sparse 两种召回结果融合起来。

论文模型

SPLADE 基于 Masked Language Model 的 logits，把一段文本映射到词表空间中。假设词表里有 30522 个 WordPiece token，那么每个文本最终可以表示为：

1

token_id -> weight

也就是一个稀疏向量。大部分 token 的权重为 0，只有少量被模型认为重要的 token 会有非零权重。

这和普通 embedding 最大的区别是：dense embedding 的每一维通常不可解释，而 sparse vector 的维度就是词表 token。一个被模型激活的 token 可以理解为“这段文本与这个词项相关”。

例如一段文档没有显式出现“报销”，但出现了“差旅费”“发票”“审批单”，SPLADE 可能会激活与“报销”相关的 token。这样在查询“报销流程”时，即便文档没有完全命中原词，也可能被召回。

更具体地说，SPLADE 会利用 Masked Language Model 层的 logits，在 BERT WordPiece 词表中预测每个词项的重要性。假设输入文本在分词后是：

$$ t=(t_{1},t_{2},...,t_{N}) $$

对应的上下文表示是：

$$ (h_{1},h_{2},...,h_{N}) $$

那么对输入中第 $i$ 个 token，模型会计算它对词表中第 $j$ 个 token 的重要性：

$$ w_{ij}=transform(h_{i})^{T}E_{j}+b_{j}, \quad j\in\{1,...,|V|\} $$

这里 $E_j$ 词表 ${token}_j$ 的 BERT 输入嵌入，$b_j$ 是 token 级偏置，transform(.) 通常是带 GeLU 和 LayerNorm 的线性变换。直觉上，这一步是在问：输入里的这个位置，和词表里的每个词项分别有多相关。

但检索时需要的不是“某个位置对某个词的分数”，而是“整段文本对某个词的分数”。因此 SPLADE 会把不同位置的激活聚合成整段文本的稀疏表示：

$$ w_{j}=\sum_{i\in t}\log(1+ReLU(w_{ij})) $$

这个公式里有三层含义：

ReLU 把负分清零，只保留正向相关的词项。
$log(1+x)$ 做对数饱和，避免高频词或重复词的分数被无限放大。
$\sum$ 把不同位置对同一个词表 token 的激活累加起来，得到整段文本的词项权重。

最后，文本就变成了一个很高维但很稀疏的向量：

1

token_id -> weight

查询和文档都映射到同一个词表空间后，检索分数就是稀疏向量点积：

$$ s(q,d)=\sum_j w_j^q w_j^d $$

这也是 SPLADE 能接入倒排索引或稀疏向量索引的原因。

排序损失

训练时，SPLADE 要让相关文档得分更高，不相关文档得分更低。给定一个查询 $q_i$ 、一个正样本文档 $d_i^+$ 、一个困难负样本 $d_i^-$ ，以及一组批内负样本 ${d_{i,j}^{-}}$ ，可以使用类似下面的对比排序损失：

$$ \mathcal{L}_{rank-IBN} = -\log \frac{e^{s(q_i,d_i^+)}} {e^{s(q_i,d_i^+)} + e^{s(q_i,d_i^-)} + \sum e^{s(q_i,d_{i,j}^{-})}} $$

它的目标很直接：让正样本在候选集合里的概率尽可能大。工程上可以理解为，模型会不断学习哪些词项扩展能帮助它把正确文档排到前面。

FLOPS 稀疏正则

如果只优化排序效果，模型可能会激活太多 token。这样虽然召回可能变强，但倒排索引会膨胀，查询时需要访问的 posting list 也会变多。

因此 SPLADE 引入 FLOPS 正则来控制稀疏性。对一批文档来说，可以先估计词表 token (j) 在这批文档中的平均激活：

$$ \overline{a}_{j}=\frac{1}{N}\sum_{i=1}^{N}w_{j}^{(d_i)} $$

然后对平均激活做平方求和：

$$ l_{FLOPS}=\sum_{j\in V}\overline{a}_{j}^{2} =\sum_{j\in V}(\frac{1}{N}\sum_{i=1}^{N}w_{j}^{(d_i)})^{2} $$

这个正则项不是简单控制“向量维度”，而是在控制非零 token 的数量和分布。它希望模型不要把大量文档都绑定到少数高频词上，也不要让每个文档都激活过多词项。

因此，稀疏性权重可以理解为一个召回质量和检索成本之间的旋钮：

权重更大：稀疏向量更短，索引更小，检索更快，但可能损失召回。
权重更小：稀疏向量更长，扩展更丰富，但索引和检索成本更高。

总体损失

最终，SPLADE 会把排序损失和稀疏正则放在一起训练：

$$ \mathcal{L}=\mathcal{L}_{rank-IBN} +\lambda_q\mathcal{L}_{reg}^{q} +\lambda_d\mathcal{L}_{reg}^{d} $$

其中 (\lambda_q) 控制查询侧稀疏性，(\lambda_d) 控制文档侧稀疏性。查询侧通常对延迟更敏感，所以查询侧稀疏性非常重要。文档侧可以离线计算，通常可以接受更高一点的计算成本，但仍然要控制索引体积。

从求和到最大池化

原始 SPLADE 会对输入文本中每个位置的词项预测进行聚合：

$$ w_{j}=\sum_{i\in t}\log(1+ReLU(w_{ij})) $$

后续更常见的 SPLADE-max 使用最大池化：

$$ w_{j}=\max_{i\in t}\log(1+ReLU(w_{ij})) $$

这并不是整段文本只保留一个 token，而是对词表里的每个维度分别取最大激活值。这样可以减少长文本或重复词带来的累加放大，让表示更关注“是否强烈激活某个语义词项”，而不是简单依赖出现次数。

SPLADE-doc 与蒸馏训练

标准 SPLADE 会同时编码 query 和 document。也就是说，查询侧和文档侧都可能产生神经扩展词项，检索时计算的是：

$$ s(q,d)=\sum_j w_j^q w_j^d $$

SPLADE-doc 则更偏工程效率。它只在文档侧做 SPLADE 编码，查询侧通常只使用原始 query token，文档得分可以写成：

$$ s(q,d)=\sum_{j\in q}w_j^d $$

这样文档侧扩展可以离线预计算，查询侧不需要跑 SPLADE encoder，延迟会更低。代价是 query 侧没有神经扩展能力，只能利用“文档侧扩展”。

另外，很多效果较强的 SPLADE 模型会使用知识蒸馏和困难负样本。常见做法是先训练一个第一阶段检索器和 cross-encoder 重排器，再用更难的负样本和重排器分数继续训练。工程上不用自己复现这套训练流程，也能使用公开模型；但理解这一点有助于判断模型名称里 distil、ensemble、cocondenser 这类词为什么会出现。

稀疏性为什么重要

如果模型把大量 token 都激活，召回效果也许会上升，但索引会变大，检索会变慢。SPLADE 使用 FLOPS 正则化来控制非零 token 的数量和分布。

工程上可以把它理解为：稀疏向量不是越长越好。

非零 token 太少：索引小、检索快，但召回可能不够。
非零 token 太多：召回可能更好，但索引膨胀，检索成本上升。

落地时通常还会做二次裁剪，例如：

只保留 top_k 个 token
过滤 weight 低于阈值的 token
限制单个 chunk 的最大稀疏维度数量

这些参数往往比模型本身更影响线上成本。

模型选择

SPLADE 更像一类稀疏神经检索方法，而不是单一模型。Naver 官方仓库也特别提醒：不同正则化强度会得到从“非常稀疏”到“强 query/doc 扩展”的不同模型，效果、索引大小和延迟都会变。

如果只是想快速做工程验证，可以从 naver/splade-cocondenser-ensembledistil 开始。它是官方 SPLADE++ 系列里常见的强效果模型，在 Naver 官方仓库列出的 MS MARCO dev MRR@10 为 38.3，高于 splade_v2_max 的 34.0 和 splade_v2_distil 的 36.8。它适合先验证 sparse 召回是否能补足 dense 的关键词、实体、术语召回缺口。

如果更看重推理成本，可以看 naver/splade_v2_max 或 efficient SPLADE 系列。splade_v2_max 结构简单，Hugging Face 模型页标注为 DistilBERT base、512 token 最大长度、30522 维输出、点积相似度。efficient SPLADE 系列则进一步区分 document encoder 与 query encoder，目标是降低查询侧延迟。

一个实用的选型顺序是：

先选一个效果强的公开模型做离线评测，例如 naver/splade-cocondenser-ensembledistil。
如果离线评测有效，再统计平均非零 token 数、索引大小、文档侧编码吞吐和查询侧 P95 延迟。
如果查询侧太慢，优先尝试 query 缓存、ONNX/OpenVINO、量化或 efficient SPLADE。
如果索引太大，优先调小 top-k、提高最小权重阈值，或选择更强正则化、更稀疏的模型。
如果业务语料和公开英文检索数据差异很大，再考虑用领域数据微调，而不是直接相信公开榜单。

不要只按 MRR 选模型。SPLADE 选型至少要同时看五件事：检索效果、平均非零维度、索引体积、查询延迟、部署复杂度。

Sentence Transformers 现在提供了 SparseEncoder，可以直接加载 SPLADE 模型：

1
2
3
4


from sentence_transformers import SparseEncoder

model = SparseEncoder("naver/splade-cocondenser-ensembledistil")
embeddings = model.encode(["example query"])

它也提供 encode_query()、encode_document()、稀疏度统计、Qdrant/Elasticsearch/OpenSearch 集成，以及 ONNX/OpenVINO/量化相关部署能力。工程上可以优先用这条路线做原型，再根据性能瓶颈决定是否切到自定义推理服务。

SPLADE 和 BM25 的区别

BM25 和 SPLADE 都可以使用倒排索引完成检索，但权重来源不同。

BM25 的权重来自统计量，例如 TF、IDF 和文档长度归一化。它主要依赖 query 原词和 document 原词的精确匹配。

SPLADE 的权重来自神经模型预测。它不仅可以保留原文出现的 token，也可能激活原文没有出现但语义相关的 token。

因此可以粗略理解为：

1
2


BM25 = 原始词项的统计匹配
SPLADE = 神经扩展词项的加权匹配

在企业知识库、技术文档、客服 FAQ、代码文档、规范制度等场景中，BM25 和 SPLADE 都很有价值。BM25 更轻，SPLADE 更强但成本更高。

RAGFlow切片策略解析

Tue, 14 Apr 2026 20:06:34 +0800

RAGFlow 切片策略解析

众所周知RAGFlow是较早成熟且开源的RAG项目之一，近日笔者正在学习构建一个RAG项目，所以从RAGFlow的源码下手。首先学习的是它对markdown文件的解析方法和切片策略。

`rag/app/naive.py`

naive.py 中支持很多文件的类型，比如PDF, DOCX, Markdown……

那么我们要学习的markdown类，主入口是__call__()，这是核心方法，编排了整个 Markdown 解析流程。

`call()`

1

def __call__(self, filename, binary=None, separate_tables=True, delimiter=None, return_section_images=False):

参数	类型	说明
`filename`	str	文件路径（当 `binary` 为空时用来读文件）
`binary`	bytes	文件二进制内容，优先使用
`separate_tables`	bool	是否将表格从正文中分离出来
`delimiter`	str	自定义分割符，如果指定则用分割符切分而非按元素类型切分
`return_section_images`	bool	是否额外返回每个 section 对应的图片

执行流程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


Step 1: 文本解码
 ┌────────────────────────────┐
 │ binary → find_codec() → │
 │ decode(encoding) │
 │ 或 open(filename).read() │
 └────────────┬───────────────┘
 ↓
Step 2: 表格提取（继承自父类）
 ┌────────────────────────────────────────────────────┐
 │ self.extract_tables_and_remainder(txt+"\n", │
 │ separate_tables) │
 │ → (remainder, tables[]) │
 │ │
 │ 注意：这里传入的是 txt+"\n"（末尾补换行） │
 └────────────┬───────────────────────────────────────┘
 ↓
Step 3: 元素扫描
 ┌────────────────────────────────────────────────────┐
 │ MarkdownElementExtractor(txt) │
 │ .extract_elements(delimiter, include_meta=True) │
 │ → element_sections[] │
 │ │
 │ ★ 关键：这里传入的是原始 txt，而非 remainder！ │
 │ （注释 L682-683 说明了原因：为避免重复表格） │
 └────────────┬───────────────────────────────────────┘
 ↓
Step 4: 图片 URL 提取
 ┌────────────────────────────────────────────────────┐
 │ self.extract_image_urls_with_lines(txt) │
 │ → image_refs = [{url, line}, ...] │
 └────────────┬───────────────────────────────────────┘
 ↓
Step 5: 元素-图片关联（核心融合逻辑）
 ┌────────────────────────────────────────────────────┐
 │ for element in element_sections: │
 │ ① 取 element 的 start_line ~ end_line │
 │ ② 筛选行范围内的 image_refs │
 │ ③ load_images_from_urls() 下载图片（有缓存） │
 │ ④ 多张图用 concat_img 合并为一张 │
 │ ⑤ sections.append((content, "")) │
 │ ⑥ section_images.append(combined_image or None) │
 └────────────┬───────────────────────────────────────┘
 ↓
Step 6: 表格后处理
 ┌────────────────────────────────────────────────────┐
 │ for table in tables: │
 │ markdown(table, extensions=["tables"]) → html │
 │ tbls.append(((None, html), "")) │
 └────────────┬───────────────────────────────────────┘
 ↓
Step 7: 返回结果
 ┌────────────────────────────────────────────────────┐
 │ if return_section_images: │
 │ return sections, tbls, section_images │
 │ else: │
 │ return sections, tbls │
 └────────────────────────────────────────────────────┘

输出数据结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


sections = [
 ("## 标题\n正文内容...", ""), # (文本, 位置标签—永远为空字符串)
 ("```python\ncode\n```", ""), # 代码块
 ...
]

tbls = [
 ((None, "<table>...</table>"), ""), # (None, HTML表格字符串)
 ...
]

section_images = [
 PIL.Image, # 该 section 中所有图片合并后的图像对象
 None, # 该 section 无图片
 PIL.Image,
 ...
]

这其中最关键的是表格提取和元素扫描的部分：

`extract_tables_and_remainder()`

这个方法定义于deepdoc/parser/resume/markdown_parser.py的RAGFlowMarkdownParser类中，用于将markdown中的表格提取出来

1
2
3
4
5
6


class RAGFlowMarkdownParser:
 def __init__(self, chunk_token_num=128):
 self.chunk_token_num = int(chunk_token_num)

 def extract_tables_and_remainder(self, markdown_text, separate_tables=True):
 # 返回: (剩余正文, [表格列表])

表格识别策略：

类型	正则	示例
有边框 Markdown 表格	`	…
无边框 Markdown 表格	`text	text` + 分隔行 + 数据行
HTML 表格	`<table>...</table>`，支持包裹在 `<html><body>` 中	`<table><tr><td>...</td></tr></table>`

当 separate_tables=True 时，表格从正文里移除并单独返回；为 False 时则就地转为 HTML。

`MarkdownElementExtractor`

该类位于deepdoc/parser/markdown_parser.py，实现了一个简易的 Markdown 元素识别器，将文本按行扫描并归类为不同的块类型。

1
2
3
4
5
6
7


class MarkdownElementExtractor:
 def __init__(self, markdown_content):
 self.markdown_content = markdown_content
 self.lines = markdown_content.split("\n")

 def extract_elements(self, delimiter=None, include_meta=False):
 """提取各种元素(headers, code blocks, lists, 等)"""

输出元素结构：

1
2
3
4
5
6


{
 "type": "header" | "code_block" | "list_block" | "blockquote" | "text_block",
 "content": "具体文本内容",
 "start_line": 0, # 起始行号
 "end_line": 5, # 结束行号
}

_extract_header() : 返回单行的"header"
_extract_code_block() : 直到遇到" ``` “返回多行的代码块"code_block”
_extract_list_block() : 吞入满足以下条件的行：
- 以 -, *, + 或 数字. 开头（列表项）
- 空行（列表项间隙）
- 以 2+ 空格缩进的子列表或续行
_extract_blockquote() : 持续吞入">“开头的行或内部的空行
_extract_text_block() : 处理不属于上面几种类型的普通文本"text_block”，直到符合上面类型的元素再次出现

`extract_image_urls_with_lines()`

这个方法用于找出 Markdown 文本中所有图片引用及其所在行号。行号用于后续将图片关联到对应的 section。

三阶段提取策略：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


阶段 1: Markdown 语法图片

 正则: ![alt](url) → 提取 url

 模式: r"!\[[^\]]*\]\(([^)\s]+)"

阶段 2: HTML 内联图片（单行）

 正则: src="url" / src='url' → 提取 url

 模式: r'src=["\\\'"]([^"\\\'>\\s]+)'

阶段 3: HTML 跨行图片（BeautifulSoup 兜底）

 解析整个文本为 HTML，查找所有 <img> 标签的 src

 通过字符偏移量计算行号

 用 seen 集合避免与阶段 1/2 重复

返回值：

1
2
3
4
5


[
 {"url": "https://example.com/img.png", "line": 5},
 {"url": "./assets/diagram.svg", "line": 12},
 ...
]

`load_images_from_urls()`

1
2


def load_images_from_urls(self, urls, cache=None):
 # 返回: (images[], cache{})

功能	细节
HTTP 图片	`requests.get(url, timeout=30)`，校验 `Content-Type` 为 `image/`
本地图片	`Path(url).exists()` 检查后用 `PIL.Image.open()`
缓存机制	`cache` dict 避免重复下载同一 URL
统一格式	所有图片转为 `RGB` 模式 (`convert("RGB")`)
错误处理	失败时 `cache[url] = None`，不中断流程

这里的思路比较朴素，但很实用：

先根据 url 判断是网络图片还是本地图片
统一加载成 PIL.Image
放入缓存，避免同一张图在多个 section 中重复读取
后续如果某个 section 对应多张图片，再交给 concat_img 合并

也就是说，RAGFlow 在 Markdown 中并不是把每一张图片都单独当成一个 chunk，而是先尝试把同一个 section 内的图片聚合起来，再与文本一起进入后续流程。

`urls_in_section = [...]`

在 Markdown.__call__() 中，真正把文本 section 和图片联系起来的代码是这一段：

1
2
3
4
5


for element in element_sections:
 content = element["content"]
 start_line = element["start_line"]
 end_line = element["end_line"]
 urls_in_section = [ref["url"] for ref in image_refs if start_line <= ref["line"] <= end_line]

其核心思想非常直接：按行号做区间归属。

一个 Markdown 元素先被标记 start_line 和 end_line
所有图片引用也带有自己的 line
只要图片所在行落在元素区间内，就认为这张图属于这个 section

这是一种很工程化的做法。它不追求复杂语义理解，而是利用 Markdown 本身“按行组织”的特点，以较低成本建立图文关联。

例如下面这段 Markdown：

1
2
3
4
5
6
7


## 模型结构

这里介绍整体流程。

![pipeline](./pipeline.png)

接着说明各模块职责。

如果这一整段被 MarkdownElementExtractor 视为同一个 text_block，那么图片就会和这一段正文绑定在一起；如果标题和正文被分成两个元素，则图片通常会归到正文所在的 section，而不会归到标题 section。

表格处理细节

前面提到，Markdown.__call__() 中虽然调用了：

1

remainder, tables = self.extract_tables_and_remainder(f"{txt}\n", separate_tables=separate_tables)

但后面真正做元素扫描时，使用的是：

1

extractor = MarkdownElementExtractor(txt)

而不是 remainder。

源码里其实已经留了注释：

1
2
3


# To eliminate duplicate tables in chunking result, uncomment code below and set separate_tables to True ...
# extractor = MarkdownElementExtractor(remainder)
extractor = MarkdownElementExtractor(txt)

这说明作者其实也意识到了一个现象：表格可能同时出现在 section chunk 和 table result 中。

从实现角度看，这未必是 bug，更像是一种偏保守的召回策略：

正文 chunk 中保留表格原始上下文
tables 中再额外保留结构化表格内容

这样做可能带来一定冗余，但也提高了检索时命中表格信息的概率。

`chunk()`

看到这里，其实还只是完成了解析和预处理。真正决定最终 chunk 长什么样的，不在 Markdown.__call__()，而在 rag/app/naive.py 下面的 chunk() 函数里。

Markdown 文件分支一开始会先调用前面的解析器：

1
2
3
4
5
6
7
8


markdown_parser = Markdown(int(parser_config.get("chunk_token_num", 128)))
sections, tables, section_images = markdown_parser(
 filename,
 binary,
 separate_tables=False,
 delimiter=parser_config.get("delimiter", "\n!?;。；！？"),
 return_section_images=True,
)

这里有两个细节值得注意：

return_section_images=True 说明 Markdown 解析阶段生成的图片不会丢，而是继续带到后面的 chunk 合并流程中。
separate_tables=False 说明这里并没有把表格完全从正文切走，而是倾向于让表格继续留在 Markdown 上下文里，同时又额外生成 tables 供表格索引使用。

接着，如果当前租户存在 IMAGE2TEXT 模型，chunk() 会尝试给 Markdown 中的图片补一段描述文本：

1
2
3
4
5
6


try:
 vision_model_config = get_tenant_default_model_by_type(kwargs["tenant_id"], LLMType.IMAGE2TEXT)
 vision_model = LLMBundle(kwargs["tenant_id"], vision_model_config)
except Exception as e:
 logging.warning(f"Failed to detect figure extraction: {e}")
 vision_model = None

如果视觉模型可用，则继续遍历每个 section：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


for idx, (section_text, _) in enumerate(sections):
 images = []
 if section_images and len(section_images) > idx and section_images[idx] is not None:
 images.append(section_images[idx])

 if images and len(images) > 0:
 combined_image = reduce(concat_img, images) if len(images) > 1 else images[0]
 markdown_vision_parser = VisionFigureParser(
 vision_model=vision_model,
 figures_data=[((combined_image, ["markdown image"]), [(0, 0, 0, 0, 0)])],
 **kwargs
 )
 boosted_figures = markdown_vision_parser(callback=callback)
 sections[idx] = (
 section_text + "\n\n" + "\n\n".join([fig[0][1] for fig in boosted_figures]),
 sections[idx][1]
 )

这里可以看出 Markdown 图片增强的几个特点：

粒度是 section 级别
输入图片是前面已经聚合好的 section_images[idx]
输出不是新的 chunk，而是把图片描述文本直接追加回原 section_text

`VisionFigureParser`

该类定义在 deepdoc/parser/figure_parser.py 中：

1
2
3
4
5
6


class VisionFigureParser:
 def __init__(self, vision_model, figures_data, *args, **kwargs):
 self.vision_model = vision_model
 self.figure_contexts = kwargs.get("figure_contexts") or []
 self.context_size = max(0, int(kwargs.get("context_size", 0) or 0))
 self._extract_figures_info(figures_data)

这个类的职责并不复杂，可以理解为一个“图片描述批处理器”：

接收图片列表 figures_data
整理出图片、描述、位置信息
调用视觉模型生成描述
再把结果重新组装回原来的数据结构

Markdown 分支给它传入的 figures_data 形式是：

1

[((combined_image, ["markdown image"]), [(0, 0, 0, 0, 0)])]

也就是说，每次只处理当前 section 对应的一张聚合图，原始描述先放一个占位值 "markdown image"，位置则放一个 dummy tuple。

`_extract_figures_info()`

这个方法负责把 figures_data 拆成内部使用的三个列表：

1
2
3
4


def _extract_figures_info(self, figures_data):
 self.figures = []
 self.descriptions = []
 self.positions = []

其中核心分支是：

1
2
3
4
5
6


if len(item) == 2 and isinstance(item[0], tuple) and len(item[0]) == 2:
 img_desc = item[0]
 img = ensure_pil_image(img_desc[0])
 self.figures.append(img)
 self.descriptions.append(img_desc[1])
 self.positions.append(item[1])

因此传入的：

1

((combined_image, ["markdown image"]), [(0, 0, 0, 0, 0)])

会被拆成：

self.figures : [combined_image]
self.descriptions : [["markdown image"]]
self.positions : [[(0, 0, 0, 0, 0)]]

这里的 ensure_pil_image() 负责把输入统一成 PIL.Image 对象，因此前面无论传入的是普通图片对象还是惰性图片对象，到了这里都会被标准化。

`call()`

VisionFigureParser.__call__() 才是真正执行视觉增强的入口：

1
2


def __call__(self, **kwargs):
 callback = kwargs.get("callback", lambda prog, msg: None)

它内部先定义了一个 process()，用于处理单张图片：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def process(figure_idx, figure_binary):
 context_above = ""
 context_below = ""
 if figure_idx < len(self.figure_contexts):
 context_above, context_below = self.figure_contexts[figure_idx]
 if context_above or context_below:
 prompt = vision_llm_figure_describe_prompt_with_context(
 context_above=context_above,
 context_below=context_below,
 )
 else:
 prompt = vision_llm_figure_describe_prompt()

然后通过线程池并发调用：

1
2


for idx, img_binary in enumerate(self.figures or []):
 futures.append(shared_executor.submit(process, idx, img_binary))

等所有任务完成之后，将返回的描述文本写回：

1
2
3
4


for future in as_completed(futures):
 figure_num, txt = future.result()
 if txt:
 self.descriptions[figure_num] = txt + "\n".join(self.descriptions[figure_num])

最后再调用 _assemble() 重新组装：

1
2


self._assemble()
return self.assembled

对于 Markdown 分支来说，这里有两个细节：

没有显式传入 figure_contexts，因此默认使用 vision_llm_figure_describe_prompt()
回填时会把模型输出和原始描述拼在一起，因此最终描述中理论上可能保留 "markdown image" 这个占位文本

`picture_vision_llm_chunk()`

process() 里真正调用视觉模型的函数是 rag/app/picture.py 中的：

1

def vision_llm_chunk(binary, vision_model, prompt=None, callback=None):

虽然名字叫 vision_llm_chunk，但其作用其实很直接，就是把图片交给 VLM 并返回描述文本。

其主要步骤如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


with io.BytesIO() as img_binary:
 try:
 img.save(img_binary, format="JPEG")
 except Exception:
 img_binary.seek(0)
 img_binary.truncate()
 img.save(img_binary, format="PNG")

 img_binary.seek(0)
 ans = clean_markdown_block(vision_model.describe_with_prompt(img_binary.read(), prompt))
 txt += "\n" + ans
 return txt

这里做了几件事：

先把 PIL.Image 编码成二进制
优先尝试保存为 JPEG，失败则退回 PNG
调用 vision_model.describe_with_prompt() 生成描述
用 clean_markdown_block() 清理模型输出中的 Markdown 包裹

因此这个函数返回的是一段纯文本，而不是结构化对象。

`vision_llm_figure_describe_prompt()`

在 VisionFigureParser.__call__() 中，无上下文情况下使用的是：

1

prompt = vision_llm_figure_describe_prompt()

而如果存在上下文，则切换到：

1
2
3
4


prompt = vision_llm_figure_describe_prompt_with_context(
 context_above=context_above,
 context_below=context_below,
)

这两组 prompt 都定义在 rag/prompts/ 下。其核心约束是：

只根据图中可见内容生成文本
如果是表格、柱状图、折线图这类“可枚举数据图”，则按固定字段输出
如果不是结构化数据图，则按空间顺序描述可见内容
不允许额外推断流程、功能或语义

也就是说，这一步生成的不是泛化摘要，而是偏向检索友好的图片文本表示。

`sections[idx] = (...)`

最终在 rag/app/naive.py 中，增强结果是这样写回 section 的：

1
2
3
4


sections[idx] = (
 section_text + "\n\n" + "\n\n".join([fig[0][1] for fig in boosted_figures]),
 sections[idx][1]
)

因此 Markdown 图像增强不会引入新的切片层级，而是把图片描述文本直接拼回现有 section。

在这一轮增强之后，chunk() 才会真正进入 Markdown 专属的 chunk 合并逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


if is_markdown:
 merged_chunks = []
 merged_images = []
 chunk_limit = max(0, int(parser_config.get("chunk_token_num", 128)))

 current_text = ""
 current_tokens = 0
 current_image = None

 for idx, sec in enumerate(sections):
 text = sec[0] if isinstance(sec, tuple) else sec
 sec_tokens = num_tokens_from_string(text)
 sec_image = section_images[idx] if section_images and idx < len(section_images) else None

这段代码表明，Markdown 的切片单位不是“原始全文直接按分隔符硬切”，而是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Markdown 文本
 ↓
按元素扫描成多个 section
 ↓
每个 section 绑定对应图片
 ↓
图片描述增强（如果启用）
 ↓
按 token 上限逐个累积合并
 ↓
得到最终 chunk

RAGFlow 对 Markdown 没有直接调用通用的 naive_merge_with_images()，而是单独写了一套更简单的逻辑。其规则是：

如果加入下一个 section 后仍未超过 chunk_token_num，则继续追加
如果会超过上限，就先把当前 chunk 落盘，再开启一个新的 chunk
如果开启新 chunk 时配置了 overlapped_percent，则保留上一 chunk 尾部的一部分文本作为重叠上下文
与此同时，当前 chunk 内涉及的所有图片会被不断 concat_img 合并

关键代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


if current_text and current_tokens + sec_tokens > chunk_limit:
 merged_chunks.append(current_text)
 merged_images.append(current_image)
 overlap_part = ""
 if overlapped_percent > 0:
 overlap_len = int(len(current_text) * overlapped_percent / 100)
 if overlap_len > 0:
 overlap_part = current_text[-overlap_len:]
 current_text = overlap_part
 current_tokens = num_tokens_from_string(current_text)
 current_image = current_image if overlap_part else None

这里可以看出两个特点：

重叠是按字符长度截尾，而不是按 section 粒度重叠
图片是按 chunk 聚合的，只要 section 被并入同一个 chunk，其图片也会被拼到同一张图上

因此，一个最终的 Markdown chunk，本质上是：

1
2
3
4


{
 "text": "若干相邻 section 合并后的文本",
 "image": "这些 section 内图片拼接后的结果（如果有）"
}

在 chunk 合并完成之后，RAGFlow 会根据该批 chunk 是否含图走两条不同路径：

1
2
3
4
5
6


has_images = merged_images and any(img is not None for img in merged_images)

if has_images:
 res.extend(tokenize_chunks_with_images(chunks, doc, is_english, merged_images, child_delimiters_pattern=child_deli))
else:
 res.extend(tokenize_chunks(chunks, doc, is_english, pdf_parser, child_delimiters_pattern=child_deli))

其中：

tokenize_chunks() 负责纯文本 chunk 的分词和字段封装
tokenize_chunks_with_images() 则会把对应图片写入文档对象的 image 字段
表格则另外通过 tokenize_table(tables, doc, is_english) 进入结果集

也就是说，Markdown 在 RAGFlow 中最后会被拆成三类可检索对象：

普通文本 chunk
携带图片的多模态 chunk
表格对象

小结

至此，RAGFlow 对 Markdown 的“切片”逻辑就比较清楚了。它并不是简单地按固定长度裁文本，而是分成了几层：

先识别表格、标题、代码块、列表、引用块和普通文本块
再根据图片引用所在行号，把图片绑定到对应 section
然后按 token 上限把多个相邻 section 合并为 chunk
最后把文本、图片、表格分别包装成可检索对象

从工程实现上看，这套方案的优点是：

实现简单，可维护性高
比纯分隔符切片更保留 Markdown 结构
能较自然地支持图文混合检索
表格被单独抽出后，也便于做专门处理

当然，它也有一些局限，例如：

图片归属依赖行号，精度有限
section 的粒度较粗，未做更深层的语义切分
表格与正文可能存在信息重复

但对一个通用 RAG 系统来说，这样的取舍是相当合理的。它没有追求复杂而昂贵的 Markdown AST 解析，而是用较低复杂度完成了“结构感知切片”。

笔者认为，这也是 RAGFlow 值得学习的一点：很多时候，切片策略不一定要非常“聪明”，但一定要足够稳定、可解释，并且方便与后续检索流程对接。

RAG on 边个濑椰的博客

稀疏向量与 SPLADE 模型

参考网站

稀疏向量与 SPLADE 模型

论文模型

排序损失

FLOPS 稀疏正则

总体损失

从求和到最大池化

SPLADE-doc 与蒸馏训练

稀疏性为什么重要

模型选择

SPLADE 和 BM25 的区别

RAGFlow切片策略解析

RAGFlow 切片策略解析

rag/app/naive.py

__call()__

extract_tables_and_remainder()

MarkdownElementExtractor

extract_image_urls_with_lines()

load_images_from_urls()

urls_in_section = [...]

表格处理细节

chunk()

VisionFigureParser

_extract_figures_info()

__call__()

picture_vision_llm_chunk()

vision_llm_figure_describe_prompt()

sections[idx] = (...)

小结

`rag/app/naive.py`

`call()`

`extract_tables_and_remainder()`

`MarkdownElementExtractor`

`extract_image_urls_with_lines()`

`load_images_from_urls()`

`urls_in_section = [...]`

`chunk()`

`VisionFigureParser`

`_extract_figures_info()`

`call()`

`picture_vision_llm_chunk()`

`vision_llm_figure_describe_prompt()`

`sections[idx] = (...)`