部署说明

机房侧 RTX 5090 + vLLM ≥ 0.26 的安装、启动与接入 AI 网关说明。

项	值
工作目录	`/home/jlw/DS-ocr2`
Conda 环境	`deepseek-ocr-2`
默认 GPU	`1`
默认端口	`8202`
服务地址	`http://{ip:port}`

Windows WSL 通用安装参考（同目录、不进导航）：DeepSeek-OCR-2：Windows WSL 本地安装参考
5090 上不要套用官方旧组合 torch 2.6 + vllm 0.8.5 + cu118（会报 no kernel image）。

1. 环境要求

项目	要求
GPU	NVIDIA RTX 5090（sm_120 / Blackwell）
驱动	支持 CUDA 13.0（`nvidia-smi` 右上角 CUDA Version ≥ 13.0）
Python	3.12.x（推荐 3.12.9）
框架	vLLM ≥ 0.26 + torch==2.11.0+cu130（必须带 sm_120）

2. 一次性环境安装

bash

conda create -n deepseek-ocr-2 python=3.12.9 -y
conda activate deepseek-ocr-2

# 2.1 先装与 vLLM 匹配的 cu130 torch（以 dry-run 解析结果为准）
#    uv pip install -U vllm --torch-backend cu130 --dry-run
#    当前解析结果示例：torch==2.11.0+cu130
uv pip uninstall torch torchvision torchaudio triton -y 2>/dev/null || true
uv pip install torch==2.11.0+cu130 torchvision==0.26.0+cu130 torchaudio==2.11.0+cu130 \
  -f https://mirrors.aliyun.com/pytorch-wheels/cu130/ \
  -i https://mirrors.aliyun.com/pypi/simple/

# 2.2 再装 vLLM（钉死 torch，避免被 -U 换掉）
uv pip install vllm --torch-backend cu130 "torch==2.11.0"

# 2.3 业务依赖（注意：装 PyMuPDF，不要装 fitz）
uv pip uninstall fitz frontend -y 2>/dev/null || true
uv pip install PyMuPDF addict matplotlib easydict einops \
  fastapi "uvicorn[standard]" pydantic requests httpx Pillow numpy tqdm img2pdf

# 2.4（可选）解决 conda 与系统 libstdc++ 冲突
conda install -c conda-forge "libstdcxx-ng>=14" libgcc-ng -y

自检

bash

export LD_LIBRARY_PATH="${CONDA_PREFIX}/lib:${LD_LIBRARY_PATH:-}"
python - <<'PY'
import torch, vllm
print("torch", torch.__version__, "cuda", torch.version.cuda)
print("arch", torch.cuda.get_arch_list())
print("vllm", vllm.__version__)
print(torch.zeros(1, device="cuda"))
print("gpu", torch.cuda.get_device_name(0))
PY

arch 中应包含 sm_120 / 12.0，且 torch.zeros(..., device="cuda") 成功。

3. 模型权重

本地快照（已下载可直接用）：

text

/home/jlw/.cache/huggingface/hub/models--deepseek-ai--DeepSeek-OCR-2/snapshots/fdee390b3b35687ac6016795fb81c74c1af109ac

若缺失，用镜像拉取：

bash

export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=/home/jlw/.cache/huggingface
huggingface-cli download deepseek-ai/DeepSeek-OCR-2
# 或
python -c "from huggingface_hub import snapshot_download; print(snapshot_download('deepseek-ai/DeepSeek-OCR-2'))"

确认存在 config.json：

bash

ls /home/jlw/.cache/huggingface/hub/models--deepseek-ai--DeepSeek-OCR-2/snapshots/*/config.json

4. 代码要点（vLLM 0.26 内置模型）

不要再 ModelRegistry.register_model 旧版自定义 deepseek_ocr2.py。
使用 vLLM 内置 DeepSeek-OCR-2，并注意：

LLM(...) 不要传 swap_space（0.26 已删除）
SamplingParams 不要传 logits_processors（改为引擎级或 extra_args）
multi_modal_data["image"] 传 PIL.Image，不要传 tokenize_with_images 的结果
可删掉无效的 VLLM_USE_V1=0

推荐初始化片段：

python

from vllm import LLM, SamplingParams
from vllm.model_executor.models.deepseek_ocr import NGramPerReqLogitsProcessor

llm = LLM(
    model=MODEL_PATH,
    trust_remote_code=True,
    max_model_len=8192,
    max_num_seqs=10,
    tensor_parallel_size=1,
    gpu_memory_utilization=0.9,
    enable_prefix_caching=False,
    mm_processor_cache_gb=0,
    logits_processors=[NGramPerReqLogitsProcessor],
)

sampling_params = SamplingParams(
    temperature=0.0,
    max_tokens=8192,
    skip_special_tokens=False,
    include_stop_str_in_output=True,
    extra_args=dict(
        ngram_size=30,
        window_size=90,
        whitelist_token_ids={128821, 128822},
    ),
)

推理输入：

python

inputs = {
    "prompt": "<image>\n<|grounding|>Convert the document to markdown.",
    "multi_modal_data": {"image": image.convert("RGB")},
}
outputs = llm.generate(inputs, sampling_params)

5. 一键启动

bash

cd /home/jlw/DS-ocr2
chmod +x start_ocr2.sh
./start_ocr2.sh

常用参数：

bash

# 指定 GPU / 端口 / 后台
GPU_ID=1 PORT=8202 ./start_ocr2.sh

# 前台调试
FOREGROUND=1 GPU_ID=1 PORT=8202 ./start_ocr2.sh

# 停止
./start_ocr2.sh stop

健康检查：

bash

curl -sS http://127.0.0.1:8202/health
curl -sS http://{ip:port}/health

项	地址
接口文档	`http://{ip:port}/docs`
推理接口	`POST /infer`
默认日志	`/home/jlw/DS-ocr2/logs/ocr2_8202.log`

首次启动会做编译 / CUDA Graph，可能需数分钟。

6. 注册到 AI 网关（手动）

服务起来且 /health 正常后，在有集群权限的机器执行：

bash

kubectl -n ai-tools set env deploy/model-gateway EXTERNAL_MODELS_JSON='{
  "model-deepseek-ocr2": {
    "url": "http://{ip:port}",
    "health": "/health",
    "envelope": "flat"
  }
}'

项	值
命名空间	`ai-tools`
Deployment	`model-gateway`
模型名	`model-deepseek-ocr2`
上游	`http://{ip:port}`
健康路径	`/health`
响应封装	`flat`

若机器 IP / 端口变更，同步改 url 后再执行上述命令。

验证：

bash

kubectl -n ai-tools get deploy model-gateway -o wide
kubectl -n ai-tools rollout status deploy/model-gateway

7. 常见问题

现象	处理
`no kernel image` / sm_120 incompatible	换 `torch*+cu130`（含 sm_120），勿用 cu118/cu124 旧轮子
`import fitz` 进到 `frontend`	`uv pip uninstall fitz frontend && uv pip install PyMuPDF`
`CXXABI_1.3.15` not found	`export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH`
`Unexpected keyword argument 'swap_space'`	从 `LLM(...)` 删除该参数
`Unexpected keyword argument 'logits_processors'`（SamplingParams）	不要放在 SamplingParams；用 `LLM(logits_processors=[NGramPerReqLogitsProcessor])` + `extra_args`
`'list' object has no attribute 'size'`	`multi_modal_data` 传 PIL，不要传旧 `tokenize_with_images` 结果
HuggingFace 拉模型失败	`HF_ENDPOINT=https://hf-mirror.com` 或改用本地 `MODEL_PATH`
torch 被 vllm `-U` 重新下载	先 dry-run 看目标版本，再 `"torch==x.y.z"` 钉死

8. 目录约定

text

/home/jlw/DS-ocr2/
  ocr2_service.py      # HTTP 服务入口
  start_ocr2.sh        # 一键启停
  DEPLOY.md            # 本文档对应内容
  logs/                # 运行日志（脚本自动创建）
  process/             # 可选业务辅助代码

模型缓存默认在：

text

/home/jlw/.cache/huggingface/hub/models--deepseek-ai--DeepSeek-OCR-2/

K3s

Docker

DeepSeek-OCR-2

小众问题

部署说明

1. 环境要求

2. 一次性环境安装

自检

3. 模型权重

4. 代码要点（vLLM 0.26 内置模型）

5. 一键启动

6. 注册到 AI 网关（手动）

7. 常见问题

8. 目录约定

部署说明 ​

1. 环境要求 ​

2. 一次性环境安装 ​

自检 ​

3. 模型权重 ​

4. 代码要点（vLLM 0.26 内置模型） ​

5. 一键启动 ​

6. 注册到 AI 网关（手动） ​

7. 常见问题 ​

8. 目录约定 ​

部署说明

1. 环境要求

2. 一次性环境安装

自检

3. 模型权重

4. 代码要点（vLLM 0.26 内置模型）

5. 一键启动

6. 注册到 AI 网关（手动）

7. 常见问题

8. 目录约定