LlamaIndex 的 ingestion 怎么用：数据进得来才谈得上检索

2026-07-28

数据截至 2026-07，价格与限额以各官网为准。

做 RAG 的人容易把力气全花在检索侧——换嵌入模型、加重排、调混合检索权重——但真正决定上限的是 ingestion：数据以什么形态进到索引里。进库那一步切错了、丢了表格、没带元数据，后面再怎么调检索都是在一堆碎渣里捞答案。LlamaIndex 的价值恰恰集中在这一段，它是数据优先的框架，RAG 专用原语更贴身。

一个很常见的误解是：ingestion 就是”把文件读进来切成块再算向量”，属于跑通就完事的体力活。实际情况正相反。读取和入库确实是体力活，但中间的解析、分块和元数据设计是需要针对语料反复试的，而且这几步一旦定错，代价是全量重跑。把它当成一次性脚本写，通常两周之后就会推倒重来一次。

先交代一下 LlamaIndex 的位置，免得被 star 数带偏。第三方对比统计的一组数据显示，截至 2026 年 1 月的 GitHub star 排名中，LangChain 约 125,000，Dify 约 114,000，RAGFlow 约 70,000，LlamaIndex 约 46,500，Haystack 约 24,000。这些数字只反映关注度，不代表哪个更适合你的场景；具体能力和接口以各项目官方文档当前版本为准。LlamaIndex 的定位是对私有内容做索引与查询，深度 ingestion 连接器和高级索引策略是它的强项；LangChain 则是生态更广、集成更多，但抽象开销更高。两者不是二选一的关系，这一点后面还会展开。

一、ingestion 拆开是六个环节

把 ingestion 当成一条流水线看，从原始文件到可检索的索引，中间要经过六个环节：

取数：从文件系统、数据库、对象存储、API、网页等来源把原始内容拿到手。
解析：把 PDF、Word、PPT、HTML 这类格式还原成结构化的文本，表格、标题层级、图注都属于这一步的产物。
分块：把长文档切成检索粒度合适的片段。
元数据：给每个片段挂上来源、时间、部门、文档类型、章节标题等标签。
嵌入：调用嵌入模型把片段转成向量。
入库：把向量和元数据一起写进向量数据库。

数一下就是这六步，缺一步链路就不完整。多数团队的注意力集中在第五步和第六步，因为这两步最容易跑通、最有”做完了”的感觉。而实际返工率最高的是第二到第四步。

二、大部分项目其实卡在解析

如果你的语料是干净的 Markdown 或纯文本，解析这一步几乎不存在。但真实企业语料往往是扫描版 PDF、带合并单元格的财报表格、版式复杂的合同和制度文件。传统文本解析器面对这类内容会把表格拍扁成一行乱码，把双栏排版按行错位读串。这时候你在检索侧做再多优化也没用——答案根本没进库。

按瓶颈选工具比按名气选靠谱。瓶颈在解析的，可以从 LlamaIndex 的 LlamaParse 或者 RAGFlow 入手，后者的差异化正是深度文档理解：版面感知解析、分块尊重文档结构、内置知识图谱构建，适合扫描件、财报、版式复杂的法律文书这类语料。具体对比可以看 RAGFlow 强在哪：扫描件与复杂版式的文档理解。

可操作的做法：在写任何 pipeline 代码之前，先抽 20 份最难的文档手工过一遍解析结果。不看整体准确率，只看表格有没有塌、标题层级在不在、页眉页脚有没有混进正文。这一步花半天，能省掉后面两周的莫名其妙。

三、分块要跟着文档结构走，不是按字数硬切

固定长度切分是默认选项，也是效果最差的选项之一。它会把一个完整的条款从中间劈开，让上半句和下半句进了两个不同的片段，检索时哪一半都答不全。

更实用的几种思路：

按结构切：以标题层级、章节、条款编号为边界，段落自然结束的地方才切。制度文件、技术文档、法规类语料尤其适用。
保留重叠：相邻片段之间留一段重叠，缓解边界处语义被切断的问题。代价是索引变大、重复内容变多。
把标题拼进片段正文：一个片段单独看往往缺主语，把它所在的文档标题和章节标题拼到片段开头，检索命中率通常会有肉眼可见的改善。
表格单独处理：表格不要跟着正文一起按长度切，整表作为一个片段、并在片段里带上表名和列头，比切碎了好用得多。

具体的块长度、重叠长度没有普适答案，跟你的嵌入模型上下文长度、文档类型、问题类型都有关。建议从框架的默认值起步，用一组真实问题做对照实验再调，不要抄别人文章里的数字。默认值本身以官方文档当前版本为准。

四、元数据是后期唯一的救命稻草

这一条常被跳过，然后在上线三个月后追悔莫及。检索出来的片段如果只有一段文本，你既没法做权限隔离，也没法按时间过滤掉作废版本，更没法在回答里给出可点击的原文出处。

进库时至少挂上这几类标签：来源文件路径或文档编号、文档版本与生效日期、所属部门或权限范围、文档类型、章节或页码。写入的时候顺手，事后补要全量重跑。

元数据能不能用好，也取决于向量库是否支持结构化过滤。常见的搭配是 Qdrant，它支持过滤、payload 索引与量化，第三方评测称在 100 万以上向量规模下可以做到 50 毫秒以内的检索——这是第三方基准口径，不是官方承诺的指标，实际表现取决于硬件、索引参数和过滤条件复杂度。Qdrant 既可以作为独立二进制运行，也能用 Docker 容器跑。向量库的横向比较可以参考向量数据库怎么选。

五、增量更新和去重才是真正的工程量

演示环境里 ingestion 是一次性的：跑一遍，索引建好，收工。生产环境里它是长期运行的任务，麻烦几乎全在这里：

文档更新了怎么办。同一份制度改了第三版，旧版本的片段还留在库里，检索时新旧混着出来，模型给的答案是错的。必须有稳定的文档标识，更新时先删旧片段再写新片段。
重复跑的成本。嵌入调用是要花钱和时间的，没做缓存的话每次全量重跑都是一次重复付费。做法是给内容算指纹，内容没变就跳过嵌入直接复用。
同一份文件被多个来源收录。共享盘里一份合同存了四个副本，不去重的话检索结果全是同一段内容的四份拷贝，把上下文窗口占满还挤掉了别的相关内容。
失败恢复。批量处理跑到第 800 份挂了，要能从断点续跑，而不是从头再来一遍。

这几点没有捷径，属于必须自己写的工程代码。LlamaIndex 提供了 ingestion pipeline 的抽象和缓存机制来减轻负担，但业务上”哪份文档算同一份、什么情况下算过期”的判断只能你自己定。

六、pipeline 的最小骨架长什么样

概念上，一条 ingestion pipeline 就是”读取器 + 若干变换 + 目标存储”的组合：读取器负责取数，变换按顺序处理（分块、抽元数据、算嵌入），最后写进向量库。用伪代码表达大致是这个形状：

# 结构示意，具体类名与参数以 LlamaIndex 官方文档当前版本为准
documents = reader.load_data()        # 1. 取数（含解析）

pipeline = IngestionPipeline(
    transformations=[
        splitter,        # 2. 分块
        metadata_extractor,   # 3. 元数据
        embed_model,     # 4. 嵌入
    ],
    vector_store=vector_store,   # 5. 入库
    cache=cache,                 # 6. 缓存，避免重复嵌入
)

nodes = pipeline.run(documents=documents)

要提醒的是，这类框架的接口在不同版本之间调整过多次，网上几个月前的示例代码经常已经跑不通。写之前先看官方文档当前版本的对应页面，别照抄旧教程，包括这篇里的示意结构也只是帮你理解流水线的形状，不能当作可直接运行的代码。

真正需要你花心思的不是这段骨架，而是每个位置上填什么：用哪个解析器、切分策略怎么定、抽哪些元数据。骨架半小时能写完，这三个决定要试几轮。

七、什么时候该换别的工具

诚实说局限：LlamaIndex 不是万金油，按瓶颈换工具比硬扛更省时间。

瓶颈在检索（嵌入选型、混合检索、重排）的，LangChain、Haystack、Cognita 这类可调的旋钮更多。
瓶颈在解析且语料确实很脏的，LlamaParse 之外也可以评估 RAGFlow，它还带低代码界面配 RAG 工作流。
瓶颈在评估的，不用换框架，在现有框架上加挂 RAGAS 就行。
语料是有链接的结构化内容（人物、组织、事件互相关联）的，考虑图检索，RAGFlow 的 GraphRAG 是一条路。

还有一点值得强调：这些框架并不互斥。一种常见的生产组合是 LlamaIndex 做 ingestion 与索引，LangChain 做编排，LangGraph 做 agent 工作流——各取所长，而不是非要用一家把所有事都办了。两者的分工差异在 LangChain 和 LlamaIndex 的分工里讲得更细。

另外要清楚一点：LlamaIndex 是库不是服务，所谓”自托管”就是你自己跑 Python 服务和向量库，运维、扩容、监控都得自己接。要数据留在内网，这条路是通的；要快速搭起来看效果，低代码平台的搭建成本更低。

八、几个容易踩的坑

把 ingestion 写成一次性脚本。上线后一定会有增量更新的需求，一开始就按可重复运行来设计，比事后重构便宜。
先调检索再看进库质量。顺序反了。检索不准时第一件事是把命中的片段打印出来肉眼看，通常一眼就能看出是分块切坏了还是根本没解析出来。
元数据留到以后再补。补的代价是全量重跑加重新嵌入。
抄别人的分块参数。语料不同，参数不通用。
忽略嵌入模型的换代成本。换嵌入模型意味着整库向量作废、必须全量重算，选型时就该把这件事的成本算进去。
只测干净文档。验收集里必须放最难的那几份扫描件和复杂表格，否则上线当天才发现问题。

小结

ingestion 是 RAG 里投入产出比最高、也最容易被低估的一段。六个环节里，取数和入库是体力活，解析、分块、元数据才是需要针对语料反复试的地方。LlamaIndex 在这一段的原语相对贴身，适合数据密集型的 RAG 场景，但它是库不是平台，运维和业务判断得你自己扛。选工具的依据是你卡在哪一段，不是谁 star 多；框架之间也完全可以混着用，让每一段由更擅长的那个来做。落地顺序建议是：先手工验解析，再定分块和元数据，最后才动检索侧的参数。