DeepSeek-OCR 本地部署：使用 vLLM 构建 OCR API 服务

# 创建项目目录
mkdir -p ~/projects/deepseek-ocr
cd ~/projects/deepseek-ocr

# 使用 uv 创建虚拟环境
uv venv --python 3.12

# 激活虚拟环境
source .venv/bin/activate

# 安装 vLLM
uv pip install vllm

# 设置镜像环境变量
export HF_ENDPOINT=https://hf-mirror.com

# 使用 hf 命令下载模型（推荐）
hf download deepseek-ai/DeepSeek-OCR --local-dir ./DeepSeek-OCR

cd ~/projects/deepseek-ocr
source .venv/bin/activate

vllm serve ./DeepSeek-OCR \
    --served-model-name deepseek-ocr \
    --host 0.0.0.0 \
    --port 8100 \
    --trust-remote-code \
    --gpu-memory-utilization 0.35 \
    --max-model-len 2048 \
    --max-num-seqs 64 \
    --api-key <YOUR_API_KEY>

sudo vim /etc/systemd/system/deepseek-ocr.service

[Unit]
Description=DeepSeek-OCR vLLM Service
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/home/$USER/projects/deepseek-ocr
Environment="PATH=/home/$USER/projects/deepseek-ocr/.venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/home/$USER/projects/deepseek-ocr/.venv/bin/vllm serve /home/$USER/projects/deepseek-ocr/DeepSeek-OCR \
    --served-model-name deepseek-ocr \
    --host 0.0.0.0 \
    --port 8100 \
    --trust-remote-code \
    --gpu-memory-utilization 0.35 \
    --max-model-len 2048 \
    --max-num-seqs 64 \
    --api-key <YOUR_API_KEY>
Restart=on-failure
RestartSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable deepseek-ocr
sudo systemctl start deepseek-ocr

# 查看服务状态
sudo systemctl status deepseek-ocr

# 查看日志
journalctl -u deepseek-ocr -f

{
  "candidate_resolutions": [[1024, 1024]],
  "patch_size": 16,
  "downsample_ratio": 4,
  ...
}

# 编辑配置文件
vim ~/projects/deepseek-ocr/DeepSeek-OCR/processor_config.json

sudo systemctl restart deepseek-ocr

vllm serve ./DeepSeek-OCR --served-model-name deepseek-ocr ...

# Gundam 模式配置
BASE_SIZE = 1024
IMAGE_SIZE = 640
CROP_MODE = True  # 启用裁剪
MIN_CROPS = 2
MAX_CROPS = 6

if image.size[0] <= 640 and image.size[1] <= 640:
    crop_ratio = [1, 1]  # 小图不裁剪
else:
    if cropping:  # CROP_MODE = True 时启用
        images_crop_raw, crop_ratio = dynamic_preprocess(
            image, image_size=IMAGE_SIZE)  # 本地裁剪
    else:
        crop_ratio = [1, 1]

def dynamic_preprocess(image, min_num=MIN_CROPS, max_num=MAX_CROPS,
                       image_size=640, use_thumbnail=False):
    orig_width, orig_height = image.size
    aspect_ratio = orig_width / orig_height

    # 根据图片宽高比，计算最优网格布局（如 2x3 = 6 个 tiles）
    target_ratios = set(
        (i, j) for n in range(min_num, max_num + 1)
        for i in range(1, n + 1) for j in range(1, n + 1)
        if i * j <= max_num and i * j >= min_num)

    # 调整大小后裁剪成多个 640x640 的块
    resized_img = image.resize((target_width, target_height))
    for i in range(blocks):
        box = (...)  # 计算每个 tile 的坐标
        split_img = resized_img.crop(box)
        processed_images.append(split_img)

    return processed_images, target_aspect_ratio

原始大图 → Python 本地裁剪成多个 640x640 tiles → 每个 tile 单独编码 → 传给 vLLM 引擎

# 修改模型配置为 large 模式
vim ~/projects/deepseek-ocr/DeepSeek-OCR/processor_config.json
# 将 "candidate_resolutions": [[1024, 1024]] 改为 "candidate_resolutions": [[1280, 1280]]

# 重启服务
sudo systemctl restart deepseek-ocr

import base64
from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key="<YOUR_API_KEY>",  # 使用启动服务时设置的 API key
    base_url="http://localhost:8100/v1"
)

def ocr_image(image_path: str) -> str:
    """对图片进行 OCR 识别，返回 Markdown 格式文本"""

    # 读取并编码图片
    with open(image_path, "rb") as f:
        image_data = base64.b64encode(f.read()).decode("utf-8")

    # 根据文件扩展名确定 MIME 类型
    ext = image_path.lower().split(".")[-1]
    mime_type = {
        "png": "image/png",
        "jpg": "image/jpeg",
        "jpeg": "image/jpeg",
        "gif": "image/gif",
        "webp": "image/webp"
    }.get(ext, "image/png")

    # 调用 API
    response = client.chat.completions.create(
        model="deepseek-ocr",
        messages=[
            {
                "role": "user",
                "content": [
                    # 图片必须放在第一个位置
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": f"data:{mime_type};base64,{image_data}"
                        }
                    },
                    # 使用 grounding prompt
                    {
                        "type": "text",
                        "text": "<|grounding|>Convert the document to markdown."
                    }
                ]
            }
        ],
        max_tokens=2048
    )

    return response.choices[0].message.content

# 使用示例
if __name__ == "__main__":
    result = ocr_image("./test_document.png")
    print(result)

# 将图片转换为 base64
IMAGE_BASE64=$(base64 -w 0 test_document.png)

curl -X POST http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "model": "deepseek-ocr",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,'$IMAGE_BASE64'"
            }
          },
          {
            "type": "text",
            "text": "<|grounding|>Convert the document to markdown."
          }
        ]
      }
    ],
    "max_tokens": 2048
  }'