MiniCPM-OCR-1.0-AWQ常见问题排查清单:显存不足、输出截断、乱码一次搞懂
MiniCPM-OCR-1.0-AWQ常见问题排查清单:显存不足、输出截断、乱码一次搞懂
MiniCPM-OCR-1.0-AWQ 是 OpenBMB 推出的 1.3B 文档解析(OCR)模型 MiniCPM-OCR 1.0 的 AWQ 4-bit(W4A16)量化版本,权重体积从 BF16 的约 2.42 GiB 降到约 1.74 GiB,让普通单卡也能跑文档解析。本文围绕部署和使用时最常见的三类问题——显存不足、输出截断、乱码——整理了一份新手可直接照做的排查清单,帮你快速定位并解决。
一、排查前先做:30 秒健康检查 🔍
| 检查项 | 怎么看 | 正常标准 |
|---|---|---|
| 权重文件大小 | 查看本地 model.safetensors |
约 1.86 GB(1,865,177,152 字节) |
| 运行时版本 | vLLM / SGLang / transformers 版本 | config.json 中标注 transformers 5.21.0 |
| Prompt 与区域匹配 | 请求里用的 prompt 前缀 | 表格区用 Table Recognition:、公式区用 Formula Recognition: 等 |
| GPU 显存 | nvidia-smi |
建议 ≥ 4 GB,8 GB 更从容 |
⚠️ 最容易被忽略的一点:model.safetensors 由 Git LFS 管理。如果拉取后该文件只有几百字节(例如 134 字节),说明它还是 LFS 指针文件而非真实权重,必须先把 LFS 文件拉下来,否则任何运行方式都会加载失败。
二、显存不足(CUDA out of memory)排查清单
典型症状:服务启动或推理时报 CUDA out of memory。
常见原因与对应解法:
- 没有用 AWQ 版权重。确认 config.json 中
quantization_config为quant_method: awq、bits: 4、group_size: 128。AWQ 版权重仅约 1.74 GiB;注意视觉编码器(vision tower)和lm_head按设计保持 BF16,只量化了语言模型线性层,这是正常现象,不是加载错误。 --max-model-len设得过大。官方 vLLM 示例中使用了--max-model-len 40960,KV cache 会随该值线性增长。OCR 单区域识别的输出通常是短文本,可根据实际需求调低(如 8192~16384),显存占用会明显下降。- 并发过高或 GPU 被其他进程占用。先用
nvidia-smi确认显存空闲量,再逐步降低并发请求数。 - 合理配置显存占用比例。vLLM 可通过
--gpu-memory-utilization控制显存占用上限,避免预留过满导致启动失败。
💡 顺序建议:先确认用的是 AWQ 版 → 再降
max-model-len→ 最后降并发。
三、输出截断排查清单(finish_reason = length)
官方 README.md 明确指出:如果 finish_reason 是 length,说明输出被截断了——需要调大 token 预算。
| 表现 | 原因 | 解法 |
|---|---|---|
| 表格 HTML 少行、突然中断 | 表格 HTML 输出 token 很多,超出 max_tokens |
调大输出 token 上限 |
| 公式 LaTeX 缺结尾分隔符 | 同上 | 同上 |
| 整页文档解析结果不完整 | 一次性塞入内容过长 | 按区域切分识别(SDK 流程会自动做版面检测、裁剪、并发识别) |
注意区分:截断不是乱码——截断的文本本身是正确的,只是“说不完”;乱码则是内容本身无意义,两者排查方向不同。生成默认值可参考 generation_config.json(含 use_cache、eos token 等设置)。
四、乱码排查清单:先分清“真乱码”还是“预期输出”
- 伪乱码(最常见):Prompt 和裁剪区域不匹配。比如对表格区域用
Text Recognition:,或对普通文本用了Table Recognition:却收到 HTML 标签、收到 LaTeX 公式。这其实是模型的预期行为,对照 README.md 中的 Prompt 对照表(文本区Text Recognition:、公式区Formula Recognition:、印章区Seal Recognition:等)即可消除误会。 - 图像质量问题:原图模糊、倾斜严重、分辨率过低时,识别结果会退化为无意义字符。图像处理参数见 preprocessor_config.json:4 倍下采样、
scale_resolution448、最多 9 个切片(max_slice_nums)。图太小太糊时,先提升源图质量。 - 请求编码损坏:通过 vLLM API 传图时使用 base64 编码,编码损坏或传了非图片数据,模型会“一本正经”地输出乱码。
- 运行时不支持 AWQ:AWQ 权重依赖运行时读取
config.json中的quantization_config完成 W4A16 加载(vLLM 无需额外参数)。版本过旧不支持 AWQ 时,可能出现加载报错或输出异常,升级运行时即可。 - DSpark 加速版本混用:如果用了 DSpark 解码加速,草稿(draft)模型必须与主模型来自同一发布版本,官方明确警告不要混用不同主检查点的草稿权重,否则会输出乱码。
五、关键配置文件速查 📁
| 文件 | 作用 |
|---|---|
| config.json | 模型结构 + AWQ 量化配置(awq / 4bit / group 128),运行时据此自动加载量化权重 |
| model.safetensors | 4-bit 量化权重(Git LFS,约 1.86 GB) |
| generation_config.json | 生成默认参数(缓存、结束符等) |
| preprocessor_config.json | 图像预处理:4x 下采样、448 缩放、最多 9 切片 |
| chat_template.jinja | 对话模板,含 enable_thinking 开关(OCR 场景默认关闭思考) |
| tokenizer_config.json | 分词器配置,model_max_length 262144 |
| README.md | 官方文档:快速开始、Prompt 表、量化说明、FAQ 入口 |
六、一页速查表:症状 → 原因 → 解法 ✅
| 症状 | 最可能原因 | 快速解法 |
|---|---|---|
CUDA out of memory |
KV cache 过大 / 并发高 / 用了 BF16 版 | 确认 AWQ 版、调低 --max-model-len、降并发 |
finish_reason: length |
输出 token 预算不足 | 调大 max_tokens,长文档按区域切分 |
| 输出满屏 HTML / LaTeX | Prompt 与区域匹配,属正常输出 | 按 Prompt 对照表选择正确前缀 |
| 输出无意义字符 | 图片损坏 / 运行时过旧 / draft 模型混用 | 检查图像编码、升级运行时、DSpark 主草稿同版本 |
| 权重加载失败 | model.safetensors 是 LFS 指针 |
拉取 Git LFS,确认文件约 1.86 GB |
| 中文识别效果差 | 源图模糊 / prompt 未指定识别任务 | 提升图像质量,补全对应 Prompt |
写在最后
MiniCPM-OCR-1.0-AWQ 的部署排障思路可以浓缩为一句话:先查权重(LFS/大小),再查显存(量化版 + max-model-len),最后查输入(prompt、图片、编码)。按照上面的清单逐项过一遍,显存不足、输出截断、乱码这三类高频问题基本都能快速定位。
登录后查看全文