GLM-OCR本地部署实战：显存估算、模型量化与vLLM服务化

简介：GLM-OCR开源大模型部署项目源码包，面向需要在资源受限环境下落地多模态OCR能力的开发者，尤其适合在单张T4显卡上实现低延迟的文本识别、表格还原与数学公式解析场景。压缩包共3个文件，包含一个inscode项目入口、一个HTML页面及一个gitignore配置，整体仅8KB，作为轻量级启动模板，HTML页可用于查看部署架构、性能指标和常见问题说明，inscode则帮助快速搭建运行环境。目前已有267人学习下载，其以极简结构覆盖了GLM-OCR从环境准备到API调用的关键链路，结合包内说明可快速掌握文档结构理解、表格逻辑还原、公式识别等核心能力的实测表现。对于希望在文档处理、数据录入和信息提取中快速验证开源OCR方案的团队，这是低门槛、易复现的入门参考。

1. GLM-OCR 是什么，能解什么实际问题

传统 OCR 工具在规整印刷体上表现不差，一旦遇到扫描件倾斜、表格错位、公式复杂、中英文混排，识别结果就断得不成样子。GLM-OCR 是智谱基于开源视觉大模型 GLM-4V 系列微调出来的 OCR 模型，输出不是一串孤立文字框，而是带着版式理解和上下文语义的文本结构。它继承了多模态大模型的对话能力，用户可以把整页文档当作一张图扔给它，让它按阅读顺序输出 Markdown、表格或 JSON。

这个项目适合正在做文档数字化、档案管理系统、RAG 知识库预处理和票据自动化录入的团队。尤其当你手里的材料是责任在己的私有数据，不方便调云端 API 时，GLM-OCR 的开源权重和项目源码就是一条可以直接走的本地部署路线。部署本身不复杂，真正的门槛在于显存预算、推理框架选择和源码配套环境，这三件事会在后面几章逐个讲透。

2. GLM-OCR 的模型选型与显存估算：先算家底再动手

2.1 开源权重版本：先弄清仓库里那个“GLM”是哪一档

GLM-OCR 这个名字在开源社区里通常指两样东西：一个是完整的项目源码仓库，里面包含部署脚本、推理示例和评测工具；另一个是针对 OCR 场景微调好的开源权重，底层底座一般落在 GLM-4V-9B / GLM-4V-9D 这一档视觉语言模型上。9D 相比 9B 的差异主要体现在更长的上下文支持，官方口径上可以走到 128K，这对整页文档输入非常关键，因为一张 1120x1120 的大图进入视觉编码器后会展开成上千个图像 token，上下文窗口小一点就被图片本身撑爆了。

选权重时还有一个考虑点：你是在做纯文字抽取还是做结构化抽取。GLM-OCR 微调权重在文档、表格、公式这类视觉密集任务上比通用基础权重稳得多，直接拉官方发布的 OCR 专用权重即可，不要图省事用 GLM-4V-9B 通用权重代替。两者差在训练数据分布，通用模型对复杂版面经常“看得懂但写不对”，OCR 专用权重则把阅读顺序和格式还原能力强化过。下载前先在发布页看好这个权重对应的是对话格式还是 OCR 格式，不同权重配不同 prompt 模板。

我的建议是：企业私有化部署走“GLM-OCR 项目源码 + OCR 专用权重”这条路，别考虑调免费大模型 API 来做生产链路。API 虽然零部署成本，但数据出境和调用量风险在正式业务里都是绕不开的坎，一旦跑起来再迁移就是伤筋动骨。源码在自己手里，权重在本地磁盘上，后续微调、量化、裁剪都有后悔药可吃。

2.2 显存估算：从 24G 到 12G 的配置路线

部署一个 9B 级别的开源大模型，第一反应是看参数量，9B 的 FP16 权重存储占用通常在 18GB 到 22GB 之间，具体以实际权重文件为准。但权重大小不等于完整运行显存，服务启动时还要给 KV cache、激活值和 CUDA context 预留空间，所以用 FP16/BF16 精度跑 GLM-OCR，一张 24GB 的 4090 或 3090 是起步线。

如果手头只有 12GB 或 16GB 的卡，常见的做法是把权重量化到 AWQ 4bit 或 GPTQ 4bit，权重体积能压到 6GB 到 8GB，剩余显存都留给 KV cache。此时要配合调低最大序列长度，比如把--max-model-len从 32768 降到 16384，否则图像 token 一多照样 OOM。下面这张配置表可以帮你快速定位自己的机器落在哪个档位。

这里要特别提醒一下“大模型上下文长度”这个热词，GLM-OCR 的上下文长度听起来很充裕，但视觉 token 消耗速度远高于纯文本。一张大图动辄一千多个 token，128K 上下文实际能容纳的图片张数并没有想象中多。部署时不要只看参数支持多长，要看你的业务单请求里塞了几张图、每张图多大，算清楚再定max-model-len。

2.3 推理框架选型：为什么我用 vLLM 而不是 Ollama 或 Transformers

很多人的第一反应是图省事用 ollama 本地部署，把模型拉下来就能跑。Ollama 对单机交互式体验确实友好，但 GLM-OCR 这种视觉语言模型要进生产链路，我更推荐 vLLM 或者 SGLang。vLLM 的优势在于 PagedAttention 对 KV cache 的高效管理、连续批处理带来的高吞吐，以及直接兼容 OpenAI 的/v1/chat/completions接口。

Transformers 的pipeline也能跑通，但那是给研究验证用的，单请求推理慢且并发能力弱。真上了生产，每秒可能要扛住几十个识别请求，Transformers 的显存管理和批处理策略撑不住这个压力。vLLM 则把服务化考虑得很完整，内置 API server、支持张量并行、输出 Prometheus 指标，这些正好对应企业大模型私有化部署里最看重的可观测性和扩展性。

选择框架时还有一个容易被忽略的点：vLLM 新特性更新太快，偶尔会跟模型仓库里自带的自定义代码不兼容。我的习惯是先看一下项目源码 README 里锁定的 vLLM 版本，然后严格按那个版本建虚拟环境。这套“环境隔离 + 版本锁定”的流程，能帮你避掉后面一整类玄学报错。

3. 本地部署 GLM-OCR：从拉源码到跑通第一次识别

3.1 环境准备：CUDA、Python 与依赖隔离

动手之前先把基础环境捋一遍，GPU 驱动版本要在 CUDA 12 以上，Python 用 3.10 或更高版本，Conda 环境单独建一个，别装进系统 Python 里。项目源码里通常有requirements.txt，里面会写清楚依赖库的版本范围，直接用下面这段命令创建干净环境。

conda create -n glm-ocr python=3.10 -y conda activate glm-ocr pip install torch --index-url https://download.pytorch.org/whl/cu121 pip install vllm

第一行创建名为glm-ocr的独立 Conda 环境，避免污染系统 Python；第二行激活环境；第三行安装带 CUDA 12.1 支持版的 PyTorch，这是视觉模型推理的基础依赖；第四行装 vLLM。如果是企业内网离线机器，可以提前在一台联网机器上把 wheel 包下载好拷入内网安装，这就是完整的大模型私有化部署链路里常见的离线做法。

装依赖时留意一下 vLLM 和 PyTorch 的版本配对，最新版 vLLM 可能要求特定 PyTorch 版本，直接用 pip 装通常会拉过新版本导致和 CUDA 不匹配。稳妥做法是先看项目 README 里给的版本组合，按 README 的推荐来装。装完后跑一句python -c "import torch; print(torch.cuda.is_available())"，输出 True 再进下一步。

3.2 源码与权重：项目源码和模型权重从哪来、放哪

GLM-OCR 是开源项目，源码直接从官方仓库拉取到工作目录下，目录名保持英文不带空格。权重文件体积比较大，国内网络环境下我习惯从 ModelScope 拉，速度和稳定性都更好。下面这段命令展示拉源码和下载权重的完整过程。

git clone <GLM-OCR官方仓库地址> glm-ocr-src cd glm-ocr-src # 在 ModelScope 页面复制你选定的模型 ID，例如 ZhipuAI/glm-4v-9d-ocr modelscope download --model <你的模型ID> --local_dir ./models/glm-ocr

第一行把项目源码克隆到本地；第三行用 ModelScope 官方 CLI 下载权重，--local_dir参数指定权重存放路径，让模型文件落在项目内的models/glm-ocr目录下，方便统一管理。实际使用时，把<你的模型ID>替换成发布页上那一串真实 ID 即可，不同发布渠道 ID 会有差异，以官方 README 为准。

下载完成后别急着启动，先看一眼目录结构。一个完整的权重目录里至少应该有多个*.safetensors分片文件、config.json、tokenizer.model或tokenizer.json、added_tokens.json，以及可能是chat_template相关的配置。缺任何一个文件都可能导致模型加载失败或输出乱码。另外核对一下所有分片文件是否齐全，常见做法是看*.safetensors.index.json里列出的分片文件名，然后逐一比对磁盘上真实存在的文件。

如果你用的是自己量化过的 AWQ 权重，权重目录里还会多出quant_config.json，这时启动命令要额外加--quantization awq，后面会讲到。

3.3 用 vLLM 启动 GLM-OCR：最常用的一条命令

环境就绪、权重就位后，启动一个兼容 OpenAI 接口的推理服务，只需一条命令。这个命令在项目部署中最常被用到，值得逐参数拆开看。

python -m vllm.entrypoints.openai.api_server \ --model ./models/glm-ocr \ --served-model-name glm-ocr \ --task chat \ --trust-remote-code \ --gpu-memory-utilization 0.92 \ --max-model-len 32768 \ --limit-mm-per-prompt image=1 \ --port 8000

--model指向权重目录绝对路径或相对路径；--served-model-name给这个模型起一个对外名称，客户端调用时 model 字段要填它；--trust-remote-code允许加载模型仓库里的自定义代码，GLM 这类模型几乎必带这个参数，不加会报权限错误；--gpu-memory-utilization限制显存分配上限，0.92 表示最多吃 92% 显存，留一点给输入预处理和 CUDA context；--max-model-len是模型最大上下文，这里设 32768，足够应付单张大图加一段文本；--limit-mm-per-prompt image=1限定每次请求最多传一张图，防止业务方一次塞 N 张图把 KV cache 打满。

日志里出现Uvicorn running on http://0.0.0.0:8000就表示服务起来了。此时用nvidia-smi看一眼显存，你会发现闲置状态也占了十几 GB，这是正常的，因为模型权重已经全部常驻显存。如果你看到加载后显存占用率极低但服务报错，多半是权重路径给错了，vLLM 没加载起模型反而起了个空壳。

3.4 请求一个识别任务：用 curl 快速验证，再用 Python 接业务

服务起来后先用 curl 发一个最小请求，验证模型能不能正常出字。下面命令中的图片以 base64 形式直接嵌进 JSON，适用于任何格式的图片。

curl http://127.0.0.1:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "glm-ocr", "messages": [ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,'$(base64 -w0 ./test.jpg)'"}}, {"type": "text", "text": "识别这张图片中的全部文字，按阅读顺序输出。"} ] } ], "max_tokens": 1024 }'

命令里的model字段必须是启动时--served-model-name指定的名字，传错会报模型不存在；image_url.url里用data:image/jpeg;base64,前缀加 base64 字符串，vLLM 会自动解码；下面跟一个 text 消息作为指令。返回结果里的choices[0].message.content就是模型识别出的文字。第一个注意点是 base64 串里别带换行符，base64 -w0是 Linux 下取消换行折行的标准写法。第二个注意点是 prompt 别写太短，只说“识别文字”和“按原阅读顺序输出并保留层级”在版式复杂时差异极大。

生产业务一般不会用 curl 裸调，封装成 Python 函数更现实。下面这段代码用requests库实现同样请求，并做了图片路径到 base64 的转换。

import base64 import requests def glm_ocr(image_path: str, prompt: str, server_url: str = "http://127.0.0.1:8000/v1/chat/completions") -> str: with open(image_path, "rb") as f: b64 = base64.b64encode(f.read()).decode("utf-8") payload = { "model": "glm-ocr", "messages": [{ "role": "user", "content": [ {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}}, {"type": "text", "text": prompt}, ], }], "max_tokens": 1024, "temperature": 0.1, } resp = requests.post(server_url, json=payload, timeout=120) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"]

这段代码有两个实用细节。base64.b64encode得到的 bytes 必须decode("utf-8")，否则直接塞进 JSON 会报 TypeError。timeout=120要留足，大图首轮推理很可能超过 30 秒，响应超时往往会把一个本来正常的上游请求误判成失败。如果服务端返回 400，优先检查消息结构里的 role、type、text 三件套是否齐全；如果返回 500，去查看 vLLM 终端日志里的 traceback。

4. 参数调优与多场景识别：文档、表格、公式怎么调

4.1 推理参数：temperature、top_p、max_tokens 怎么设

GLM-OCR 本质上是生成模型，这就意味着它的输出天生带有随机性。传统 OCR 是确定性的，同一个输入永远给同一个结果，而生成式模型在同一张图上跑十次可能有细微差异，尤其当识别对象是模糊文字或生僻符号时。理解这一点后，第一条调参原则就出来了：OCR 场景要尽量压低随机性，把解码策略收敛到接近贪心搜索。

我在生产环境里固定用temperature=0.1，部分团队直接设 0。temperature 越低，模型输出的确定性越高，代价是偶尔会陷入重复循环，但 OCR 场景下确定性优先级最高。top_p推荐 0.8 到 0.9，它控制候选词集合的采样范围，配合低 temperature 能抑制无意义输出。max_tokens的设定则要看文档篇幅，一段几十字的票据截图 512 足够，整页 PDF 文字量大时给到 2048 甚至 4096。如果输出被截断在中间，现象是最后一段文字戛然而止，这时不是模型能力不行，是max_tokens设短了。

还有个参数容易被忽略：repetition_penalty。识别表格时模型偶尔会把同一行重复输出好几遍，调高一点惩罚值能缓解，但调太高会导致漏字。我的经验是控制在 1.0 到 1.05 之间，超过 1.1 就开始产生副作用了。

4.2 图像侧参数：分辨率、裁剪与多图限制

GLM-4V 系列的视觉编码器对输入图像有内部缩放逻辑，过小的图片会先被放大，过大的图片会被压缩，这个处理过程可能直接决定你最终识别质量的上下限。文字截图如果原始尺寸只有 600px 宽，识别效果通常不如 1200px 宽的同一张图；而原图超过 2000px 时，信息量虽然多了，但视觉 token 数量膨胀，推理时延和显存占用同步上升。

经验做法是用脚本统一做一次预处理：把长度超过 2000px 的图按比例缩到 2000px 内，把长度低于 800px 的图先放大到 800px，输出为 PNG 或高质量 JPEG。压缩率太高的 JPEG 会在文字边缘留下锯齿状伪影，尤其白底黑字反色区域，这一条就能造成可观的识别率下降。处理好坏用肉眼都能分辨，别把脏图直接扔给模型然后怪模型能力不行。

多图场景更要注意--limit-mm-per-prompt的约束。如果你业务里需要一次识别的多页合同，不要强行把十张图拼进一条消息发过去，更可靠的做法是逐页识别再按页码拼接结果。这么做既绕开了视觉 token 的上下文瓶颈，又给了每页充分的采样空间。批量任务可以把请求并发打到服务上，让 vLLM 自己做连续批处理，整批吞吐远高于单条消息多图。

4.3 场景化提示词：同一个权重，不同指令效果差很多

很多人误以为 OCR 模型不需要写提示词，这个认知在 GLM-OCR 上不成立。权重虽然经过了 OCR 微调，但它依然保留着对话模型的指令跟随能力。同样是识表格，你说“识别文字”它可能输出纯文本，你说“输出为 Markdown 表格”它就能按行按列还原结构。下面三条提示词模板是我在项目里验证过的。

# 通用文档抽取 prompt = "识别图片中的全部文字，按从上到下、从左到右的阅读顺序输出，保留标题和段落层级。" # 表格结构化 prompt = "提取图片中的表格内容，输出为 Markdown 表格，不要遗漏任何一行一列。" # 公式转换 prompt = "识别图片中的所有数学公式，用 LaTeX 语法输出，文字部分照抄。"

第一条针对合同、扫描件和书籍页面，强调阅读顺序能显著减少乱序输出；第二条针对财务表格和台账，指定输出格式后模型会主动对齐行列；第三条针对理科论文和试卷，如果不用 LaTeX 要求，模型经常把公式描述成一段别扭的文本。业务上还有一个小技巧：识别票据时把 prompt 里的“识别”换成“抽取关键字段”，模型会直接输出结构化 JSON，省掉下游一大段字段解析工作。

先别急着做模型微调。开源大模型的微调成本不低，数据标注、训练资源、评估回归三者缺一不可。GLM-OCR 这种底座能力已经不错的模型，九成业务问题可以用“图像预处理 + 提示词模板”解决，只有当你发现特定版式无论怎么写提示词都稳定出错，才值得考虑基于项目源码做一次轻量微调。微调数据至少要准备几百张标注样本，否则效果不稳定，这就是另一条战线了。

5. 部署 GLM-OCR 的五个常见问题与排查：现象、原因、解决

5.1 权重下载到一半断了，怎么续传

现象：ModelScope 或 GitHub 下载权重时网络中断，重新执行命令却从头开始下载，浪费大量时间。

原因：官方 CLI 对超大文件支持断点续传，但只针对单文件多线程分块下载的场景；直接复制文件地址用wget不带-c参数时，中断后重启会重新拉全量。我遇到过一百多 GB 的数据集，断一次重来一次，非常折磨人。

解决：权重文件逐个下载，对每个safetensors分片用wget -c断点续传，-c让已下载的部分继续，而不是重头再来。ModelScope CLI 实测对断点续传的支持不如 wget 稳定，所以我在内网环境里更信任wget -c加循环脚本的方式。下载完成后务必用sha256sum校验，官方发布页会给每个文件校验和，比对不一致就删掉那个分片重新拉。

5.2 服务启动直接 OOM，卡死在 CUDA out of memory

现象：vLLM 启动命令敲下去，日志滚了几行，紧接着报CUDA out of memory，进程退出。

原因：常见的有两种。第一种是权重以 BF16 完整精度加载，光权重就吃掉了 20GB 显存，剩余空间不够分配 KV cache；第二种是--max-model-len设得太大，vLLM 启动时按最大长度预分配 KV cache，32768 比 16384 的预留空间大得多。

解决：先降--max-model-len，从 8192 起步逐步往上试，跑通后再按业务需要加量。还不行就换 AWQ 量化权重，并在启动命令里声明--quantization awq。显存仍然吃紧时，用两张卡做张量并行，加--tensor-parallel-size 2，注意两张卡要型号一致、NVLink 或 PCIe 带宽足够，否则并行后吞吐还跑不过单卡。

5.3 版本不匹配：源码要求和已装框架“掐架”

现象：服务启动后报AttributeError: 'XXX' object has no attribute 'yyy'，或者 transformers 加载权重时报 key 对不上。

原因：GLM-OCR 源码里用了特定版本的 transformers API 和 vLLM 接口，而你的环境里 pip 安装的是新版或旧版，接口签名已经变过。这种情况在大模型生态里太常见了，vLLM 每两周发一个小版本，接口说废就废。

解决：回到项目源码根目录，找到requirements.txt，按照里面的版本号原样重装依赖。注意先把当前环境 clear 掉，当前已经安装过的包不会自动降级，混装版本比全部重装更容易出问题。装好版本后用pip freeze导出requirements-lock.txt存在项目里，以后每次复现都锁定这套版本。开源框架发生的剧烈变动，锁版本就是锁住确定性，这比任何部署技巧都管用。

5.4 识别结果乱码、漏字，问题出在图片预处理

现象：同一张图用接口预览工具看清晰无比，但 GLM-OCR 输出各种错字，空白区域还会莫名多出标点符号。

原因：图像输入环节出问题，但不在模型，在 base64 编码或压缩算法。常见的坑有三个：把 PNG 图转成了质量 60 的 JPEG，文字边缘产生伪影；base64 串里混入了换行符，解码后图片被截断；图片本身有旋转，模型不擅长纠正大角度旋转。

解决：先把图片统一转成高质量 PNG，或 JPEG 质量调到 95 以上。base64 生成后做一个去换行处理，Python 里就是b64.replace("\n", "")。倾斜超过十度的图先做透视校正再送识别。识别手写体是另一个难度等级，GLM-OCR 对手写体的泛化能力弱于印刷体，遇到手写表单，先把预期收益调低，再用裁剪放大的方式把每个字段区域单独送进去识别。

5.5 并发一高就卡死，吞吐上不去怎么办

现象：单请求识别正常，用脚本并发压测时，服务端报超时，有的请求直接连接拒绝。

原因：vLLM 是连续批处理架构，但它 LRU 淘汰策略会优先保留活跃请求的 KV cache。图像请求比纯文本请求更占显存，并发一高，KV cache 直接被打满，服务进入排队状态，响应时延从两秒拉到二十秒，客户端 timeout 一到期就报失败。

解决：启动命令里加--max-num-seqs 8限制单批并发序列数，防止 CPU 和显存同时被打爆。同时把--gpu-memory-utilization从 0.92 降到 0.85，留点显存余量给动态分配的中间张量。压测时从 1 并发慢慢往上加，观察服务日志里的Running batch参数，找到吞吐拐点，别指望默认参数适用于所有业务。

6. 验证与进阶：如何评测你的 GLM-OCR 部署是否合格

6.1 评测集与指标：CER、ANLS 怎么算

部署完成后不能只看几张测试图“看起来挺好”，要有一个可复跑的最小评测集。抽出五十到一百张覆盖典型业务场景的图，人工标注正确文字作为基准，计算字符错误率 CER，公式是编辑距离除以标准答案总字符数。CER 低于 5% 基本可以上生产，10% 以上需要回头查上文说过的图片预处理和提示词。文档理解任务还可以用 ANLS，它放宽了字符级别的严格匹配，允许模型用同义词和近似表述替代，适合 KV 抽取类需求。

from rapidfuzz.distance import Levenshtein def cer(pred: str, gt: str) -> float: if not gt: return 0.0 return Levenshtein.distance(pred, gt) / len(gt)

这段代码用 rapidfuzz 的 Levenshtein 距离算 CER，输入是模型输出文本和人工标注基准文本，输出 0 到 1 之间的错误率。特别留意一点：评测时要把模型输出的换行符和多余空格在两端去掉，否则格式差异会被算成字符错误，虚高干扰判断。

6.2 服务监控与日志：GPU、请求时延、失败率

vLLM 启动时带有/metrics端点，直接接 Prometheus 就能看到请求总量、时延分布、token 吞吐这些关键指标。日常排查不需要这么重的监控，先把三个信息源盯住：nvidia-smi -l 2看显存和 GPU 利用率，vLLM 终端日志看请求队列和 KV cache 占用，业务侧记录每个请求的响应时间和返回码。我自己的排障习惯是先查日志尾部有没有killed字样，再查显存峰值，最后才怀疑模型本身。分布式的脚本无状态并行批量识别合适，但需要一套脚本把输入列表、并发数、失败重试次数都编排好。

6.3 一个实用习惯：固化环境，再谈优化

部署 GLM-OCR 这类项目我最深的血泪经验就一句话：把所有环境细节固化下来，否则三天后你解不开自己布过的局。权重校验和、依赖版本、启动参数、评测集路径，全都写进一个部署文档放进仓库里。Conda 环境用conda env export > environment.yml导出，依赖用pip freeze > requirements-lock.txt导出，下次迁移环境或换卡扩容，照着清单原样还原就行。

评测集也要定期重跑，不是跑一次就完事。以后如果升级权重、换推理框架、调了图像预处理管线，把新版本在老评测集上跑一遍基线对比。做过几次回归之后你会发现，OCR 项目的质量维护本质就是这套循环：数据标注、评测对比、参数调整。这条路没有一劳永逸的捷径，可复现的部署基线就是你唯一的底气。希望这套部署脉络能帮你在 GLM-OCR 上少走一段弯路，把精力留给真正的业务难题。

本文还有配套的精品资源，点击获取