尧图网站建设 
DoclingDocument 深度解析Docling 统一文档数据模型的结构、序列化与源码实现【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文围绕 Docling 仓库的 API 参考页docs/reference/docling_document.md所覆盖的DoclingDocument类型展开。读完本文你将理解 Docling 转换结果背后的统一文档表示它由哪些 Pydantic 数据类构成、顶层字段如何组织正文与页面结构、树形层级与阅读顺序如何表达以及如何在代码中构建、序列化与导出该文档模型并能在源码层面定位这些机制的实现位置。DoclingDocument 是什么统一文档表示的载体Docling 的转换流程最终都收敛到同一个产物DocumentConverter返回的转换结果中document字段承载的正是DoclingDocument实例。在 文档转换器 中可以看到转换成功时结果对象会“包装一个DoclingDocument”见docling/document_converter.py第 336 行附近 docstring 说明。DoclingDocument及其配套类型并非定义在 docling 仓库内而是来自独立维护的docling-core包pyproject.toml 声明了依赖docling-core2.91.0,3.0.0uv.lock中锁定版本为 2.92.0。所有 Pydantic 类型定义位于docling_core.types.doc模块。docling 仓库自身则大量从该模块导入类型仅 后端实现 中就有几十处from docling_core.types.doc import ...说明DoclingDocument是连接“各类输入后端”与“各类导出目标”的核心枢纽类型。API 参考覆盖的类型清单参考页 docling_document.md 本身是一个 mkdocs 自动生成的 API 参考页通过 mkdocstrings 的pythonhandler 指向docling_core.types.doc并显式枚举了 25 个成员、启用show_inherited_members、隐藏下划线私有成员filters: [!^_]。按照各类型的语义可以把这份清单分为四类类别类型作用文档主体DoclingDocument、DocumentOrigin文档根对象记录来源路径、URI、mime 等内容项继承DocItemTextItem、SectionHeaderItem、PictureItem、TableItem、TableCell、TableData、TableCellLabel、KeyValueItem各类正文内容表格携带结构化数据TableData结构项继承NodeItemGroupItem、GroupLabel、NodeItem、PageItem、FloatingItem、RefItem树节点、分组、页面容器与跨节点引用标注与几何DocItemLabel、ProvenanceItem、ImageRef、ImageRefMode、PictureClassificationClass、PictureClassificationData、BoundingBox、CoordOrigin、Size语义标签、溯源信息、图片引用、边界框与坐标系从源码结构看这条继承链是理解模型的关键内容项继承自DocItem携带标签、文本/数据与 provenance而所有需要参与层级树的项TextItem、TableItem、PictureItem、GroupItem、PageItem等都继承自NodeItem通过 JSON 指针引用父节点与子节点。顶层字段内容项与内容结构两大类别概念文档 对DoclingDocument的顶层字段给出了权威划分分为两类内容项content itemstexts所有具有文本表示的项段落、章节标题、公式等基础类型为TextItemtables所有表格类型TableItem可携带结构标注pictures所有图片类型PictureItem可携带结构标注key_value_items所有键值对项类型KeyValueItem。这些字段都是列表存储继承自DocItem的实例通过 JSON 指针引用父节点与子节点。内容结构content structurebody主文档正文的树结构根节点furniture不属于正文的项页眉、页脚等的树结构根节点groups不直接代表内容、而是作为其他内容项容器的项如列表、章节。body、furniture、groups只存储NodeItem实例同样通过 JSON 指针表达父子关系。文档的阅读顺序由body树以及树中每个节点children的顺序共同决定——这意味着遍历body树并遵循子节点顺序即可还原人类阅读次序。文档层级从实际转换结果看树结构以tests/data/word_sample.docx转换得到的DoclingDocument序列化为 YAML为例第一页的所有项都嵌套在title项JSON 指针#/texts/1之下这种“YAML 片段 原始 Word 页面”的并排对照方式直观展示了树结构如何映射回版面title作为父节点其后的段落、表格等依次作为子节点排布。分组Grouping机制如上图所示标题 “Lets swim”#/texts/5之下的所有项都作为其子节点嵌套。值得注意的是它的子节点既包含文本项也包含分组项——列表元素被收纳在这些分组内而分组项本身存储于顶层groups字段。这正是参考页中GroupItem/GroupLabel存在的意义把“一个列表”“一个章节”这类容器抽象为一等公民使 RAG 切块、层级感知检索等下游任务可以直接利用结构信息。在 docling 源码中操作 DoclingDocument构建与获取最简路径是通过DocumentConverter转换获得。仓库示例 minimal.py 展示了完整流程from docling.document_converter import DocumentConverter converter DocumentConverter() result converter.convert(source) # source 可为本地路径或 URL print(result.document.export_to_markdown())result.document即DoclingDocument。转换器会自动识别支持的格式PDF、DOCX、HTML、PPTX、图片等。序列化与反序列化JSON 往返在 datamodel/document.py 中可以看到DoclingDocument作为ConversionResult.document的默认值与序列化约定第 108 行_EMPTY_DOCLING_DOC DoclingDocument(namedummy)—— 转换失败时返回一个空文档占位保证返回类型稳定第 493 行doc_dict self.document.export_to_dict()—— 保存为 JSON 时优先使用export_to_dict以获得稳定的 schema第 576 行document DoclingDocument.model_validate(data)—— 从 JSON 数据反序列化回DoclingDocument。这印证了DoclingDocument作为 Pydantic 模型的两大能力export_to_dict()/model_dump输出稳定的 JSON 表示docling 生态的中间存储格式以及model_validate支持从 JSON 无损还原这也是 后端 json 模块 能够把 Docling JSON 再读回文档管线的基础。导出目标DoclingDocument上提供了多套导出 API覆盖了 RAG 与文档处理的主流需求export_to_markdown()生成 Markdown 文本示例中直接打印到 stdoutexport_to_dict()/model_dump()生成 JSON 可序列化结构用于持久化图片等资源通过ImageRef表达配合ImageRefMode决定是否内嵌 base64 数据导出时可与文本一并落盘。适用前提与限制DoclingDocument类型定义位于外部依赖docling-core当前锁定 2.92.0本文所有类型语义说明以该包的docling_core.types.doc模块为准docling 仓库内不重复定义这些类参考页 docling_document.md 中的成员签名与文档字符串由 mkdocstrings 从docling-core实时渲染阅读完整 API 签名参数、默认值、继承成员时建议以渲染后的参考页为准层级信息body/furniture树、PageItem、BoundingBox在纯文本类输入如 Markdown、CSV上可能不完整这些字段“if available”的表述即来源于 概念文档 对布局信息的描述。参考文件API 参考页docs/reference/docling_document.md概念说明docs/concepts/docling_document.md转换器实现docling/document_converter.py序列化数据模型docling/datamodel/document.pyDocling JSON 后端docling/backend/json/docling_json_backend.py最小示例docs/examples/minimal.py【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DoclingDocument 深度解析：Docling 统一文档数据模型的结构、序列化与源码实现
DoclingDocument 深度解析Docling 统一文档数据模型的结构、序列化与源码实现【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文围绕 Docling 仓库的 API 参考页docs/reference/docling_document.md所覆盖的DoclingDocument类型展开。读完本文你将理解 Docling 转换结果背后的统一文档表示它由哪些 Pydantic 数据类构成、顶层字段如何组织正文与页面结构、树形层级与阅读顺序如何表达以及如何在代码中构建、序列化与导出该文档模型并能在源码层面定位这些机制的实现位置。DoclingDocument 是什么统一文档表示的载体Docling 的转换流程最终都收敛到同一个产物DocumentConverter返回的转换结果中document字段承载的正是DoclingDocument实例。在 文档转换器 中可以看到转换成功时结果对象会“包装一个DoclingDocument”见docling/document_converter.py第 336 行附近 docstring 说明。DoclingDocument及其配套类型并非定义在 docling 仓库内而是来自独立维护的docling-core包pyproject.toml 声明了依赖docling-core2.91.0,3.0.0uv.lock中锁定版本为 2.92.0。所有 Pydantic 类型定义位于docling_core.types.doc模块。docling 仓库自身则大量从该模块导入类型仅 后端实现 中就有几十处from docling_core.types.doc import ...说明DoclingDocument是连接“各类输入后端”与“各类导出目标”的核心枢纽类型。API 参考覆盖的类型清单参考页 docling_document.md 本身是一个 mkdocs 自动生成的 API 参考页通过 mkdocstrings 的pythonhandler 指向docling_core.types.doc并显式枚举了 25 个成员、启用show_inherited_members、隐藏下划线私有成员filters: [!^_]。按照各类型的语义可以把这份清单分为四类类别类型作用文档主体DoclingDocument、DocumentOrigin文档根对象记录来源路径、URI、mime 等内容项继承DocItemTextItem、SectionHeaderItem、PictureItem、TableItem、TableCell、TableData、TableCellLabel、KeyValueItem各类正文内容表格携带结构化数据TableData结构项继承NodeItemGroupItem、GroupLabel、NodeItem、PageItem、FloatingItem、RefItem树节点、分组、页面容器与跨节点引用标注与几何DocItemLabel、ProvenanceItem、ImageRef、ImageRefMode、PictureClassificationClass、PictureClassificationData、BoundingBox、CoordOrigin、Size语义标签、溯源信息、图片引用、边界框与坐标系从源码结构看这条继承链是理解模型的关键内容项继承自DocItem携带标签、文本/数据与 provenance而所有需要参与层级树的项TextItem、TableItem、PictureItem、GroupItem、PageItem等都继承自NodeItem通过 JSON 指针引用父节点与子节点。顶层字段内容项与内容结构两大类别概念文档 对DoclingDocument的顶层字段给出了权威划分分为两类内容项content itemstexts所有具有文本表示的项段落、章节标题、公式等基础类型为TextItemtables所有表格类型TableItem可携带结构标注pictures所有图片类型PictureItem可携带结构标注key_value_items所有键值对项类型KeyValueItem。这些字段都是列表存储继承自DocItem的实例通过 JSON 指针引用父节点与子节点。内容结构content structurebody主文档正文的树结构根节点furniture不属于正文的项页眉、页脚等的树结构根节点groups不直接代表内容、而是作为其他内容项容器的项如列表、章节。body、furniture、groups只存储NodeItem实例同样通过 JSON 指针表达父子关系。文档的阅读顺序由body树以及树中每个节点children的顺序共同决定——这意味着遍历body树并遵循子节点顺序即可还原人类阅读次序。文档层级从实际转换结果看树结构以tests/data/word_sample.docx转换得到的DoclingDocument序列化为 YAML为例第一页的所有项都嵌套在title项JSON 指针#/texts/1之下这种“YAML 片段 原始 Word 页面”的并排对照方式直观展示了树结构如何映射回版面title作为父节点其后的段落、表格等依次作为子节点排布。分组Grouping机制如上图所示标题 “Lets swim”#/texts/5之下的所有项都作为其子节点嵌套。值得注意的是它的子节点既包含文本项也包含分组项——列表元素被收纳在这些分组内而分组项本身存储于顶层groups字段。这正是参考页中GroupItem/GroupLabel存在的意义把“一个列表”“一个章节”这类容器抽象为一等公民使 RAG 切块、层级感知检索等下游任务可以直接利用结构信息。在 docling 源码中操作 DoclingDocument构建与获取最简路径是通过DocumentConverter转换获得。仓库示例 minimal.py 展示了完整流程from docling.document_converter import DocumentConverter converter DocumentConverter() result converter.convert(source) # source 可为本地路径或 URL print(result.document.export_to_markdown())result.document即DoclingDocument。转换器会自动识别支持的格式PDF、DOCX、HTML、PPTX、图片等。序列化与反序列化JSON 往返在 datamodel/document.py 中可以看到DoclingDocument作为ConversionResult.document的默认值与序列化约定第 108 行_EMPTY_DOCLING_DOC DoclingDocument(namedummy)—— 转换失败时返回一个空文档占位保证返回类型稳定第 493 行doc_dict self.document.export_to_dict()—— 保存为 JSON 时优先使用export_to_dict以获得稳定的 schema第 576 行document DoclingDocument.model_validate(data)—— 从 JSON 数据反序列化回DoclingDocument。这印证了DoclingDocument作为 Pydantic 模型的两大能力export_to_dict()/model_dump输出稳定的 JSON 表示docling 生态的中间存储格式以及model_validate支持从 JSON 无损还原这也是 后端 json 模块 能够把 Docling JSON 再读回文档管线的基础。导出目标DoclingDocument上提供了多套导出 API覆盖了 RAG 与文档处理的主流需求export_to_markdown()生成 Markdown 文本示例中直接打印到 stdoutexport_to_dict()/model_dump()生成 JSON 可序列化结构用于持久化图片等资源通过ImageRef表达配合ImageRefMode决定是否内嵌 base64 数据导出时可与文本一并落盘。适用前提与限制DoclingDocument类型定义位于外部依赖docling-core当前锁定 2.92.0本文所有类型语义说明以该包的docling_core.types.doc模块为准docling 仓库内不重复定义这些类参考页 docling_document.md 中的成员签名与文档字符串由 mkdocstrings 从docling-core实时渲染阅读完整 API 签名参数、默认值、继承成员时建议以渲染后的参考页为准层级信息body/furniture树、PageItem、BoundingBox在纯文本类输入如 Markdown、CSV上可能不完整这些字段“if available”的表述即来源于 概念文档 对布局信息的描述。参考文件API 参考页docs/reference/docling_document.md概念说明docs/concepts/docling_document.md转换器实现docling/document_converter.py序列化数据模型docling/datamodel/document.pyDocling JSON 后端docling/backend/json/docling_json_backend.py最小示例docs/examples/minimal.py【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考