企业官网建设流程全解析

Docling 安装与入门终极指南：3 分钟装好文档解析 SDK 并跑通第一份 PDF

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling

Docling 是一个文档解析 SDK + CLI 工具，把 PDF、DOCX、HTML、扫描件、音频等格式统一解析成 DoclingDocument，再导出为 Markdown / HTML / JSON，直接喂给生成式 AI 应用。下面不绕弯子：先让你 3 分钟内看到结果，再回头讲环境、引擎选型和踩坑急救。

3 分钟跑通：pip 一行安装 + 最短可运行代码

先建个干净的虚拟环境，然后装包：

python -m venv docling-env && source docling-env/bin/activate pip install docling

接着用 Python 把一份 PDF 转成 Markdown：

from docling.document_converter import DocumentConverter doc = DocumentConverter().convert("paper.pdf").document print(doc.export_to_markdown())

不想写代码？CLI 一行也能跑，默认输出 Markdown：

docling paper.pdf --to md

看到控制台滚出解析进度、终端里生成paper.md，就说明安装成功了。整个链路是「Backend 解析 → 标准 PDF 流水线 → DoclingDocument → 导出」，架构全貌见下图：

动手前先过一遍环境自检清单

安装失败 80% 的坑出在环境不达标。装之前对照这张表打勾：

两个容易翻车的环境特例，提前记住：

• Intel 老款 Mac：新版 PyTorch 已不提供 x86_64 macOS wheel，需钉住旧版，后文「分场景安装」里给出命令（注意该组合要求 Python ≤ 3.12）。
• 纯 CPU Linux 服务器：默认会拉到 GPU 版 PyTorch，白占几百 MB，建议装 CPU 版。

按你的场景走：本地体验 / GPU 服务器 / 离线内网三条安装路线

场景 A：本地快速体验（笔记本 / 台式，无 GPU）

标准安装就够了，Docling 会自动按你的环境选 PyTorch 发行版：

# pip pip install docling # uv uv add docling

纯 CPU 的 Linux 服务器，追加 CPU 索引避免装到 CUDA 版 torch：

pip install docling --extra-index-url https://download.pytorch.org/whl/cpu

场景 B：服务器生产部署（NVIDIA GPU）

GPU 上可拿到最高约 6 倍的提速。步骤：装好 NVIDIA 驱动 → 装 CUDA → 先卸载可能已存在的 CPU 版 torch，再装 CUDA 版 → 最后装 Docling（它会自动检测到 GPU，无需额外配置）：

pip uninstall torch torchaudio -y pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128 pip install docling

细节与批处理调优见 RTX GPU 加速指南。

场景 C：受限 / 离线 / 内网环境

Docling 完全支持本地运行（air-gapped），做法是「联网机下包、离线机解包」：

# 联网机：下载 docling 及全部依赖的 wheel pip download docling -d ./wheels # 把 ./wheels 拷到离线机后 pip install docling --no-index --find-links ./wheels

注意首次convert仍会尝试从 HuggingFace 下载模型权重，内网场景需要提前把模型缓存搬进离线机的HF_HOME目录，或在联网机上先跑一次convert完成缓存。

引擎怎么选：标准流水线 vs VLM 流水线 + OCR 引擎对比表

Docling 有两条解析主路线，先按文档类型定路线，再按文档质量定 OCR 引擎。

主线决策：

• 默认场景（数字 PDF、DOCX、HTML）→ 标准流水线（PdfPipelineOptions），速度快、CPU 就能跑。
• 复杂版面、扫描件、高精度要求、有 GPU→ VLM 流水线（VlmPipelineOptions，如 GraniteDocling 258M），质量更高但需要模型推理能力。

CLI 切 VLM 流水线只需加两个参数：

docling --pipeline vlm --vlm-model granite_docling paper.pdf

OCR 引擎对比（处理扫描件 / 图片 PDF 时才需要）：

切换引擎只改一行ocr_options，以 Tesseract 为例：

from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import TesseractOcrOptions, PdfPipelineOptions from docling.document_converter import DocumentConverter, PdfFormatOption opts = PdfPipelineOptions() opts.do_ocr = True opts.ocr_options = TesseractOcrOptions() converter = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})

更多可选 extra（vlm、asr、htmlrender等）一览见 安装文档。

冒烟验证：5 行代码确认你的安装没问题

装完后跑这个最小用例，能同时验证「包能 import、流水线能加载、模型能下载、导出能工作」：

import docling from docling.document_converter import DocumentConverter print("version:", docling.__version__) doc = DocumentConverter().convert("paper.pdf").document print("markdown length:", len(doc.export_to_markdown()))

三个常见观察点：

1. 首次运行会下载布局 / 表格模型，进度条走完才算真正装好；
2. 输出长度明显偏短 → 大概率遇到扫描件，文档没有文本层，需要开 OCR（回到上一节选引擎）；
3. CLI 用户等价验证：docling paper.pdf --to md，然后检查生成的.md里标题层级和表格是否还原。

解析结果在内部是带层级的文档树，标题、表格、图片都保留了位置与结构信息：

踩坑急救包：现象 → 原因 → 解法

• 现象：安装时 PyTorch 相关报错，机器是 Intel Mac。原因：PyTorch 2.6+ 停更 x86_64 macOS wheel。解法：pip install "docling[mac_intel]"，或手动钉版本pip install torch==2.2.2 torchvision==0.17.2 docling（需 Python ≤ 3.12）。

• 现象：tesserocr编译失败 / 找不到 Tesseract。原因：缺系统依赖或 tessdata 路径没配。解法：先用包管理器装 Tesseract（Debian：apt-get install tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config），再pip uninstall tesserocr && pip install --no-binary :all: tesserocr，最后确保TESSDATA_PREFIX指向 tessdata 目录且以/结尾。

• 现象：torch.cuda.is_available()返回False，GPU 没生效。原因：装的是 CPU 版 torch，或驱动 / CUDA 不齐。解法：nvidia-smi确认驱动 → 按「场景 B」重装 CUDA 版 torch → 再验证。

• 现象：转换速度上不去。原因：默认线程 / 批大小保守。解法：调大max_workers、OCR / layout 批大小；GPU 场景按显存调整（RTX 4090 建议 32–64，参考 GPU 指南）。

• 现象：内网机器convert卡住或报网络错误。原因：首次运行要拉模型权重。解法：联网机预跑一次转换生成 HF 缓存，把缓存目录整体迁移到离线机。

进阶与生态：源码开发、跑测试、升级与周边工具

想改代码或跟上游：

git clone https://gitcode.com/GitHub_Trending/do/docling cd docling uv sync --all-extras --no-extra feat-ocr-nemotron pytest tests/test_backend_pdfium.py -x

日常升级与版本确认：

pip install --upgrade docling pip show docling

装好之后下一步：

• 想接 RAG：看 分块与序列化概念 和 序列化文档；
• 想看支持的全部输入 / 输出格式：格式清单；
• 想集成 LangChain / LlamaIndex 等框架：集成总览；
• 想跑 VLM、ASR 等高级流水线：CLI 参考 和 GPU 指南。

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling