GLM-OCR完全指南:在华为昇腾NPU上部署视觉OCR大模型的完整路线图
GLM-OCR完全指南:在华为昇腾NPU上部署视觉OCR大模型的完整路线图
本指南面向新手,手把手教你用 vLLM + vLLM-Ascend 推理框架,将轻量级视觉 OCR 大模型 GLM-OCR 部署到华为昇腾 NPU 上,并完成图像文字识别服务。全程只需 5 个步骤:准备环境、应用补丁、一条命令启动服务、验证 OCR 效果、开启性能优化。仓库已内置现成的补丁文件和一份 170 个请求零失败的完整实测报告,照着做即可。
GLM-OCR 是什么?
GLM-OCR 是一个面向图像文字识别的视觉语言大模型(Vision-Language Model),它能看懂图片中的文字并输出结构化文本,同时支持纯文本对话。它的几个核心特点,决定了它非常适合用 NPU 做低成本批量部署:
| 特性 | 参数 | 说明 |
|---|---|---|
| 模型体积 | 约 2.9 GB | 单文件 safetensors,加载快 |
| 图像分辨率 | 336 × 336 | 输入小,推理开销低 |
| 上下文长度 | 131,072 tokens | 长文档识别无压力 |
| 位置编码 | M-RoPE | 专为多模态设计的多维旋转位置编码 |
| 数据精度 | BFloat16 | 单卡 HBM 占用约 59 GB |
| MTP 层 | 1 层 | 原生支持推测解码,无需额外 draft 模型 |
一句话总结:模型小、识别快、原生支持 MTP 推测解码,是昇腾平台上跑 OCR 业务的理想选择。
部署路线图总览
整个部署路径可以概括为 5 步,下面逐节展开:
- 📦 环境准备:确认 NPU 与软硬件版本
- 🔧 应用补丁:让 vLLM 和 vLLM-Ascend 认识 GLM-OCR
- 🚀 启动服务:一条
vllm serve命令拉起推理服务 - ✅ 效果验证:文本对话 + 图像 OCR 双重测试
- ⚡ 性能调优:MTP 推测解码 + HCCL AIV 模式
第一步:环境准备——硬件与软件清单
在动手之前,先对照下表确认你的环境(数据来源为仓库实测报告):
硬件要求
| 项目 | 详情 |
|---|---|
| NPU 型号 | Ascend 910 |
| 芯片数量 | 16 芯片(8 卡 × 2 芯片)或 8 芯片(8 卡 × 1 芯片) |
| 单芯片 HBM | 65,536 MB(64 GB) |
软件要求
| 组件 | 版本 |
|---|---|
| vLLM | 0.17.0rc1(含 GLM-OCR 定制补丁) |
| vLLM-Ascend | 0.17.0rc1(含 MTP 补丁) |
| PyTorch / torch-npu | 2.9.0 |
| CANN | 8.5.0 |
| Transformers | 4.57.6 |
| Python | 3.11.14 |
| 操作系统 | openEuler 22.03(aarch64) |
💡 如果不想手动装环境,可直接使用官方推理镜像
quay.io/ascend/vllm-ascend(版本见 README-patch.md),再按下面步骤打补丁即可。
模型文件需要提前放到本地目录(测试环境放在 /models/GLM-OCR)。
第二步:一键打补丁——让 vLLM 认识 GLM-OCR
GLM-OCR 是新架构,原版 vLLM 并不认识它。好消息是:仓库提供了现成的官方补丁,全部兼容性修复都在 vLLM 侧完成,无需修改模型配置文件。
先克隆本仓库获取补丁文件:
git clone https://gitcode.com/Ascend-SACT/glm-ocr
v0.17 版本需要应用两个补丁(详见 README-patch.md):
cd /vllm-workspace/vllm
git apply /path/to/0001-vllm-glm-ocr-v0.17.patch
cd /vllm-workspace/vllm-ascend
git apply /path/to/0002-vllm-ascend-glm-ocr-v0.17.patch
两个补丁分别解决什么问题?
| 补丁文件 | 作用对象 | 核心内容 |
|---|---|---|
| 0001-vllm-glm-ocr-v0.17.patch | vLLM | 模型实现、配置注册、MTP 支持、tokenizer 回退加载,并附带 M-RoPE 位置编码单元测试 |
| 0002-vllm-ascend-glm-ocr-v0.17.patch | vLLM-Ascend | 修复 NPU 上 M-RoPE 旋转位置编码的数据类型与旋转模式,并将 GLM-OCR 加入 MTP 推测解码的多模态模型白名单 |
仓库中另有面向 v0.14 版本的两份早期补丁 GLM-OCR-model-support-vllm.patch 和 GLM-OCR-MTP-support-vllm-ascend.patch,如果镜像是
v0.14.0rc1,用这一对即可。
第三步:一条命令启动 OCR 推理服务
补丁打完后,推荐使用如下命令启动服务(含 HCCL AIV 优化 + MTP 推测解码):
cd /workspace
HCCL_OP_EXPANSION_MODE=AIV vllm serve /models/GLM-OCR \
--trust-remote-code \
--speculative-config '{"method":"mtp","num_speculative_tokens":1}'
参数说明(新手重点看这里):
--trust-remote-code:信任模型自带的代码,多模态模型加载必需--speculative-config:开启 MTP 推测解码,每次额外推测 1 个 tokenHCCL_OP_EXPANSION_MODE=AIV:启用昇腾集合通信的 AI Vector 模式,显著降低首 token 延迟- 如需限制并发、控制显存,可再加
--max-num-seqs 64
服务默认监听 8000 端口。启动后访问 GET http://localhost:8000/v1/models,能看到模型 ID 与 max_model_len: 131072,即代表加载成功。
第四步:验证效果——文本对话与图像识别实测
服务起来后,仓库测试报告(README.md)中给出了完整的功能验证结论,供你对照自查:
| 测试项 | 结果 | 备注 |
|---|---|---|
| 服务启动与模型加载 | ✅ 通过 | MTP 推测解码正常启用 |
| 纯文本对话 | ✅ 通过 | 响应流畅、语义正确 |
| 英文 + 数字 OCR | ✅ 通过 | 如 "Hello World! / 12345" 全部准确识别 |
| 特殊字符 OCR | ⚠️ 基本通过 | 邮箱、价格可识别,小数点后偶有轻微数字重复 |
| Vision API(base64 传图) | ✅ 通过 | 图像编码传输正常 |
OCR 调用与调用普通多模态大模型完全一致:走 OpenAI 兼容的 Chat Completions API,content 里放 image_url(base64 data URI)加一句"请识别图片中的所有文字"即可,完整示例代码见 README-patch.md 的 Test 部分。
第五步:性能调优——MTP 推测解码与 AIV 模式实测
这是昇腾部署最有价值的部分:两项优化叠加后,极限压力下峰值输出吞吐可达 5,000 tok/s,纯文本场景首 token 延迟低至 44 ms。
MTP 推测解码效果(模型原生 1 层 MTP,无需额外 draft 模型):
| 测试场景 | MTP 接受率 | 说明 |
|---|---|---|
| 多模态(2 RPS) | 65.2% | 图像 token 预测难度更高,属正常现象 |
| 纯文本(中负载) | 79.9% | 文本预测质量高 |
| 纯文本(压力测试) | 75.3% | 平均接受长度 1.75,等效加速约 70-80% |
HCCL AIV 模式效果(HCCL_OP_EXPANSION_MODE=AIV):
| 场景 | 首 token 延迟 (TTFT) 变化 | 适用建议 |
|---|---|---|
| 多模态(低负载) | -42%(4.6s → 2.7s) | ✅ 推荐启用 |
| 纯文本(中负载) | +8%(毫秒级变化) | ⚠️ 基本持平 |
| 极限压力测试 | -56%(4.4s → 1.9s) | ✅ 推荐启用 |
性能总览(AIV 优化配置,Ascend 910):
| 场景 | 输出吞吐 | TTFT(中位数) |
|---|---|---|
| 多模态(2 RPS) | ~206 tok/s | 2.8 s |
| 纯文本(5 RPS) | ~1,070 tok/s | 44 ms |
| 压力测试(100 并发) | ~3,190 tok/s | 1.9 s |
详细数据(含 170 个请求全部成功的稳定性评估、HBM 与温度监控)见 README.md 的性能基准章节。
生产环境配置建议
结合实测结论,给出 4 条可直接照抄的建议:
- 始终启用 AIV 模式:对多模态和高并发场景收益最大,中负载场景代价可忽略
- 按需限制并发:要低延迟/控内存就加
--max-num-seqs 64;要最大吞吐则去掉 - 保持 MTP 默认配置:
num_speculative_tokens=1已足够,多模态接受率偏低无需调参 - 关注 HBM 水位:模型主芯片占用约 59 GB / 64 GB,同卡混部其他模型时要预留空间
延伸阅读:项目文件导航
| 文件 | 用途 |
|---|---|
| README.md | 完整测试报告:环境、功能、性能、稳定性、压测命令与功能测试代码 |
| README-patch.md | 补丁应用说明、启动命令、测试与基准测试脚本 |
| 0001-vllm-glm-ocr-v0.17.patch | vLLM v0.17 GLM-OCR 模型支持补丁 |
| 0002-vllm-ascend-glm-ocr-v0.17.patch | vLLM-Ascend v0.17 M-RoPE 与 MTP 适配补丁 |
| GLM-OCR-model-support-vllm.patch | vLLM v0.14 模型支持补丁(ACL Graph 优化 + MTP) |
| GLM-OCR-MTP-support-vllm-ascend.patch | vLLM-Ascend v0.14 MTP 位置处理补丁 |
按照这份路线图走下来,你只需要"打补丁 + 一条启动命令",就能在华为昇腾 NPU 上拥有一个吞吐 5,000 tok/s 的 GLM-OCR 视觉识别服务。动手试试吧!