DeepSeek-OCR-2¶

1 简介¶

DeepSeekOCR2 是一个用于从以 LLM 为中心的视角研究视觉编码器作用的模型。

DeepSeek-OCR-2 模型首次在 vllm-ascend:v0.16.0 中受支持，并可在 v0.16.0 及更高版本中稳定运行。

本文档将展示该模型的主要验证步骤，包括支持的功能、功能配置、环境准备、单节点部署以及精度和性能评估。

2 支持的功能¶

请参阅支持的功能列表以获取模型支持的功能矩阵。

请参阅功能指南以获取功能的配置。

3 前提条件¶

3.1 模型权重¶

权重版本	下载链接
`DeepSeek-OCR-2`	Hugging Face

建议将模型权重下载到多节点共享目录，例如 /root/.cache/。

路径说明：将模型权重下载到您选择的目录并记录该目录。确保后续部署命令中的模型路径与该目录一致。

3.2 验证多节点通信¶

如果要部署多节点环境，您需要根据验证多节点通信环境验证多节点通信。

4 安装¶

4.1 Docker 镜像安装¶

您可以使用我们的官方 Docker 镜像直接运行 DeepSeek-OCR-2。

根据机器类型选择镜像，并在节点上启动 Docker 镜像，请参阅使用 Docker。

A2 系列A3 系列

export IMAGE=m.daocloud.io/quay.io/ascend/vllm-ascend:v0.23.0
export NAME=vllm-ascend

# Run the container using the defined variables
# Note: If you are running bridge network with docker, please expose available ports for multiple nodes communication in advance.
docker run --rm \
--name $NAME \
--net=host \
--shm-size=1g \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
--device /dev/davinci3 \
--device /dev/davinci4 \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /root/.cache:/root/.cache \
-it $IMAGE bash

export IMAGE=m.daocloud.io/quay.io/ascend/vllm-ascend:v0.23.0
export NAME=vllm-ascend

# Run the container using the defined variables
# Note: If you are running bridge network with docker, please expose available ports for multiple nodes communication in advance.
docker run --rm \
--name $NAME \
--net=host \
--shm-size=1g \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
--device /dev/davinci3 \
--device /dev/davinci4 \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
--device /dev/davinci8 \
--device /dev/davinci9 \
--device /dev/davinci10 \
--device /dev/davinci11 \
--device /dev/davinci12 \
--device /dev/davinci13 \
--device /dev/davinci14 \
--device /dev/davinci15 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /root/.cache:/root/.cache \
-it $IMAGE bash

如果要部署多节点环境，需要在每个节点上设置环境。

5 在线服务部署¶

5.1 单节点在线部署¶

DeepSeek-OCR-2 可以部署在 1 台 Atlas 800 A2 上。

运行以下脚本以执行在线推理。

#!/bin/sh

export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"

# Ensure the model path matches the directory recorded during download
vllm serve /root/.cache/DeepSeek-OCR-2 \
    --served-model-name deepseekocr2 \
    --trust-remote-code \
    --tensor-parallel-size 1  \
    --port 1055 \
    --max_model_len 8192 \
    --no-enable-prefix-caching \
    --gpu-memory-utilization 0.8 \
    --allowed-local-media-path / \
    --additional-config '{
      "weight_nz_mode": 0,
      "enable_cpu_binding": true,
      "multistream_overlap_shared_expert": true,
      "ascend_compilation_config": {"fuse_qknorm_rope": false}
    }' \
    --mm-processor-cache-gb 0

注意： 参数说明如下：

--max-model-len 指定最大上下文长度，即单个请求的输入和输出 Token 总数。
--no-enable-prefix-caching 表示已禁用前缀缓存。若要启用，请移除此选项。
--gpu-memory-utilization 表示 vLLM 用于实际推理的 HBM 比例。其核心功能是计算可用的 kv_cache 大小。在预热阶段（在 vLLM 中称为 profile run），vLLM 会记录输入大小为 --max-num-batched-tokens 的推理过程中的峰值 GPU 内存使用量。随后，可用的 kv_cache 大小按以下公式计算：--gpu-memory-utilization * HBM 大小 - 峰值 GPU 内存使用量。因此，--gpu-memory-utilization 的值越大，可使用的 kv_cache 越多。但是，由于预热阶段的 GPU 内存使用量可能与实际推理期间不同（例如，由于 EP 负载不均衡），将 --gpu-memory-utilization 设置得过高可能会导致实际推理期间出现 OOM（内存不足）问题。默认值为 0.9。

5.2 多节点部署¶

建议采用单节点部署。

5.3 Prefill-Decode 分离¶

无需进行 Prefill-Decode 分离。

6 功能验证¶

如果服务启动成功，您会看到如下信息：

INFO:     Started server process [87471]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

服务器启动后，您可以使用输入 Prompt 查询模型：

curl http://<node0_ip>:<port>/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "deepseekocr2",
        "prompt": "The future of AI is",
        "max_completion_tokens": 50,
        "temperature": 0
    }'

7 精度评估¶

7.1 使用 AISBench¶

详情请参见使用 AISBench。
执行完成后，您可以获取结果。以下为 DeepSeek-OCR-2 的结果，仅供参考。

数据集	版本	指标	模式	vllm-api-general-chat	备注
textvqa	-	accuracy	gen	50.28	1 Atlas 800 A2
omnidocbench	-	accuracy	gen	66.86	1 Atlas 800 A2

8 性能评估¶

8.1 使用 AISBench¶

详情请参见使用 AISBench 进行性能评估。

性能结果如下：

硬件：A2-313T，1 个节点

输入/输出：1080P/256

性能：TTFT = 2s，TPOT = 200ms，每张卡的平均性能为 864TPS（Token Per Second）。

9 性能调优¶

9.1 推荐配置¶

注意：以下配置已在特定测试环境中验证，仅供参考。最优配置取决于最大输入/输出长度、前缀缓存命中率、精度要求以及部署机器比例等因素。建议根据实际条件参考第 9.2 节进行调优。

表 1：场景概览¶

*Total NPUs 表示所有节点使用的 NPU 总数。1 个节点 = 1 台 Atlas 800 A3 服务器（64GB × 16 NPU）。

场景	部署模式	*NPU 总数	权重版本	关键考量
多模态 (1080P)	单节点混合	16 (A3)	deepseekocr2	dp1 tp1，适用于高分辨率视觉输入

9.2 调优指南¶

9.2.1 通用调优参考¶

调优方法请参见公共性能调优文档。

详细功能描述请参见功能矩阵。

10 常见问题¶

对于常见环境、安装和通用参数问题，请参见公共常见问题。

问：启动失败，出现 HCCL 端口冲突（地址已绑定）。我该怎么办？

答：清理旧进程并重启：pkill -f vLLM*。

问：如何处理 OOM 或启动不稳定？

答：首先降低 --max-num-seqs 和 --max-model-len。如有需要，降低并发和压测压力（例如 max-concurrency / num-prompts）。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 vl/vllm-ascend