GLM-OCR大PDF解析实战：timeout与pdf_dpi关键参数设置指南-育师

GLM-OCR大PDF解析实战：timeout与pdf_dpi关键参数设置指南

【免费下载链接】GLM-OCRGLM-OCR: Accurate × Fast × Comprehensive项目地址: https://gitcode.com/GitHub_Trending/gl/GLM-OCR

GLM-OCR 是一款开源的文档解析 OCR 工具，能把大体积 PDF、图片精准转换为结构化的 Markdown 和 JSON，支持版面检测、表格识别和公式还原。但在实战中，很多新手会遇到两个典型问题：解析大 PDF 时频繁超时、渲染出来的页面文字发糊导致识别率下降。其实，这两个问题都可以通过两个核心参数——timeout和pdf_dpi——快速解决。本文带你用 5 分钟搞懂它们的默认值、设置方法和调优技巧。

一、timeout：超时参数到底控制什么

timeout控制的是 SDK 向 OCR 服务发起请求时的等待上限，实际由两个字段组成：

字段	含义	MaaS 云端模式默认值	自部署模式默认值
`connect_timeout`	建立连接的最长时间（秒）	30	30
`request_timeout`	单次请求的最长等待时间（秒）	300	120

大 PDF 每页都要单独请求识别，页面多、区域多时整体耗时很容易超过默认值，触发超时中断。默认值定义见 glmocr/config.py（MaaS）与 glmocr/config.py（自部署 OCR API）。

💡调优技巧：解析页数多的文档时，把request_timeout提高到 600 甚至 900；自部署 GPU 较慢时同样适当调大。同时项目内置了自动重试机制（遇到 429/5xx 会退避重试 2 次），调大 timeout 后成功率会明显提升，重试策略见 glmocr/config.yaml。

三种设置方法

方法 1：修改 YAML 配置文件

编辑 glmocr/config.yaml 中的对应行：

pipeline: maas: connect_timeout: 30 request_timeout: 600 # 大 PDF 建议调大

方法 2：环境变量（无需改文件）

在项目根目录的.env文件写入：

GLMOCR_TIMEOUT=600

环境变量GLMOCR_TIMEOUT会直接映射到pipeline.maas.request_timeout，映射关系见 glmocr/config.py。

方法 3：Python API 调用时传入

GlmOcrConfig.from_env(api_key="sk-xxx", timeout=600)

二、pdf_dpi：清晰度与速度的平衡点

pdf_dpi决定 PDF 每页渲染成图片时的分辨率。GLM-OCR 内部会用 PyMuPDF 按该 DPI 把 PDF 逐页转成图片再送去识别，核心实现见 glmocr/utils/image_utils.py。

pdf_dpi 怎么选？

DPI 值	适用场景	说明
150	快速预览、大字号文档	速度最快，小字易糊
200（默认）	日常文档、论文、报告	速度与清晰度的最佳平衡
300	密集小字、扫描件、代码页	识别更准，但渲染和耗时明显增加

默认值定义见 glmocr/config.py 和 glmocr/config.yaml：

pipeline: page_loader: pdf_dpi: 200 pdf_max_pages: null # null = 不限页数

📌两个实用建议：

小字看不清就调高 DPI：如果结果里出现大量错字漏字，先尝试把pdf_dpi调到 300；
页数太多用pdf_max_pages截断：先用前几页验证参数是否合适，避免整份百页文档白跑一遍。

三、大 PDF 实战组合拳

以一份 100 页的论文为例（可参考仓库自带的 examples/source/GLM-4.5V.pdf 试跑），推荐组合：

pipeline: maas: request_timeout: 600 # 给足单页等待时间 page_loader: pdf_dpi: 200 # 论文先默认，小字多则升 300 pdf_max_pages: 100 # 明确页数，心里有数

一句话口诀：超时了就调大 timeout，看不清了就调大 pdf_dpi。两个参数互不干扰，可分别独立调整，无需重新部署。

四、常见问题 FAQ

Q1：一直报超时错误怎么办？按顺序排查：调大request_timeout→ 降低并发（max_workers）→ 检查网络。重试相关配置见 glmocr/config.yaml。

Q2：自部署模式和云端模式参数一样吗？不完全一样。自部署的request_timeout默认只有 120 秒（见 glmocr/config.yaml），跑大 PDF 建议显式调大到 300 以上；云端模式默认 300 秒。

Q3：DPI 是不是越高越好？不是。DPI 过高会让单页像素爆炸，请求变慢甚至超过服务端像素上限，200~300 之间通常足够。

总结

掌握timeout和pdf_dpi这两个参数，就能解决 GLM-OCR 解析大 PDF 时 80% 的"翻车"场景：超时中断靠调大request_timeout（YAML、GLMOCR_TIMEOUT环境变量、Python 传参三种方式任选），识别模糊靠上调pdf_dpi到 300。配合pdf_max_pages先小范围验证，再全量跑，是新手上手大文档解析最稳妥的路径。

【免费下载链接】GLM-OCRGLM-OCR: Accurate × Fast × Comprehensive项目地址: https://gitcode.com/GitHub_Trending/gl/GLM-OCR

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考