昆
昆仑AI工具大全KUN.NET
提交工具

第 1 课

装好 Docling，用命令行把 PDF 转成 Markdown，并对比开关 OCR

用 uv 或 pip 安装 docling 2.148.0（Linux 无显卡用 CPU 版 torch），确认版本；下载官方技术报告 PDF，用 docling convert 转成 Markdown，再关 OCR、图片改占位符，看耗时从 48.89 秒降到 9.74 秒、体积从 570 KB 降到 29 KB。

图文20 分钟Docling 官方文档 ↗

课程目录第 1 / 3 课
  1. 01装好 Docling，用命令行把 PDF 转成 Markdown，并对比开关 OCR20 分钟
  2. 02只转指定页、导出 JSON 与表格 CSV，用 Python API 定制转换25 分钟
  3. 03用 HybridChunker 切块做 RAG，再把 Docling 接成 MCP 工具25 分钟
返回课程介绍

学习位置仅保存在当前浏览器，有效期 180 天。

01 / 图文教材

装好 Docling，用命令行把 PDF 转成 Markdown，并对比开关 OCR

本课对照的官方页面：Installation 、Quickstart 、CLI reference 、GitHub：docling-project/docling 。测试环境：2026-11-08，Asia/Shanghai，Linux x86_64 云主机（8 核、无 GPU），Python 3.12.15，docling 2.148.0（2026-11-05 发布），torch 2.15.0 CPU 版。下面所有「对照结果」都是这台机器的真实输出，只做了节选。

Docling 是 IBM Research 发起、现由 LF AI & Data 基金会托管的 MIT 开源文档解析工具（GitHub 约 7 万星）。它在本机用版面分析模型和 TableFormer 表格模型读懂 PDF 的标题层级、阅读顺序和表格，再统一成 DoclingDocument，导出 Markdown、JSON、HTML 等格式。本课先把它装好，用命令行把官方技术报告 PDF 转成 Markdown，并对比开、关 OCR 的耗时。

第 1 步：建虚拟环境并安装（Linux 用 CPU 版 torch）

官方安装页的写法是直接 pip install docling。如果你的 Linux 机器没有 NVIDIA 显卡，官方建议加 PyTorch CPU 源，省掉几 GB 的 CUDA 依赖。本课用 uv 建 Python 3.12 虚拟环境（用 pip 也一样）：

mkdir -p ~/docling-lab && cd ~/docling-lab
uv venv .venv -p 3.12
source .venv/bin/activate
uv pip install docling --extra-index-url https://download.pytorch.org/whl/cpu --index-strategy unsafe-best-match

只用 pip 的写法（与官方安装页一致）：

python3 -m venv .venv && source .venv/bin/activate
pip install docling --extra-index-url https://download.pytorch.org/whl/cpu

macOS（Apple 芯片）和 Windows 直接 pip install docling 即可。uv 用户加了 CPU 源后要带上 unsafe-best-match 这个索引策略，否则 uv 只认第一个源里的 torch 版本，可能解析失败。

对照结果（节选；测试机网络较快，约 4 秒装完 103 个包，其中 torch 约 200 MB，你的耗时取决于网络）：

Resolved 103 packages in 842ms
Downloading torch (199.8MiB)
...
 + docling==2.148.0
 + docling-core==2.106.0
 + docling-ibm-models==4.0.4
 + docling-parse==7.24.2

装完的虚拟环境约 1.6 GB，请预留磁盘。

第 2 步：确认版本

docling --version

对照结果：

Docling version: 2.148.0
Docling Core version: 2.106.0
Docling IBM Models version: 4.0.4
Docling Parse version: 7.24.2
Python: cpython-312 (3.12.15)
Platform: Linux-6.12.94+-x86_64-with-glibc2.41

新版命令行把转换放进了 convert 子命令。运行 docling -h 能看到三个子命令：convert（本地转换）、options（查看某个引擎可用的参数）和 convert-remote（交给 docling-serve 服务转换）。官方 Quickstart 里不带子命令的旧写法仍然可用，但本课统一写 docling convert，和 docling convert -h 的帮助对得上。

第 3 步：准备一份 PDF

用官方 README 里的示例文档，也就是 Docling 自己的技术报告（arXiv 2408.09869，9 页，带图和表）：

curl -L -o 2408.09869.pdf https://arxiv.org/pdf/2408.09869
ls -lh 2408.09869.pdf

对照结果：

-rw-r--r-- 1 box box 5.4M Nov  8 00:08 2408.09869.pdf

为什么先下载，而不是直接把 URL 交给 Docling？官方示例确实可以写 URL。但 Docling 会先解析域名，拒绝解析到内网或保留网段的地址（防 SSRF）。如果你在开了 Clash 之类「TUN / Fake-IP」模式的代理环境里，域名会被解析成 198.18.x.x 这类保留地址，Docling 就报 URL is not allowed。测试机正是这种环境，所以本课统一先用 curl 下载到本地再转换。

第 4 步：第一次转换（默认开 OCR）

mkdir -p out
time docling convert 2408.09869.pdf --output out
ls -lh out

第一次运行会自动从 Hugging Face 下载两个模型：版面分析模型 docling-layout-heron 和 docling-models（含 TableFormer）。以后会复用缓存，不再下载。

对照结果（节选）：

INFO  docling.models.utils.hf_model_download: Downloaded model docling-project/docling-layout-heron ... in 5.67 sec.
INFO  docling.models.utils.hf_model_download: Downloaded model docling-project/docling-models ... in 3.99 sec.
INFO  docling.pipeline.base_pipeline: Processing document 2408.09869.pdf
WARNING docling.models.stages.ocr.rapid_ocr_model: RapidOCR returned empty result!
INFO  docling.document_converter: Finished converting document 2408.09869.pdf in 48.89 sec.

real    0m56.734s

-rw-r--r-- 1 box box 570K Nov  8 00:09 2408.09869.md

两个提示不用慌：HF_TOKEN 警告只是说匿名下载限速；RapidOCR returned empty result 是因为这页的位图区域里没有可识别文字。

第 5 步：看一眼输出的 Markdown

head -c 1200 out/2408.09869.md

对照结果（图片的 base64 已省略）：

![Image](data:image/png;base64,...)

## Docling Technical Report

## Version 1.0

Christoph Auer MaksymLysak Ahmed Nassar Michele Dolfi ...

## Abstract

This technical report introduces Docling, an easy to use, self-contained, MITlicensed open-source package for PDF document conversion. ...

标题、摘要、章节都变成了 Markdown 标题，正文按阅读顺序排好。文件有 570K，是因为默认把图片以 base64 嵌进了 Markdown。

第 6 步：关掉 OCR、图片只留占位符

这份技术报告是「电子版」PDF，文字本来就能直接取出来，不需要 OCR。扫描件、拍照件才需要 OCR。再跑一次：

time docling convert 2408.09869.pdf --no-ocr --image-export-mode placeholder --output out6
ls -lh out6
grep -c "<!-- image -->" out6/2408.09869.md

对照结果：

INFO  docling.document_converter: Finished converting document 2408.09869.pdf in 9.74 sec.

real    0m16.386s

-rw-r--r-- 1 box box 29K Nov  8 00:11 2408.09869.md
5
跑法转换耗时Markdown 大小
默认（OCR 开，图片 base64 内嵌）48.89 秒570 KB
关 OCR，图片用占位符9.74 秒29 KB

9 页文档，关 OCR 后快了约 5 倍，文件缩到原来的约二十分之一；5 张图在正文里只留下一行 HTML 注释形式的 image 占位（就是上面 grep 数出来的 5 处）。想把图片单独存成 PNG，把占位模式换成 referenced。实测输出目录最好写绝对路径（见下方代码块）：

docling convert 2408.09869.pdf --no-ocr --page-range 1-3 --image-export-mode referenced --output "$PWD/out-ref"
find out-ref | head -4

对照结果：

out-ref
out-ref/2408.09869.md
out-ref/2408.09869_artifacts
out-ref/2408.09869_artifacts/image_000001_48a04bd....png

图片存进 2408.09869_artifacts 文件夹，Markdown 里写的是图片的绝对路径。如果输出目录写成相对路径 out-ref，2.148.0 实测会把图片放进 out-ref/out-ref/ 这一层嵌套目录，Markdown 里的链接按当前目录计算，移动文件夹后容易断链。

常见坑

  • 没有 GPU 也能跑：本课全程 CPU。帮助里设备参数默认 auto，有 CUDA 或 Apple MPS 会自动用上。
  • 扫描件要开 OCR：默认 OCR 引擎是自带的 RapidOCR。中文扫描件可以按 docling convert -h 里的示例指定中文语言（见下方代码块），本课没有中文扫描件，未实测。
  • URL 被拒：见第 3 步，代理 Fake-IP 环境先下载再转换。
docling convert scan.pdf --ocr-engine rapidocr --ocr-lang ch --output out-ocr

小结

你已经装好 Docling 2.148，用 docling convert 把一份 9 页带图带表的 PDF 转成了 Markdown，知道了关 OCR、图片占位能大幅提速瘦身。下一课只转指定页、导出 JSON 和表格 CSV，并改用 Python API。

本课资料

DoclingIBM Research 发起的 MIT 开源文档解析工具，把 PDF、Office、网页、音频等文件转成适合大模型和 RAG 的 Markdown/JSON，可本地离线运行，也能作为 MCP 服务器交给智能体。

适用环境

  • API
  • macOS
  • Windows
  • Linux

官方文档

Docling ↗