ContextQMD
Back to Lightrag

Parser CLI Debuger使用指南

docs/ParserDebugCLI-zh.md

1.5.07.4 KB
Original Source

Parser CLI Debuger使用指南

本工具用于本地调试 LightRAG 的三个内容解析引擎（native / mineru / docling），针对单个文件触发 LightRAG.parse_<engine> 生产代码路径，并把解析产物（sidecar 与 raw 缓存）输出到一个扁平目录布局——与生产入库目录相比，区别仅在于：

  • 无 __parsed__/ 中间层：产物直接落在指定父目录下，便于查看；
  • 源文件不会被归档：源文件保留在原位置（生产路径会把源文件移到 <INPUT_DIR>/__parsed__/）；
  • raw 缓存只看目录是否存在：mineru / docling 的 raw 目录非空即视为有效，跳过 _manifest.json 校验。

其余流程（IR 构建、sidecar 写入、对 full_docs 的同步逻辑）与生产入库完全一致，便于排查解析阶段问题。

命令格式

bash
python -m lightrag.parser.cli <input_file> \
    --engine {native|mineru|docling} \
    [-o <sidecar_parent_dir>] \
    [--doc-id <doc-id>] \
    [--force-reparse] \
    [--preview N]
参数说明
input_file待解析的源文件路径（位置参数，必填）。文件必须实际存在。
--engine必填：native（仅 .docx，本地解析）/ mineru（PDF/办公文档，调 MinerU 服务）/ docling（PDF/办公文档，调 docling-serve）。
-o / --sidecar-parent-dirsidecar 与 raw 目录的父目录，默认 = 源文件所在目录。
--doc-id自定义文档 ID，默认 doc-<md5(源文件绝对路径)>（同一文件多次跑结果稳定）。
--force-reparse仅对 mineru / docling 生效：清空 raw 目录、强制重新下载与解析。默认行为是 raw 目录非空即复用。
--preview N解析完成后打印前 N 个 block 的预览（headings + 内容片段），默认 5；0 关闭。

输出目录布局

以输入 ./inputs/workspace/sample.pdf + 默认 sidecar 父目录（即 ./inputs/workspace/）为例：

./inputs/workspace/
├── sample.pdf                       # 原文件，不动
├── sample.pdf.parsed/               # ← sidecar 输出
│   ├── sample.blocks.jsonl          # JSONL：首行 meta，后续每行一个 block
│   ├── sample.blocks.assets/        # native 抽取的图片/媒体资产（若有）
│   ├── sample.tables.json           # 表格 sidecar（若 IR 含 tables）
│   ├── sample.drawings.json         # 图纸/图片 sidecar（若 IR 含 drawings）
│   └── sample.equations.json        # 公式 sidecar（若 IR 含 equations）
└── sample.pdf.<engine>_raw/         # ← mineru / docling 的 raw 缓存（native 无此目录）
    ├── _manifest.json               # 由引擎下载流程写入；CLI 缓存校验不读
    └── <bundle files>               # 引擎特定 raw 产物（content_list.json / *.json / 资产等）

native 引擎不产生 raw 目录（解析是本地的，无外部服务参与）。

典型用例

A. 本地解析 .docx（零网络依赖）

bash
python -m lightrag.parser.cli ./inputs/workspace/sample.docx --engine native
# 产出：./inputs/workspace/sample.docx.parsed/  （含 blocks.jsonl + assets）

B. 用 MinerU 解析 PDF（首次会下载 raw）

bash
# 第一次：下载 raw bundle + 生成 sidecar
python -m lightrag.parser.cli ./inputs/workspace/sample.pdf --engine mineru
# 第二次（无任何修改）：raw 目录非空 → 直接复用 → 仅重建 sidecar，速度快
python -m lightrag.parser.cli ./inputs/workspace/sample.pdf --engine mineru
# 日志会显示： [parse_mineru] raw cache hit doc_id=... raw_dir=.../sample.pdf.mineru_raw

C. 用 Docling 解析 PDF + 复用已有 raw 目录

bash
# 已有 ./inputs/workspace/sample.pdf.docling_raw/ （含 docling 产物的 JSON 等文件）
python -m lightrag.parser.cli ./inputs/workspace/sample.pdf --engine docling
# CLI 不查 manifest，只要 raw 目录非空就跳过 docling-serve 调用

注：这是旧 python -m lightrag.parser.external.docling 调试入口「从已有 raw 重建 sidecar」场景的等价替代——只需把 raw 目录放到约定位置（<sidecar_parent>/<source>.docling_raw/）即可触发缓存命中分支。

D. 输出到自定义目录

bash
python -m lightrag.parser.cli ./inputs/workspace/sample.docx \
    --engine native -o /tmp/debug_sidecar
# 产出：/tmp/debug_sidecar/sample.docx.parsed/
# 原文件 ./inputs/workspace/sample.docx 不会被移动

E. 强制重新解析（清空 raw 后重新下载）

bash
python -m lightrag.parser.cli ./inputs/workspace/sample.pdf \
    --engine docling --force-reparse
# raw 目录被清空 → 重新调 docling-serve 下载 → 重新生成 sidecar

环境变量

mineru / docling 引擎在 缓存未命中（首次解析或 --force-reparse）时会调用外部服务，所需环境变量与生产入库一致：

  • MinerU：MINERU_API_MODE（local / official）、MINERU_API_TOKEN、MINERU_LOCAL_ENDPOINT 或 MINERU_OFFICIAL_ENDPOINT，可选 MINERU_ENGINE_VERSION / MINERU_MODEL_VERSION / MINERU_POLL_INTERVAL_SECONDS / MINERU_MAX_POLLS。
  • Docling：DOCLING_ENDPOINT，可选 DOCLING_ENGINE_VERSION / DOCLING_DO_OCR / DOCLING_FORCE_OCR / DOCLING_OCR_ENGINE / DOCLING_OCR_PRESET / DOCLING_OCR_LANG / DOCLING_DO_FORMULA_ENRICHMENT / DOCLING_POLL_INTERVAL_SECONDS / DOCLING_MAX_POLLS。

详见 FileProcessingConfiguration-zh.md。

缓存命中时（raw 目录已存在且非空，且未传 --force-reparse）无需任何外部服务环境变量——可用于离线复现解析输出。

常见排障

现象处理
error: input file does not exist: ...检查 input_file 路径，必须是已存在的文件（不是 raw 目录）。
raw 目录存在但 sidecar 内容仍是旧的默认会复用 raw 重建 sidecar。如果 raw 本身就过期或被替换，加 --force-reparse 清空重下。
MinerU 报 MINERU_API_TOKEN 缺失 / Docling 连接 DOCLING_ENDPOINT 失败缓存未命中触发了外部服务调用——核对对应环境变量；或确认 raw 目录是否非空（命中缓存时无需服务）。
源文件被意外移动不应发生：CLI 已 mock 归档函数。若复现请提 issue（可能是 pipeline 内增加了新的归档调用点）。
parse_docling 报 produced zero blocksdocling raw 中的主 JSON 内容不可解析或为空。检查 raw 目录的 *.json 是否合法。

与 LightRAG.parse_* 生产路径的等价性

本 CLI 直接调用生产代码路径 LightRAG.parse_native / parse_mineru / parse_docling（通过 lightrag/parser/debug.py 的轻量 RAG 替身），因此：

  • sidecar 字段、命名、内容格式与生产入库完全一致；
  • IR 构建器、write_sidecar 调用、_persist_parsed_full_docs 行为完全一致；
  • 三处差异均由 CLI 内的 monkey-patch 实现，不修改任何生产代码：
    1. parsed_artifact_dir_for_source → 返回扁平路径（无 __parsed__/）；
    2. is_bundle_valid → 「raw 非空即有效」；
    3. archive_docx_source_after_full_docs_sync → no-op，保留源文件。

可与 tests/parser/docx/golden/native_docx/ 下的 golden fixture 对比验证（CLI 不冻结时间戳，比对时排除 created_at 等时间字段即可）。