DeepSeek-OCR-2 昇腾 NPU 部署指南从 vLLM-Ascend 镜像到单卡批量 OCR 识别【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer如果你手上有 Atlas 800I/T A2 服务器需要把 DeepSeek-OCR-2 跑在昇腾 NPU 上把扫描版文档、PDF、照片里的文字转成结构化 Markdown这个项目能帮你省下最繁琐的移植环节它基于 vllm-ascend v0.8.5rc1 做了一套非侵入式适配一条脚本就能把 DeepSeek-OCR-2 官方代码改造成 NPU 可运行的版本再配上单图、PDF、批量评估三类入口脚本直接出结果。几个值得先知道的价值点MoE 前向用 vllm-ascend 原生fused_experts替换了 CUDA 实现不需要自己改模型代码补丁在 import 时自动挂载。适配采用拷贝加补丁的方式官方源码保持原样升级模型版本时只需重跑一次转换脚本。输出直接是 Markdown 格式单图流式、整份 PDF、目录批量评估三种粒度都有现成脚本。压测脚本内置并发档位可配方便你评估自己机型上的吞吐上限。适配改动集中在三个配置点上MoE 算子替换、注意力回退 SDPA、引擎参数ENFORCE_EAGERTrue、显存利用率 0.85排查问题时有明确范围。硬件与基础镜像先把环境门槛对齐这套方案在 Atlas 800I/T A2 上验证过机器配置按下面的底线准备即可项目要求昇腾设备Atlas 800I/T A2内存≥ 32GB磁盘≥ 50GB模型存储运行环境直接拉官方镜像版本是 vllm-ascend v0.8.5rc1 对应的 Docker 镜像docker pull quay.io/ascend/vllm-ascend:v0.8.5rc1 镜像里已装好 CANN 与 vllm-ascend你只需要关心模型权重和适配脚本两样东西。从创建容器到跑通第一条推理命令下面按实际操作时序走一遍每步都给出完整命令。第一步创建容器并挂载 NPU 设备docker run -it -d --nethost --shm-size512g \ --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两个挂载点需要特别留意/dev/davinci_manager、/dev/hisi_hdc、/dev/devmm_svm三个设备节点缺一不可否则 NPU 初始化会失败/data/model_weight:/data是宿主机模型目录到容器/data的映射后面的模型下载会落到这里。第二步下载模型权重容器内先装 modelscope再把权重拉到/data下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指定落盘路径后续配置文件里MODEL_PATH要指向这个目录。第三步拉取适配代码进入容器/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如果本地没有源码自动 clone DeepSeek-OCR-2 官方仓库把 NPU 补丁文件拷入目标目录输出生成在deepseek_ocr2_npu/目录脚本还会对拷贝出来的源码做三处定向修补注释掉sam_vary_sdpa.py里的flash_attn导入让注意力走 SDPA、向config.py追加 NPU 配置段DEVICEnpu、ENFORCE_EAGERTrue、MAX_MODEL_LEN8192、SWAP_SPACE0、TENSOR_PARALLEL_SIZE1、GPU_MEMORY_UTILIZATION0.85、DISABLE_MM_PREPROCESSOR_CACHETrue、在三个运行脚本里注入VLLM_USE_V10与 MoE 补丁 的导入并把enforce_eager改为 True、显存利用率统一调成 0.85。第五步修改配置文件cd deepseek_ocr2_npu # 初始化环境变量 source set_env.sh # 编辑 config.py 修改以下参数 vi config.py # - MODEL_PATH: 模型路径如 /data/models/DeepSeek-OCR-2 # - INPUT_PATH: 输入文件路径 # - OUTPUT_PATH: 输出文件路径set_env.sh 会设置ASCEND_TOOLKIT_HOME、LD_LIBRARY_PATH、PYTHONPATH以及VLLM_ATTENTION_BACKENDNPU、VLLM_USE_TRITON_FLASH_ATTN0、HCCL_WHITELIST_DISABLE1等 NPU 侧关键变量。每次新开 shell 都要先 source 一次再跑推理脚本。第六步运行推理# 图片流式输出 python run_dpsk_ocr2_image.py # PDF 处理 python run_dpsk_ocr2_pdf.py # 图片批量处理 python run_dpsk_ocr2_eval_batch.py⚠️ 用批量脚本时config.py里的输入图片路径要填图片文件夹而不是单个文件。压测命令与参数速查想在自己机型上复现吞吐数据用转换后的benchmark.pypython 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最大输出 token8192--gpu-mem显存利用率0.85--output结果输出文件benchmark_results.txt单张图片会被复制成 N 份来模拟并发请求所以跑出来的数字反映的是同一文档重复识别场景下的吞吐上限而不是真实多样数据的混跑结果。单卡性能实测吞吐随并发爬升64 并发后开始放缓以下为单卡测试数据并发数输出吞吐 (tokens/s)总吞吐 (tokens/s)140.5096.784106.50292.688212.52584.0232413.681136.8164486.621337.26100550.451512.68三点解读1→32 并发区间吞吐近乎线性增长单请求从 40.50 tokens/s 提到 413.68 tokens/s说明这个规模下 NPU 算力是富余的多请求摊薄了 prefill 开销。拐点出现在 64 并发总吞吐从 584.02 提到 1337.26 之后64→100 并发只再涨 12%1337.26 → 1512.68继续堆并发收益已经很有限单请求延迟会被明显拉长。如果你的业务是少量大文档低延迟选 8~32 并发档位如果是图片工厂批量转写压到 64~100 并发能拿到最高的绝对吞吐。适配原理浅析改了哪三处为什么这么改想排查问题或者二次开发需要知道 NPU 版本和官方 CUDA 版本的差异面有多大。全部改动就三块1. MoE 算子替换。DeepSeek-OCR-2 是 MoE 架构官方实现的fused_moe依赖 CUDA 核函数在 NPU 上不可用。deepseek_ocr2_npu.py 的做法是在 import 阶段从vllm_ascend.ops.fused_moe取fused_experts和select_experts先做专家选择softmax 打分、top-k 选择再调用 NPU 融合算子完成前向最后把结果函数直接覆盖回vllm.model_executor.layers.fused_moe.fused_moe。模型代码一行没动这就是非侵入的含义——代价是它强依赖 vllm-ascend 的接口签名升级 vllm-ascend 大版本时要确认这两个符号还在。2. 注意力走 SDPA。转换脚本把sam_vary_sdpa.py中的flash_attn导入行注释掉让视觉编码器SAM 系列的注意力回退到 SDPA 实现配合set_env.sh里的VLLM_ATTENTION_BACKENDNPU语言侧注意力也落到 NPU 后端。flash_attn 没有 NPU 版本这条回退是必须的。3. 引擎参数保守化。ENFORCE_EAGERTrue关掉 CUDA Graph 路径NPU 上对应机制未对齐先保证正确性gpu_memory_utilization0.85统一各脚本的显存水位并留 15% 余量给 KV cache 突发VLLM_USE_V10钉在 V0 引擎上SWAP_SPACE0和disable_mm_preprocessor_cacheTrue分别避免 NPU 上的换页开销和多模态缓存问题。项目结构一览与常见问题处理目录结构非常小每个文件干什么一目了然deepseek-ocr-2/ ├── convert_to_npu.sh # 一键转换脚本 ├── README.md ├── LICENSE └── npu_patch/ ├── benchmark.py # 性能压测脚本 ├── deepseek_ocr2_npu.py # NPU MOE 补丁 └── set_env.sh # 环境初始化convert_to_npu.sh 是整个流程的入口npu_patch/ 下的补丁文件会在转换阶段被拷贝进生成的deepseek_ocr2_npu/目录所以日常调试时改的是生成目录里的文件升级模型后重新跑脚本会覆盖掉你的改动。场景处理方式指定 NPU 设备export ASCEND_RT_VISIBLE_DEVICES0NPU 初始化失败检查docker run时三个设备节点/dev/davinci_manager、/dev/hisi_hdc、/dev/devmm_svm是否全部挂载提示 torch_npu 未找到确认容器由 vllm-ascend 官方镜像启动且已执行source set_env.shMoE 补丁未生效终端应打印[INFO] Ascend NPU MOE patch applied若看到 skip 警告检查 vllm-ascend 是否安装完整批量脚本无输出核对config.py中INPUT_PATH是否为图片文件夹路径参考资料DeepSeek-OCR-2本项目适配的模型MoE 多模态 OCR 架构vLLM推理引擎基础vLLM-AscendvLLM 的昇腾适配层MoE 补丁依赖其中的fused_moe实现SAMMeta视觉编码器组件Apache License 2.0许可证说明本项目采用 MIT License所集成的第三方组件包括 SAMApache License 2.0、DeepSeek-VL2MIT License、vLLMApache License 2.0二次分发时请一并保留相应声明。【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考