1. DeepSeek-OCR 本地部署踩坑实录从 Dockerfile 构建到 vLLM 推理链路DeepSeek-OCR 是 DeepSeek-AI 推出的视觉语言模型专门用来探索视觉 2D 映射压缩长上下文的可行性。它由 DeepEncoder约 380M 参数和 DeepSeek3B-MoE-A570M 解码器激活 570M 参数组成核心思路是通过串联窗口注意力、16 倍卷积压缩器和全局注意力在高分辨率输入下把激活内存压下来同时保持高压缩比。实测在 Fox 基准上压缩比小于 10 倍时 OCR 精度能到 97%20 倍时仍有 60% 精度在 OmniDocBench 上只用 100 个视觉 token 就超过了 GOT-OCR2.0 的 256 token不到 800 视觉 token 超过 MinerU2.0 的 6000 token。它还支持图表、化学式、几何图形深度解析能识别近 100 种语言生产级场景下单张 A100-40G 一天能生成 20 万页以上的训练数据。这套东西适合谁如果你手头有 A100-40G 或同级别显存想把 PDF、扫描件、复杂排版文档批量转成 Markdown或者想拿它做 LLM 训练数据清洗那 DeepSeek-OCR 值得折腾。但它的部署链路不算短CUDA 11.8 基础镜像、Python 3.12.9 编译、vLLM 0.8.5 的 whl 包、flash-attn 2.7.3每一步都有坑。我试过从零走一遍下面把 Dockerfile 构建、vLLM 与 Transformers 两种推理后端的配置解析、以及端到端测试验证完整拆开讲代码和参数都能直接复制。1.1 环境准备与文件拉取先确认显卡环境。官方推荐 A100-40G实际测试中 24G 显存的卡跑 Gundam 模式会紧张建议至少 32G 起步。CUDA 版本锁死 11.8因为 vLLM 0.8.5 的预编译 whl 是 cu118 版本换 12.x 会碰到 ABI 不兼容。拉取基础镜像和代码# 拉取 CUDA 11.8 基础镜像 docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:11.8.0-devel-ubuntu22.04 # 克隆仓库 git clone https://github.com/deepseek-ai/DeepSeek-OCR.git # 下载 vLLM 0.8.5 whl 包 wget https://github.com/vllm-project/vllm/releases/download/v0.8.5/vllm-0.8.5cu118-cp38-abi3-manylinux1_x86_64.whl # 下载模型权重 git lfs install git clone https://www.modelscope.cn/deepseek-ai/DeepSeek-OCR.git这里有个细节vLLM 的 whl 包命名里带cp38-abi3意思是它兼容 Python 3.8 以上的 ABI3 稳定接口所以后面用 Python 3.12.9 也能装。但 flash-attn 必须和 torch 版本对齐torch 2.6.0 对应 flash-attn 2.7.3装错版本会在 import 时报undefined symbol。1.2 Dockerfile 完整构建片段把requirements.txt、sources.list、SimHei.ttf和 vLLM whl 包放到同一目录然后写 DockerfileFROM swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:11.8.0-devel-ubuntu22.04 ENV PYTHON_VERSION3.12.9 ENV PYTHONUNBUFFERED1 ENV DEBIAN_FRONTENDnoninteractive WORKDIR /workspace COPY requirements.txt sources.list SimHei.ttf vllm-0.8.5cu118-cp38-abi3-manylinux1_x86_64.whl /workspace/ RUN mv /workspace/SimHei.ttf /usr/share/fonts/ \ mv /workspace/sources.list /etc/apt/sources.list RUN apt-get update apt-get install -y \ wget curl git vim build-essential zlib1g-dev \ libncurses5-dev libgdbm-dev libnss3-dev libssl-dev \ libreadline-dev libffi-dev libsqlite3-dev libbz2-dev \ liblzma-dev pkg-config cmake \ rm -rf /var/lib/apt/lists/* RUN cd /tmp \ wget https://www.python.org/ftp/python/${PYTHON_VERSION}/Python-${PYTHON_VERSION}.tgz \ tar -xzf Python-${PYTHON_VERSION}.tgz \ cd Python-${PYTHON_VERSION} \ ./configure --enable-optimizations --enable-shared \ make -j$(nproc) \ make altinstall \ ldconfig \ cd /tmp rm -rf Python-* RUN ln -sf /usr/local/bin/python3.12 /usr/local/bin/python3 \ ln -sf /usr/local/bin/python3.12 /usr/local/bin/python \ curl -sS https://bootstrap.pypa.io/get-pip.py | python3.12 ENV PATH/usr/local/cuda/bin:$PATH ENV LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH ENV CUDA_HOME/usr/local/cuda RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple \ pip install --upgrade pip RUN pip install torch2.6.0 torchvision0.21.0 torchaudio2.6.0 \ --index-url https://download.pytorch.org/whl/cu118 RUN pip install vllm-0.8.5cu118-cp38-abi3-manylinux1_x86_64.whl RUN pip install -r requirements.txt RUN pip install flash-attn2.7.3 --no-build-isolation RUN python -c import transformers; print(transformers导入成功) CMD [/bin/bash]构建命令docker build -t deepseek-ocr-cuda11.8-pytorch2.6:v1.0 . # 如果缓存导致依赖没更新加 --no-cache docker build --no-cache -t deepseek-ocr-cuda11.8-pytorch2.6:v1.0 . # 构建时间长用 nohup 挂后台 nohup docker build -t deepseek-ocr-cuda11.8-pytorch2.6:v1.0 . 编译 Python 3.12.9 和 flash-attn 是耗时大头flash-attn 编译时内存占用可能冲到 8G 以上机器内存不够会 OOM。镜像最终大小在 15G 左右提前留好磁盘。1.3 运行容器与验证环境docker run -it --gpus all -v $(pwd):/workspace deepseek-ocr-cuda11.8-pytorch2.6:v1.0进容器后逐条验证python -c import torch; print(fPyTorch: {torch.__version__}, CUDA: {torch.version.cuda}) python -c import torch; print(fGPU可用: {torch.cuda.is_available()}, GPU数量: {torch.cuda.device_count()}) python -c import flash_attn; print(flash_attn安装成功) python -c from flash_attn import flash_attention; print(CUDA内核可用) nvidia-smi如果flash_attention导入报ImportError: libcudart.so.11.0说明LD_LIBRARY_PATH没生效检查 Dockerfile 里的 ENV 是否被后续 RUN 覆盖。正常输出应该是 PyTorch 2.6.0、CUDA 11.8、GPU 可用为 True。2. DeepSeek-OCR config.py 配置解析模型模式与图像处理参数怎么调配置文件在DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py所有推理脚本都读它。理解每个参数的含义比盲目改数值重要得多。2.1 模型模式与核心图像参数配置文件顶部注释列了 5 种预定义模式# Tiny: base_size 512, image_size 512, crop_mode False # Small: base_size 640, image_size 640, crop_mode False # Base: base_size 1024, image_size 1024, crop_mode False # Large: base_size 1280, image_size 1280, crop_mode False # Gundam: base_size 1024, image_size 640, crop_mode True当前默认是 Gundam 模式BASE_SIZE 1024 IMAGE_SIZE 640 CROP_MODE TrueBASE_SIZE决定处理的最大分辨率IMAGE_SIZE是模型实际处理的图像尺寸CROP_MODE控制是否启用裁剪。Gundam 模式先用 1024×1024 拿全局视图再智能裁剪出多个 640×640 局部区域最后综合全局和局部信息生成结果。这种设计对多列、图表混合的大尺寸文档特别有效。2.2 裁剪与性能参数MIN_CROPS 2 MAX_CROPS 6 # max:9; GPU内存小建议设6 MAX_CONCURRENCY 100 # GPU内存有限时降低 NUM_WORKERS 64 # 图像预处理线程数MAX_CROPS最大能到 9但显存小于 24G 建议保持 6。MAX_CONCURRENCY是并发处理数A100-40G 可以保持 10024G 卡建议降到 30-50。NUM_WORKERS按 CPU 核心数的 1-2 倍设置纯 GPU 瓶颈时这个值影响不大。2.3 功能开关与路径设置PRINT_NUM_VIS_TOKENS False SKIP_REPEAT True MODEL_PATH deepseek-ai/DeepSeek-OCR INPUT_PATH OUTPUT_PATH PRINT_NUM_VIS_TOKENS调试时设 True 能看到实际消耗的视觉 token 数。INPUT_PATH必须改成实际路径PDF 用run_dpsk_ocr_pdf.py图片用run_dpsk_ocr_image.py批量评估用run_dpsk_ocr_eval_batch.py。2.4 提示词设置与模式切换PROMPT image\n|grounding|Convert the document to markdown. # PROMPT image\nFree OCR. # PROMPT image\n|grounding|OCR this image. # PROMPT image\nParse the figure. # PROMPT image\nDescribe this image in detail. # PROMPT image\nLocate |ref|xxxx|/ref| in the image.带|grounding|的提示词会保留布局信息输出 Markdown 时表格、标题层级更准。Free OCR不带布局速度快但结构丢失。图表解析用Parse the figure特定内容定位用Locate。切换到 Base 模式只需改三行BASE_SIZE 1024 IMAGE_SIZE 1024 CROP_MODE False各模式的视觉 token 数量Tiny 64、Small 100、Base 256、Large 400。token 越多细节越丰富但显存和处理时间也上去。显存小于 8G 用 Tiny/Small8-16G 用 Base大于 16G 用 Large 或 Gundam。3. vLLM 推理链路配置图像流式输出与 PDF 并发处理vLLM 后端适合批量处理吞吐量比 Transformers 高不少。工作目录切到DeepSeek-OCR-master/DeepSeek-OCR-vllm。3.1 图像流式输出cd DeepSeek-OCR-master/DeepSeek-OCR-vllm python run_dpsk_ocr_image.py跑之前改config.pyINPUT_PATH指向图片文件或目录OUTPUT_PATH设结果保存位置。支持 jpg、png、jpeg。流式输出会实时打印识别结果到控制台同时保存到输出路径。单图处理适合调试提示词效果。3.2 PDF 并发处理python run_dpsk_ocr_pdf.pyPDF 处理走并发链路A100-40G 上约 2500 tokens/s。MAX_CONCURRENCY根据显存调24G 卡建议 30-5040G 卡可以 100。如果跑的时候报CUDA out of memory先把MAX_CONCURRENCY砍半再降MAX_CROPS到 4。3.3 批量评估基准测试python run_dpsk_ocr_eval_batch.py用于 OmnidocBench 等标准测试集INPUT_PATH指向测试数据目录按标准格式组织。输出评估报告能对比不同模式下的精度差异。3.4 vLLM 启动参数与 settings 片段如果要把 vLLM 当服务跑可以用 OpenAI 兼容接口。启动命令python -m vllm.entrypoints.openai.api_server \ --model deepseek-ai/DeepSeek-OCR \ --trust-remote-code \ --dtype bfloat16 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --port 8000对应的客户端 settings 片段以 Cline MCP 配置为例{ mcpServers: { deepseek-ocr: { command: python, args: [-m, vllm.entrypoints.openai.api_server], env: { BASE_URL: http://localhost:8000/v1, API_KEY: sk-your-key, MODEL_ID: deepseek-ai/DeepSeek-OCR } } } }三件套对齐Base URL 指向本地 vLLM 服务Key 随便填本地不校验Model ID 必须和--model参数一致。如果走远程 API 网关把 Base URL 换成对应地址Key 换成实际签发的。4. Transformers 推理与端到端测试验证Transformers 后端适合单次推理和调试代码直观。4.1 Transformers 加载配置from transformers import AutoModel, AutoTokenizer import torch import os os.environ[CUDA_VISIBLE_DEVICES] 0 model_name deepseek-ai/DeepSeek-OCR tokenizer AutoTokenizer.from_pretrained(model_name, trust_remote_codeTrue) model AutoModel.from_pretrained( model_name, _attn_implementationflash_attention_2, trust_remote_codeTrue, use_safetensorsTrue ) model model.eval().cuda().to(torch.bfloat16) prompt image\n|grounding|Convert the document to markdown. image_file your_image.jpg output_path your/output/dir res model.infer( tokenizer, promptprompt, image_fileimage_file, output_pathoutput_path, base_size1024, image_size640, crop_modeTrue, save_resultsTrue, test_compressTrue )trust_remote_codeTrue必须加模型带自定义代码。_attn_implementationflash_attention_2启用 flash attention 加速use_safetensorsTrue更安全。model.eval().cuda().to(torch.bfloat16)三步不能少bfloat16 精度在 OCR 任务上损失很小但显存省一半。4.2 端到端验证动作跑完推理后对比验证分三步第一步检查输出目录是否生成 Markdown 文件内容是否包含表格结构。如果表格变成纯文本说明提示词没带|grounding|。第二步用同一张图分别跑 Gundam 和 Base 模式对比识别结果。Gundam 在多列文档上应该保留列顺序Base 可能串行。第三步看test_compressTrue时打印的压缩比和视觉 token 数。正常 Gundam 模式单页消耗 100-800 视觉 token超过 1000 说明裁剪区域过多考虑降MAX_CROPS。4.3 成功结果判断标准识别成功的标志Markdown 标题层级正确、表格用|分隔、公式用 LaTeX 包裹、图片位置有占位符。如果输出全是乱码或重复字符检查SKIP_REPEAT是否被关掉或者提示词是否匹配文档类型。5. DeepSeek-OCR 部署常见报错排查5.1 401 Unauthorized 与 local proxy failed如果走远程 API 网关报 401先确认 Key 是否过期、Base URL 是否带/v1后缀。local proxy failed通常是本地 vLLM 服务没起来用curl http://localhost:8000/v1/models测一下。服务没起就检查启动命令里的--model路径是否正确。5.2 reading choices 报错Error reading choices一般出现在 OpenAI 兼容接口返回格式不对时。vLLM 0.8.5 的返回结构是choices[0].message.content如果客户端按choices[0].text解析就会报这个。检查客户端版本或者手动 curl 看返回 JSON 结构。5.3 OAuth 与鉴权失败OAuth 报错多见于走云端网关的场景。本地 vLLM 不需要 OAuth如果配置里带了 OAuth 相关字段删掉。远程网关的 OAuth 流程按对应平台文档走别把本地配置直接搬过去。5.4 CUDA out of memory最常見的报错。处理顺序先降MAX_CONCURRENCY到 30再降MAX_CROPS到 4还不行就切 Base 模式CROP_MODEFalse。如果单张图就 OOM说明BASE_SIZE设太大降到 640。5.5 flash-attn 导入失败ImportError: undefined symbol基本是 flash-attn 和 torch 版本不匹配。torch 2.6.0 必须配 flash-attn 2.7.3装的时候加--no-build-isolation避免 pip 重新拉 torch。5.6 模型加载卡住trust_remote_codeTrue首次加载会下载自定义代码网络慢会卡住。提前把模型权重下到本地MODEL_PATH改成绝对路径。如果卡在Loading safetensors检查磁盘 IO模型文件约 6G。6. 推理后端选型与接入建议vLLM 和 Transformers 两条链路各有适用场景。批量 PDF 处理、需要高吞吐走 vLLMMAX_CONCURRENCY拉满A100-40G 能到 2500 tokens/s。单图调试、提示词调优、小批量验证走 Transformers代码直观改起来快。如果要把 OCR 能力接进现有工作流比如 Cline、Codex 这类编码 Agent建议用 vLLM 的 OpenAI 兼容接口做一层封装。Base URL 指向本地服务Model ID 填deepseek-ai/DeepSeek-OCRKey 本地随便填。这样 Agent 调 OCR 和调普通 LLM 的代码路径一致不用改客户端逻辑。长期跑批量任务的话Coding Plan 这类按量计费的方式比自建 GPU 更省心尤其是不想维护 CUDA 环境和显存调度的时候。模型对话入口可以用来快速验证提示词效果不用每次都起服务。接入文档里有完整的 API 参数说明API Keys 页面能拿到调用凭证。实测下来Gundam 模式在复杂排版文档上的表现明显好于 Base但显存占用也高。如果文档以单列纯文本为主Base 模式性价比更高。提示词里带|grounding|是保留布局的关键去掉之后表格和标题层级会丢。flash-attn 编译那步最容易卡住建议单独跑一次构建确认成功再继续后面的步骤。