Docling项目离线模型使用指南

背景介绍

Docling是一个强大的文档处理工具，它依赖于多个预训练模型来完成文档转换任务。在实际企业环境中，由于网络安全策略限制，许多内部网络无法直接访问互联网下载模型文件。本文将详细介绍如何在Docling项目中配置和使用本地存储的模型文件，解决内网环境下的模型加载问题。

模型缓存机制

Docling默认会通过Hugging Face Hub下载所需的模型文件，这些文件会被缓存在系统默认位置。了解这一机制对于离线使用至关重要：

1. Hugging Face模型默认缓存路径：用户目录下的.cache/huggingface/hub文件夹
2. Docling自定义模型路径：用户目录下的.cache/docling/models文件夹

离线使用方案

方案一：预下载模型

在能够访问互联网的环境中预先下载所有必需的模型文件：

converter = DocumentConverter()
converter.initialize_pipeline(InputFormat.PDF)

执行上述代码会自动下载并缓存所有相关模型文件。之后可以将整个缓存目录打包，部署到内网环境中使用。

方案二：指定自定义模型路径

如果已经将模型文件存放在特定位置，可以通过配置指定路径：

pipeline_options = PdfPipelineOptions(artifacts_path="自定义路径")
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

EasyOCR的特殊配置

Docling集成了EasyOCR进行OCR识别，其模型文件需要单独处理：

1. EasyOCR默认模型路径：用户目录下的.EasyOCR/model文件夹
2. 在Docling中需要将其链接到.cache/docling/models/EasyOcr路径

可以通过以下方式配置EasyOCR选项：

easyocr_options = EasyOcrOptions(
    model_storage_directory="自定义路径",
    download_enabled=False  # 禁用自动下载
)

模型路径映射技巧

由于Docling对模型路径命名规则与原始Hugging Face有所不同，建议创建符号链接：

ln -s ~/.cache/huggingface/hub/models/ds4sd/DocumentFigureClassifier ~/.cache/docling/models/ds4sd--DocumentFigureClassifier
ln -s ~/.cache/huggingface/hub/models/ds4sd/docling-models/ ~/.cache/docling/models/ds4sd--docling-models
ln -s ~/.cache/huggingface/hub/models/ds4sd/CodeFormula/ ~/.cache/docling/models/ds4sd--CodeFormula
ln -s ~/.EasyOCR/model/ ~/.cache/docling/models/EasyOcr

最佳实践建议

1. 统一管理模型文件：建议将所有模型文件集中存放在一个网络共享位置，便于团队共享和维护
2. 版本控制：对模型文件进行版本管理，确保开发、测试和生产环境使用相同版本的模型
3. 自动化部署：编写部署脚本自动创建所需的符号链接和目录结构
4. 文档记录：详细记录所使用的模型版本和配置，便于问题排查和后续升级

总结

通过合理配置模型文件路径，Docling可以完全在内网环境中运行，无需互联网连接。本文介绍的两种方案和路径映射技巧，可以帮助企业用户顺利部署和使用Docling进行文档处理工作。对于需要更高安全级别的环境，还可以考虑将模型文件打包到Docker镜像中，实现完全自包含的部署方案。