GLM-OCR API调用教程:如何用OpenAI接口在昇腾上实现中英文OCR识别
GLM-OCR API调用教程:如何用OpenAI接口在昇腾上实现中英文OCR识别
本 GLM-OCR API 调用教程带你完成完整流程:在华为昇腾 NPU 上部署 GLM-OCR 视觉语言模型,通过 OpenAI 兼容接口调用,几行代码即可实现中英文 OCR 文字识别。无需修改业务代码,原有 OpenAI 客户端只需改一个 base_url 就能接入国产算力。
一、GLM-OCR 是什么?为什么选择昇腾部署
GLM-OCR 是一个视觉语言(VL)模型,架构名为 GlmOcrForConditionalGeneration,主打"看图识字":你发一张图片给它,它把图中的中英文文字、数字、特殊字符按行识别输出。
本项目 glm-ocr 提供了在 华为昇腾 NPU 上运行 GLM-OCR 的完整方案:基于 vLLM + vLLM-Ascend 推理框架,通过定制补丁让框架原生支持该模型,并暴露标准的 OpenAI 兼容 API(/v1/chat/completions、/v1/models),让你像调用大模型 API 一样做 OCR。
模型关键参数一览(详见 README.md):
| 项目 | 详情 |
|---|---|
| 模型大小 | 2.9 GB(单文件 safetensors) |
| 数据精度 | BFloat16 |
| 最大上下文 | 131,072 tokens |
| 图像分辨率 | 336 × 336 |
| MTP 推测解码 | 内置 1 层,可加速生成 |
💡 2.9 GB 的体积意味着显存需求友好,Ascend 910 单芯片 64 GB HBM 加载后仅占约 59 GB,实测服务稳定。
二、项目文件速览:补丁与文档在哪里
| 文件 | 作用 |
|---|---|
| 0001-vllm-glm-ocr-v0.17.patch | vLLM 侧模型支持补丁(v0.17 版本) |
| 0002-vllm-ascend-glm-ocr-v0.17.patch | vLLM-Ascend 侧 MTP 支持补丁(v0.17 版本) |
| GLM-OCR-model-support-vllm.patch | 旧版 vLLM 模型支持补丁(v0.14 镜像适用) |
| GLM-OCR-MTP-support-vllm-ascend.patch | 旧版 vLLM-Ascend MTP 补丁(v0.14 镜像适用) |
| README.md | 完整测试报告:环境、功能测试、性能基准 |
| README-patch.md | 补丁应用与启动服务的最短路径文档 |
补丁的核心内容(见 GLM-OCR-model-support-vllm.patch):
- 新增
GlmOcrForConditionalGeneration模型实现与GlmOcrConfig配置类; - 注册模型到 vLLM 模型注册表与配置注册表;
- 支持 MTP(Multi-Token Prediction)推测解码与 ACL Graph 优化;
- 处理 tokenizer 类名未知等兼容性问题——无需修改模型配置。
三、环境准备:镜像与依赖版本
🐳 推荐直接使用官方 Docker 镜像:
quay.io/ascend/vllm-ascend:v0.14.0rc1
实测通过的软件环境(见 README.md):
| 组件 | 版本 |
|---|---|
| vLLM / vLLM-Ascend | 0.17.0rc1(含 GLM-OCR 定制补丁) |
| PyTorch / torch-npu | 2.9.0 |
| CANN | 8.5.0 |
| Transformers | 4.57.6 |
| Python | 3.11.14 |
⚠️ 补丁与框架版本强绑定:v0.14 镜像用
GLM-OCR-*开头的旧补丁,v0.17 框架用0001/0002-*补丁,注意匹配。
四、打补丁:三步给 vLLM 装上 GLM-OCR 支持
先拉取本项目获取补丁文件:
git clone https://gitcode.com/Ascend-SACT/glm-ocr
然后分别给 vLLM 和 vLLM-Ascend 打补丁(以 v0.17 为例,参考 README.md):
cd /vllm-workspace/vllm
git apply /path/to/glm-ocr/0001-vllm-glm-ocr-v0.17.patch
cd /vllm-workspace/vllm-ascend
git apply /path/to/glm-ocr/0002-vllm-ascend-glm-ocr-v0.17.patch
使用旧版镜像时,改打下面两个补丁即可(参考 README-patch.md):
cd /vllm-workspace/vllm
git am /path/to/glm-ocr/GLM-OCR-model-support-vllm.patch
cd /vllm-workspace/vllm-ascend
git am /path/to/glm-ocr/GLM-OCR-MTP-support-vllm-ascend.patch
打完后框架即识别 GlmOcrForConditionalGeneration 架构,模型配置无需任何改动。
五、一键启动 GLM-OCR 推理服务
模型放到 /models/GLM-OCR 后,执行以下启动命令(推荐配置,见 README-patch.md):
cd /workspace
HCCL_OP_EXPANSION_MODE=AIV vllm serve /models/GLM-OCR \
--trust-remote-code \
--speculative-config '{"method":"mtp","num_speculative_tokens":1}'
参数说明:
HCCL_OP_EXPANSION_MODE=AIV:启用 HCCL 集合通信 AIV 模式,多模态场景首 Token 延迟(TTFT)可降低 42% 以上,生产环境建议常开(环境变量说明见 README.md);--speculative-config:开启模型自带的 MTP 推测解码,每次多猜 1 个 token,纯文本场景接受率可达 75%~80%;- 需要控制内存或延迟时,可追加
--max-num-seqs 64限制并发。
服务默认监听 http://localhost:8000。
六、验证服务:先查模型再调接口
启动后先确认模型加载成功,调用 /v1/models 接口(实测返回,见 README.md):
curl http://localhost:8000/v1/models
能返回 {"id":"/models/GLM-OCR", ...} 即就绪,max_model_len 为 131,072。
七、OpenAI 接口调用:curl 与 Python 两种方式
方式一:curl 直接调 HTTP 接口
把图片转成 base64,放进 image_url 字段(data URI 格式):
IMG_B64=$(base64 -w0 test.png)
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "/models/GLM-OCR",
"messages": [{"role": "user", "content": [
{"type": "text", "text": "请识别图片中的所有文字"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,YOUR_B64"}}
]}],
"max_tokens": 512
}'
返回结构与 OpenAI Chat Completions 完全一致,识别结果在 choices[0].message.content 中。
方式二:Python openai SDK(推荐)
from openai import OpenAI
import base64
client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
with open("image.png", "rb") as f:
img_b64 = base64.b64encode(f.read()).decode()
resp = client.chat.completions.create(
model="/models/GLM-OCR",
messages=[{
"role": "user",
"content": [
{"type": "image_url",
"image_url": {"url": f"data:image/png;base64,{img_b64}"}},
{"type": "text", "text": "请识别图片中的所有文字"}
]
}],
max_tokens=512,
)
print(resp.choices[0].message.content)
这段代码见 README-patch.md,把 base_url 从云端换成昇腾本地地址,业务代码零改造。
纯文本对话也支持
不传图片时,它就是一个普通文本模型(见 README.md):
resp = client.chat.completions.create(
model="/models/GLM-OCR",
messages=[{"role": "user", "content": "你能做什么?"}],
max_tokens=256,
)
print(resp.choices[0].message.content)
八、中英文 OCR 识别效果参考
项目实测的功能测试结论(完整用例见 README.md):
| 测试项 | 结果 | 备注 |
|---|---|---|
| 服务启动与模型加载 | ✅ 通过 | MTP 推测解码正常启用 |
| 英文 + 数字 OCR | ✅ 通过 | Hello World! / 12345 全部准确识别 |
| 特殊字符 OCR | ⚠️ 基本通过 | 邮箱地址完整识别;价格小数点处偶发数字重复 |
| Vision API(base64) | ✅ 通过 | 图像编码传输正常 |
| 纯文本对话 | ✅ 通过 | 响应流畅、语义正确 |
💡 小贴士:OCR 提示词用"请识别图片中的所有文字"这类明确指令效果最佳;识别结果按图片中的行顺序输出,方便后续解析。
九、性能速览:昇腾 910 实测有多快
在 Ascend 910 + MTP + AIV 优化下的实测数据(见 README-patch.md 与 README.md):
| 场景 | 输出吞吐 | 中位 TTFT | MTP 接受率 |
|---|---|---|---|
| 多模态(2 RPS) | ~206 tok/s | 2.8 s | 65% |
| 纯文本(5 RPS) | ~1,070 tok/s | 44 ms | 80% |
| 压力测试(100 并发) | ~3,190 tok/s | 1.9 s | 75% |
极限压力下峰值输出吞吐可达 5,000 tok/s,170 个请求零失败。对 OCR 这类"短输出"业务,延迟表现非常友好。
十、常见问题 FAQ
Q1:启动时提示不识别模型架构? 确认补丁已打在正确目录(vLLM 与 vLLM-Ascend 各一个),且补丁版本与框架版本匹配,参考 README-patch.md 的补丁清单。
Q2:多模态场景 MTP 接受率只有 65%,是不是坏了? 不是。图像 token 经过视觉编码后与文本 token 表征不同,多模态场景接受率偏低属正常现象(分析见 README.md)。
Q3:价格、邮箱等小数内容识别有轻微偏差怎么办?
实测中 $199.99 这类内容可能出现小数位重复,属已知轻微偏差,主体内容识别正确;对精度要求极高的场景建议配合业务侧正则校验。
Q4:需要限制并发吗?
追求最大吞吐可不加限制;要控制 HBM 占用或保证低延迟,加 --max-num-seqs 64(见 README.md)。
十一、延伸阅读
- 完整测试环境与性能基准:README.md
- 补丁应用与服务启动最短路径:README-patch.md
- 压测命令参考(
vllm bench serve):README.md - 功能测试代码(Python 完整示例):README.md
按本文步骤,从打补丁到跑通第一张中英文 OCR 识别,最快十几分钟即可在昇腾上完成部署。祝你顺利上手!