LightRAG文档处理：增量更新、解析引擎与存储边界治理

文档进入知识库后，重复导入、增量更新和存储膨胀会逐渐影响检索质量。本文围绕 LightRAG 的文档处理流程，说明文件指纹、状态记录、增量边界、VLM 处理和向量/图数据存储如何分工，并给出更新失败时可回滚的检查点。文中只讨论可复现的步骤，不把单次结果扩展成产品承诺；每个结论都标注前提、证据和无法覆盖的边界。读者可以先完成最小验证，再按自己的版本、权限和数据补充实验。

项目地址：HKUDS/LightRAG

很多知识库项目第一次演示都很顺。

上传一个 Markdown，问一个问题，模型回答得不错。到了第二周，真实文件进来了：PDF 有表格，DOCX 里有图片，手册换了版本，旧制度要删除，财务团队还要求把数据放到 PostgreSQL。

这时候问题就不再是“能不能检索”，而是：LightRAG 到底保存了哪些派生数据？改一个解析器会影响什么？删除文件会不会把其他文件里的实体关系一起删掉？换 Embedding 要不要全量重建？

这一篇只讲工程事实。

LightRAG 当前仓库已经提供 legacy、native、MinerU、Docling 多种解析路径，支持 Fix、Recursive、Vector、Paragraph 四类分块策略，也能对图片、表格和公式做 VLM 分析。它的增量更新能力很有价值，但并不等于任何配置都可以在运行中随意替换。

如果你的 LLM、Embedding 或 VLM 通过上游 API 或企业 API 网关调用，还要把“每次上传一个文件会触发多少次模型请求”纳入预算。知识库的成本往往不是查询一次产生，而是建库、重处理和删除重建累积出来的。

一、文件进入 LightRAG 后发生了什么

一个文档从上传到可查询，大致要经过：

接收文件或文本
  -> 判断解析引擎和文件名 hint
  -> 提取正文、标题、表格、图片、公式等 sidecar
  -> 按分块策略切成 text chunks
  -> EXTRACT 模型抽取实体、关系和摘要
  -> 生成文本块、实体和关系的 Embedding
  -> 写入 KV、Vector、Graph、Doc Status 四类存储
  -> 标记 processed 并返回可查询状态

其中每一步都会产生不同的失败类型：

文件打不开，属于输入或解析问题。
文本提取成功但实体关系为空，可能是抽取模型或格式问题。
Embedding 失败，可能是模型地址、维度或并发配置问题。
写入失败，可能是数据库扩展、权限、连接池或向量维度问题。
文档状态停在 processing，可能是后台任务、超时或外部解析服务没有响应。

不要只看 WebUI 上的一句“处理失败”，生产系统要保存 track_id、文件名、解析引擎、处理状态、错误信息和重试次数。

二、解析引擎怎么选

当前文档处理管线支持四类引擎。

`legacy`，兼容旧行为

legacy 覆盖的文件扩展名比较广，适合先处理纯文本、Markdown、代码、CSV、JSON 和基础办公文件。升级新版本以后，如果没有调整 LIGHTRAG_PARSER，一些文件仍可能沿用旧解析行为。

它的优势是兼容面广，缺点是对复杂布局、文档结构和多模态内容的理解不如专门解析器。

`native`，本地结构化解析

native 是 LightRAG 内置的结构化提取器，不依赖 MinerU 或 Docling 外部服务。当前文档重点支持 DOCX、Markdown 和 Textpack。

它可以提取 DOCX 的标题、段落、表格、图片和公式，并把相应内容保存为 sidecar。Markdown 也能识别标题、表格、块级公式和嵌入图片。

native 适合不想额外部署解析服务、希望先在本地稳定跑通的团队。它不是“所有 PDF 都能完美还原”的通用解析器，文件格式和结构复杂时要看实际输出。

`mineru`，外部文档解析引擎

MinerU 适合 PDF、DOCX、PPTX、Excel、图片等包含复杂排版、表格、公式和图片的材料。LightRAG 可以连接官方服务，也可以使用本地部署的 MinerU。

云端 MinerU 会受到文件大小、页数和配额限制。企业内部资料通常更适合评估本地部署，同时确认 GPU、服务地址、任务队列和资源成本。

`docling`，另一条外部解析路径

Docling 也支持 PDF、DOCX、PPTX、XLSX、Markdown、HTML 和图片等格式。它同样需要先启动外部服务并配置 endpoint。

不要把 mineru 或 docling 写进 .env 就以为解析器已经可用。LightRAG 需要能够访问对应服务，首次接入先用小文件验证，确认原始文本、表格和图片 sidecar 都生成了。

三、用 LIGHTRAG_PARSER 路由文件

解析规则的基本形态是：

LIGHTRAG_PARSER=ext:engine-options,ext:engine,*:legacy-R

例如：

LIGHTRAG_PARSER=pdf:mineru-R;docx:native-iet;*:legacy-R

仓库当前建议用分号分隔规则，扩展名写在左边，通配规则通常放在最后。规则按从左到右匹配，因此优先级高的格式要放前面。

文件名可以临时覆盖规则

单个文件可以在文件名里指定解析器和处理选项：

paper.[mineru-R].pdf
proposal.[native-iet].docx
slides.[docling].pptx
notes.[-R].md

这里的方括号是 LightRAG 的文件名 hint，不是文件名装饰。[mineru-R] 表示使用 MinerU 和对应分块/处理选项，[-R] 表示只覆盖选项而保留默认引擎。

如果已有文件要从 legacy 改成 native，不能只改规则然后期待旧文档自动改变。当前文档明确说明，解析路由影响新上传文件；旧文件需要删除后重新上传，或使用项目提供的重处理路径，并确认最终处理引擎。

解析缓存的好处和陷阱

MinerU 和 Docling 的解析结果会在本地缓存。重复上传同一个文件，通常不会每次都重新调用外部解析服务，这可以节省时间和费用。

但如果你修改了 endpoint 或有效解析参数，缓存可能失效并触发重解析。删除文件时，如果希望连解析缓存一并清理，也要确认删除对话框里的“同时删除文件”选项。缓存不是永久真相，换引擎或参数后要核对文档状态。

四、四种分块策略不是四套风格

仓库当前版本引入了四个可选的文本分块策略。

`F`，Fix，固定分块

按照 token 大小和重叠长度切分，适合结构普通、希望行为稳定的文本。调整 chunk_token_size 和 chunk_overlap_token_size 会影响新处理的文档。

`R`，Recursive，递归分块

按分隔符递归寻找更自然的边界，适合长段落、教程和一般 Markdown。可以为 R 指定分块大小和重叠参数。

`V`，Vector，向量语义分块

按语义相似性判断分割点，适合段落主题变化明显的材料，但会增加 Embedding 相关开销，需要看数据量和延迟预算。

`P`，Paragraph，段落语义分块

利用段落、标题和文档结构组织分块，对论文、报告和有明显章节层级的文档更有价值。参考文献很多时，仓库还提供 drop_references 等配置，避免参考文献变成大量低价值实体关系。

分块策略必须和查询效果一起评估。块越大，不代表上下文越完整；块越小，也不代表召回更精准。至少要记录：命中的原文位置、引用是否完整、跨段落信息是否丢失、索引时间和 Token 消耗。

五、图片、表格和公式的多模态处理

当前仓库的多模态处理需要两个条件同时成立：

文档的 process_options 包含对应的 i、t 或 e 标志。
VLM_PROCESS_ENABLE=true，并且配置了支持图片输入的 VLM。

示例配置：

LIGHTRAG_PARSER=*:native-iteP,*:legacy-R
VLM_PROCESS_ENABLE=true
VLM_LLM_MODEL=<your-vision-model>

这些选项分别对应图片、表格和公式分析。只打开 VLM_PROCESS_ENABLE，但文件路由没有带对应标志，VLM 不会凭空分析所有内容；反过来只有 i/t/e 而没有可用 VLM，也无法完成多模态分析。

为什么 VLM 不是默认全开

图片、表格和公式分析会增加模型调用、解析时间和文件处理失败面。所有 PDF 都开 VLM，很容易把一个只需要文字检索的任务变成昂贵的批处理。

更合理的方式是：

纯文本制度：不开 VLM
包含流程图的操作手册：开启图片分析
财务报表：开启表格分析，保留原表结构
学术论文：按需开启公式和图片分析

如果 VLM 通过上游 API 或其他 API 网关调用，单独给 VLM 角色设 Key、模型白名单和预算。不要让普通 Markdown 上传也能消耗高价视觉模型。

六、新增文档和增量更新

LightRAG 的增量能力来自这样一个思路：新文档先生成自己的局部图和向量，再把实体、关系和文本块合并到现有工作区，而不是每次从零重建全局索引。

一个常见的更新流程是：

上传新版本手册
  -> 等待新文档 processed
  -> 用新旧版本分别查询关键问题
  -> 确认引用来自新文件
  -> 将旧版本标记失效或删除
  -> 再跑回归问题集

增量更新不等于新旧内容自动消歧。如果旧版和新版同时保留，查询可能把两个版本都召回。文档状态、版本号、来源日期和有效期最好作为业务元数据管理，而不是只依赖文件名。

删除文件会发生什么

删除一份文档不只是删一个 PDF。它可能影响：

文档状态。
归属该文档的文本块和向量。
只由该文档支持的实体和关系。
仍被其他文档引用的共享实体描述。
建库阶段产生的 LLM 缓存。

当前实现提供按文档删除并重建受影响关系的流程，仓库说明也提到会利用建库阶段的 LLM 缓存加快重建。但这是一个破坏性操作，不能和任意上传任务无条件并发。Server 对清空、删除和扫描有流水线占用控制，业务层也应该让删除进入队列并记录审计。

七、换 Embedding、换分块和换存储的代价

换 Embedding

如果改变模型、维度、非对称 Embedding、查询前缀或文档前缀，旧向量语义就不再和新配置一致。正确做法通常是：

停止写入
  -> 备份原始文档和 LLM 缓存
  -> 清理受影响的向量数据
  -> 使用新配置重新索引
  -> 用固定问题集比较新旧召回
  -> 通过后再切换业务流量

不要只改 EMBEDDING_MODEL 然后继续查询旧工作区。

换分块策略

新的 LIGHTRAG_PARSER 或 chunk 配置主要影响之后进入队列的文件。已有文档要不要重处理，要看你是否需要全库使用同一套规则。混合版本并不一定错误，但必须保存每个文档实际使用的 chunk_options，否则出现召回差异时很难解释。

换存储后端

当前 API 文档明确说明，新增文档后不能随便更换存储实现，LightRAG 还没有通用的直接迁移路径。切换 PostgreSQL、OpenSearch 或其他后端前，要先做备份、迁移演练和回滚方案。LLM 缓存可以通过专门工具迁移，但缓存迁移不等于所有图、向量和文档状态都已经迁移。

八、四类存储各自保存什么

LightRAG 使用四类后端：

类型	保存内容	典型实现
KV	LLM 缓存、文本块和文档信息	JSON、PostgreSQL、Redis、MongoDB、OpenSearch
Vector	文本块、实体和关系的向量	NanoVectorDB、pgvector、Milvus、Qdrant、FAISS、OpenSearch
Graph	实体节点和关系边	NetworkX、Neo4j、PostgreSQL AGE、Memgraph、OpenSearch
Doc Status	文档处理状态和元数据	JSON、PostgreSQL、MongoDB、OpenSearch

默认的 JSON、NetworkX 和本地向量存储适合开发和调试，不应该直接当作生产高可用方案。

PostgreSQL，一体化选择

PostgreSQL 可以结合 pgvector 和 Apache AGE，同时承担 KV、向量和图存储。适合团队希望减少数据库种类、统一备份和权限管理的场景，但部署前要确认扩展、版本、连接池和向量维度。

MongoDB 或 OpenSearch，统一后端

仓库当前支持 MongoDB 和 OpenSearch 作为多类存储的统一后端。它们适合已经有对应基础设施和运维经验的团队。不要因为“一个数据库能保存所有东西”就忽略索引、容量、查询延迟和备份恢复。

Milvus、Qdrant，专注向量

如果向量规模大、检索吞吐高，Milvus 或 Qdrant 可以作为专业向量存储，图谱仍然交给 Neo4j、Memgraph 或其他图存储。

Neo4j、Memgraph，专注关系

如果业务核心是实体关系浏览、图谱运营和复杂关系查询，Neo4j 或 Memgraph 更适合承担图存储。它们不是简单替换向量数据库，四类存储仍要分别配置。

九、企业级 API 和数据治理

文档处理阶段的模型调用比单次查询更难估算。一个上传动作可能触发解析、实体关系抽取、摘要合并、多个 Embedding 批次和 VLM 分析。

通过上游 API 或企业 API 网关接入时，建议按阶段统计：

文件级：文件大小、页数、解析引擎、处理耗时
抽取级：chunk 数、EXTRACT 调用量、失败重试
向量级：Embedding 文本数、批次、维度和费用
多模态级：图片/表格/公式数量、VLM 调用量
查询级：模式、top_k、rerank、输入输出 Token 和延迟

为每个项目设置月度预算、单文件上限和失败告警。MAX_PARALLEL_INSERT、MAX_ASYNC_LLM、EMBEDDING_FUNC_MAX_ASYNC 和批大小会影响吞吐，也会影响上游网关的并发压力，不能为了追求速度无限调大。

敏感文件先做权限分类和脱敏，再决定能否发送到外部解析服务或模型网关。企业 API 网关可以统一审计请求，但不能自动判断 PDF 里有没有客户身份证号、内部价格或未公开合同。

十、安全和版本边界

LightRAG 的解析器会处理本地文件、外部服务返回的 sidecar 和可能下载的图片资源。生产环境要限制：

输入目录可读取的路径。
外部解析服务可以访问的网络范围。
文档删除和重处理的操作者。
VLM 能看到哪些图片和表格。
原文、缓存、图谱和向量的保存周期。

文档中出现的实体和关系是模型抽取结果，不能直接作为合同、财务或合规事实。删除文件也要保留审计记录，因为一条关系可能由多份文档共同支持。

本文依据当前仓库文档编写。升级 LightRAG 前重点重读 FileProcessingPipeline.md、RoleSpecificLLMConfiguration.md、env.example 和存储迁移说明，不要把旧版本的解析 hint、环境变量和表结构直接复制到新环境。

十一、文档流水线验收清单

解析验收

每种实际文件都记录了最终解析引擎和处理选项。
PDF、DOCX、表格、图片和公式分别用小样本验证过。
LIGHTRAG_PARSER 和文件名 hint 没有互相覆盖到无法解释。
MinerU/Docling 外部服务、缓存和失败重试都可观测。

索引验收

文档进入 processed 后，文本块、实体、关系和向量都能查询。
新旧版本文件的有效期和来源清楚，查询不会无意混用。
删除一份文件后，其他文件共享的实体关系仍然存在。
换 Embedding 或分块策略前已经备份并准备重新索引。

存储验收

KV、Vector、Graph、Doc Status 的实现和数据目录都有记录。
默认本地存储只用于开发和调试。
生产后端的扩展、维度、连接池、权限、备份和恢复都演练过。
没有在已有数据上直接切换存储实现。

成本和安全验收

上游 API 或其他网关能按 EXTRACT、QUERY、KEYWORD、VLM 统计调用。
单文件大小、页数、并发、重试和 VLM 使用有预算限制。
原文、缓存、图谱和向量不被无授权用户读取。
删除和重处理操作有审批或审计记录。

总结

LightRAG 的增量更新真正省下来的，不只是一次重建时间，而是让变化中的知识库有机会持续运行。但前提是你知道哪些东西可以增量合并，哪些东西必须重新索引：

新增文件：通常可以走增量图和向量流程
删除文件：要清理派生数据并重建受影响关系
换解析器：旧文件需要重新处理
换 Embedding：向量数据通常要重建
换存储后端：先迁移演练，不要直接切换

结论

本文给出了问题定位、配置或创作流程的可执行路径。实际结果仍取决于当前版本、权限和运行环境，提交前应按官方文档复核可变字段，并保留失败证据和回滚边界。