ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

LlamaIndex DoclingReader 深度指南:用 Docling 解析 PDF/DOCX/HTML 并接入 RAG 流水线

LlamaIndex DoclingReader 深度指南:用 Docling 解析 PDF/DOCX/HTML 并接入 RAG 流水线 LlamaIndex DoclingReader 深度指南用 Docling 解析 PDF/DOCX/HTML 并接入 RAG 流水线【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index输出文章LlamaIndex DoclingReader 深度指南用 Docling 解析 PDF/DOCX/HTML 并接入 RAG 流水线DoclingReader 是 LlamaIndex 官方集成包llama-index-readers-docling提供的高性能文档读取器它基于开源文档解析引擎 Docling将 PDF、DOCX、HTML 等富格式文档统一转换为 Markdown 或 Docling 原生 JSON 格式直接产出可供 LlamaIndex 索引与检索的Document对象。本文结合仓库源码系统讲解 DoclingReader 的安装、两种导出模式、与 SimpleDirectoryReader 的组合用法以及配套的 DoclingNodeParser帮助你构建从任意格式文档到可检索 RAG 索引的完整链路。一、DoclingReader 是什么能力与定位DoclingReader 的官方说明位于 llama-index-readers-docling/README.md它使用 Docling 实现对 PDF、DOCX、HTML 及其他文档类型的快速、简便抽取输出为 Markdown 或 JSON 序列化的 Docling 原生格式供 LlamaIndex 流水线在 RAG / QA 等场景中使用。从源码看DoclingReader继承自llama_index.core.readers.base中的BasePydanticReader类注释明确其职责为 Extracts PDF, DOCX, and other document formats into LlamaIndex Documents as either Markdown or JSON-serialized Docling native format核心实现位于 base.py。值得注意的是Docling 输出的是一种富格式表示不仅包含纯文本还保留了版面布局、表格结构等文档级信息该描述来自仓库内示例笔记本 DoclingReaderDemo.ipynb 的 Overview 部分。这正是它在复杂文档 RAG 场景中的价值传统 PDF 解析器往往丢失表格与版面语义而 Docling 可以保留这些结构为检索与回答提供更扎实的文档级证据。二、安装与依赖安装命令见 README.mdpip install llama-index-readers-docling该包的依赖约束可从 pyproject.toml 中确认llama-index-core0.13.0,0.15docling-core2.2.0,3docling2.2.0,3numpy2.0包要求 Python3.10,4.0许可证为 MIT。需要注意docling是重量级依赖首次安装会一并拉取其解析引擎与相关模型依赖。示例笔记本 DoclingReaderDemo.ipynb 给出了完整的 RAG 场景安装方式Colab 环境下可去掉--no-warn-conflicts以获得更严格的依赖校验%pip install -q --progress-bar off --no-warn-conflicts \ llama-index-core llama-index-readers-docling llama-index-node-parser-docling \ llama-index-embeddings-huggingface llama-index-llms-huggingface-api \ llama-index-readers-file python-dotenv三、DoclingReader 核心 API 与参数DoclingReader的完整参数定义位于 base.py核心配置项如下参数类型默认值说明export_typeExportType枚举markdown/jsonExportType.MARKDOWN控制导出格式doc_converterDocumentConverterDocumentConverter()工厂默认Docling 转换器实例可注入自定义配置md_export_kwargsDict[str, Any]{image_placeholder: }Markdown 导出的额外参数如图片占位符id_funcDocIDGenCallable_uuid4_doc_id_gen文档 ID 生成函数关键类型与默认实现源码对应 base.pyclass ExportType(str, Enum): MARKDOWN markdown JSON json runtime_checkable class DocIDGenCallable(Protocol): def __call__(self, doc: DLDocument, file_path: str | Path) - str: ... staticmethod def _uuid4_doc_id_gen(doc: DLDocument, file_path: str | Path) - str: return str(uuid.uuid4())需要留意的几个实现细节export_type采用str枚举因此既可以用DoclingReader.ExportType.JSON也可以直接传入字符串jsondoc_converter支持注入自定义的 DoclingDocumentConverter例如需要配置 Docling 的 PDF 后端如 high-res 模式时可以自行构造转换器传入md_export_kwargs默认将图片替换为空占位符若你希望 Markdown 输出中保留图片引用可覆盖此参数id_func默认使用 UUID4 生成文档 ID你可以实现DocIDGenCallable协议接收DLDocument与文件路径返回字符串来自定义 ID 策略例如基于文件路径或文档哈希生成稳定的 ID。惰性加载lazy_load_dataDoclingReader继承自BasePydanticReader其核心加载方法为lazy_load_database.py签名如下def lazy_load_data( self, file_path: str | Path | Iterable[str] | Iterable[Path], extra_info: dict | None None, fs: Optional[AbstractFileSystem] None, ) - Iterable[LIDocument]:实现要点输入灵活性file_path既可以是单个字符串本地文件路径或 URL或pathlib.Path也可以是它们的可迭代对象内部会将其规范化为列表后逐个处理逐文档转换对每个源调用self.doc_converter.convert(source).document得到 Docling 原生文档对象按需导出根据export_type分别调用dl_doc.export_to_markdown(**self.md_export_kwargs)或json.dumps(dl_doc.export_to_dict())若枚举值意外越界会抛出ValueError产出 LlamaIndex Document以id_func生成doc_id、以导出文本作为text构造LIDocument并用extra_info默认为空字典填充metadata最后逐条yield因此适合大文档流式处理不会一次性把所有文档载入内存。由于返回的是生成器load_dataBasePydanticReader提供的便捷方法会将其物化为列表两种调用方式在语义上等价。四、实战一Markdown 导出默认模式README 给出的最小可用示例README.mdfrom llama_index.readers.docling import DoclingReader reader DoclingReader() docs reader.load_data(file_pathhttps://arxiv.org/pdf/2408.09869) print(f{docs[0].text[389:442]}...) # ## Abstract # # This technical report introduces Docling...要点默认导出 Markdown因此无需任何配置即可使用示例直接以 arXiv 论文 PDF 的 URL 作为输入说明 Docling 具备远程 URL 拉取与解析能力输出保留了## Abstract等 Markdown 标题结构这为后续使用MarkdownNodeParser做结构感知切分提供了基础返回的docs[0].text是完整的 Markdown 文本可通过切片或全文索引进行验证。五、实战二JSON 导出Docling 原生格式JSON 导出模式README.mdfrom llama_index.readers.docling import DoclingReader reader DoclingReader(export_typeDoclingReader.ExportType.JSON) docs reader.load_data(file_pathhttps://arxiv.org/pdf/2408.09869) print(f{docs[0].text[:53]}...) # {schema_name: DoclingDocument, version: 1.0.0...[!IMPORTANT] 官方 README 明确提示使用 JSON 导出时务必在流水线中配合 Docling Node Parser 使用才能正确解析 Docling 的原生格式。若直接按纯文本切分Docling 丰富的文档结构信息将无法被有效利用。JSON 模式下docs[0].text是一段 JSON 序列化的 Docling 原生文档schema 名为DoclingDocument其中包含段落、标题、表格等元素的语义化描述以及页码、边界框等文档级定位信息是实现文档原生 grounded RAG的基础。六、实战三与 SimpleDirectoryReader 组合当需要批量解析一个目录下的多种文档时可以把DoclingReader作为file_extractor注入SimpleDirectoryReaderREADME.mdfrom llama_index.core import SimpleDirectoryReader dir_reader SimpleDirectoryReader( input_dir/path/to/docs, file_extractor{.pdf: reader}, ) docs dir_reader.load_data() print(docs[0].metadata) # {file_path: /path/to/docs/2408.09869v3.pdf, # file_name: 2408.09869v3.pdf, # file_type: application/pdf, # file_size: 5566574, # creation_date: 2024-10-06, # last_modified_date: 2024-10-03}这里SimpleDirectoryReader的file_extractor参数允许按扩展名映射自定义 reader.pdf扩展名交给DoclingReader处理目录中其余格式仍可走其他默认 reader形成多格式混合目录的统一加载方案。注意SimpleDirectoryReader会为每个文件补充文件路径、文件名、MIME 类型、大小与时间戳等元数据。七、进阶构建完整 RAG 流水线Reader Node Parser Index示例笔记本 DoclingReaderDemo.ipynb 演示了将 DoclingReader 接入 RAG 的完整流程分为两条路线。路线 AMarkdown 导出 MarkdownNodeParserfrom llama_index.core import VectorStoreIndex from llama_index.core.node_parser import MarkdownNodeParser from llama_index.readers.docling import DoclingReader reader DoclingReader() # 默认 Markdown 导出 node_parser MarkdownNodeParser() # 标准 Markdown 结构切分 index VectorStoreIndex.from_documents( documentsreader.load_data(SOURCE), transformations[node_parser], embed_modelEMBED_MODEL, ) result index.as_query_engine(llmGEN_MODEL).query(QUERY)适合只需要文本语义检索的常规场景实现简单、开销低。路线 BJSON 导出 DoclingNodeParser文档原生 groundingfrom llama_index.node_parser.docling import DoclingNodeParser reader DoclingReader(export_typeDoclingReader.ExportType.JSON) node_parser DoclingNodeParser() index VectorStoreIndex.from_documents( documentsreader.load_data(SOURCE), transformations[node_parser], embed_modelEMBED_MODEL, ) result index.as_query_engine(llmGEN_MODEL).query(QUERY)笔记本中特别指出此路线下检索结果会附带文档级 grounding 信息例如页码、边界框信息即来源中不再只是一段文字而是能定位到具体页与版面位置的富证据。DoclingNodeParser 的实现原理DoclingNodeParser位于 llama-index-node-parser-docling类注释明确其作用将DoclingReader的 JSON 输出按 Docling 数据模型中的文档元素段落、标题、表格等切分为节点。核心实现base.py反序列化对每个输入BaseNode用LIDocument.model_validate还原为 LlamaIndex Document再通过DLDocument.model_validate_json从文本内容重建 Docling 原生文档层级切分调用默认的HierarchicalChunker对 Docling 文档做语义化 chunkingchunker字段默认为HierarchicalChunker()可注入自定义BaseChunker节点构建为每个 chunk 构造TextNode文本取chunk.text将 chunk 元数据写入node.metadata并同步excluded_embed_metadata_keys/excluded_llm_metadata_keys以控制哪些元数据参与 embedding 与 LLM 上下文溯源关系为每个节点设置NodeRelationship.SOURCE关系指向原始文档保证检索结果可回溯到源文档ID 生成id_func默认为_uuid4_node_id_gen同样可用自定义函数替换并可通过show_progressTrue借助get_tqdm_iterable展示解析进度。从源码结构可以推断这套JSON 导出 DoclingNodeParser组合的价值在于将 Docling 富格式的文档结构语义完整保留到节点粒度从而实现比纯文本切分更高质量的检索。与 SimpleDirectoryReader 组合的完整示例笔记本还演示了先把源 PDF 下载到临时目录、再交给SimpleDirectoryReader批量加载的用法from llama_index.core import SimpleDirectoryReader dir_reader SimpleDirectoryReader( input_dirtmp_dir_path, # 存放 PDF 的临时目录 file_extractor{.pdf: reader}, # 复用上文定义的 reader任一路线 ) index VectorStoreIndex.from_documents( documentsdir_reader.load_data(), transformations[node_parser], embed_modelEMBED_MODEL, ) result index.as_query_engine(llmGEN_MODEL).query(QUERY)这样即使目录中有多份不同来源的 PDF也能统一走 Docling 的富格式解析路径。八、性能与部署提示示例笔记本在 Setup 阶段给出两条官方实践建议优先使用 GPU 加速Docling 的版面分析等步骤依赖深度学习模型GPU 环境如 Colab 的 GPU 运行时能显著提升转换速度合理配置 LLM 服务笔记本使用 HuggingFace Inference API 作为生成模型后端可通过环境变量HF_TOKEN提供 token 以获得更高配额在你的生产环境中可替换为任意 LlamaIndex 兼容的 LLM。此外由于lazy_load_data采用逐文档惰性生成处理大批量文档时建议以流式方式消费结果避免一次性物化全部文档导致内存压力。九、总结与选用建议DoclingReader 为 LlamaIndex 提供了一条从复杂文档PDF/DOCX/HTML到 RAG 索引的高质量通路其设计可概括为双导出模式默认 Markdown 适合快速接入JSON 原生格式配合 DoclingNodeParser 可获得文档级 grounding灵活的依赖注入doc_converter、id_func、md_export_kwargs均可自定义便于适配不同解析后端与 ID 策略生态集成自然既可作为独立 reader 使用也可注入SimpleDirectoryReader.file_extractor与VectorStoreIndex、MarkdownNodeParser、DoclingNodeParser无缝组合。选用建议如果业务文档以版式复杂的 PDF、扫描件、表格为主且对检索答案的可溯源性与版面语义有较高要求推荐走JSON 导出 DoclingNodeParser路线如果仅需快速将文档转文本建立基础问答Markdown 导出路线成本更低、链路更短。两者所需的相关源码均可分别在 llama-index-readers-docling 与 llama-index-node-parser-docling 中进一步研读。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表