Docling 安装与入门终极指南3 分钟装好文档解析 SDK 并跑通第一份 PDF【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 是一个文档解析 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 转成 Markdownfrom docling.document_converter import DocumentConverter doc DocumentConverter().convert(paper.pdf).document print(doc.export_to_markdown())不想写代码CLI 一行也能跑默认输出 Markdowndocling paper.pdf --to md看到控制台滚出解析进度、终端里生成paper.md就说明安装成功了。整个链路是「Backend 解析 → 标准 PDF 流水线 → DoclingDocument → 导出」架构全貌见下图动手前先过一遍环境自检清单安装失败 80% 的坑出在环境不达标。装之前对照这张表打勾检查项要求自检命令Python 版本3.10 – 3.14docling2.x要求3.10,4.0python --version操作系统macOS / Linux / Windowsuname -a或系统设置CPU 架构x86_64 或 arm64uname -m磁盘空间预留 2GB首次运行要下载布局/表格模型df -h内存建议 8GB 起系统监视器GPU可选NVIDIA CUDA 可显著提速nvidia-smi两个容易翻车的环境特例提前记住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 版 torchpip install docling --extra-index-url https://download.pytorch.org/whl/cpu场景 B服务器生产部署NVIDIA GPUGPU 上可拿到最高约 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.pdfOCR 引擎对比处理扫描件 / 图片 PDF 时才需要引擎安装方式适用平台特点EasyOCRpip install docling[easyocr]全平台最省心中文友好Tesseract系统包管理器 docling[tesserocr]全平台多语言、精度高需配TESSDATA_PREFIXRapidOCRpip install docling[rapidocr]全平台轻量、速度快ONNX 后端ocrmacpip install docling[ocrmac]仅 macOSApple 原生引擎Nemotron OCRdocling[feat-ocr-nemotron]仅 Linux x86_64 CUDA 13仅限特定环境切换引擎只改一行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_optionsopts)})更多可选 extravlm、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()))三个常见观察点首次运行会下载布局 / 表格模型进度条走完才算真正装好输出长度明显偏短 → 大概率遇到扫描件文档没有文本层需要开 OCR回到上一节选引擎CLI 用户等价验证docling paper.pdf --to md然后检查生成的.md里标题层级和表格是否还原。解析结果在内部是带层级的文档树标题、表格、图片都保留了位置与结构信息踩坑急救包现象 → 原因 → 解法现象安装时 PyTorch 相关报错机器是 Intel Mac。原因PyTorch 2.6 停更 x86_64 macOS wheel。解法pip install docling[mac_intel]或手动钉版本pip install torch2.2.2 torchvision0.17.2 docling需 Python ≤ 3.12。现象tesserocr编译失败 / 找不到 Tesseract。原因缺系统依赖或 tessdata 路径没配。解法先用包管理器装 TesseractDebianapt-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()返回FalseGPU 没生效。原因装的是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考