Docling × NVIDIA RTXGPU 加速安装、调优与 VLM 推理服务器实战【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文基于 Docling 官方 RTX GPU 加速指南docs/getting_started/rtx.md面向希望在 NVIDIA RTX 40/50 系显卡上部署文档转换能力的开发者。读完后你可以完成从 NVIDIA 驱动、CUDA、PyTorch CUDA 版到 Docling 的完整环境搭建掌握AcceleratorOptions与线程化流水线批处理参数的含义并能搭建 vLLM / llama-server 本地 VLM 推理服务器让 Docling 的 VLM 流水线以高并发吞吐处理大批量文档。适用前提与硬件要求在开始之前请确认你的环境满足以下条件摘自官方指南一张 NVIDIA RTX 显卡RTX 40/50 系列Windows 10/11 或 Linux 操作系统官方文档指出GPU 加速相比纯 CPU 处理可获得最高约 6 倍的速度提升文档内部标注了具体性能数据待补充下表数据来自同仓库的 GPU Support 指南 实测结果可作参考。环境安装五步走通 GPU 加速1. 安装 NVIDIA 驱动确认已安装最新显卡驱动Windows 从 NVIDIA 官网下载Linux 可用发行版包管理器或 NVIDIA 官方渠道。用下面命令验证nvidia-smi命令应能显示 GPU 信息与驱动版本。2. 安装 CUDA ToolkitCUDA 是 NVIDIA 的并行计算平台GPU 加速的底层依赖。按官方安装向导操作即可安装器会自动配置所需环境变量。3. 安装 cuDNNcuDNN 提供深度学习算子的优化实现。同样遵循官方安装指引覆盖所有受支持平台。4. 安装带 CUDA 支持的 PyTorch这是最容易踩坑的一步。关键点在于必须使用extra-index-url/--index-url从 PyTorch 官方 CUDA 构建源安装否则装到的是 CPU 版。如果你此前已经安装了 Docling 且环境中没有可用 CUDA大概率装的是 CPU 版 PyTorch需要先卸载再重装# 先卸载 CPU 版模块 pip uninstall torch torchaudio -y# CUDA 12.8当前 PyTorch 默认 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128 # 或 CUDA 13.0 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130!!! 注意--index-url参数至关重要它确保你拿到的是 CUDA 版本而非 CPU 版本的 PyTorch。其他 CUDA 版本的组合参见 PyTorch 官方安装矩阵。安装完成后用这段脚本验证 CUDA 是否真正可用import torch print(fPyTorch version: {torch.__version__}) print(fCUDA available: {torch.cuda.is_available()}) print(fCUDA version: {torch.version.cuda}) print(fGPU device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else None})5. 安装并运行 Doclingpip install docling到此即可完成基础配置。Docling 会在可用时自动检测并使用 RTX GPUfrom docling.document_converter import DocumentConverter # Docling 自动在可用时使用 GPU converter DocumentConverter() result converter.convert(document.pdf)源码级原理自动检测是怎么工作的自动检测并非空话。从源码结构看设备选择逻辑集中在 accelerator_utils.py 的decide_device函数中通过torch.backends.cuda.is_built() and torch.cuda.is_available()判断系统是否真的有可用 CUDA这正是第 4 步验证脚本的作用当deviceauto时按 CUDA → MPS → XPU 的优先级自动选择命中 CUDA 则落到cuda:0若用户显式指定了不存在的设备例如指定cuda但环境无 CUDA会回退到 CPU。设备枚举定义在 accelerator_options.pyAUTO / CPU / CUDA / MPS / XPU。进阶显式配置加速器与批处理参数AcceleratorOptions设备与线程在批量处理场景下建议显式配置加速器from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions accelerator_options AcceleratorOptions( deviceAcceleratorDevice.CUDA, # NVIDIA GPU 使用 CUDA )AcceleratorOptions是 PydanticBaseSettings子类支持环境变量覆盖前缀DOCLING_从源码字段定义accelerator_options.py可确认完整参数面| 参数 | 默认值 | 说明 | | - | - | - | |device|auto| 取值auto/cpu/cuda/cuda:N指定第 N 块 GPU/mps/xpu可设环境变量DOCLING_DEVICE| |num_threads|4| CPU 推理线程数官方推荐设为物理核心数兼容读取OMP_NUM_THREADS| |cuda_use_flash_attention2|False| 在 Ampere 及以上 GPU 上启用 Flash Attention 2可显著加速并降低显存占用需安装flash-attn|线程化流水线的三个批大小GPU 吞吐的关键在于批处理。官方给出的推荐配置from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions pipeline_options ThreadedPdfPipelineOptions( ocr_batch_size64, # 为 GPU 调大批大小 layout_batch_size64, # 为 GPU 调大批大小 table_batch_size4, # 表格结构提取暂不使用 GPU 批处理 )结合 pipeline_options.py 中的字段定义与文档注释这三个参数的默认值均为4且仅被线程化StandardPdfPipeline使用ocr_batch_sizeOCR 阶段页面分组大小。值越大 GPU/CPU 利用率越高但显存/内存占用越大layout_batch_size布局分析layout 检测阶段批大小是 GPU 批量推理收益最大的阶段table_batch_size表格结构提取批大小。注意 GPU Support 指南 明确注释currently not using GPU batching即该阶段调大它对 GPU 帮助有限保持默认即可。完整可运行的示例见 gpu_standard_pipeline.py它通过PdfFormatOption把ThreadedStandardPdfPipeline 上述选项绑定到 PDF 格式并打印 pages/second 作为吞吐指标。另外page_batch_size是全局性能开关默认值为4定义于 settings.py。GPU Support 指南 指出调高page_batch_size会让 Docling 模型尤其是布局检测阶段进入 GPU 批量推理模式。GPU 加速 VLM 流水线本地推理服务器对视觉语言模型VLM而言在 RTX GPU 上跑本地推理服务器能获得比进程内inline推理高得多的吞吐。Docling 支持任何暴露 OpenAI 兼容chat/completions端点的服务。LinuxvLLM推荐vllm serve ibm-granite/granite-docling-258M \ --host 127.0.0.1 --port 8000 \ --max-num-seqs 512 \ --max-num-batched-tokens 8192 \ --enable-chunked-prefill \ --gpu-memory-utilization 0.9参数含义--max-num-seqs 512允许服务器内部并发 512 个序列--gpu-memory-utilization 0.9让 vLLM 占用约 90% 显存做 KV cache 预分配--enable-chunked-prefill开启分块预填充以提升混合吞吐。Windowsllama-server在 Windows 上可用 llama.cpp 的llama-server下载 llama.cpp 的最新 release解压后找到llama-server.exe启动命令PowerShell注意续行符为反引号llama-server.exe --hf-repo ibm-granite/granite-docling-258M-GGUF -cb -ngl -1 --port 8000 --context-shift -np 16 -c 131072其中-ngl -1表示全部层放 GPU-np 16为 16 个并行槽位-c 131072为 128K 上下文。官方性能对比结论vLLM 相比 llama-server 约有 4 倍的性能优势。Windows 用户若追求极致性能可考虑通过 WSL2 运行 vLLM。配置 Docling 接入 VLM 服务器服务器起来后配置 Doclingfrom docling.datamodel.pipeline_options import VlmPipelineOptions from docling.datamodel.settings import settings BATCH_SIZE 64 # 使用 vLLM API 预设 vlm_options vlm_model_specs.GRANITEDOCLING_VLLM_API vlm_options.concurrency BATCH_SIZE # 若运行的是 llama.cppllama-server需改用对应的模型名 # vlm_options.params[model] ibm-granite_granite-docling-258M-GGUF_granite-docling-258M-BF16.gguf # page_batch_size 必须 concurrency settings.perf.page_batch_size BATCH_SIZE converter DocumentConverter( pipeline_optionsvlm_options, )源码级核对GRANITEDOCLING_VLLM_API 预设长什么样该预设在 vlm_model_specs.py 中是一个ApiVlmOptions关键默认值urlhttp://localhost:8000/v1/chat/completions注释标明 LM Studio 默认端口为 1234、vLLM 为 8000正好与上文的服务器端口对应params.modelibm-granite/granite-docling-258M、max_tokens4096concurrency4默认偏保守高吞吐需按示例调大到 64timeout90、temperature0.0、scale2.0、响应格式DOCTAGS。因此指南中llama-server 需换模型名的注释是必要的——预设默认 model 名是 HF 仓库 id与 GGUF 推理服务上报的模型名不一致。page_batch_size concurrency为什么是硬要求GPU Support 指南 明确要求settings.perf.page_batch_size vlm_options.concurrency。从流水线结构可以推断其含义page_batch_size控制单次交给 VLM 阶段的页面数若页面批大小小于并发数多出的并发请求会因无页面可发而空转吞吐无法达到并发上限。仓库中的完整示例 gpu_vlm_pipeline.py 正是这一模式的落地它设置settings.perf.page_batch_size 64再用VlmConvertOptions.from_preset(granite_docling, engine_optionsApiVlmEngineOptions(runtime_typeVlmEngineType.API, url..., concurrency64))构建选项并开启enable_remote_servicesTrue使用远端推理服务时必需最后按 PDF 格式绑定VlmPipeline。性能优化技巧按显存选批大小官方给出的经验值| 显卡 | 显存 | 推荐批大小 | | - | - | - | | RTX 5090 | 32GB | 64–128 | | RTX 4090 | 24GB | 32–64 | | RTX 5070 | 12GB | 16–32 |显存监控import torch if torch.cuda.is_available(): print(fGPU Memory allocated: {torch.cuda.memory_allocated(0) / 1024**3:.2f} GB) print(fGPU Memory reserved: {torch.cuda.memory_reserved(0) / 1024**3:.2f} GB)allocated是 PyTorch 实际分配的张量显存reserved是缓存池保留量包含碎片排查 OOM 时两个数字对照看。实测吞吐参考GPU Support 指南 给出了三台机型的对比实测ViDoRe V3 HR14 文档 / 1110 页RTX 5090 上 Standard 流水线无 OCR约 7.9 页/秒纯 CPU 约 1.5 页/秒VLM 推理服务器方案约 3.6–4.5 页/秒高于同机型的 inline 场景。注意这些数字与具体 CUDA 版本、驱动版本及是否启用 OCR 强相关仅作量级参考。故障排查CUDA 显存溢出OOM降低pipeline_options中的批大小减少并发处理的文档数批次之间清理显存缓存import torch torch.cuda.empty_cache()torch.cuda.is_available()返回 Falsenvidia-smi验证驱动是否安装nvcc --version检查 CUDA 工具链按第 4 步重新安装匹配 CUDA 版本的 PyTorch确认显卡本身支持 CUDARTX 40/50 系均支持。性能没有提升在显存允许时继续调大批大小确认文档量足够多——GPU 并行的收益在大批量场景才明显单页短文档上批处理开销可能反而占优用nvidia-smi -l 1实时观察 GPU 利用率判断瓶颈是否在 GPU 侧再次确认torch.cuda.is_available()为True。延伸阅读GPU Support 指南设备选择、各流水线的 GPU 策略与完整性能对比数据gpu_standard_pipeline.py标准流水线 GPU 批量转换完整示例gpu_vlm_pipeline.pyvLLM VLM 流水线高吞吐完整示例AcceleratorOptions设备枚举与环境变量支持vlm_model_specs.py全部 VLM 预设含 Ollama / MLX 变体定义【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Docling × NVIDIA RTX：GPU 加速安装、调优与 VLM 推理服务器实战
Docling × NVIDIA RTXGPU 加速安装、调优与 VLM 推理服务器实战【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文基于 Docling 官方 RTX GPU 加速指南docs/getting_started/rtx.md面向希望在 NVIDIA RTX 40/50 系显卡上部署文档转换能力的开发者。读完后你可以完成从 NVIDIA 驱动、CUDA、PyTorch CUDA 版到 Docling 的完整环境搭建掌握AcceleratorOptions与线程化流水线批处理参数的含义并能搭建 vLLM / llama-server 本地 VLM 推理服务器让 Docling 的 VLM 流水线以高并发吞吐处理大批量文档。适用前提与硬件要求在开始之前请确认你的环境满足以下条件摘自官方指南一张 NVIDIA RTX 显卡RTX 40/50 系列Windows 10/11 或 Linux 操作系统官方文档指出GPU 加速相比纯 CPU 处理可获得最高约 6 倍的速度提升文档内部标注了具体性能数据待补充下表数据来自同仓库的 GPU Support 指南 实测结果可作参考。环境安装五步走通 GPU 加速1. 安装 NVIDIA 驱动确认已安装最新显卡驱动Windows 从 NVIDIA 官网下载Linux 可用发行版包管理器或 NVIDIA 官方渠道。用下面命令验证nvidia-smi命令应能显示 GPU 信息与驱动版本。2. 安装 CUDA ToolkitCUDA 是 NVIDIA 的并行计算平台GPU 加速的底层依赖。按官方安装向导操作即可安装器会自动配置所需环境变量。3. 安装 cuDNNcuDNN 提供深度学习算子的优化实现。同样遵循官方安装指引覆盖所有受支持平台。4. 安装带 CUDA 支持的 PyTorch这是最容易踩坑的一步。关键点在于必须使用extra-index-url/--index-url从 PyTorch 官方 CUDA 构建源安装否则装到的是 CPU 版。如果你此前已经安装了 Docling 且环境中没有可用 CUDA大概率装的是 CPU 版 PyTorch需要先卸载再重装# 先卸载 CPU 版模块 pip uninstall torch torchaudio -y# CUDA 12.8当前 PyTorch 默认 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128 # 或 CUDA 13.0 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130!!! 注意--index-url参数至关重要它确保你拿到的是 CUDA 版本而非 CPU 版本的 PyTorch。其他 CUDA 版本的组合参见 PyTorch 官方安装矩阵。安装完成后用这段脚本验证 CUDA 是否真正可用import torch print(fPyTorch version: {torch.__version__}) print(fCUDA available: {torch.cuda.is_available()}) print(fCUDA version: {torch.version.cuda}) print(fGPU device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else None})5. 安装并运行 Doclingpip install docling到此即可完成基础配置。Docling 会在可用时自动检测并使用 RTX GPUfrom docling.document_converter import DocumentConverter # Docling 自动在可用时使用 GPU converter DocumentConverter() result converter.convert(document.pdf)源码级原理自动检测是怎么工作的自动检测并非空话。从源码结构看设备选择逻辑集中在 accelerator_utils.py 的decide_device函数中通过torch.backends.cuda.is_built() and torch.cuda.is_available()判断系统是否真的有可用 CUDA这正是第 4 步验证脚本的作用当deviceauto时按 CUDA → MPS → XPU 的优先级自动选择命中 CUDA 则落到cuda:0若用户显式指定了不存在的设备例如指定cuda但环境无 CUDA会回退到 CPU。设备枚举定义在 accelerator_options.pyAUTO / CPU / CUDA / MPS / XPU。进阶显式配置加速器与批处理参数AcceleratorOptions设备与线程在批量处理场景下建议显式配置加速器from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions accelerator_options AcceleratorOptions( deviceAcceleratorDevice.CUDA, # NVIDIA GPU 使用 CUDA )AcceleratorOptions是 PydanticBaseSettings子类支持环境变量覆盖前缀DOCLING_从源码字段定义accelerator_options.py可确认完整参数面| 参数 | 默认值 | 说明 | | - | - | - | |device|auto| 取值auto/cpu/cuda/cuda:N指定第 N 块 GPU/mps/xpu可设环境变量DOCLING_DEVICE| |num_threads|4| CPU 推理线程数官方推荐设为物理核心数兼容读取OMP_NUM_THREADS| |cuda_use_flash_attention2|False| 在 Ampere 及以上 GPU 上启用 Flash Attention 2可显著加速并降低显存占用需安装flash-attn|线程化流水线的三个批大小GPU 吞吐的关键在于批处理。官方给出的推荐配置from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions pipeline_options ThreadedPdfPipelineOptions( ocr_batch_size64, # 为 GPU 调大批大小 layout_batch_size64, # 为 GPU 调大批大小 table_batch_size4, # 表格结构提取暂不使用 GPU 批处理 )结合 pipeline_options.py 中的字段定义与文档注释这三个参数的默认值均为4且仅被线程化StandardPdfPipeline使用ocr_batch_sizeOCR 阶段页面分组大小。值越大 GPU/CPU 利用率越高但显存/内存占用越大layout_batch_size布局分析layout 检测阶段批大小是 GPU 批量推理收益最大的阶段table_batch_size表格结构提取批大小。注意 GPU Support 指南 明确注释currently not using GPU batching即该阶段调大它对 GPU 帮助有限保持默认即可。完整可运行的示例见 gpu_standard_pipeline.py它通过PdfFormatOption把ThreadedStandardPdfPipeline 上述选项绑定到 PDF 格式并打印 pages/second 作为吞吐指标。另外page_batch_size是全局性能开关默认值为4定义于 settings.py。GPU Support 指南 指出调高page_batch_size会让 Docling 模型尤其是布局检测阶段进入 GPU 批量推理模式。GPU 加速 VLM 流水线本地推理服务器对视觉语言模型VLM而言在 RTX GPU 上跑本地推理服务器能获得比进程内inline推理高得多的吞吐。Docling 支持任何暴露 OpenAI 兼容chat/completions端点的服务。LinuxvLLM推荐vllm serve ibm-granite/granite-docling-258M \ --host 127.0.0.1 --port 8000 \ --max-num-seqs 512 \ --max-num-batched-tokens 8192 \ --enable-chunked-prefill \ --gpu-memory-utilization 0.9参数含义--max-num-seqs 512允许服务器内部并发 512 个序列--gpu-memory-utilization 0.9让 vLLM 占用约 90% 显存做 KV cache 预分配--enable-chunked-prefill开启分块预填充以提升混合吞吐。Windowsllama-server在 Windows 上可用 llama.cpp 的llama-server下载 llama.cpp 的最新 release解压后找到llama-server.exe启动命令PowerShell注意续行符为反引号llama-server.exe --hf-repo ibm-granite/granite-docling-258M-GGUF -cb -ngl -1 --port 8000 --context-shift -np 16 -c 131072其中-ngl -1表示全部层放 GPU-np 16为 16 个并行槽位-c 131072为 128K 上下文。官方性能对比结论vLLM 相比 llama-server 约有 4 倍的性能优势。Windows 用户若追求极致性能可考虑通过 WSL2 运行 vLLM。配置 Docling 接入 VLM 服务器服务器起来后配置 Doclingfrom docling.datamodel.pipeline_options import VlmPipelineOptions from docling.datamodel.settings import settings BATCH_SIZE 64 # 使用 vLLM API 预设 vlm_options vlm_model_specs.GRANITEDOCLING_VLLM_API vlm_options.concurrency BATCH_SIZE # 若运行的是 llama.cppllama-server需改用对应的模型名 # vlm_options.params[model] ibm-granite_granite-docling-258M-GGUF_granite-docling-258M-BF16.gguf # page_batch_size 必须 concurrency settings.perf.page_batch_size BATCH_SIZE converter DocumentConverter( pipeline_optionsvlm_options, )源码级核对GRANITEDOCLING_VLLM_API 预设长什么样该预设在 vlm_model_specs.py 中是一个ApiVlmOptions关键默认值urlhttp://localhost:8000/v1/chat/completions注释标明 LM Studio 默认端口为 1234、vLLM 为 8000正好与上文的服务器端口对应params.modelibm-granite/granite-docling-258M、max_tokens4096concurrency4默认偏保守高吞吐需按示例调大到 64timeout90、temperature0.0、scale2.0、响应格式DOCTAGS。因此指南中llama-server 需换模型名的注释是必要的——预设默认 model 名是 HF 仓库 id与 GGUF 推理服务上报的模型名不一致。page_batch_size concurrency为什么是硬要求GPU Support 指南 明确要求settings.perf.page_batch_size vlm_options.concurrency。从流水线结构可以推断其含义page_batch_size控制单次交给 VLM 阶段的页面数若页面批大小小于并发数多出的并发请求会因无页面可发而空转吞吐无法达到并发上限。仓库中的完整示例 gpu_vlm_pipeline.py 正是这一模式的落地它设置settings.perf.page_batch_size 64再用VlmConvertOptions.from_preset(granite_docling, engine_optionsApiVlmEngineOptions(runtime_typeVlmEngineType.API, url..., concurrency64))构建选项并开启enable_remote_servicesTrue使用远端推理服务时必需最后按 PDF 格式绑定VlmPipeline。性能优化技巧按显存选批大小官方给出的经验值| 显卡 | 显存 | 推荐批大小 | | - | - | - | | RTX 5090 | 32GB | 64–128 | | RTX 4090 | 24GB | 32–64 | | RTX 5070 | 12GB | 16–32 |显存监控import torch if torch.cuda.is_available(): print(fGPU Memory allocated: {torch.cuda.memory_allocated(0) / 1024**3:.2f} GB) print(fGPU Memory reserved: {torch.cuda.memory_reserved(0) / 1024**3:.2f} GB)allocated是 PyTorch 实际分配的张量显存reserved是缓存池保留量包含碎片排查 OOM 时两个数字对照看。实测吞吐参考GPU Support 指南 给出了三台机型的对比实测ViDoRe V3 HR14 文档 / 1110 页RTX 5090 上 Standard 流水线无 OCR约 7.9 页/秒纯 CPU 约 1.5 页/秒VLM 推理服务器方案约 3.6–4.5 页/秒高于同机型的 inline 场景。注意这些数字与具体 CUDA 版本、驱动版本及是否启用 OCR 强相关仅作量级参考。故障排查CUDA 显存溢出OOM降低pipeline_options中的批大小减少并发处理的文档数批次之间清理显存缓存import torch torch.cuda.empty_cache()torch.cuda.is_available()返回 Falsenvidia-smi验证驱动是否安装nvcc --version检查 CUDA 工具链按第 4 步重新安装匹配 CUDA 版本的 PyTorch确认显卡本身支持 CUDARTX 40/50 系均支持。性能没有提升在显存允许时继续调大批大小确认文档量足够多——GPU 并行的收益在大批量场景才明显单页短文档上批处理开销可能反而占优用nvidia-smi -l 1实时观察 GPU 利用率判断瓶颈是否在 GPU 侧再次确认torch.cuda.is_available()为True。延伸阅读GPU Support 指南设备选择、各流水线的 GPU 策略与完整性能对比数据gpu_standard_pipeline.py标准流水线 GPU 批量转换完整示例gpu_vlm_pipeline.pyvLLM VLM 流水线高吞吐完整示例AcceleratorOptions设备枚举与环境变量支持vlm_model_specs.py全部 VLM 预设含 Ollama / MLX 变体定义【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考