Kotaemon 集成 Docling基于结构感知的多模态文档解析器实践指南【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon导读本文讲解 Kotaemon 如何通过内置的 Docling Reader 实现本地文档的结构感知解析覆盖文本、表格与图片三类元素的完整提取流程。读者将掌握 Docling 依赖的安装方式、VLM 端点配置下的图片标题生成机制以及如何在 Kotaemon 界面中启用Docling (figuretable extraction)加载器并理解其底层将解析结果转换为Document对象的源码实现原理。Docling 集成概览Kotaemon 是一个开源的、基于 RAG检索增强生成的文档问答工具。其文档解析层loader支持多种后端其中 Docling 以“结构感知structure-aware”解析见长——它不只抽取纯文本还能识别文档的版面结构把正文、表格table和图片figure分别提取出来。在 Kotaemon 仓库中Docling 集成位于libs/kotaemon/kotaemon/loaders/docling_loader.py核心类是DoclingReader。它继承自libs/kotaemon/kotaemon/loaders/base.py中定义的BaseReader并在libs/kotaemon/kotaemon/loaders/__init__.py中以DoclingReader名称导出统一纳入 Kotaemon 的加载器体系。启用 Docling 后Kotaemon 会在文档索引indexing阶段调用它把解析出的文本、表格、图片元素分别构造成Document对象供后续切分、向量化与检索问答使用。前置条件安装 Docling 依赖Docling 并非 Kotaemon 的默认依赖需要显式安装。Kotaemon 在libs/kotaemon/pyproject.toml的[project.optional-dependencies]中声明了docling可选依赖组其版本约束为docling2.5.2uv pip install -e libs/kotaemon[docling]使用uv时-e表示以可编辑editable模式安装libs/kotaemon包[docling]会同时拉取docling2.5.2及其依赖。若使用 pip等价命令为pip install -e libs/kotaemon[docling]安装完成后DoclingReader的converter_参数见docling_loader.py第 44-51 行会惰性导入docling.document_converter.DocumentConverter并缓存为转换器实例如果未安装 docling该处会抛出ImportError: Please install docling: pip install docling。从源码结构看converter_使用了Param.auto(cacheTrue)装饰说明其实例创建与缓存由 Kotaemon 的参数机制托管每次读取文档时直接复用。配置可选能力VLM 端点与图片标题生成Docling 本身会为图片输出“抽取式标题extractive caption即文档原文中已存在的图注文字”。若要生成“生成式标题generative caption即由多模态模型看图生成的摘要”则需要一个可用的 VLM视觉语言模型端点。在.env文件或应用设置中配置KH_VLM_ENDPOINThttp://your-vlm-endpoint这个环境变量的读取链如下libs/kotaemon/kotaemon/indices/ingests/files.py第 41 行docling_reader.vlm_endpoint getattr(flowsettings, KH_VLM_ENDPOINT, )——将配置值注入DoclingReader.vlm_endpoint参数同样地该值也同步赋给adobe_reader.vlm_endpoint与azure_reader.vlm_endpoint即 Adobe 与 Azure AI Document Intelligence 加载器共用同一个 VLM 端点在libs/kotaemon/kotaemon/indices/qa/citation_qa.py第 99 行vlm_endpoint也被引用用于问答阶段的多模态支持。需要注意如果KH_VLM_ENDPOINT未设置Docling 仍然会正常提取文本、表格和图片元数据只是跳过生成式图片标题只保留抽取式标题甚至无标题。这一行为在docling_loader.py第 74-76 行有直接体现for figure_obj in result_dict.get(pictures, []): if not self.vlm_endpoint: continueDoclingReader 参数详解DoclingReader在docling_loader.py中定义了三个核心参数均使用 Kotaemon 的Param声明参数默认值说明vlm_endpoint空字符串用于生成式图片标题的 VLM 端点为空则跳过图片标题生成max_figure_to_caption100最多为前 N 张图片生成生成式标题其余图片照常索引但不带生成标题figure_friendly_filetypes[.pdf, .jpeg, .jpg, .png, .bmp, .tiff, .heif, .tif]可可靠打开并裁剪出图片的文件类型.docx、.html等格式在不同工具中视觉布局可能不一致无法使用版面坐标可靠裁剪图片关于max_figure_to_caption的语义源码第 122-128 行给出了精确行为当已生成的标题数量达到上限后后续图片的gen_caption置为空字符串但图片本身仍会被裁剪、转码并写入Document。figure_friendly_filetypes的裁剪逻辑复用自libs/kotaemon/kotaemon/loaders/azureai_document_intelligence_loader.py中的crop_image函数PDF 通过 PyMuPDFfitz按页码渲染页面并裁剪TIFF 等多帧图片按页码 seek普通图片直接打开裁剪。裁剪坐标来自 Docling 输出的版面边界框bbox若坐标原点为BOTTOMLEFT则通过_convert_bbox_bl_tldocling_loader.py第 211-221 行换算为左上原点百分比坐标。界面配置在 Kotaemon 中启用 Docling按照官方文档的指引在 Kotaemon 界面中启用 Docling 的步骤如下启动 Kotaemon打开应用界面进入Settings设置→ Retrieval Settings检索设置→ File loader文件加载器选择Docling (figuretable extraction)保存设置随后上传或导入文档。Kotaemon 将在索引期间使用 Docling并把提取出的内容转换为Document对象。从代码层面看加载器的选择最终会体现在DocumentIngestorlibs/kotaemon/kotaemon/indices/ingests/files.py的文件提取器映射中override_file_extractors允许按文件扩展名覆盖默认提取器默认映射见该文件第 48-64 行的KH_DEFAULT_FILE_EXTRACTORS。选中 Docling 加载器后相应扩展名的解析会被替换为DoclingReader随后由DirectoryReader统一调度。底层原理Docling 解析结果如何转换为 DocumentDoclingReader.load_datadocling_loader.py第 58-209 行是整个集成的核心其处理链路可以拆解为四步调用 Docling 转换self.converter_.convert(file_path)解析文档随后result.document.export_to_dict()把结构化结果导出为字典result_dict其中包含texts、tables、pictures、pages等键。图片提取与标题拼接第 72-148 行遍历result_dict[pictures]若未配置 VLM 端点或文件类型不受支持则跳过通过$ref引用从result_dict[texts]中取回 Docling 提供的抽取式标题依据prov[0]中的页码与 bbox 调用crop_image裁剪图片转成data:image/png;base64,...格式调用generate_single_figure_caption实现在libs/kotaemon/kotaemon/loaders/utils/adobe.py第 205-221 行内部走generate_gpt4v提示词为 “Provide a short 2 sentence summary of this image?”生成两句话的图片摘要将抽取式标题与生成式标题用换行拼接作为图片Document的text并写入image_originbase64 图片、type: image、page_label等元数据。表格提取与 Markdown 化第 150-186 行遍历result_dict[tables]通过_parse_table第 223-232 行读取table_obj[data][grid]二维网格再交给make_markdown_tablelibs/kotaemon/kotaemon/loaders/utils/adobe.py第 113-145 行转换为标准 Markdown 表格表格的抽取式标题会拼接到 Markdown 表格上方元数据包含type: table、table_origin、page_label等。正文按页聚合第 188-207 行遍历result_dict[texts]按page_no分组合并文本每页生成一个Document元数据记录page_label、file_name、file_path。最终返回值顺序为texts tables figures即每页正文在前、表格居中、图片殿后。这些Document随后进入 Kotaemon 的TokenSplitter默认chunk_size1024, chunk_overlap256见files.py第 88-93 行切分为节点再交由文档解析器与向量索引流程处理。仓库中的相关测试也印证了这一设计libs/kotaemon/tests/_test_multimodal_reader.py依据doc.metadata.get(type, )区分table与image类型的文档libs/kotaemon/tests/test_table_reader.py与libs/kotaemon/tests/test_paddleocr_loader.py则验证了表格类Document的table_origin、page_label等元数据完整性。这从测试侧确认了 Kotaemon 对多模态解析结果按类型分发处理的约定。常见问题与注意事项未安装 docling 时如何报错converter_惰性导入会抛出ImportError提示先执行pip install docling。官方推荐用uv pip install -e libs/kotaemon[docling]一并安装。图片没有标题检查两处——一是KH_VLM_ENDPOINT是否已配置且端点可达未配置则完全跳过生成式标题二是图片数量是否超过max_figure_to_caption默认 100超出部分只有抽取式标题或空标题。图片未被提取确认文件扩展名是否在figure_friendly_filetypes列表中.docx、.html等格式因版面坐标在不同工具间不可靠被设计为不参与图片裁剪。VLM 端点错误或响应被拒generate_single_figure_caption内部捕获异常并打印错误若输出文本包含 “sorry” 字样也会被置空避免把无效标题写入文档。总结Docling 集成为 Kotaemon 提供了本地的、无需云服务的结构感知文档解析能力文本、表格、图片三类元素被分别提取并封装为带类型元数据的Document配合可选的 VLM 端点还能自动生成图片摘要。通过uv pip install -e libs/kotaemon[docling]安装依赖、配置KH_VLM_ENDPOINT、在 Retrieval Settings 中选择Docling (figuretable extraction)即可让 Kotaemon 的索引管线获得更精细的多模态文档理解能力为后续的 RAG 问答提供更高质量的结构化上下文。相关资源加载器实现libs/kotaemon/kotaemon/loaders/docling_loader.py文件摄取与加载器注册libs/kotaemon/kotaemon/indices/ingests/files.pyVLM 图片标题生成工具libs/kotaemon/kotaemon/loaders/utils/adobe.py图片裁剪实现libs/kotaemon/kotaemon/loaders/azureai_document_intelligence_loader.py加载器基类libs/kotaemon/kotaemon/loaders/base.py依赖声明docling可选组libs/kotaemon/pyproject.toml相关测试libs/kotaemon/tests/test_table_reader.py、libs/kotaemon/tests/_test_multimodal_reader.py【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Kotaemon 集成 Docling：基于结构感知的多模态文档解析器实践指南
Kotaemon 集成 Docling基于结构感知的多模态文档解析器实践指南【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon导读本文讲解 Kotaemon 如何通过内置的 Docling Reader 实现本地文档的结构感知解析覆盖文本、表格与图片三类元素的完整提取流程。读者将掌握 Docling 依赖的安装方式、VLM 端点配置下的图片标题生成机制以及如何在 Kotaemon 界面中启用Docling (figuretable extraction)加载器并理解其底层将解析结果转换为Document对象的源码实现原理。Docling 集成概览Kotaemon 是一个开源的、基于 RAG检索增强生成的文档问答工具。其文档解析层loader支持多种后端其中 Docling 以“结构感知structure-aware”解析见长——它不只抽取纯文本还能识别文档的版面结构把正文、表格table和图片figure分别提取出来。在 Kotaemon 仓库中Docling 集成位于libs/kotaemon/kotaemon/loaders/docling_loader.py核心类是DoclingReader。它继承自libs/kotaemon/kotaemon/loaders/base.py中定义的BaseReader并在libs/kotaemon/kotaemon/loaders/__init__.py中以DoclingReader名称导出统一纳入 Kotaemon 的加载器体系。启用 Docling 后Kotaemon 会在文档索引indexing阶段调用它把解析出的文本、表格、图片元素分别构造成Document对象供后续切分、向量化与检索问答使用。前置条件安装 Docling 依赖Docling 并非 Kotaemon 的默认依赖需要显式安装。Kotaemon 在libs/kotaemon/pyproject.toml的[project.optional-dependencies]中声明了docling可选依赖组其版本约束为docling2.5.2uv pip install -e libs/kotaemon[docling]使用uv时-e表示以可编辑editable模式安装libs/kotaemon包[docling]会同时拉取docling2.5.2及其依赖。若使用 pip等价命令为pip install -e libs/kotaemon[docling]安装完成后DoclingReader的converter_参数见docling_loader.py第 44-51 行会惰性导入docling.document_converter.DocumentConverter并缓存为转换器实例如果未安装 docling该处会抛出ImportError: Please install docling: pip install docling。从源码结构看converter_使用了Param.auto(cacheTrue)装饰说明其实例创建与缓存由 Kotaemon 的参数机制托管每次读取文档时直接复用。配置可选能力VLM 端点与图片标题生成Docling 本身会为图片输出“抽取式标题extractive caption即文档原文中已存在的图注文字”。若要生成“生成式标题generative caption即由多模态模型看图生成的摘要”则需要一个可用的 VLM视觉语言模型端点。在.env文件或应用设置中配置KH_VLM_ENDPOINThttp://your-vlm-endpoint这个环境变量的读取链如下libs/kotaemon/kotaemon/indices/ingests/files.py第 41 行docling_reader.vlm_endpoint getattr(flowsettings, KH_VLM_ENDPOINT, )——将配置值注入DoclingReader.vlm_endpoint参数同样地该值也同步赋给adobe_reader.vlm_endpoint与azure_reader.vlm_endpoint即 Adobe 与 Azure AI Document Intelligence 加载器共用同一个 VLM 端点在libs/kotaemon/kotaemon/indices/qa/citation_qa.py第 99 行vlm_endpoint也被引用用于问答阶段的多模态支持。需要注意如果KH_VLM_ENDPOINT未设置Docling 仍然会正常提取文本、表格和图片元数据只是跳过生成式图片标题只保留抽取式标题甚至无标题。这一行为在docling_loader.py第 74-76 行有直接体现for figure_obj in result_dict.get(pictures, []): if not self.vlm_endpoint: continueDoclingReader 参数详解DoclingReader在docling_loader.py中定义了三个核心参数均使用 Kotaemon 的Param声明参数默认值说明vlm_endpoint空字符串用于生成式图片标题的 VLM 端点为空则跳过图片标题生成max_figure_to_caption100最多为前 N 张图片生成生成式标题其余图片照常索引但不带生成标题figure_friendly_filetypes[.pdf, .jpeg, .jpg, .png, .bmp, .tiff, .heif, .tif]可可靠打开并裁剪出图片的文件类型.docx、.html等格式在不同工具中视觉布局可能不一致无法使用版面坐标可靠裁剪图片关于max_figure_to_caption的语义源码第 122-128 行给出了精确行为当已生成的标题数量达到上限后后续图片的gen_caption置为空字符串但图片本身仍会被裁剪、转码并写入Document。figure_friendly_filetypes的裁剪逻辑复用自libs/kotaemon/kotaemon/loaders/azureai_document_intelligence_loader.py中的crop_image函数PDF 通过 PyMuPDFfitz按页码渲染页面并裁剪TIFF 等多帧图片按页码 seek普通图片直接打开裁剪。裁剪坐标来自 Docling 输出的版面边界框bbox若坐标原点为BOTTOMLEFT则通过_convert_bbox_bl_tldocling_loader.py第 211-221 行换算为左上原点百分比坐标。界面配置在 Kotaemon 中启用 Docling按照官方文档的指引在 Kotaemon 界面中启用 Docling 的步骤如下启动 Kotaemon打开应用界面进入Settings设置→ Retrieval Settings检索设置→ File loader文件加载器选择Docling (figuretable extraction)保存设置随后上传或导入文档。Kotaemon 将在索引期间使用 Docling并把提取出的内容转换为Document对象。从代码层面看加载器的选择最终会体现在DocumentIngestorlibs/kotaemon/kotaemon/indices/ingests/files.py的文件提取器映射中override_file_extractors允许按文件扩展名覆盖默认提取器默认映射见该文件第 48-64 行的KH_DEFAULT_FILE_EXTRACTORS。选中 Docling 加载器后相应扩展名的解析会被替换为DoclingReader随后由DirectoryReader统一调度。底层原理Docling 解析结果如何转换为 DocumentDoclingReader.load_datadocling_loader.py第 58-209 行是整个集成的核心其处理链路可以拆解为四步调用 Docling 转换self.converter_.convert(file_path)解析文档随后result.document.export_to_dict()把结构化结果导出为字典result_dict其中包含texts、tables、pictures、pages等键。图片提取与标题拼接第 72-148 行遍历result_dict[pictures]若未配置 VLM 端点或文件类型不受支持则跳过通过$ref引用从result_dict[texts]中取回 Docling 提供的抽取式标题依据prov[0]中的页码与 bbox 调用crop_image裁剪图片转成data:image/png;base64,...格式调用generate_single_figure_caption实现在libs/kotaemon/kotaemon/loaders/utils/adobe.py第 205-221 行内部走generate_gpt4v提示词为 “Provide a short 2 sentence summary of this image?”生成两句话的图片摘要将抽取式标题与生成式标题用换行拼接作为图片Document的text并写入image_originbase64 图片、type: image、page_label等元数据。表格提取与 Markdown 化第 150-186 行遍历result_dict[tables]通过_parse_table第 223-232 行读取table_obj[data][grid]二维网格再交给make_markdown_tablelibs/kotaemon/kotaemon/loaders/utils/adobe.py第 113-145 行转换为标准 Markdown 表格表格的抽取式标题会拼接到 Markdown 表格上方元数据包含type: table、table_origin、page_label等。正文按页聚合第 188-207 行遍历result_dict[texts]按page_no分组合并文本每页生成一个Document元数据记录page_label、file_name、file_path。最终返回值顺序为texts tables figures即每页正文在前、表格居中、图片殿后。这些Document随后进入 Kotaemon 的TokenSplitter默认chunk_size1024, chunk_overlap256见files.py第 88-93 行切分为节点再交由文档解析器与向量索引流程处理。仓库中的相关测试也印证了这一设计libs/kotaemon/tests/_test_multimodal_reader.py依据doc.metadata.get(type, )区分table与image类型的文档libs/kotaemon/tests/test_table_reader.py与libs/kotaemon/tests/test_paddleocr_loader.py则验证了表格类Document的table_origin、page_label等元数据完整性。这从测试侧确认了 Kotaemon 对多模态解析结果按类型分发处理的约定。常见问题与注意事项未安装 docling 时如何报错converter_惰性导入会抛出ImportError提示先执行pip install docling。官方推荐用uv pip install -e libs/kotaemon[docling]一并安装。图片没有标题检查两处——一是KH_VLM_ENDPOINT是否已配置且端点可达未配置则完全跳过生成式标题二是图片数量是否超过max_figure_to_caption默认 100超出部分只有抽取式标题或空标题。图片未被提取确认文件扩展名是否在figure_friendly_filetypes列表中.docx、.html等格式因版面坐标在不同工具间不可靠被设计为不参与图片裁剪。VLM 端点错误或响应被拒generate_single_figure_caption内部捕获异常并打印错误若输出文本包含 “sorry” 字样也会被置空避免把无效标题写入文档。总结Docling 集成为 Kotaemon 提供了本地的、无需云服务的结构感知文档解析能力文本、表格、图片三类元素被分别提取并封装为带类型元数据的Document配合可选的 VLM 端点还能自动生成图片摘要。通过uv pip install -e libs/kotaemon[docling]安装依赖、配置KH_VLM_ENDPOINT、在 Retrieval Settings 中选择Docling (figuretable extraction)即可让 Kotaemon 的索引管线获得更精细的多模态文档理解能力为后续的 RAG 问答提供更高质量的结构化上下文。相关资源加载器实现libs/kotaemon/kotaemon/loaders/docling_loader.py文件摄取与加载器注册libs/kotaemon/kotaemon/indices/ingests/files.pyVLM 图片标题生成工具libs/kotaemon/kotaemon/loaders/utils/adobe.py图片裁剪实现libs/kotaemon/kotaemon/loaders/azureai_document_intelligence_loader.py加载器基类libs/kotaemon/kotaemon/loaders/base.py依赖声明docling可选组libs/kotaemon/pyproject.toml相关测试libs/kotaemon/tests/test_table_reader.py、libs/kotaemon/tests/_test_multimodal_reader.py【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考