LightRAG Parser Debug CLI 实战单文件调试解析引擎与 Sidecar 产物【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG本文介绍 LightRAG 内置的解析调试 CLIpython -m lightrag.parser.cli它针对单个文件触发与生产 pipeline worker 完全相同的注册表派发路径get_parser(engine).parse(...)把 sidecar 与 raw 缓存输出到扁平目录便于本地排查任意解析引擎native/legacy/mineru/docling及第三方引擎的问题。读完后你将掌握完整的命令参数、输出目录布局、缓存命中/强制重解析策略以及该 CLI 与生产路径的三处 monkey-patch 差异。一、工具定位与生产入库同路径仅目录布局不同该 CLI 的核心设计是复用生产代码路径而非另写一套逻辑——这一点在 CLI 入口 的模块 docstring 中写得很明确它通过注册表派发get_parser(engine).parse(...)驱动单个文件并将产物写入扁平布局。与生产入库目录相比区别仅在于三点无__parsed__/中间层产物直接落在指定父目录下与源文件并排便于查看源文件不会被归档生产路径会把源文件移到INPUT_DIR/__parsed__/CLI 则保留源文件在原位置raw 缓存只看目录是否存在mineru/docling的 raw 目录非空即视为有效跳过_manifest.json校验。其余流程IR 构建、sidecar 写入、对full_docs的同步逻辑与生产入库完全一致。从源码结构看这一等价性是通过unittest.mock的三处 patch 实现的见等价性一节生产代码零改动。二、命令格式与参数说明python -m lightrag.parser.cli input_file \ --engine engine \ [-o sidecar_parent_dir] \ [--doc-id doc-id] \ [--force-reparse] \ [--preview N]参数说明input_file待解析的源文件路径位置参数必填。文件必须实际存在。--engine必填可选值来自注册表内置native本地解析支持.docx/.md/.textpack/legacy纯文本抽取无 sidecar支持 txt、md、pdf、docx、pptx 等数十种后缀/mineruPDF/办公文档/图片调 MinerU 服务/doclingPDF/办公文档调 docling-serve以及任何已注册的第三方引擎。-o / --sidecar-parent-dirsidecar 与 raw 目录的父目录默认 源文件所在目录。--doc-id自定义文档 ID默认doc-md5(源文件绝对路径)同一文件多次跑结果稳定。--force-reparse仅对外部服务引擎mineru/docling及继承ExternalParserBase的第三方引擎生效清空 raw 目录、强制重新下载与解析。默认行为是 raw 目录非空即复用。--preview N解析完成后打印前 N 个 block 的预览headings 内容片段默认 50关闭。对无 sidecar 的引擎如legacy改为打印解析文本的前 400 字符。结合 参数解析源码有几个文档层面值得补充的实现细节--engine的候选值来自注册表CLI 在构建参数解析器时调用 supported_parser_engines() 获取所有user_selectableTrue的引擎且该导入是设计上的廉价操作不拉入任何解析实现。这意味着通过lightrag.parsersentry point 注册的第三方引擎无需修改 CLI 代码即可出现在--engine选项中——main() 在解析参数前先调用load_third_party_parsers()完成插件发现与服务器在create_app时的加载时机对齐。后缀/引擎不匹配会提前报错_run() 会用 suffix_capabilities() 在入口处校验文件后缀避免失败发生在 IR builder 深层、留下更难懂的报错。例如给.pdf文件传--engine native会直接得到engine native does not support .pdf files的提示。--doc-id默认值由compute_mdhash_id(str(source), prefixdoc-)生成以源文件绝对路径为哈希输入因此同一文件重复运行 doc_id 稳定便于比对产物。各内置引擎的后缀能力在 注册表 中声明native支持docx/md/textpackmineru基线支持pdf/docx/pptx/xlsx及常见图片格式可通过MINERU_ADDITIONAL_SUFFIXES环境变量按部署追加docling基线支持pdf/docx/pptx/xlsx/md/html及图片格式可通过DOCLING_ADDITIONAL_SUFFIXES追加legacy覆盖 txt、代码文件等纯文本类后缀共三十余种。三、输出目录布局以输入./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 目录解析是本地的无外部服务参与。从源码看扁平路径的构造逻辑在 _run()sidecar 目录固定为sidecar_parent/source.name.parsedraw 目录名为source.nameraw_dir_suffix其中后缀直接取自引擎实例的raw_dir_suffix属性如 docling 为.docling_raw见 DoclingParser因此任何继承 ExternalParserBase 的外部引擎都能在这里工作。解析完成后CLI 会打印一份摘要parsed dir、raw dir、doc_id、block 数、各 sidecar 文件路径再按--preview输出 block 预览对legacy这类无 sidecar 的引擎则改为打印内容字符数与前 400 字符见 _print_summary / _print_raw_summary。四、典型用例A. 本地解析.docx零网络依赖python -m lightrag.parser.cli ./inputs/workspace/sample.docx --engine native # 产出./inputs/workspace/sample.docx.parsed/ 含 blocks.jsonl assetsB. 用 MinerU 解析 PDF首次会下载 raw# 第一次下载 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 # 日志会显示 [mineru] raw cache hit doc_id...C. 用 Docling 解析 PDF 复用已有 raw 目录# 已有 ./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. 输出到自定义目录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 后重新下载python -m lightrag.parser.cli ./inputs/workspace/sample.pdf \ --engine docling --force-reparse # raw 目录被清空 → 重新调 docling-serve 下载 → 重新生成 sidecar缓存命中/未命中的决策发生在外部引擎的统一模板 ExternalParserBase.parse() 中先按生产规则计算force_reparseCLI 通过 patch 将该判断强制为 True 或目录非空命中时记录[mineru] raw cache hit doc_id...日志并保持纯本地外部服务临时不可用时重解析仍可工作未命中时先mkdirclear_dir_contents清空旧 bundle再调用引擎的download_into重新下载。命中/未命中两条分支随后都走build_ir → write_sidecar → _persist_parsed_full_docs → archive_source的相同收尾流程。五、与生产解析路径的等价性三处 monkey-patch本 CLI 与 pipeline parse worker 走同一条注册表派发路径——get_parser(engine).parse(ParseContext(rag, ...))rag是 lightrag/parser/debug.py 的轻量替身因此sidecar 字段、命名、内容格式与生产入库完全一致IR 构建器、write_sidecar调用、_persist_parsed_full_docs行为完全一致三处差异均由 CLI 内的mock.patch实现见 patch 代码不修改任何生产代码parsed_artifact_dir_for→ 返回扁平路径无__parsed__/。由于该函数在lightrag.pipeline模块加载时就被 from-importCLI 同时对lightrag.utils_pipeline和lightrag.pipeline两个命名空间打补丁避免漏 patch解析器实例的is_bundle_valid→ raw 非空即有效仅外部服务引擎CLI 直接 patch 已解析的 parser 实例方法cli.py 的 Patch 2无需了解具体引擎模块--force-reparse传入时则替换为恒返回False的_force_miss强制走下载分支archive_docx_source_after_full_docs_sync→ no-op保留源文件。所有引擎的归档都经由ctx.archive_source落到这个函数上一处 patch 即可覆盖。其中轻量替身rag由 build_debug_rag() 构造它复用真实的LightRAG._persist_parsed_full_docs方法配上内存版full_docs和 no-opdoc_status并实现_resolve_source_file_for_parser、_build_global_config等 parser 会读取的rag表面。该替身还被 golden fixture 再生脚本scripts/regen_native_docx_golden.py与字节等价性 golden 测试共用——所有引擎都用get_parser(engine).parse(ParseContext(rag, ...))同一种方式驱动当某个 parser 新增对rag的依赖时只需扩展这一处模块而不必在各调用点复制桩代码。六、环境变量与离线复现mineru/docling引擎在缓存未命中首次解析或--force-reparse时会调用外部服务所需环境变量与生产入库一致MinerUMINERU_API_MODElocal/official、MINERU_API_TOKEN、MINERU_LOCAL_ENDPOINT或MINERU_OFFICIAL_ENDPOINT可选MINERU_ENGINE_VERSION/MINERU_MODEL_VERSION/MINERU_POLL_INTERVAL_SECONDS/MINERU_MAX_POLLS。从 endpoint 能力闭包 看official模式要求MINERU_API_TOKENlocal模式要求MINERU_LOCAL_ENDPOINTDoclingDOCLING_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。详见 FileProcessingPipeline-zh.md。缓存命中时raw 目录已存在且非空且未传--force-reparse无需任何外部服务环境变量——可用于离线复现解析输出。这一特性在测试中得到了验证tests/parser/test_parser_cli.py 通过在临时目录预置一份最小的 docling raw JSONdemo.pdf.docling_raw/demo.json来驱动完整 CLI 流程零外部服务依赖即可断言 sidecar 输出、扁平布局与源文件不被移动保证。七、常见排障现象处理error: input file does not exist: ...检查input_file路径必须是已存在的文件不是 raw 目录。对应源码中的 is_file 检查。raw 目录存在但 sidecar 内容仍是旧的默认会复用raw 重建 sidecar。如果 raw 本身就过期或被替换加--force-reparse清空重下。MinerU 报MINERU_API_TOKEN缺失 / Docling 连接DOCLING_ENDPOINT失败缓存未命中触发了外部服务调用——核对对应环境变量或确认 raw 目录是否非空命中缓存时无需服务。源文件被意外移动不应发生CLI 已 mock 归档函数。若复现请提 issue可能是 pipeline 内增加了新的归档调用点。docling 报produced zero blocksdocling raw 中的主 JSON 内容不可解析或为空。检查 raw 目录的*.json是否合法。另外DOCX 内容超限如 zip 预算违规时native 解析器抛出DocxContentErrorCLI 会打印格式化的错误消息并以非零码退出、不带 traceback见 错误处理分支——这是服务器 pipeline 只失败单个文档、CLI 侧保留友好 UX 的专门设计。八、与 golden fixture 的交叉验证CLI 的产物可与tests/parser/docx/golden/native_docx/下的 golden fixture 对比验证当前仓库包含text_only_hierarchy、tables_mixed、equations_block_and_inline、drawings_with_assets、all_modalities等八个场景目录。注意 CLI 不冻结时间戳而 golden 测试通过 FrozenDateTime 固定datetime.now以获得确定性输出因此比对时应排除created_at等时间字段。总结该 CLI 的价值在于与生产同路径 三处最小 patch 扁平可读布局——你在本地排查的 sidecar 字节内容就是生产入库时会写入的内容raw 缓存的宽松校验又让你能离线复用已有 bundle。对于解析阶段的问题定位block 缺失、表格/公式 sidecar 异常、doc_id 不一致等它是比直接跑完整 pipeline 更快的验证手段。更多注册表与引擎注册的细节可参考 ThirdPartyParser-zh.md。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考