GLM-OCR API调用教程:如何用OpenAI接口在昇腾上实现中英文OCR识别

原创2026-10-29 20:54:501,717 阅读
文章标签:大模型计算机视觉后端

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 识别,最快十几分钟即可在昇腾上完成部署。祝你顺利上手!

登录后查看全文
glm-ocr