常见问题

这是从以下链接收集的用户问题汇总的常见问题解答：https://github.com/docling-project/docling/discussions。

是否支持 Python 3.13？

Docling 2.18.0 及更高版本支持 Python 3.13。

与 numpy (python 3.13) 的安装冲突

使用 docling-ibm-models>=2.0.7 和 deepsearch-glm>=0.26.2 时，这些问题应该不会再出现。Docling 支持 >=1.24.4,<3.0.0 版本的 numpy，这应该匹配所有用法。

对于旧版本

在通过 poetry 安装 docling 和 langchain 时观察到此问题。

...
Thus, docling (>=2.7.0,<3.0.0) requires numpy (>=1.26.4,<2.0.0).
So, because ... depends on both numpy (>=2.0.2,<3.0.0) and docling (^2.7.0), version solving failed.

Numpy 仅从某个 2.x.y 版本开始添加 Python 3.13 支持。为了准备支持 3.13，Docling 依赖于 3.13 的 2.x.y 版本，否则依赖 1.x.y 版本。如果在 pyproject.toml 中允许使用 3.13，Poetry 将尝试协调 Docling 的 3.13 版本 numpy（某个 2.x.y 版本）与 LangChain 的 3.13 版本（某个 1.x.y 版本），这会导致上述错误。

检查 pyproject.toml 允许的 Python 版本中是否包含 Python 3.13。如果包含，请将其删除并重试。例如，如果设置了 python = "^3.10"，则改用 python = ">=3.10,<3.13"。

如果您想保留与 Python 3.9-3.13 的兼容性，也可以在 pyproject.toml 中使用类似以下的选择器

numpy = [
    { version = "^2.1.0", markers = 'python_version >= "3.13"' },
    { version = "^1.24.4", markers = 'python_version < "3.13"' },
]

来源：Issue #283

是否支持文本样式（加粗、下划线等）？

目前 DoclingDocument 格式不支持文本样式。如果您有兴趣贡献此功能，请开启一个讨论主题来集思广益设计方案。

注意：这不是一个简单的主题

如何完全离线运行？

Docling 不使用任何远程服务，因此可以在完全隔离的空气隔离环境中运行。

唯一的要求是将 Docling 运行时指向模型工件的存储位置。

例如

pipeline_options = PdfPipelineOptions(artifacts_path="your location")
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

来源：Issue #326

运行 Docling 需要哪些模型权重？

PDF 流水线中使用的 AI 模型需要模型权重。其他文档类型（如 docx、pptx 等）没有此要求。

为了处理 PDF 文档，Docling 需要从以下链接获取模型权重：https://hugging-face.cn/ds4sd/docling-models。

启用 OCR 时，某些引擎也需要模型工件。例如 EasyOCR，Docling 为其提供了特殊流水线选项来控制运行时行为。

下载模型权重时出现 SSL 错误

URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)>

一些用户观察到了类似的 SSL 下载错误。这发生在从 Hugging Face 获取模型权重时。当 Python 环境没有最新的可信证书列表时，可能会出现此错误。

可能的解决方案包括

更新到 certifi 的最新版本，即运行 pip install --upgrade certifi
使用 pip-system-certs 来使用系统上最新的可信证书。

将环境变量 SSL_CERT_FILE 和 REQUESTS_CA_BUNDLE 设置为 python -m certifi 的值

CERT_PATH=$(python -m certifi)
export SSL_CERT_FILE=${CERT_PATH}
export REQUESTS_CA_BUNDLE=${CERT_PATH}

支持哪些 OCR 语言？

Docling 支持多种 OCR 引擎，每种引擎都有自己的支持语言列表。以下是原始 OCR 引擎文档的链接集合，其中列出了支持的 OCR 语言。

在 Docling 中设置 OCR 语言是通过 OCR 流水线选项完成的

from docling.datamodel.pipeline_options import PdfPipelineOptions

pipeline_options = PdfPipelineOptions()
pipeline_options.ocr_options.lang = ["fr", "de", "es", "en"]  # example of languages for EasyOCR

MS Word 和 Powerpoint 中的某些图片丢失

Docling 使用的图像处理库仅在 Windows 平台上能够处理嵌入的 WMF 图像。如果您在其他操作系统上，这些图像将被忽略。

HybridChunker 触发警告：'令牌索引序列长度长于此模型的指定最大序列长度'

TLDR：在 HybridChunker 的上下文中，这是一个已知且预期的“误报”。

详情:

使用HybridChunker时通常会触发如下警告

Token indices sequence length is longer than the specified maximum sequence length for this model (531 > 512). Running this sequence through the model will result in indexing errors

这是 transformers 发出的一个警告，表示实际上*将此序列通过模型运行*将导致索引错误，也就是说，只有当确实将特定序列通过（嵌入）模型时，才会出现问题。

然而，在我们的案例中，这表现为“误报”，因为发生了以下情况

分块器在一个可能很长的序列上调用分词器（例如警告中提到的 530 个令牌），目的是计算其令牌数量，即评估它是否足够短。此时 transformers 已经发出了上述警告！
无论何时处理的序列过长，分块器都会继续将其分割（但 transformers 的警告已经显示出来了）

重要的是生成的分块的实际令牌长度。下面的代码片段可用于获取实际最大分块大小（对于想要确认这未超出模型限制的用户）

chunk_max_len = 0
for i, chunk in enumerate(chunks):
    ser_txt = chunker.serialize(chunk=chunk)
    ser_tokens = len(tokenizer.tokenize(ser_txt))
    if ser_tokens > chunk_max_len:
        chunk_max_len = ser_tokens
    print(f"{i}\t{ser_tokens}\t{repr(ser_txt[:100])}...")
print(f"Longest chunk yielded: {chunk_max_len} tokens")
print(f"Model max length: {tokenizer.model_max_length}")

另请参阅 docling#725。

来源：Issue docling-core#119