文件处理流水线工作方式说明

从版本 v1.5.0 （目前在dev分支）开始，LightRAG的文件处理流水线进行了重大的升级：

• 支持多种文件内容抽引擎：legacy、native、mineru、docling
• 支持多种文本块分块方法：Fix、Recursive、Vector、Paragraph
• 支持对个别文件关闭实体关系抽取

LightRAG Server引入了一个文件处理的中间格式： LightRAG Document 。该格式支持表格和图片等多模态数据，同时包含文章的章节段落元数据，方便日后进行内容溯源。

本文以 LightRAG Server 的部署与使用视角组织：先给出快速开始可直接套用的配置，再展开内容抽取与分块的配置语法、存储 / 目录布局、去重、并发以及续跑规则。直接通过 Python 代码调用 LightRAG 类的开发者请翻到第十一章 Python SDK 调用。

目录

• 1. 快速开始
• 2. 处理选项与配置语法
• 3. 文件解析引擎
• 4. 多模态分析（VLM）
• 5. 分块器参数配置（chunk_options）
• 6. 存储与目录布局
• 7. 同名与重复文档
• 8. 运行控制：边跑边传、停止与重试
• 9. 流水线启动时的续跑规则
• 10. 常见问题排查
• 11. Python SDK 调用
• 附录 A：从旧版升级的注意事项
• 附录 B：环境变量速查

1. 快速开始

1.1 保持旧版文件处理行为

所有文件按旧版的文档解析和分块策略处理所有文档。不配置 LIGHTRAG_PARSER 或把它配置为如下值：

LIGHTRAG_PARSER=*:legacy-F

1.2 推荐起步文件处理行为

不依赖外部文档解析服务，不依赖VLM视觉模型。使用新版原生的 Native 解析 docx 文档，开启表格(t)和公式(e)的模态分析，搭配P分块策略；其余文档使用老版本的内容解析器，搭配效果更好的R分块策略。

LIGHTRAG_PARSER=*:native-teP,*:legacy-R

1.3 开启多模态处理能力

开启多模态处理能力需要依赖 MinerU 文件解析服务和 VLM 视觉识别模型。使用 Native 解释 docx 文件，使用 MinerU 解析 pdf、office 和各种图片文件。以上文件都开启图片(i)、表格(t)和公式(e)的模态分析，并并搭配P分块策略。其余文档回退到老版本的内容解析器并搭配R分块策略。

LIGHTRAG_PARSER=*:native-iteP,*:mineru-iteP,*:legacy-R
VLM_PROCESS_ENABLE=true
VLM_LLM_MODEL=kimi-k2.6
MINERU_API_MODE=local
MINERU_LOCAL_ENDPOINT=http://localhost:8000

P分块策略是LightRAG原生的分块策略，详情请参阅Paragraph Semantic 分块策略。VLM的配资请参阅基于角色的 LLM/VLM 配置指南

1.4 逐字段读懂一条预设

LIGHTRAG_PARSER 用逗号分隔的每一项都是一条路由规则，按文件后缀从左到右匹配，第一条可用的规则胜出。把 *:native-iteP,*:legacy-R 拆开看：

*  :  native  -  iteP
│     │          │
│     │          └─ 处理选项：i/t/e 分别开启图片、表格、公式分析；
│     │             P 选择段落语义分块器
│     └─ 内容抽取引擎
└─ 规则适用的后缀；`*` 匹配任意后缀

所以第一条规则的意思是"任何文件都交给 native 解析，三种模态全部分析，用 P 分块"，第二条是"第一条处理不了的，退回 legacy 并用 R 分块"。当引擎不支持该后缀、或外部引擎没有配置服务端点时，该规则会被跳过——这正是 *:native-iteP 实际只接管 docx / md / textpack、其余文件全部落到 legacy 的原因。

完整语法见 §2.3，选项字母见 §2.1，各引擎见 §3。

1.5 第一次运行：跑通一个文档并确认成功

一条不依赖任何外部服务的冒烟路径——一个 .docx，不需要 MinerU、docling、VLM：

LIGHTRAG_PARSER=*:native-teP,*:legacy-R

1. 先验证路由，别浪费一次解析。 写错的 LIGHTRAG_PARSER 在启动时就会失败（§2.7）。服务起来后，GET /documents/supported_file_types 返回服务端实际解析出的后缀白名单与引擎-后缀映射，不入库一个文件就能确认规则是否生效。

2. 把文件送进来。 要么 POST /documents/upload（文件存入 INPUT_DIR，响应带 track_id），要么把文件放进 INPUT_DIR 后调 POST /documents/scan。想对单个文件试不同配置又不改 .env，就用文件名 hint：report.[native-teP].docx（§2.5）。

3. 看进度。 GET /documents/track_status/{track_id} 看这次上传，GET /documents/pipeline_status 看实时日志，GET /documents/status_counts 看整批。状态阶梯是 PENDING → PARSING → ANALYZING → PROCESSING → PROCESSED。

4. 产物落在哪。 全部在 INPUT_DIR/__parsed__/ 下（§6.2）。以 report.[native-teP].docx 为例：

__parsed__/report.[native-teP].docx   # 归档的原件，保留 hint
__parsed__/report.docx.parsed/        # 规范名，已剥掉 hint
    report.blocks.jsonl               # 首行是 meta，其余是内容块
    report.tables.json                # 仅当文档确实有表格
    report.equations.json             # 仅当文档确实有公式
    report.blocks.assets/             # 导出的图片

5. 验证解析，按这个顺序：

1. *.blocks.jsonl 首行是 meta 记录。
2. 内容行的标题结构合理——这正是 P 的切分依据。
3. 你预期的 sidecar 存在。缺失意味着文档没有该类内容，或该引擎不产出它（legacy 一个都不产出，见 §3.2）。
4. 你启用了分析的那些 sidecar item 带有 "llm_analyze_result": {"status": "success"}。这里是 skipped 或 failure，就是"为什么我的图片/表格没进知识图谱"的答案（§4.3）。

6. 验证分块与入库。 GET /documents/paginated 的 chunks_count 是分块数；doc_status 记录里的 metadata.parse_engine 与 metadata.process_options 表明实际生效的引擎和选项，这是发现"hint 被静默判为无效"最快的办法（§2.7）。

失败了怎么办： 源文件留在 INPUT_DIR，改完配置可以重新扫描。doc_status 记录上的 error_msg 是诊断入口，§10 列出了常见的几种。注意引擎与处理选项都在入队时就已冻结——改 LIGHTRAG_PARSER 或改 hint 都不影响已有记录，要用新配置重跑就得删除文档后重新上传（§9.3）。想脱离服务器离线复现一次解析，用 python -m lightrag.parser.cli（ParserDebugCLI-zh.md）。

2. 处理选项与配置语法

LightRAG 的文件处理配置由两部分合成：内容抽取引擎决定原始文件如何被解析，处理选项决定解析后是否执行多模态分析、使用哪种分块方式，以及是否构建知识图谱。通常先用环境变量 LIGHTRAG_PARSER 按文件后缀设置默认规则，再用文件名中的 [hint] 覆盖单个文件。引擎和选项可以写在同一个配置片段里，例如 docx:native-iet 或 report.[native-R!].docx。

为了向后兼容，在未修改配置的情况下，升级后的文件内容提取方式会维持原来的 legacy 行为。如需启用新的内容处理引擎，请按本章说明配置；各引擎自身的能力与设置见 §3。

2.1 文件处理选项

处理选项以文件为粒度控制多模态分析、知识图谱构建和文本分块的行为；既可在 LIGHTRAG_PARSER 中作为规则默认值批量设置（见 §2.4），也可通过文件名 hint 对单个文件覆盖（见 §2.5）。所有选项都是可选的；缺省值见下表。同一文件最多指定一种分块方式（F/R/V/P），其它选项可任意组合。

多模态全局开关 addon_params["enable_multimodal_pipeline"] 已废弃，相关行为统一由文件级 i/t/e 选项控制。详见附录 A。

2.2 选项生效阶段

处理选项的不同字符在流水线的不同阶段生效：

模态可用性以"sidecar 文件是否存在"为唯一信号，内容提取引擎不需要在 meta 中声明能力。某文档若没有任何图像/表格/公式，对应 sidecar 不会写入；用户即使开启了 i/t/e，对应模态也只会被静默跳过，但 analyze_multimodal 会在该篇文档落一行 INFO 级日志（[analyze_multimodal] sidecar e:equations empty: doc—id ...），便于排查"VLM 为何没跑"。这种情况不会报错。

2.3 配置语法总览

完整配置模型如下：

LIGHTRAG_PARSER=后缀:引擎-选项,后缀:引擎,*:legacy-R
filename.[ENGINE].ext
filename.[ENGINE-OPTIONS].ext
filename.[-OPTIONS].ext

• LIGHTRAG_PARSER 是默认规则表，按文件后缀匹配，例如 pdf:mineru、docx:native-iet。

• 文件名 [hint] 是单文件覆盖规则，例如 paper.[mineru].pdf、memo.[native-R!].docx。

• ENGINE 是内容抽取引擎。选哪个决定了解析阶段能产出什么：

  引擎	是什么	什么时候用它
  legacy	纯文本抽取，不产出 sidecar	想保持升级前的行为，或文档本来就是纯文本
  native	内置结构化抽取器，完全本地，不依赖外部服务	docx / md / textpack，且希望不部署任何东西就用上 P 分块或模态分析
  mineru	外部 MinerU 服务	PDF、扫描件，以及需要版面识别与 OCR 的 office / 图片格式
  docling	外部 docling-serve	MinerU 的替代方案；也是内置路径里唯一能出 LaTeX 公式的

  只有 native、mineru、docling 会产出 sidecar，因此也只有它们能支撑 i / t / e 选项与 P 分块器。各引擎的能力、配置与部署见 §3。

• OPTIONS 是处理选项字符组合，例如 iet、R!、P。选项最终写入 process_options，由后续流水线阶段读取。

• ENGINE-OPTIONS 中的连字符只用于分隔引擎和选项，不属于选项本身。

• 仅指定处理选项时必须写成 [-OPTIONS]，例如 [-!]。无横线的 [abc] 会被严格解释为引擎名并报错，不会回退为选项串。

常见组合示例：

LIGHTRAG_PARSER=pdf:mineru-R,docx:native-ietP,*:legacy-R
MINERU_API_MODE=local
MINERU_LOCAL_ENDPOINT=http://localhost:8000
DOCLING_ENDPOINT=http://localhost:5001

my-proposal.[native-iet].docx   # 使用 native 引擎，开启图、表、公式分析
my-memo.[native-R!].docx        # 使用 native 引擎，递归语义分块，禁止知识图谱构建
my-proposal.[-!].docx           # 使用默认引擎，仅禁止知识图谱构建
my-proposal.[mineru].docx       # 使用 MinerU 引擎，处理选项全部默认

2.4 默认规则：LIGHTRAG_PARSER

LIGHTRAG_PARSER 用来为不同文件后缀配置默认内容抽取引擎，也可以在引擎后追加该规则的默认处理选项：

后缀:引擎,后缀:引擎,*:legacy
后缀:引擎;后缀:引擎;*:legacy
后缀:引擎-选项

• 左侧匹配的是文件后缀，不是完整文件名；应写 pdf:mineru，不要写 *.pdf:mineru。
• 规则使用分号 ;（推荐）或英文逗号 , 分隔。
• 规则按从左到右的顺序检查；优先规则放在前面，通配符规则通常放在最后。
• 引擎后缀 -选项 部分作为该规则匹配文件的默认 process_options。例如 LIGHTRAG_PARSER=docx:native-iet 表示所有 .docx 默认采用 native 引擎，并开启图像、表格、公式分析。

2.5 单文件覆盖：文件名 hint

文件名中可以使用中括号临时指定单个文件的处理方式：

paper.[mineru-R].pdf
slides.[docling].pptx
memo.[native-P].docx
notes.[-R].md

中括号内的内容支持三种形式：

[ENGINE]              # 仅指定引擎，处理选项使用默认或 LIGHTRAG_PARSER 提供的默认
[ENGINE-OPTIONS]      # 同时指定引擎和处理选项
[-OPTIONS]            # 仅指定处理选项，引擎仍按 LIGHTRAG_PARSER / 默认规则解析

解析 hint 时，无横线内容必须整体匹配引擎名（mineru / native / docling / legacy）；带横线且横线前有内容时，横线前是引擎、横线后是选项；以横线开头时表示仅指定选项。旧式 [OPTIONS] 写法不再合法，例如 [iet] 应改为 [-iet]。

2.6 为分块策略附加参数

分块策略选择符（F / R / V / P）——无论在 LIGHTRAG_PARSER 规则还是文件名 hint 中——都可以用圆括号附加该策略的分块参数。括号内逗号只用于分隔参数；规则切分是括号感知的，因此该逗号绝不会被误判为规则分隔符（; 与 , 都是合法的规则分隔符，但推荐 ;）。

notes.[-R(chunk_ts=800,chunk_ol=80)].md                            # 文件名 hint
LIGHTRAG_PARSER=pdf:legacy-R(chunk_ts=800,chunk_ol=80);*:legacy-R  # 规则

当前支持的参数（全称 / 短别名）：

• process_options 仍是纯选择符字符串；每个参数会写入该策略的 chunk_options（见 §5），策略其它来自环境变量的参数保持不变。别名在内部统一归一化为全称。
• 合并优先级：选择符仍遵循“文件名 hint 的非空选项整体覆盖规则选项”；参数按同一策略叠加——先规则参数，再文件名 hint 参数（同一键以文件名为准）。
• 启动期（LIGHTRAG_PARSER）与上传期（文件名 hint）均严格校验：未知参数、类型错误、取值越界、把参数加到不支持的策略（如 V 上的 chunk_ol）都会给出友好报错。

drop_references 检测调参 CHUNK_P_REFERENCES_TAIL_N（默认 0：扫描全部内容块；正数表示只扫描文末最后 N 块）/ CHUNK_P_REFERENCES_HEADINGS（竖线分隔，默认 References\|Bibliography\|参考文献）仅经环境变量、运行时实时读取。drop_references可以通过环境变量 CHUNK_P_DROP_REFERENCES 设置为全局默认值.

2.7 校验、优先级与回退

• 启动时会严格校验 LIGHTRAG_PARSER：未知内容提取引擎、错误后缀写法、显式使用不支持的后缀、外部引擎缺少 endpoint、处理选项中的非法字符都会导致启动失败。
• 通配符规则匹配某后缀时，引擎需通过两道可用性检查（见 parser_routing._engine_is_usable）：(a) 该引擎能力表支持此后缀；(b) 若是外部引擎（mineru / docling），对应 endpoint/token 环境变量已配置。任一检查不过，本规则跳过，继续匹配下一条规则。例如 *:mineru;html:docling 中：MinerU 不支持 html 后缀（条件 a 不过），html 继续命中 docling；如果 MINERU_API_MODE=local 但未设置 MINERU_LOCAL_ENDPOINT，所有 PDF 也会跳过 *:mineru 落到下一条规则（条件 b 不过）。这一行为对 LIGHTRAG_PARSER 规则匹配和文件名 hint 引擎选择都生效。
• 文件名 hint 的优先级高于 LIGHTRAG_PARSER。如果 hint 指定的引擎不支持该后缀，系统会回退到默认规则继续选择可用引擎。
• 如果文件名 hint 提供了非空选项串，则以 hint 为准；否则使用 LIGHTRAG_PARSER 规则中匹配项的默认选项；都没有则使用全部默认。
• 如果所有规则都不可用，文件内容提取方式会回退到 legacy；如果 legacy 也不支持对应的文件后缀，会向系统添加一个错误条目，上传文件保留在 INPUT 目录。
• F/R/V/P至多出现一个；同一选项重复时只生效一次但不报错。
• 大小写敏感：分块选项 F/R/V/P必须大写；其它选项 i/t/e小写。
• 中括号内出现非法字符时，整个 hint 失效，引擎按默认规则解析，选项按 LIGHTRAG_PARSER 默认或全部默认；同时落日志 warning。
• P 对任何能产出 .blocks.jsonl sidecar 的引擎（native / mineru / docling）抽取出的结构化结果有效；对 legacy 路径或无 sidecar 的输出会自动降级到 R 并记录 warning。

3. 文件解析引擎

3.1 引擎能力矩阵

mineru 和 docling 是外部内容提取引擎，启用相关规则前必须先把服务跑起来，再在 LightRAG 配置对应 endpoint/token。

两个外部引擎上表列的都是基线格式集 —— 即引擎开箱即可处理的格式。它们其余的输入格式（旧版 Office doc / xls / ppt，docling 还有 ODF、EPUB、AsciiDoc、LaTeX、CSV 等）取决于服务侧而非 LightRAG 侧安装的组件 —— 旧版 Office 转换需要服务侧装有 LibreOffice —— MinerU 还额外取决于当前的 MINERU_API_MODE。因此这些格式不全局对外声明：请用 MINERU_ADDITIONAL_SUFFIXES / DOCLING_ADDITIONAL_SUFFIXES 声明你自己的部署实际能处理哪些（见下文各引擎小节，以及 env.example 里的 MinerU / Docling 配置块），再用 LIGHTRAG_PARSER 规则或文件名 hint 把这些后缀路由过去 —— 只声明后缀并不会让裸 x.doc 变成可上传。

LightRAG 在本地会缓存 mineru 和 docling 引擎的解析结果。重复上传相同的文件通常不会重新调用引擎解析文档。如果需要删除解析缓存，必须在文档管理界面删除文件弹窗中点击“同时删除文件”选项。修改 mineru 和 docling 引擎的端点地址和有效提取参数也会导致缓存失效，下次上传相同文件的时候会重新调用引擎解析文件内容。

3.2 使用 legacy 内容抽取器

legacy 是除 .textpack（路由层强制交给 native）之外所有后缀的兜底引擎，也是不配置 LIGHTRAG_PARSER 时的默认行为。它只抽取纯文本，由此带来四个在把文件路由给它之前值得先知道的后果：

• 它永不产出 sidecar。 输出是 parse_format=raw，不存在 drawings.json / tables.json / equations.json 供分析阶段读取。因此 i / t / e 选项对 legacy 解析的文档完全无效，P 也会因为没有标题结构可切而退化为 R（§2.7）。
• 它没有原始缓存目录，所以 LIGHTRAG_FORCE_REPARSE_* 对它不适用（§3.7）。
• 它唯一的配置项是 PDF_DECRYPT_PASSWORD，用于打开受密码保护的 PDF。
• 无文本层的扫描版 PDF 会硬失败，而不是产出一个空文档。这类文件应改路由到能做 OCR 的 mineru 或 docling。

3.3 使用 Native 文件解析引擎

native 是 LightRAG 内置的结构化内容抽取引擎，纯本地运行：不依赖 MinerU / Docling 等外部服务，抽取阶段也不调用 VLM，开箱即用无需任何部署。运行依赖仅 python-docx + defusedxml（必备）；其中 markdown 路径的 SVG 栅格化额外依赖可选的 cairosvg（缺失时跳过该 SVG 并记 warning，不影响其余内容）。为 docx 启用可选的 smart_heading 引擎参数时，额外需要钉定版本的 zh_core_web_sm / en_core_web_sm spaCy 模型（spacy 运行时已随 api extra 一并安装，模型用 lightrag-download-cache --spacy-install 安装——Docker 主镜像已内置）；从不启用该参数的部署无需模型，另外 smart_heading 路径会在解析阶段调用 EXTRACT 角色 LLM。设置环境变量 DOCX_SMART_HEADING=true 后，路由到 native 引擎的 .docx 文件默认启用 smart_heading——单个文件/规则可用显式 native(smart_heading=false) 关闭——同时服务器会在启动时校验 spaCy 模型并 fail-fast（而不是等到首次解析才报错）；LIGHTRAG_PARSER 规则中携带 native(smart_heading=true)（或其省值写法 native(smart_heading)）时同样触发启动校验。该默认值仅作用于新上传：已入库文档重解析时沿用其持久化的引擎参数。

支持后缀：docx / md / textpack。启用方式：

• docx、md 默认仍走 legacy，需显式选择 native，例如默认规则 LIGHTRAG_PARSER=docx:native、LIGHTRAG_PARSER=md:native，或文件名 hint report.[native-iet].docx、notes.[native].md（语法见 §2.4 / §2.5）。
• textpack 为 native 独占后缀，无需 hint/规则即自动路由到 native。

docx 抽取能力

native 直接解析 OOXML，能识别以下结构并写入对应 sidecar（sidecar 是否生成由文档实际内容决定，见 §6.2）：

图片落盘细节：

• 嵌入图片导出到 blocks.jsonl 同级的 <base>.blocks.assets/ 目录，支持 png jpeg gif bmp tiff webp emf wmf。
• SVG 图片：Word 在保存 SVG 时会同时存矢量 .svg 与一张 PNG 位图回退，native docx 落盘的是这张 PNG 回退（读取 <a:blip> 的 r:embed，指向 PNG），不导出 SVG 矢量原图。对下游 VLM 消费而言 PNG 通常已足够，无需再做栅格化。（注意这与下文 md 路径「SVG 经 cairosvg 栅格化」是不同实现：docx 直接取 Word 已生成的 PNG。）
• VML / OLE 对象（旧版 Word 图片、Visio 图、公式编辑器预览等）：通过 v:imagedata 导出其渲染预览，常见为 EMF/WMF，落入同一 assets 目录；若关系标记为外部链接（TargetMode="External"），只记录 URL 不导出字节。注意：EMF/WMF（及 Visio 等 OLE 对象的预览）目前只能"提取落盘"，无法进入多模态分析——下游 VLM 图像分析只接受栅格格式 png / jpg / jpeg / gif / webp，其余格式（EMF/WMF/SVG 等）会被静默跳过（标记 skipped，不报错、不影响整篇文档）。例外是公式：它以 LaTeX 文本而非图片存储，走文本（EXTRACT）角色分析而非 VLM，因此能被正常处理。

docx 段落溯源（paraId）提示

native docx 会采集 Word 2013+ 写入的 w14:paraId 作为段落级溯源锚点。若文档由 LibreOffice / WPS / 旧版 Word 生成，或被手工改过 docx 内部 XML，部分段落会缺少 paraId，此时会在日志输出一次提示：

[parse_native] <文件名>: N paragraphs lack paraId; Re-saving file in Word 2013+ to regenerate ids.

受影响块的 positions 退化为 [{"type": "paraid", "range": null}]。这只是提示，不影响解析成功；如需精确段落溯源，按提示在 Word 2013+ 中「另存为 .docx」即可重建 id。

md / textpack 抽取能力

native 引擎除 docx 外还支持 Markdown：

• md：按标题（ATX #）分块，识别 md 原生竖线表格（含表头）、HTML <table>（含 <thead>，保留 colspan/rowspan）、段落级公式（以 $$ 开头并以 $$ 结束的段落；行内 $...$ 不识别）、内嵌图片（base64 data URL）。代码围栏（```）内的内容原样保留，不参与识别。与 docx 一样，md 默认仍走 legacy，需用 LIGHTRAG_PARSER=md:native 或文件名 [native] hint 选择 native。
• textpack：TextBundle 规范的 zip 包（md 正文 + 资源目录，约定为 assets/，Bear / Ulysses 等导出格式）。只有 native 支持该后缀，因此无需 hint/规则即自动路由到 native。
  • 包内结构要求（正文按扩展名定位，不要求固定叫 text.markdown，方便用任意 zip 工具自行打包）：
    • 正文文件名任意，扩展名为 .md 或 .markdown 即可。
    • 若包内含 *.textbundle 后缀的子目录，则最多只能有 1 个（多于 1 个报错），且正文只从该 .textbundle 子目录查找（忽略根目录的 md）。
    • 若包内不含 *.textbundle 子目录，则正文只从压缩包根目录查找。
    • 查找目录内 .md / .markdown 文件必须恰好 1 个：0 个或多于 1 个均报错。
    • 正文所在目录即资源解析的"包根"（bundle_root）。
  • 包内以相对路径（文件引用）内嵌的图片按相对包根目录解析，允许放在包内任意子目录（不限于 assets/），但禁止目录穿越（..、绝对路径、越出包根的引用会被记 warning 跳过）；解析出的字节须通过图片 magic bytes 校验，否则跳过。独立 .md（非 textpack）中的相对路径图片不解析（记 warning 跳过）。
• SVG 图片（base64 / textpack 包内文件 / 在线下载）会先经 cairosvg 栅格化为 PNG 再写入 sidecar；cairosvg 不可用或渲染失败时跳过该图（记 warning）。系统依赖：cairosvg 是对 cairo 的 cffi 绑定——pip install cairosvg（随 api extra 安装）总能成功，但只有宿主机同时装了原生的 libcairo 共享库，栅格化才真正能跑（Debian/Ubuntu 用 sudo apt-get install libcairo2，RHEL/Fedora 用 sudo dnf install cairo，macOS 用 brew install cairo，Windows 需安装内含 libcairo-2.dll 的 GTK3 运行时）——pip/uv 装不了系统库，所以除官方 Docker 镜像外这一步永远不会自动完成。服务器会在启动时探测栅格化能力，缺失时记一条 warning，避免这个缺口一直藏到某篇文档处理时才被发现。
• 外部 URL 图片（![](http://...)）默认下载并内嵌（NATIVE_MD_IMAGE_DOWNLOAD_ENABLED 默认 true）；无论下载成功与否都会生成 drawing（成功内嵌资源，失败回退为外链）。下载默认仅允许可全球路由的公网 IP（DNS 解析结果与每一跳重定向目标都校验，且 socket 直连已校验 IP 以防 DNS rebinding，忽略环境 HTTP(S)_PROXY），私网 / 环回 / 链路本地 / 保留 / CGNAT（100.64.0.0/10）等一律拒绝；如需放行特定内网段，用 NATIVE_MD_IMAGE_ALLOWED_NON_PUBLIC_CIDRS 配置 CIDR 白名单。若设为 false，外链图片整个丢弃（不生成对应 drawing，故仅含外链图片的文档不会生成 drawings.json）。

环境变量

native 的所有 NATIVE_* 环境变量与 .native_raw/ 缓存目录仅作用于 markdown / textpack 引擎的外链图片下载；docx 路径不读取任何 NATIVE_* 变量。最常用的两个：

• LIGHTRAG_FORCE_REPARSE_NATIVE（默认 false）：强制丢弃 .native_raw/ 缓存、重新联网下载外链图片。
• NATIVE_MD_IMAGE_DOWNLOAD_ENABLED（默认 true）：外链图片下载总开关，设为 false 时丢弃所有外链图片。

其余下载/大小/SSRF 相关变量（NATIVE_MD_IMAGE_DOWNLOAD_TIMEOUT / NATIVE_MD_IMAGE_DOWNLOAD_REQUIRED / NATIVE_MD_IMAGE_MAX_BYTES / NATIVE_MD_IMAGE_MAX_SVG_PIXELS / NATIVE_MD_IMAGE_ALLOWED_NON_PUBLIC_CIDRS）含义与默认值见仓库根目录 env.example。

下载的外链图片缓存到 <文件>.native_raw/（与 .parsed/ 同级，类比 .mineru_raw/.docling_raw），重新解析同一未改动文件时直接复用、不再联网；源文件内容或上述大小 / SVG 像素 / CIDR 配置变化时缓存自动失效。删除文档（删除弹窗勾选「同时删除文件」）时该缓存目录会与 .parsed/ 一并清理。

3.4 使用 MinerU 文件解析引擎

LightRAG文档处理管线支持使用MinerU作为文件解析器。支持使用两种MinerU访问模式：

• official模式：使用MinerU云端的 API v4 服务。需要先到 MinerU官网 注册账号并创建API-KEY。然后在LightRAG的 .env 文件中添加以下配置：

MINERU_API_MODE=official
MINERU_API_TOKEN=<your_token>
# MINERU_OFFICIAL_ENDPOINT=https://mineru.net   # 默认值，通常无需修改

• local模式：使用本地部署的 MinerU 服务，部署方式见 ParserServiceDeployment-zh.md §1。本地MinerU服务启动后在LightRAG的 .env 文件中添加以下配置：

MINERU_API_MODE=local
MINERU_LOCAL_ENDPOINT=http://<your_mineru_local_server_ip>:8000

两种模式都生效的共享参数：

仅 local 模式：

仅 official 模式：

轮询预算与缓存：

本地部署 MinerU 服务（Docker 镜像构建、vLLM 预加载、标题层级修正）见 ParserServiceDeployment-zh.md §1。

3.5 使用 Docling 文件解析引擎

docling 内容提取引擎需要外部的 docling-serve 服务（v1 异步 API）。最少配置：

DOCLING_ENDPOINT=http://localhost:5001

DOCLING_ENDPOINT 只填 base URL（不带 /v1/convert/file/async）。目前LightRAG固定使用 Docling 的 standard 流水线处理文件。用户可以通过以下环境环境变量来控制 Docling 流水线的行为：

未配置 DOCLING_OCR_ENGINE / DOCLING_OCR_PRESET 时等同于 auto；未配置 DOCLING_OCR_LANG 时不向 docling-serve 传递语言列表，由 OCR 引擎使用自身默认值。解析缓存按这些有效参数计算签名，因此“未配置”和“显式填写默认值”不会导致缓存失效。

可选输入格式 1 个 env：

DOCLING_ADDITIONAL_SUFFIXES 使用要点：

• 用 , 分隔的裸小写后缀；允许带前导点和两侧空格（.DOC 等同 doc）。其它写法（按 glob 习惯写成 *.doc、或用 ; 分隔）会在启动时报错，不会被静默忽略。
• 它只让该后缀可以路由到 docling，本身并不会让裸 x.doc 变成可上传。必须配合路由规则（LIGHTRAG_PARSER=doc:docling）或文件名 hint（x.[docling].doc）使用 —— 否则这类文件仍会落到默认的 legacy 引擎并被判为不支持的后缀。反过来，只写 doc:docling 规则而不配这个 env，会因 doc 不在 docling 能力表内而启动校验失败。
• 该变量在使用时实时读取，因此写在父进程环境或 .env 里都同样生效。

轮询预算 2 个 env（docling-serve 是 server-side long-poll，客户端不再额外 sleep）：

Bundle 缓存 3 个 env：

DOCLING_DO_FORMULA_ENRICHMENT 启用前提：docling-serve 侧需就绪 code-formula 模型权重。adapter 双轨兼容 —— 启用时 text 字段为 LaTeX，关闭或权重缺失导致 text == orig 时自动按普通文本处理，不写 equations.json。因此默认 false 是保守值，部署侧确认模型就绪后再开启。

本地部署 docling-serve（含 DOCLING_DO_FORMULA_ENRICHMENT 所需的公式识别模型下载）见 ParserServiceDeployment-zh.md §2。

3.6 为解析引擎附加参数

参数也可以附加到引擎 token 上，按文件覆盖外部引擎的行为。它们被编码进持久化的 parse_engine 字段，同时作用于引擎请求与其原始包缓存签名（因此改动参数会触发重解析，而非复用旧缓存包）。

paper.[mineru(page_range=1-3,language=en,local_parse_method=ocr)].pdf   # 文件名 hint
scan.[docling(force_ocr=true)].pdf
report.[native(smart_heading)].docx                                      # 布尔参数的省值写法
LIGHTRAG_PARSER=pdf:mineru(language=en);*:legacy-R                       # 规则

当前支持的引擎参数（全称 / 别名）：

• page_range 可写多个页码段——每段都单独写一个 page_range=...。 括号 (...) 内逗号只分隔参数，因此多段页码要写成 page_range=1-3,page_range=5,page_range=7-9，不要写成环境变量里的单串形式 MINERU_PAGE_RANGES="1-3,5,7-9"。多段 page_range 需要 MINERU_API_MODE=official；local 模式只接受单页/单段（如 page_range=1-3）。
• local_parse_method 仅限 local 模式。 它只影响本地 MinerU 请求，因此在 MINERU_API_MODE=official 下会被拒绝（official API 既不发送它、也不计入缓存键——接受它将静默无效）。
• 布尔型引擎参数可以省略取值、写成裸开关，用于缩短规则与文件名：native(smart_heading) 等价于 native(smart_heading=true)，docling(ocr) 等价于 docling(force_ocr=true)。只有布尔参数可以这样写（mineru(language) 会友好报错）；持久化的 parse_engine 始终按全称 key=value 重新编码（native(smart_heading=true)），因此省值写法不会改变缓存签名。关闭布尔参数仍需显式写出（native(smart_heading=false)）。
• 引擎参数只被声明了参数的引擎接受（mineru / docling / native）；给 legacy 附加参数、或给任一引擎附加未知参数，都会友好报错。校验在启动期（LIGHTRAG_PARSER）与上传期均执行。
• 合并优先级：引擎参数按最终引擎解析——当文件名 hint 选中了另一个可用引擎时，规则的引擎参数会被丢弃。
• parse_engine 以 hint 语法存储（如 mineru(page_range=1-3)），并展示在 doc_status metadata 中，便于查看文档当时使用的解析参数。

3.7 解析缓存与强制重解析

native、mineru、docling 三个引擎各自在解析产物旁保留一份原始产物缓存，这样重新解析未变更的文件时不必重复昂贵的工作——一次外部服务往返，或一轮 markdown 外链图片下载。目录布局与失效规则见 §6.3；配置时需要知道的是：

每个产物包都在 manifest 里记录引擎版本与生效参数签名，所以改服务端点、改抽取参数、或改 MINERU_ENGINE_VERSION / DOCLING_ENGINE_VERSION 本身就会让缓存失效。强制标志是为 manifest 察觉不到的那种情况准备的：服务变了而它的版本串没变。删除文档时勾选"同时删除文件"会把缓存目录连同 .parsed/ 一并移除。

4. 多模态分析（VLM）

4.1 这一阶段做什么

解析阶段写 sidecar；ANALYZING 阶段读取它、把每个 item 送给模型、再把结果写回该 item 的 llm_analyze_result；随后 PROCESS 阶段据此构建多模态分块。这个顺序带来两个结论：

• 分析可以不重新解析就重跑。 抽取阶段不受 i / t / e 影响——引擎按文档实际内容产出 sidecar——所以事后再启用某个模态，只会补做 VLM 工作，不会重新碰原始文件（§9.3）。
• 没有对应 sidecar 的模态是静默空操作，仅记一条 INFO 日志。这不是错误，它意味着文档没有该类内容，或该引擎不产出它。

4.2 每个选项实际需要什么

VLM_PROCESS_ENABLE 常被读成三种模态的总开关。它不是——它只闸控图片：

这也是推荐预设 *:native-teP 在完全不配置 VLM 的情况下也能工作的原因。而 sidecar 是否存在还取决于引擎：MinerU 侧是 MINERU_ENABLE_TABLE / MINERU_ENABLE_FORMULA，docling 侧是 DOCLING_DO_FORMULA_ENRICHMENT，legacy 则一个都不产出。

4.3 失败与跳过

本节内容仅适用于 process_options 含 i 的文档。不含 i 的文档根本不会进入图片分析，因此无论它带多少张图片、无论 VLM_PROCESS_ENABLE 如何设置，都会正常处理完。

对于确实含 i 的文档，每张图片要走一条过滤链，而 VLM 闸门位于这条链的中间。闸门之前的每一步都是跳过、文档安然无恙；闸门本身则让整个文档失败：

文本模态一侧：内容为空的表格 item 会先被记为 skipped 并打 WARNING，不会走到 format 校验；只有有内容的表格 item，其 format 缺失或非法时才让文档失败，那意味着 sidecar 已损坏。内容为空的公式 item 则直接让文档失败。

4.4 token 预算

上下文预算从总预算里扣，设得过高会挤占 item 本身。发生时服务会在启动阶段告警并点名该调哪个变量：要么调高 MAX_EXTRACT_INPUT_TOKENS，要么调低这一对上下文上限。

4.5 图片限制与吞吐

VLM_MAX_IMAGE_BYTES（缺省 5 MB）与 VLM_MIN_IMAGE_PIXEL（缺省 64）界定什么值得送出去：下限的存在是为了跳过图标和分隔线，而不是为它们付一次 VLM 调用。分析阶段的并发是 MAX_PARALLEL_ANALYZE（§8.6），与解析、入库阶段互不影响。

4.6 模型配置不在本章

VLM_PROCESS_ENABLE 是流水线开关，归本章。具体哪个模型承担 VLM 角色——VLM_LLM_MODEL、VLM_LLM_BINDING、VLM_LLM_BINDING_HOST、VLM_LLM_BINDING_API_KEY、VLM_MAX_ASYNC_LLM、VLM_LLM_TIMEOUT——以及支持视觉输入的 provider 列表，归 基于角色的 LLM/VLM 配置指南，本文刻意不重复，以免两处漂移。

4.7 容易混淆的另一件事：MINERU_LOCAL_IMAGE_ANALYSIS

MinerU 自己也有一轮 VLM，由 MINERU_LOCAL_IMAGE_ANALYSIS 开启。它在解析期跑在 MinerU 主机上，改善的是 MinerU 自身输出里的 caption 与脚注，消耗那台机器的 GPU，且被 pipeline backend 忽略。它与 i 选项、与 VLM_PROCESS_ENABLE 都无关。

4.8 一个安全的启用顺序

1. 先只开 te。它只需要 EXTRACT 角色——不引入新基础设施，也不引入新的失败模式。
2. 确认 sidecar item 的 llm_analyze_result.status == "success"。
3. 再把 i 与 VLM_PROCESS_ENABLE=true 以及一个支持视觉的 binding 一起加上。

把第 3 步拆成两半，就会撞上 §4.3 第 4 行那种失败。而且因为处理选项在入队时已冻结，已经这样失败的文档无法靠改配置重试救回来：/documents/reprocess_failed 会按原来的 i 重跑。要么把 VLM 配好再重试，要么删除该文档、以不带 i 的配置重新上传（§8.3）。

5. 分块器参数配置（chunk_options）

5.1 process_options vs chunk_options 的职责

process_options 选用哪种分块策略（F/R/V/P），chunk_options 决定那一路分块器用哪些参数。两者职责正交：前者是单字符 selector，后者是结构化字典。

env vars                                                  (启动期一次性读取)
   │
   ▼
addon_params["chunker"]                                   (LightRAG 实例字段，由 env 与 legacy 兜底填入)
   │
   ▼  resolve_chunk_options(addon_params, split_by_character=…, split_by_character_only=…)
   │
full_docs[doc_id]["chunk_options"]                       (入队时冻结，每文件独立快照)
   │
   ▼
chunker(tokenizer, content, chunk_token_size, **strategy_kwargs)   (分块时按 selector 派发)

• env vars 在 LightRAG.__init__ 阶段（由 default_chunker_config() 读取 strategy 特定 env，再由 _apply_chunk_size_overlay 兜底 legacy env）灌进 addon_params["chunker"]。
• addon_params["chunker"] 是 ObservableAddonParams 字段；Server 部署只需通过 env / 重启即可让新值生效。若需要在 Python 进程内运行时改它（不重启）以及 per-file 覆盖，请见第十一章 Python SDK 调用。
• full_docs.chunk_options 在 apipeline_enqueue_documents 入队时冻结：默认由 resolve_chunk_options(self.addon_params, ...) 现场拼装；若调用方传入 chunk_options 参数则原样持久化（SDK 用法，见 §11.4）。
• 分块器调用从 full_docs.chunk_options 取对应子字典，按 process_options.chunking selector 派发到 F/R/V/P。

5.2 环境变量

以下变量都在 LightRAG 实例化时一次性读入 addon_params["chunker"]：strategy 特定 env 由 default_chunker_config() 读取，legacy env（CHUNK_SIZE / CHUNK_OVERLAP_SIZE）由 _apply_chunk_size_overlay 在 strategy env 与 legacy 构造字段都没填的槽位上兜底。修改 env 后需要重启服务（或新建 LightRAG 实例）才生效；已入队的文档持有冻结快照不受影响。

下面按各变量配置的策略分组。同一个槽位上，strategy 特定变量始终高于全局兜底。

全局兜底

• CHUNK_SIZE —— 1200，int。 顶层 chunk_token_size 兜底。低于 strategy 特定 env，也低于 SDK 路径设置的 addon_params["chunker"]["chunk_token_size"]。
• CHUNK_OVERLAP_SIZE —— 100，int。 overlap 兜底。只有当某策略既没有自己的 env（CHUNK_F_OVERLAP_SIZE / CHUNK_R_OVERLAP_SIZE / CHUNK_P_OVERLAP_SIZE）、也没有 SDK 路径的 LightRAG(chunk_overlap_token_size=…) 时才填入该槽位。

F —— 定长

• CHUNK_F_SIZE —— 未设，int。 F 自己的 chunk_token_size，高于顶层兜底（CHUNK_SIZE 与 SDK 路径的 LightRAG(chunk_token_size=…)）。未设时 F 沿用顶层解析结果。
• CHUNK_F_OVERLAP_SIZE —— 未设，int。 F 自己的 overlap，高于 legacy 构造字段与 CHUNK_OVERLAP_SIZE。
• CHUNK_F_SPLIT_BY_CHARACTER —— 未设（null），str。 预切分隔符。null 或空串表示仅按 token 窗切分。
• CHUNK_F_SPLIT_BY_CHARACTER_ONLY —— false，bool。 严格模式：不再按 token 二次切分，遇到超长片段直接抛错。

R —— 递归字符

• CHUNK_R_SIZE —— 未设，int。 R 自己的 chunk_token_size，高于顶层兜底。未设时 R 沿用顶层解析结果。

• CHUNK_R_OVERLAP_SIZE —— 未设，int。 R 自己的 overlap，高于 legacy 构造字段与 CHUNK_OVERLAP_SIZE。

• CHUNK_R_SEPARATORS —— JSON 数组字符串。默认值：

  jsonCopy

  ["\n\n","\n","。","！","？","；","，"," ",""]
  

  分隔符级联，按语义边界从最强到最弱排列。默认包含中文句末（。！？）与句中（；，）标点，使中文 / 中英混合文档能在语义边界切分。英文 .?! 被刻意排除——按字面匹配会切断数字与缩写。

  上限为 64 条、单条最长 256 字符。 切分器每保留一个分隔符就下降一层，且每层都会重扫全文，因此过长的级联付出 O(len(separators) × len(text)) 的代价却切不出更多内容。两条上限的行为并不相同，且差异会体现在输出上：单条超过 256 字符的分隔符会被整条丢弃而非截短——一条 300 字符的分隔符是消失，而不是退化成匹配它的前 256 字符；列表超过 64 条则截断到 64 条，若原列表末尾有字符级 "" 哨兵则予以保留。若无一条存活，回退目标由消费方决定，且不是本变量的默认值：chunking_by_recursive_character 走它文档化的 separators=None 路径，即切分器自带的四条纯英文级联 ["\n\n", "\n", " ", ""]，而非九条的 DEFAULT_R_SEPARATORS；load_chunk_separators 则回退到去掉哨兵的 DEFAULT_R_SEPARATORS。

  对非 HTTP 配置，收敛只会在值被缓存时告警一次：CHUNK_R_SEPARATORS 在配置装载时，显式提供或整体替换的 addon_params['chunker'] 会立即处理（为兼容而保留的嵌套原地修改，则在第一次入队时处理）。规范化后的值会原地写回并供后续文档使用——因此按文档化的运行时改法持有的那个嵌套 recursive_character 字典引用，在收敛之后仍然生效。直接 SDK 调用与旧版本已持久化的快照会保留原值，并在执行时静默收敛——包括全部丢弃后回退到 separators=None 这一分支（它只可能由直接 SDK 调用触发）——避免一个历史错误值按文档重复告警。

  有一种修正并不是收敛：addon_params['chunker'] 的 separators 若既不是 list/tuple 也不是 None，该键会被整个移除并单独告警。原因是裸 str 满足 Sequence[str]——对它做边界收敛会按字符迭代，把一处笔误改写成 64 个单字符的级联，此后看上去完全像是有意为之。移除该键则让切分器走它文档化的 separators=None 路径。HTTP 请求体则是直接拒绝：请求模型对两条上限都会抛出校验错误，因此 /documents/text 等接口返回 422，不会走丢弃、截断或回退中的任何一条。数值上限各处相同，但对越界的响应刻意不同——发起 HTTP 请求的调用方就在现场能读到错误，写环境变量的人不在。

V —— 语义向量

• CHUNK_V_SIZE —— 未设，int。 V 自己的 chunk_token_size。它是硬上限：超过的部分会通过 R 二次切分。高于顶层兜底；未设时 V 沿用顶层解析结果。

• CHUNK_V_BREAKPOINT_THRESHOLD_TYPE —— percentile，str。 取值为 percentile / standard_deviation / interquartile / gradient 之一。

• CHUNK_V_BREAKPOINT_THRESHOLD_AMOUNT —— 未设（null），float。 阈值大小。null 表示让 LangChain 按类型自选默认值（percentile 用 95）。

• CHUNK_V_BUFFER_SIZE —— 1，int。 计算距离时合并的相邻句数。

• CHUNK_V_SENTENCE_SPLIT_REGEX —— str。默认值：

  textCopy

  (?<=[.?!])\s+|(?<=[。？！])
  

  喂给 LangChain SemanticChunker 的句子切分正则。默认同时识别英文 .?!（要求后接空白，因此 0.95 不会被切开）和中文 。？！（不要求空白，适应中文连写）。env 值是原始正则，无需 JSON 引号。

P —— 段落语义

• CHUNK_P_SIZE —— 2000（DEFAULT_CHUNK_P_SIZE），int。 P 自己的 chunk_token_size，也是唯一不继承的槽位。未设时 P 不会回退到顶层 CHUNK_SIZE / LightRAG(chunk_token_size=…)，而是始终携带 DEFAULT_CHUNK_P_SIZE——段落语义合并需要比全局默认更大的上限，才能把相关段落保留在一起。部署需要别的上限时在这里覆盖。P 的内部比例常量是算法刻度，会按这里解析出的值等比推导。
• CHUNK_P_OVERLAP_SIZE —— 未设，int。 P 自己的 overlap，高于 legacy 构造字段与 CHUNK_OVERLAP_SIZE。它管两件事：同一 JSONL content 行内长正文 fallback 到 R 时的文本重叠，以及大表格前后桥接文字复制进相邻块的单侧预算。它不会让表格行级切片互相重叠。

CHUNK_F_SIZE / CHUNK_R_SIZE / CHUNK_V_SIZE 的行为与 CHUNK_P_SIZE 相反：不设时它们会沿用顶层 chunk_token_size。这通常正是你想要的——F 就是默认全局窗口，R 偏向较小目标以便按句段切分，而 V 作为 advisory ceiling 通常是被调大而非调小，以减少过度拆分。

5.3 优先级链

每个分块槽位的最终值按 specificity-ordered 链解析（高 → 低）：

1. addon_params["chunker"] 显式值 —— 通过 SDK 路径运行时设置或在构造时显式写入的字段值（见 §11.3）。Server-only 部署通常不会出现这一档。最直接，赢一切。
2. strategy 特定 env —— 如 CHUNK_F_SIZE / CHUNK_R_SIZE / CHUNK_V_SIZE（各策略 chunk_token_size）、CHUNK_F_OVERLAP_SIZE / CHUNK_R_OVERLAP_SIZE / CHUNK_P_OVERLAP_SIZE（overlap）、CHUNK_P_SIZE（P 专属）。未设对应 size env 时，F/R/V 沿用顶层 chunk_token_size。仅当槽位未被 ① 显式占用时填入。
3. legacy 构造字段 —— LightRAG(chunk_token_size=…, chunk_overlap_token_size=…)，仅 SDK 路径生效，详见 §11.2。strategy 无关，"粗粒度缺省"，只填仍空的槽位。
4. legacy env —— CHUNK_SIZE / CHUNK_OVERLAP_SIZE。最终回退。

举例：CHUNK_R_OVERLAP_SIZE=42 + LightRAG(chunk_overlap_token_size=2) → R 子字典 chunk_overlap_token_size=42（strategy env 胜出），F / P 子字典 chunk_overlap_token_size=2（无 F / P 特定 env，legacy 构造字段填入）。

P 的 chunk_token_size 特例：P 的 chunk_token_size 槽位不走完整的四档链。当 ① 未显式提供时，直接按 CHUNK_P_SIZE env > DEFAULT_CHUNK_P_SIZE（2000）解析，跳过 ③ legacy 构造字段 LightRAG(chunk_token_size=…) 与 ④ legacy env CHUNK_SIZE。理由参见 §5.2 CHUNK_P_SIZE 行。

三层语义保证：

1. 复现性：env 改了，重启后老文档仍按入队那一刻的快照分块，结果不变。
2. 续跑一致性：续跑分支 B（内容已抽取，按当前 process_options 重做分块）读的也是 full_docs.chunk_options，避免 env 漂移破坏一致性。
3. per-file 个性化：调用方可以为每个文件传不同的 chunk_options（典型用法：管理 UI 单独配置某个文件的 separators 或 V 阈值）。这是 SDK 路径的入参语义，详见 §11.4。

5.4 字段结构

addon_params["chunker"]（实例字段）保留全部四种策略的子字典作为运行时基线；full_docs[doc_id]["chunk_options"] 是精简快照——入队时只保留 process_options 选中的那一路策略子字典（缺省 F），其它策略的参数会被丢弃，因为处理阶段不会读它们。重新解析时 process_options 与 chunk_options 一同改写，避免旧策略的参数残留。

addon_params["chunker"] 全量基线（运行时可由 SDK 修改，影响后续入队）：

{
  "chunk_token_size": 1200,                                   // 通用 token 上限
  "fixed_token": {                                            // F 专属
    "chunk_token_size": 1200,                                 // 可选;不写沿用顶层 chunk_token_size(可由 CHUNK_F_SIZE 种子化)
    "chunk_overlap_token_size": 100,
    "split_by_character": null,
    "split_by_character_only": false
  },
  "recursive_character": {                                    // R 专属
    "chunk_token_size": 1200,                                 // 可选；不写沿用顶层 chunk_token_size
    "chunk_overlap_token_size": 100,
    "separators": ["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""]   // 默认 cascade 含中文标点
  },
  "semantic_vector": {                                        // V 专属
    "chunk_token_size": 1200,                                 // 可选 hard cap；超过时通过 R 二次切分
    "breakpoint_threshold_type": "percentile",                // percentile | standard_deviation | interquartile | gradient
    "breakpoint_threshold_amount": null,                      // null = LangChain 默认
    "buffer_size": 1,
    "sentence_split_regex": "(?<=[.?!])\\s+|(?<=[。？！])"      // 默认正则兼容中英文句末标点
                                                              // 仅可通过 env/SDK 配置（CHUNK_V_SENTENCE_SPLIT_REGEX）；REST 的
                                                              // `chunking.params` 传入该键会返回 422 —— 见 GHSA-32jh-39m7-8x84（ReDoS）
  },
  "paragraph_semantic": {                                     // P 专属
    "chunk_token_size": 2000,                                 // 不写则按 CHUNK_P_SIZE 或 DEFAULT_CHUNK_P_SIZE（2000）解析；
                                                              // **不**继承通用 chunk_token_size
    "chunk_overlap_token_size": 100                           // 不写沿用 legacy overlap 解析链
  }
}

full_docs[doc_id]["chunk_options"] 精简快照（按 selector 投影；下例为 process_options="R"）：

{
  "chunk_token_size": 1200,                                   // 通用 token 上限（保留为顶层 fallback）
  "recursive_character": {                                    // 唯一保留的策略子字典
    "chunk_overlap_token_size": 100,
    "separators": ["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""]
  }
}

selector → 子字典映射：F → fixed_token，R → recursive_character，V → semantic_vector，P → paragraph_semantic；无 selector 默认 F。各子字典与对应分块器函数的 keyword-only 参数一一对应；新增参数时无需改 dispatcher，只在 chunker 函数添加 kwarg 即可。

5.5 缺失兼容

老文档入队时还没有 chunk_options 字段；分块时 dispatcher 会按当前 process_options 调用 resolve_chunk_options(self.addon_params, process_options=…) 兜底拼装一份精简快照。建议在升级后通过 reprocess 一次让老文档拿到精简的 chunk_options 快照（且与当前 process_options 对齐）。

6. 存储与目录布局

6.1 full_docs 字段

文件入队和抽取结果会写入 full_docs：

pending_parse 表示文件已经入队，但还没有完成抽取。抽取成功后会改写为 raw 或 lightrag，并补齐 content_hash。抽取失败时保留 pending_parse 和空 content，便于后续排查和重试。

doc_status 中也同步保存原始 file_path（含 hint）、canonical_basename 与 content_hash，作为 get_doc_by_file_basename / get_doc_by_content_hash 的查重索引来源。get_doc_by_file_basename 内部把传入参数先经 canonicalize_parser_hinted_basename 规范化后再与 canonical_basename 比对，因此 abc.docx 与 abc.[native-iet].docx 总是命中同一文档。 process_options 同时镜像写入 doc_status.metadata["process_options"]，便于管理 UI 直接展示当前文件的处理策略。

6.2 __parsed__ 目录结构

__parsed__ 是输入目录旁的归档与分析结果目录。它同时保存已经处理过的原始文档，以及结构化解析产生的 LightRAG Document （lightrag格式）的文件和图片等资源。

• 原始文件归档：legacy 本地抽取成功并入队后，原文件会移动到同级 __parsed__ 目录；native / mineru / docling 会先保留原文件供 pipeline 解析，解析成功并写入 full_docs 后再移动到 __parsed__。归档时保留原始文件名（含 [hint]），例如 report.[native-iet].docx 归档为 __parsed__/report.[native-iet].docx，便于追溯用户最初的命名与处理选项。
• 分析结果目录：结构化解析结果会写入以规范化文件名（去掉 [hint]）加 .parsed 后缀命名的子目录，避免与归档原文件同名冲突，并保证当文件名 hint 或处理选项变化时同一逻辑文档继续指向同一目录。例如 report.docx、report.[native].docx、report.[native-iet].docx 的分析结果都写入 __parsed__/report.docx.parsed/。
• 分析结果文件：LightRAG Document blocks 文件以及 sidecar 都使用规范化文件名的主干命名，例如 __parsed__/report.docx.parsed/report.blocks.jsonl；同一目录下还可能包含 report.tables.json、report.drawings.json、report.equations.json 和 report.blocks.assets/ 图片资源目录。sidecar 是否生成由文档内容决定：解析器只在文档实际包含表格/图片/公式时写出对应文件。这是模态可用性的唯一信号 —— 引擎不需要在 meta 中声明能力。i/t/e 选项只决定下一阶段是否对已存在的 sidecar 调用 VLM 做摘要分析。
• 解析失败时，原文件不会移动，便于修复配置后重新处理。
• /documents/scan 扫描到同名且已 PROCESSED 的文件时，该输入文件会被视为已处理并移动到 __parsed__，不会作为新文档入队。
• /documents/scan 同一次扫描中发现多个规范化后同名的文件时，先取得 canonical claim 的文件获胜（即目录流式遍历时先到达的那个）。可丢弃磁盘 spool 中的 scan-wide UNIQUE claim 会在任何候选落库前把后续变体归档并输出 warning。例如 abc.docx 和 abc.[native].docx 同时存在时只处理先被遍历到的那一个。hint 只决定引擎，不再提供调度优先级。
• 扫描或解析过程中发现内容 hash 重复时，该输入文件同样会移动到 __parsed__；本次 doc_status 保留为 FAILED duplicate 以便追踪。
• 移动文件只作用于当前输入文件，不会覆盖或移动既有文档源文件。若目标目录已存在同名文件，系统会自动追加 _001、_002 等编号，例如 report.pdf 会依次归档为 report_001.pdf、report_002.pdf。若分析结果目录名已被普通文件占用，也会追加编号，例如 report.docx.parsed_001/。

6.3 原始产物包（<base>.*_raw/）

有三个引擎会在 <规范文件名>.parsed/ 旁保留一份原始产物包，使得重新解析未变更的文件时不必重复该引擎那一步昂贵的工作。三者遵循同一套设计：产物目录里存放原始产物，外加一个 _manifest.json，它同时充当原子成功标记与缓存键。

产物包是 .parsed/ 的兄弟目录而非子目录，因此能在每次重新抽取前的目录清空中存活下来。

设计目标：

• 避免重复那一步昂贵的工作。 重新解析时先用源文件的 hash 与大小校验 _manifest.json；命中则完全跳过网络工作，直接把已存产物送进 adapter 与 sidecar writer。
• 保留诊断材料。 当引擎解析有误、或下游 sidecar 字段异常时，产物包就是与"引擎实际返回了什么"对照的地方。
• 支持对象溯源（外部引擎）。由 MinerU 产出的 drawings.json / tables.json / equations.json 会在 self_ref 里记录 content_list.json#/N，可据此回查对应的 MinerU 原始对象及其 page_idx / bbox。
• 上传文件名去 hint（MinerU）。当源文件名带有 [mineru-...] / [-iet] 之类处理 hint 时，调用 MinerU API 使用的是规范化后的文件名，避免带 hint 的文件名出现在返回的产物包里。

Docling 产物包目录结构：

__parsed__/<base>.docling_raw/
├── _manifest.json
├── <base>.json        # DoclingDocument JSON（含 pages[].image base64）
├── <base>.md          # Markdown 形式，供人工查看
└── artifacts/
    └── image_*.png    # 被 pictures[*].image.uri 引用的图片资源

生命周期，三个产物包完全一致：

强制重解析（完全绕过缓存）：LIGHTRAG_FORCE_REPARSE_NATIVE / LIGHTRAG_FORCE_REPARSE_MINERU / LIGHTRAG_FORCE_REPARSE_DOCLING（§3.7）。

并发安全：LightRAG 强制同一 workspace 内 canonical_basename 唯一（upload / enqueue 时返回 HTTP 409），加上流水线对每个文档的串行处理，任何产物包都不会被并发写入，无需额外加锁。

manifest 失效条件

以下任一项不匹配即缓存未命中。三个产物包共有的：

• 源文件大小或 sha256 与 manifest 不符；
• 记录在案的产物缺失，或其大小 / sha256 与 manifest 不符。

在此之上各引擎特有的条件：

"任一侧为空即跳过" 适用于两个外部引擎的 engine_version 与 endpoint_signature。若写 manifest 时该字段为空（例如首次解析时未配置 MINERU_ENGINE_VERSION），或当前环境变量未设置，则跳过该项检查。因此，在产物包已经存在之后才设置版本号变量，并不会追溯性地让它失效——这种情况需要用对应的 LIGHTRAG_FORCE_REPARSE_* 标志。

7. 同名与重复文档

文件上传、目录扫描和文本接口都会查重。同一份内容重复入库会浪费 LLM 配额，还会在知识图谱里造出重复实体，所以 LightRAG 用文件名和内容两条规则查重：命中任一即判为重复，本次记录写为 FAILED，已有文档永远不会被覆盖。所有查重都在分块、实体抽取和图谱写入之前完成——但这不等于"落库之前"：native / mineru / docling 必须先持久化待解析记录、再持久化解析结果，才拿得到内容 hash，所以这条路径上会短暂存在一条随后被撤销的记录（见 §7.1、§7.2）。

7.1 两条查重规则

规则一：文件名重复。 只比对文件名本身（不含目录，也不含 workspace 路径），因此 /data/a.pdf、inputs/a.pdf 和 a.pdf 是同一个名字。比对前会先剥掉能识别的 [引擎-选项] hint，所以 abc.docx、abc.[native].docx、abc.[native-iet].docx 互相视为同名；无法识别的 hint 不剥离，abc.[draft].docx 仍是另一个名字。只要 doc_status 里已有同名记录，无论它处于 PENDING、PARSING、ANALYZING、PROCESSING、FAILED 还是 PROCESSED，本次都算重复。

规则二：内容重复。 比对的是抽取之后的正文，不是原始文件的字节。所以换个文件名、甚至换成另一种格式，只要抽出来的内容一致就算重复。取值口径按内容格式区分：

这也决定了内容查重发生在什么时候：legacy 在本地抽完文本、入队时就能判；native / mineru / docling 要等解析真正完成才判，此时本次记录会停在建库之前——不分块、不抽实体、不写图谱，并删掉本次临时写入的 full_docs。

两条补充规则：

• 文本接口（/documents/text、/documents/texts）必须提供有效的 file_source，并按它的 basename 判定同名；缺失时直接返回 400。
• 无来源文档（SDK 调用 insert / ainsert 时不传 file_paths，file_path 记为 unknown_source）不参与同名查重——unknown_source 只是占位名，两份无来源文档不会因为它互相冲突——但仍然按正文内容查重：重复插入同一段正文依旧会被判为重复。空字符串与 no-file-path 同理。

同一批入队内部、以及并发发起的两次入队，都不会双双穿透查重：后到的那条一定会被识别为重复并写为 FAILED。

7.2 你会看到什么

上传路径是 fail-fast 的：前两种情况直接 409，不写文件、也不在 doc_status 里留下任何痕迹。后三种会在文档列表里留下记录，但记录形态不同——运维时不能只按 dup- 前缀查找：

• 入队时发现的重复（同名，或 legacy 路径上正文 hash 已存在）：新建一条 doc id 以 dup- 开头的 FAILED 记录，原文档不受影响。metadata 带 duplicate_kind（filename / content_hash）、original_doc_id 和 original_track_id，指向保留下来的那份正本。
• 解析完成后才发现的内容重复（native / mineru / docling 入队时还没有正文 hash）：不会新建 dup-* 记录，而是把本文档原有的 doc-* 记录就地改成 FAILED，写入 metadata.is_duplicate=true 与 duplicate_kind=content_hash，删掉本次临时写入的 full_docs，并把源文件归档到 __parsed__。
• filename_conflict：库里已有多条主记录占用同一个文件名，系统故意不替你选正本，因此这条记录上的 original_doc_id 并不指向某个"保留下来的正本"——必须先按 §7.3 修复冲突。

7.3 怎么处理

• 想用新内容替换同名文档：先删除（POST /documents/delete_document，或 WebUI 文档列表里的删除对话框），再上传。上传永远不会覆盖已有记录。
• 想清掉重复记录：dup-* 记录、以及解析后被就地改成 FAILED 的那条原记录，都是惰性记录——没有正文内容，/documents/scan 与 /documents/reprocess_failed 都会跳过它们，既不会重跑，也不会再失败一次。要清掉只能显式删除；留着不管也不影响检索。
• 只是想换引擎或换处理选项重跑同一份文件：查重不是障碍，被冻结的配置才是——见 §8.3 与 §9.3，这种情况必须删除后重新上传。
• filename_conflict（一名多记录）：用 GET /documents/source_conflicts 列出冲突，POST /documents/source_conflicts/repair 指定要保留的 primary_doc_id（默认 dry-run，拿到 candidate_count / fingerprint 后回填提交；候选集有变动则返回 409），或离线执行 python -m lightrag.tools.source_conflict_repair。修好之后再扫描。

7.4 目录扫描的特殊处理

/documents/scan 用的是同一套查重口径，但它同时面对"磁盘上的文件"和"库里的记录"两侧，所以对同名文件有额外的自动处理——目的就是让"改好配置、修好源文件，再扫一次"能直接生效，而不必逐个手工删除：

两点运维须知：

• 扫描被中断（取消、崩溃、重启）时一条都不会入队。 发现与入队分两步走，源文件始终留在 INPUT_DIR，下次扫描重新发现即可。唯一回不来的是上表第三行已经删掉的失败记录——文件会作为新文档重跑，但那条留作人工复核的记录没了。
• SCAN_SPOOL_DIR 必须指向真实可写的本地磁盘。 扫描期间的候选清单落在 SCAN_SPOOL_DIR，未设置时取 WORKING_DIR/scan_spool，两者都再按 workspace 分子目录。不要指向 tmpfs（很多 Linux 主机上 /tmp 是内存盘）；WORKING_DIR 本身是网络卷时应显式设置这个变量。目录不可用时扫描直接失败且一条都不入队，错误信息会点名该变量，输入文件原封不动，改完配置重扫不丢任何东西。

8. 运行控制：边跑边传、停止与重试

本章回答三个运行期问题：流水线跑起来之后还能不能继续上传、怎么把它停下来、以及文档失败之后该怎么重试。并发调优参数与请求准入限制放在本章末尾两节。

8.1 处理进行中还能做什么

要点：

• 长批次处理期间可以继续上传，不用等。 这是最常被误解的一点：文档处理本身不阻塞上传。新文档写完记录后由运行中的流水线自动接手——可能被并进当前批次，也可能在批次边界被接上，两种都不需要你做任何额外操作。
• 扫描、删除、清空需要流水线空闲。 扫描要一边读库一边决定每个磁盘文件的去向（§7.4），删除和清空会直接拆掉存储，这两类都不能和并发写入交错。被拒时 /documents/scan 返回 HTTP 200 但 status="scanning_skipped_pipeline_busy"，删除 / 清空返回 status="busy"——都不是报错，等空闲后重试即可。
• 查询不受流水线准入约束，但清空 / 删除期间不保证结果。 查询接口不检查流水线状态，所以不会像上传那样被 409 拒绝；但 /documents/clear 会用 asyncio.gather 并发 drop 文本分块、实体 / 关系 / chunk 向量、知识图谱、full_docs 与 doc_status 等十余个存储，而查询既不持有一致性快照，也不会等它结束——中途发起的查询可能拿到空结果、部分结果或存储报错。"请求会被受理"和"能返回一致结果"是两回事：破坏性操作期间应当等它跑完再查。
• 上传被拒时按报错文案定位原因，三种 409 各自对应一种状态：
  • Document scan is classifying files. … —— 扫描正在分类阶段。
  • Pipeline is clearing or deleting documents. … —— 正在清空或删除文档。
  • A retry of failed documents is draining the pipeline. … —— 手动重试正在排空流水线（§8.3）。
• 上传返回 413 / 429 与流水线是否繁忙无关，那是请求准入限制，见 §8.7；返回 503 见 §8.5。

8.2 如何停止正在运行的流水线

POST /documents/cancel_pipeline      # 无请求体

WebUI 入口是文档管理页「流水线状态」对话框里的**「中断」**按钮，仅在流水线运行中且尚未请求中断时可点。接口返回 {"status": "cancellation_requested" | "not_busy", "message": …}：not_busy 表示当前没有在跑，无需中断。

返回 200 不代表已经停了。 它只是置了一个中断请求标志。中断是协作式的：只在阶段之间、批次边界、以及多模态分析每 0.5 秒的轮询点生效，不会打断已经发出的 LLM 调用。所以点完之后还要等当前这一步跑完，GET /documents/pipeline_status 上的 cancellation_requested 可以确认请求已经收到。

停下来之后，文档会落在这几种状态：

几点补充：

• 已完成的部分工作不会浪费。 LLM 缓存和已经分析成功的多模态条目都会落盘，之后重试会命中缓存，不会重复花钱。
• ⚠️ 被标成 FAILED 的文档不会自动重试，必须用 §8.3 的显式重试手段捞回来。
• 中断期间仍可继续上传。 新上传的文档会在这一轮退出之后，由下一轮自动接上。
• 什么时候它不管用：扫描的分类阶段不算"流水线繁忙"，此时调用会返回 not_busy，而且目前没有中断扫描任务的接口——等它跑完即可。删除 / 清空作业可以被中断，粒度是逐个文档：已删除的保持删除，剩余的会在响应里报告为未删除。

直接重启或杀掉服务是另一种停法，后果不同：

• 进行中的文档会停在 PARSING / ANALYZING / PROCESSING，不会被写成 FAILED。
• 这些中断态在下一次流水线启动时会自动恢复为 PENDING 重跑，不需要手工干预。
• 但服务启动本身不会自动开跑：需要一次上传，或调一次 POST /documents/scan 来触发。所以重启后看到文档卡在 PROCESSING 不必惊慌，触发一次即可。

8.3 出错后如何重试

失败文档有三种捞回方式，按覆盖面从大到小：

四条必须知道的口径：

1. 每次重试请求对每个文档只给一次机会。 再失败就停在 FAILED，等下一次显式重试，不会自旋。
2. 自动续跑不碰 FAILED。 上传新文件触发的那一轮只会恢复中断态（PENDING / PARSING / ANALYZING / PROCESSING）；FAILED 只能靠上表前两个显式入口。
3. 是否重新解析，取决于正文有没有抽取成功。 已经抽出正文的文档不会重解析：重试从多模态分析阶段起跑，先清掉上一轮写进去的 chunks 与图谱贡献再重做（细节见 §9.3），所以"修好 VLM 配置 / 等限流恢复之后重试"是有效的。而在解析阶段就失败的文档（full_docs 里只留着 pending_parse 占位记录）会被重置为 PENDING 后重新进入解析阶段，再次读取 INPUT_DIR 里的源文件、再次调用对应引擎——修好 MinerU / Docling 后重试因此有效，但源文件已被删除时这类重试会再次失败。
4. 重试不会改引擎与处理选项。 parse_engine、process_options、chunk_options 在入队那一刻就冻结进记录了；改 .env 或改文件名 hint 只对新上传生效。

哪些情况重试有效、哪些必须删除重传：

/documents/reprocess_failed 还有两点值得知道。它会先冻结入口、把流水线排空到空闲——这段时间上传返回 409、/documents/scan 被拒——再在没有任何 worker 运行的前提下把 FAILED 改回 PENDING，然后恢复正常处理；文档数量多时这个过程需要一点时间。它可能返回 429（未确认的重试请求过多，上限由 MAX_UNACKED_MANUAL_RETRIES 控制）或 503（栅栏已升起，或正在清空 / 删除）；排空迟迟到不了空闲时会升起栅栏，见 §8.5。

8.4 删除文档：两个勾选项的区别

删除对话框里的两个复选框默认都不勾，它们决定磁盘上的东西是否一起清掉：

• 都不勾：只删存储里的状态——chunks、向量、图谱贡献、doc_status、full_docs。磁盘上的源文件、__parsed__ 里的归档件与 .parsed/ sidecar、外部引擎的原始产物缓存全部保留。
• 勾「同时删除上传文件」（API 参数 delete_file=true）：连同 INPUT_DIR 里的源文件、__parsed__ 下的归档件与 <base>.parsed/ sidecar，以及 <base>.mineru_raw/ / <base>.docling_raw/ / <base>.native_raw/ 原始产物缓存一起删除。想换引擎重跑、或想让外部引擎真的重新解析一次，必须勾这个，否则重新上传会命中缓存拿回旧结果（§3.7、§6.3）。
• 勾「同时删除实体关系抽取 LLM 缓存」：额外清掉该文档抽取阶段的 LLM 缓存，重传时会真实重跑 LLM 而不是命中缓存。想验证换了模型或提示词之后的效果，需要勾它。

8.5 所有接口都返回 503：recovery_required 栅栏

有些故障会让 workspace 处于"继续下去只能靠猜"的状态。管线不做这种猜测，而是升起 recovery_required 栅栏：此后所有写操作（upload / text / scan / 手动重试 / delete / clear）一律返回 HTTP 503，直到运维显式解除。三种情况会升起它——其中 1 和 3 依赖跨进程的死进程检测，只在 Linux + Gunicorn 多 worker 部署下才会发生（单进程 uvicorn 的协调状态随进程一起消失）：

1. worker 在 custom_chunks / delete / clear 执行途中死亡。 这些操作可能已经半提交，不能简单重跑。（processing / scan 的执行者死亡是可重跑的，会被静默回收，不设栅栏。）
2. 手动重试的排空无法到达空闲。 有两种卡法：同一批文档反复回来且状态毫无变化（再重扫只会自旋），以及排空根本无法推进的文档——持有未完成 custom-chunk 操作的行，只有 /documents/scan 的回滚能处理它们。两种情况下重置都不执行，重试请求保持未确认（那一次机会仍然欠着），栅栏消息里带阻塞文档 ID 的有界样本。recovery_kind 区分二者：manual_drain_stalled 和 manual_drain_blocked。
3. 无法判定某个执行者是否已经死亡。 回收一个执行权必须先证明其所属进程确已死亡；不带进程身份的记录永远无法证明，管线不靠猜回收，改由栅栏提供出口。

GET /documents/pipeline_status 会返回 recovery_required（布尔）、recovery_kind（粗粒度原因）和 recovery_message（与 503 相同的文案，某些原因还带阻塞文档的有界样本）。

解除栅栏：

POST /documents/recovery/force_reset

这是不安全的人工覆盖——它不修复任何东西。除栅栏之外，它还会取消该 workspace 排队中的手动重试请求，这一点是必需的而非附带：只要还有排队请求，/documents/scan 就会拒绝执行（scan 自己也要跑独占的 FAILED 重置，不能插队），所以只清栅栏会让恢复路径照样被堵。响应里返回 cancelled_manual_retries。不会丢文档——失败文档仍是 FAILED，由下一次重试请求或 scan 自己的重置处理。由于两半都是必需的，这个调用是全有或全无的：如果排队请求无法取消，接口返回 503 且栅栏保持不变，这样可以重试来完成恢复，而不是让 API 报告一次并未发生的恢复。

恢复顺序：

能不能直接重启服务了事？ 判断标准只有一条——堵塞源在内存里还是在存储里。重启清掉的只有运行时协调状态（pipeline_status 里的栅栏与 owner 记录、ingress 里排队的手动重试请求，都不持久化），写进 doc_status / full_docs / 存储的东西一样都清不掉。

所以重启相当于一次"温和版 force_reset"：两者都清栅栏与排队请求、都不修复任何东西，区别是重启还会顺带把中断态文档重置为 PENDING（这正是 stalled 常能自愈的原因），代价是一次服务中断。能停服务就优先重启；不能停、且已确认存储未被动过（成因 2 / 3）才用 force_reset。

半提交存储怎么修：两个离线工具与 force_reset 的分工

栅栏本身不持久化（它活在 pipeline_status 里），整体重启服务就会清掉它和排队请求。这一点决定了 force_reset 该用在哪：

• 成因 2 / 3 用它。 这两种情况下重置根本没执行、存储一字未动，卡住的只是调度——为此停服务不值得。
• 成因 1 尽量别用它。 它只清标志、不修任何东西；清完之后所有写入（包括并发上传）立刻在一个可能半提交的存储上重新开工。而下面两个离线工具本来就要求先停服务——停下来栅栏自然消失，force_reset 根本不必出场。

两个离线工具能修什么、修不了什么：

两个顺序陷阱，弄反了会把可修复的数据变成不可修复的：

• kg_integrity_repair 必须在任何进一步删除之前跑。 它只能从幸存的 chunk provenance 重建锚点；半截的 delete 若已经删掉 text_chunks，那部分贡献就成了不可恢复孤儿，工具只能报告、绝不自动改。先跑一次报告模式（不加 --apply）没有任何理由不跑。
• lightrag-rebuild-vdb 必须最后跑。 它把图与 text_chunks 当作真相：半截 delete 留下的、本该删掉的图对象，会被它忠实地重新嵌入回向量库。它保证的是向量与图一致，而不是图本身正确。所以先把图这一侧的真相定下来，再考虑重建向量。

因此成因 1 的完整顺序是：

1. 停服务（栅栏随之消失，别急着 force_reset）。
2. python -m lightrag.tools.kg_integrity_repair --verbose 先看报告：锚点缺口、以及已经救不回来的不可恢复孤儿。有缺口再 --apply。
3. 起服务，把没做完的那次操作重跑一遍——whole-document purge 带 journal，会从已完成的阶段之后接着做；clear 直接重跑；custom_chunks 的回滚由 POST /documents/scan 触发。
4. 稳定之后若怀疑图↔向量漂移，再停服务跑 lightrag-rebuild-vdb，先用菜单里的只读一致性检查决定值不值得付嵌入成本。

两个工具都必须在服务已停止、workspace 空闲时运行（并发写入会让它们读到移动的目标）；lightrag-rebuild-vdb 还必须使用与服务相同的 .env，否则重建出的向量落在另一个嵌入空间里。详见 README_KG_INTEGRITY_REPAIR.md 与 README_REBUILD_VDB.md。

8.6 流水线并发参数

上面几节讲的是"谁能写"的正确性问题，本节这一组参数解决的是"同时跑几个 worker"的吞吐量问题。流水线分为 3 个阶段，每个阶段的 worker 池数量独立可调：

          ┌─ parse_queues["native"]  ─► [native 池  × N1] ─┐   ← legacy 共享此池
PENDING ─►├─ parse_queues["mineru"]  ─► [mineru 池  × N2] ─┼─► q_analyze ─►[analyzer × N4] ─► q_process ─►[processor × N5]
          ├─ parse_queues["docling"] ─► [docling 池 × N3] ─┤
          └─ parse_queues[<第三方组>] ─► [自定义并发池]  ──┘   ← 按 ParserSpec.queue_group 动态创建

解析队列按注册表的 ParserSpec.queue_group 动态创建（每批取一次注册表快照）：内置 native/mineru/docling 各占一组，legacy 共享 native 池（本地、无网络），第三方引擎可声明独立组与自定义并发数（见 ThirdPartyParser-zh.md）。入队时根据每个文档的解析引擎（来自 LIGHTRAG_PARSER 默认值或文件 hint）把它放入对应解析队列；各解析队列完全互不阻塞——mineru 占满不会拖慢 docling 或 native。解析完成后统一进入 q_analyze（多模态分析），再进入 q_process（实体/关系抽取 + 入库）。

几个要点：

1. 解析阶段按引擎隔离，所以混用 native/mineru/docling 时不必担心一种引擎慢拖累另一种。
2. mineru / docling 默认 2：两者资源占用高，默认保持适度并发。资源紧张时可降到 1（避免 OOM / 显存竞争 / 失败重试）；如果你部署了多 GPU 或专门的解析服务器，可手动调高。
3. MAX_PARALLEL_INSERT 兼任 worker 池大小和信号量上限：流水线创建 Semaphore(max_parallel_insert)，每个 process worker 在抽取入库前还要拿一次信号量。所以哪怕你把 worker 数手动改大，实际并发上限仍由这个值决定——直接调它就够了。
4. queue size 与背压：QUEUE_SIZE_INSERT=4 这个偏小的默认值是有意为之——process 阶段慢且占内存，让 analyze 阶段在队列写满时阻塞、再反压到 parse 阶段，避免一次性把成千上万份解析结果堆在内存里。
5. 改后生效方式：所有参数通过 .env（或环境变量）传入，仅在 LightRAG 实例构造时读取一次；改完需要重启服务。
6. 分块不随并发增长：分块在一个专用的单 worker 线程池里执行，目的是不阻塞事件循环，并发度不随 MAX_PARALLEL_INSERT 提高，调大并发不会让分块更快。自定义 chunking_func 仍在事件循环上执行（它的契约允许触碰运行中的事件循环），CPU 密集的实现应自行 asyncio.to_thread。

典型调优场景：

• 大量 PDF + 本地 MinerU 单 GPU：MAX_PARALLEL_PARSE_MINERU=2、MAX_PARALLEL_ANALYZE=5、MAX_PARALLEL_INSERT=3（默认即可；显存紧张时把 MINERU 降到 1）。
• 大量 PDF + MinerU 云端服务：MAX_PARALLEL_PARSE_MINERU=3~5（视云端配额），其它保持默认。
• 纯 docx / txt（仅走 native）：MAX_PARALLEL_PARSE_NATIVE=10、MAX_PARALLEL_INSERT 按 MAX_ASYNC_LLM/3 推算。
• LLM 限流明显：先降 MAX_PARALLEL_INSERT（process 阶段每文档多次 LLM 调用），再降 MAX_PARALLEL_ANALYZE（VLM 是独立配额）。

8.7 准入与请求限制

在文档触及上述任何机制之前，服务端就可能直接拒收。下面这些变量决定一次上传是被拒绝还是被排队：

它们的完整语义（含 MAX_UPLOAD_SIZE 与反向代理自身请求体上限的关系）见 LightRAG Server。

另有三个属于流水线自身、而非请求准入的旋钮：

9. 流水线启动时的续跑规则

每次 apipeline_process_enqueue_documents 起步时，会拉取所有处于 PARSING / ANALYZING / PROCESSING / PENDING / FAILED 状态的文档继续处理。续跑路径根据"内容是否已抽取"分流，保证同一个文档无论之前进度如何，按当前 process_options 续跑都有幂等结果。

续跑规则只对 doc_id 已经存在于 doc_status 的文档生效。新文件入队需要 §7 的文件查重逻辑，避免新文件挤掉旧的已经成功提取内容的文件记录。

9.1 判断"内容已抽取"

读 full_docs[doc_id]：

9.2 分支 A：未抽取

走完整流水线（注册表派发解析 get_parser(engine).parse(...) → analyze_multimodal → 分块 → 实体抽取），按 full_docs.process_options 决定每一阶段的行为。这是"首次入队"的常规流。

9.3 分支 B：已抽取

一律跳过解析（不重新调 parse_*），从 ANALYZING 阶段重启，并清光旧 chunks / entities 后按当前 process_options 重做：

这条规则保证：用户改 i/t/e 重传同名文档（先删旧 doc 再上传带新 hint 的文件）时，多模态分析能增量补齐；改 F/R/V/P 时 chunks 与图谱重建；改 ! 时停掉或恢复 KG 构建。引擎变更被视为"重大变更"，统一由 delete + 重传完成，不在续跑路径里隐式发生。

10. 常见问题排查

11. Python SDK 调用

本章针对直接 import LightRAG 类进行集成的开发者，覆盖 Server 部署不会用到的运行时 API、构造期参数和已移除的旧接口。Server 用户通常无须阅读本章。

11.1 适用对象

from lightrag import LightRAG
rag = LightRAG(working_dir="./rag_storage", ...)
await rag.initialize_storages()
await rag.ainsert("text", file_paths="doc.pdf")

这种调用方式以下行为与 Server 路径不同：可在不重启进程的情况下改 addon_params["chunker"]，可向 apipeline_enqueue_documents 传入 per-file chunk_options，可在 ainsert 调用时动态覆盖 F 策略的预切分参数。

11.2 LightRAG 构造期参数

LightRAG(chunk_token_size=…, chunk_overlap_token_size=…) 是 §5.3 优先级链中的第 3 档："legacy 构造字段"。strategy 无关、粗粒度缺省，只填仍空的槽位：

• 优先级低于 addon_params["chunker"] 显式值（§11.3）和 strategy 特定 env（§5.2）。
• 优先级高于 legacy env CHUNK_SIZE / CHUNK_OVERLAP_SIZE。
• 实例字段 self.chunk_token_size / self.chunk_overlap_token_size 在 __post_init__ 之后总会被回填为 int，方便仍读这两个字段的旧路径（如 pipeline.py 中 chunk_opts.get("chunk_token_size") or self.chunk_token_size 兜底）继续工作。

11.3 运行时改 addon_params["chunker"]

addon_params["chunker"] 是 ObservableAddonParams 字段，可以运行时改：

rag.addon_params["chunker"]["recursive_character"]["separators"] = ["##", "\n", " "]

改完后，后续入队的文档拿到新默认；已入队文档保留入队时的快照不变（参见 §5.3 三层语义保证）。这是 §5.3 优先级链的第 1 档："addon_params["chunker"] 显式值"，赢一切。

Server 部署没有这个能力 —— 改 env 后必须重启服务才生效。

11.4 apipeline_enqueue_documents(chunk_options=…)

apipeline_enqueue_documents 接受可选的 chunk_options 参数，调用方传入 dict / list[dict] 会按当前文档的 process_options 投影为精简快照（只保留对应策略子字典 + 顶层 chunk_token_size）后持久化到 full_docs[doc_id]["chunk_options"]；不传则由 resolve_chunk_options(self.addon_params, process_options=…) 现场拼装一份。调用方可以放心传入全量字典——其它策略子字典会被 dispatcher 丢弃，不会污染存储。

典型用法：

await rag.apipeline_enqueue_documents(
    input=["text A", "text B"],
    file_paths=["a.[native-R].txt", "b.txt"],
    process_options=["R", ""],
    chunk_options=[
        {"chunk_token_size": 800, "recursive_character": {"separators": ["\n\n", "\n"]}},
        {"chunk_token_size": 1500},
    ],
)

per-file 个性化的典型场景：管理 UI 单独配置某个文件的 separators 或 V 阈值；将来上传 API 也可在 form / hint 中接收覆盖。

不传 file_paths 的兼容：核心 API insert / ainsert / apipeline_enqueue_documents 仍兼容未传 file_paths 的调用；这类文档的 file_path 会保存为 unknown_source，不会参与文件名查重，文档 ID 继续按文本内容生成。

apipeline_enqueue_documents 自身的并发约束见 §8.1 的状态-操作表。

11.5 ainsert(split_by_character=…, split_by_character_only=…)

LightRAG.ainsert(split_by_character=…, split_by_character_only=…) 的运行时参数在入队时由 resolve_chunk_options 覆写到 chunk_options.fixed_token：

• split_by_character 非 None 即覆盖 env 默认；
• split_by_character_only=True 即覆盖（False 是签名默认值，与"未指定"无法区分，所以 env 默认胜出）。

仅对 F 策略生效；其它策略的子字典不受影响。

11.6 已移除的 SDK 入参：reprocess_existing_non_processed

旧 apipeline_enqueue_documents 的 reprocess_existing_non_processed=True 行为会在 scan 时直接删除非 PROCESSED 的旧记录并重建，与 §7 / §8 的规则相冲突，已整段移除。替代路径：

• 自动续跑：scan 按 §7.4 的规则处理同名文件（归档 / 续跑 / 删记录后重入队），由 §9 续跑规则在处理循环里统一接管。
• 强制刷新：先调 /documents/delete_document 删旧文档，再上传同名新文件。

附录 A：从旧版升级的注意事项

A.1 多模态全局开关已被文件级选项取代

addon_params["enable_multimodal_pipeline"] 已废弃。多模态分析现在按文档、通过 i / t / e 处理选项选择（§2.1），既可在 LIGHTRAG_PARSER 中作为规则默认值设置（§2.4），也可通过文件名 hint 指定（§2.5）。不再存在"全部分析"式的全局开关，因为一篇文档实际含有哪些模态由解析引擎决定、以 sidecar 是否存在来表达，而不是由配置决定。

迁移方式：把原来的全局开关换成路由规则上对应的字母，例如 LIGHTRAG_PARSER=*:native-iteP,*:legacy-R。注意 VLM_PROCESS_ENABLE 是一个正交的独立开关：它只闸控图片分析（表格与公式由 EXTRACT 角色分析）；若启用了 i 而 VLM 不可用，通过前置过滤的图片会让该文档失败，而不是被跳过。

升级前已入库的文档，其 process_options 在入队时就已冻结在 doc_status 记录里；改规则或改 hint 都不会追溯修改它们。要让已有文档按新选项重跑，只能删除后重新上传（§9.3）。

A.2 不主动开启则行为不变

不配置 LIGHTRAG_PARSER 时，所有扩展名仍然走 legacy 内容抽取器与旧的分块行为，与升级前完全一致。新引擎与新分块策略都是 opt-in 的；§1 给出了三套可直接套用的预设。

A.3 已移除的 SDK 入参

apipeline_enqueue_documents(reprocess_existing_non_processed=...) 已移除，替代路径见 §11.6。

附录 B：环境变量速查

本表说明各类文件处理相关环境变量该去哪里查，是索引而非复述：逐个变量的权威说明在 env.example 的注释里。