DeepSeek-OCR-2¶

1 简介¶

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

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

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

2 支持的特性¶

请参阅支持的特性列表获取模型支持的特性矩阵。

请参阅特性指南获取特性的配置方法。

3 前提条件¶

3.1 模型权重¶

DeepSeek-OCR-2：下载模型权重。

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

3.2 验证多节点通信¶

如果要部署多节点环境，需要按照验证多节点通信环境验证多节点通信。

4 安装¶

4.1 Docker 镜像安装¶

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

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

A2 系列A3 series

export IMAGE=m.daocloud.io/quay.io/ascend/vllm-ascend:v0.22.1rc1
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.22.1rc1
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

If you want to deploy multi-node environment, you need to set up environment on each node.

5 Online Service Deployment¶

5.1 Single-Node Online Deployment¶

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

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

#!/bin/sh

export VLLM_USE_V1=1
export VLLM_ASCEND_ENABLE_NZ=0
export TOKENIZERS_PARALLELISM=false
export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export TASK_QUEUE_ENABLE=1
export TOKENIZERS_PARALLELISM=false

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 '{
      "enable_cpu_binding": true,
      "multistream_overlap_shared_expert": true,
      "ascend_compilation_config": {"fuse_qknorm_rope": false}
    }' \
    --mm-processor-cache-gb 0

Notice: The parameters are explained as follows:

--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 预填充-解码分离部署¶

我们不需要预填充-解码分离部署

6 功能验证¶

如果服务启动成功，您将看到如下所示的信息：

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

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

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 精度评估¶

使用 AISBench¶

详细信息请参考使用 AISBench 进行精度评估。
执行后即可获得结果，以下是 DeepSeek-OCR-2 的结果，仅供参考。

数据集	版本	指标	模式	vllm-api-生成eral-chat	备注
textvqa	-	准确率	生成	50.28	1 台 Atlas 800 A2
ominidocbench	-	准确率	生成	66.86	1 台 Atlas 800 A2

8 性能评估¶

使用 AISBench¶

详细信息请参考使用 AISBench 进行性能评估。

性能结果如下：

硬件：A2-313T，1 节点

输入/输出：1080P/256

性能：TTFT = 2 秒，TPOT = 200 毫秒，每卡平均性能为 864 TPS（每秒处理 Token 数）。

9 性能调优¶

9.1 推荐配置¶

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

表1：场景概览¶

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

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

9.2 调优指南¶

9.2.1 通用调优参考¶

请参阅公共性能调优文档了解调优方法。

请参阅特性指南获取详细的特性描述。

10 常见问题¶

For common environment, installation, and 生成eral parameter issues, please refer to the Public FAQ.

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

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

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

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