DeepSeek-OCR-2 昇腾 NPU 推理部署完整指南-平芜编程栈

DeepSeek-OCR-2 昇腾 NPU 推理部署完整指南

【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法，提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer

把一张文档图片变成干净的结构化 Markdown，这是 OCR 模型的看家本领。但 DeepSeek-OCR-2 原生是 CUDA 方案，直接搬到昇腾 NPU 上，第一步就会卡在算子上。这份指南带你在一台昇腾机器上把它完整跑通。

整个方案基于 vLLM-Ascend v0.8.5rc1：一个一键转换脚本，外加一组非侵入式补丁，不动模型源码，就能拿到一份开箱即用的 NPU 推理工程。

项目定位：它能帮你做什么

一句话：这是基于 vLLM-Ascend 的 DeepSeek-OCR-2 昇腾 NPU 推理适配方案。模型本身负责高精度文档 OCR 识别、输出 Markdown 格式结果；方案要解决的是它在 NPU 上"跑不了、跑不好"的问题——MOE 算子和注意力机制都被换成了 NPU 原生实现，源码一行不改。

你能拿它做的事：

丢进一张文档图片，流式吐出结构化 Markdown
整份 PDF 批处理，不用一页页手工翻
一个测试图片目录批量评估，快速检验识别效果
非侵入式适配：不碰上游代码，也不用懂模型内部结构
升级路径清晰：补丁独立存放，上游模型更新后重跑一次转换脚本即可

🚀 动手前：环境要求一览

硬件门槛就是一台昇腾 A2 机器，软件版本要求不多，一张表列全：

条目	具体要求
昇腾设备	Atlas 800I/T A2
内存	≥ 32GB
磁盘	≥ 50GB（存放模型权重）
推理框架	vLLM-Ascend v0.8.5rc1（有现成 docker 镜像）
Python	3.10+

从 0 到 1：昇腾 NPU 推理部署全流程

全程五步：环境 → 模型 → 适配 → 配置 → 启动。每一步只有几条命令，照着敲就行。

第 1 步 · 环境：一键拉取 NPU 推理镜像并启动容器

先拉官方镜像，CANN 工具链和 vLLM-Ascend 运行时都已在里面：

docker pull quay.io/ascend/vllm-ascend:v0.8.5rc1

再创建容器。注意把宿主机的/data/model_weight挂到容器/data，模型权重就放这里：

docker run -it -d --net=host --shm-size=512g \ --privileged \ --name ds-ocr-2 \ --device=/dev/davinci_manager \ --device=/dev/hisi_hdc \ --device=/dev/devmm_svm \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \ -v /usr/local/sbin:/usr/local/sbin:ro \ -v /data/model_weight:/data \ quay.io/ascend/vllm-ascend:v0.8.5rc1 /bin/bash

第 2 步 · 模型：下载 DeepSeek-OCR-2 权重到本地

装好 modelscope 后直接下载权重：

pip install modelscope -i https://mirrors.huaweicloud.com/repository/pypi/simple modelscope download --model deepseek-ai/DeepSeek-OCR-2 --local_dir /data/models/DeepSeek-OCR-2

两个参数：

--model：模型名称
--local_dir：模型存储路径

第 3 步 · 适配：一个脚本生成 NPU 推理工程

把 cann-recipes-infer 仓库放到容器/workspace下（或直接 clone），执行转换脚本：

cd /workspace git clone https://gitcode.com/cann/cann-recipes-infer.git cd cann-recipes-infer/integration/vllm/deepseek-ocr-2 ./convert_to_npu.sh

脚本会自动完成四件事：

安装 Python 依赖：einops、addict、easydict、triton-ascend、PyMuPDF、img2pdf
克隆 DeepSeek-OCR-2 源码
应用 NPU 适配补丁
输出到deepseek_ocr2_npu/目录

目录里真正关键的只有三个文件：convert_to_npu.sh（一键转换脚本）、npu_patch/deepseek_ocr2_npu.py（NPU MOE 补丁）、npu_patch/set_env.sh（环境初始化）。

第 4 步 · 配置：指定模型路径与输入输出

cd deepseek_ocr2_npu source set_env.sh vi config.py

set_env.sh负责初始化昇腾 NPU 环境变量；config.py里改三处即可：

MODEL_PATH：模型路径，如/data/models/DeepSeek-OCR-2
INPUT_PATH：输入文件路径
OUTPUT_PATH：输出文件路径

第 5 步 · 启动：按场景挑一个脚本

python run_dpsk_ocr2_image.py python run_dpsk_ocr2_pdf.py python run_dpsk_ocr2_eval_batch.py

三个脚本分别对应单图流式输出、PDF 处理、图片批量评估。注意：批量脚本要求config.py里的输入图片路径是图片文件夹，不是单个文件。

⚡ 跑起来：单卡性能实测

跑通之后，用自带的benchmark.py做并发压测：

python benchmark.py --image /path/to/image.jpg --concurrent 1,8,16 --warmup 2 --rounds 3

参数说明（括号内为默认值）：

参数	说明（默认值）
`--image`	图片文件或目录（必填）
`--concurrent`	并发数列表（1,8,16）
`--warmup`	预热轮数（2）
`--rounds`	测试轮数（5）
`--max-tokens`	最大输出 token（8192）
`--gpu-mem`	显存利用率（0.85）
`--output`	结果输出文件（benchmark_results.txt）