企业官网建设流程全解析

GLM-OCR Python API实战：GlmOcr类与parse函数全用法

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

GLM-OCR 是一款面向复杂文档理解的多模态 OCR 模型，其官方 Python API 提供了GlmOcr类与parse便捷函数两种调用方式：无论是本地图片、PDF、二进制字节还是 URL，都能一行代码解析为 Markdown + 结构化 JSON 结果。本文带你完整掌握 GLM-OCR Python API 的用法，从安装、选模式到流式解析，一篇讲透。

快速安装：3 种依赖场景对应 3 条命令

GLM-OCR 的 Python SDK 包名为glmocr，按你的运行场景选择最轻量的安装方式：

包入口定义在 glmocr/init.py，安装后可直接from glmocr import GlmOcr, parse。

GLM-OCR 对真实场景文档表现稳定，比如下面这张中文手写稿图片，就是典型的输入样例：

两种调用方式：GlmOcr 类 vs parse 函数

GLM-OCR 的 Python API 核心逻辑位于 glmocr/api.py，提供两个层级的入口：

1.parse()便捷函数 —— 一次性任务

import glmocr # 单张图 → 返回 PipelineResult result = glmocr.parse("image.png") # 批量输入（路径、字节混合）→ 返回结果列表 results = glmocr.parse(["img1.png", "img2.jpg"]) # 带 API key 直接调用 result = glmocr.parse("image.png", api_key="sk-xxx")

parse()内部自动创建GlmOcr实例、执行解析并释放资源，适合脚本和批处理场景。

2.GlmOcr类 —— 长驻解析器

with GlmOcr() as parser: result = parser.parse("image.png") print(result.markdown_result) result.save(output_dir="./results")

用with上下文管理最省心，退出时自动close()释放资源。类接口的完整示例可参考 examples/example.py。

💡配置优先级：构造参数 > 环境变量 > YAML 文件 > 默认值。所有场景下 API Key 都可以通过环境变量ZHIPU_API_KEY提供。

GlmOcr 构造参数速查：选对运行模式

GlmOcr.__init__的所有参数都是可选的，关键参数如下：

两种运行模式的典型写法：

# MaaS 云端模式：只需 API Key，无需 GPU with GlmOcr(api_key="sk-xxx", mode="maas") as parser: result = parser.parse("document.png") # 单卡机器推荐：版面检测放 CPU，把 GPU 留给 OCR 模型 with GlmOcr(mode="selfhosted", layout_device="cpu") as parser: result = parser.parse("document.png")

📌 完整的配置项（MaaS 开关、OCR 服务地址、版面检测阈值等）都在 glmocr/config.yaml 中，默认maas.enabled: true。

parse 函数全参数解析：路径、字节、流式

parser.parse()和模块级parse()的入参签名一致，是 GLM-OCR Python API 中最核心的方法：

def parse( self, images, # str 路径 / pathlib.Path / bytes / URL / 以上列表 *, stream: bool = False, # True 时逐个产出结果（生成器） save_layout_visualization: bool = True, # 是否保存版面可视化 preserve_order: bool = True, # 输出顺序与输入一致 **kwargs, # MaaS 透传参数 )

支持的输入类型一览：

• str：本地文件路径，或http://、file://、data:开头的 URL
• pathlib.Path：路径对象
• bytes：图片/PDF 原始字节（格式自动识别）
• 以上任意类型的混合列表

返回值规则很简单：单输入 → 一个PipelineResult；列表输入 →List[PipelineResult]；stream=True→ 生成器，逐个产出：

# 流式解析：大 PDF 边解析边处理，不占内存 for r in parser.parse(["a.pdf", "b.pdf"], stream=True): r.save(output_dir="./output")

比如下面这张含财务表格的照片，解析后可得到标准 Markdown 表格：

PipelineResult 结果对象：取出 Markdown 与 JSON

解析结果的类定义在 glmocr/parser_result/pipeline_result.py，拿到PipelineResult后常用操作：

to_dict()是 Agent 友好设计：无需接触文件系统即可拿到完整结构化结果：

d = result.to_dict() print(d["markdown_result"]) # Markdown 文本 print(d["json_result"]) # 版面区域明细

进阶用法：PDF 页范围解析与 MaaS 透传参数

MaaS 模式下，parse()支持透传云端 API 的扩展参数，最常用的是 PDF 页范围控制：

# 只解析 PDF 的第 3 页到第 10 页（1 起） result = parser.parse("big.pdf", start_page_id=3, end_page_id=10)

另外两个常用开关：

• return_crop_images=True：返回区域裁剪图
• need_layout_visualization=True：返回版面可视化（save_layout_visualization为 True 时会自动带上）

如果不想经过PipelineResult转换、直接拿原始响应，可以用parse_maas()：

raw = parser.parse_maas("doc.pdf", return_crop_images=True)

⚠️ 注意：parse_maas()仅在 MaaS 模式可用，自部署模式下调用会抛出RuntimeError。自部署模式下还可调用parser.get_queue_stats()查看流水线队列水位。

常见坑点清单 ✅

1. API Key 找不到？检查环境变量ZHIPU_API_KEY或GLMOCR_API_KEY；MaaS 模式缺 key 会直接报MissingApiKeyError。
2. 解析 PDF 报 poppler 缺失？自部署模式下 PDF 依赖 poppler（pdfinfo/pdftoppm），macOS 执行brew install poppler。
3. 忘记 close？长驻使用时务必用with或显式close()，否则会泄漏流水线资源。
4. 单卡显存紧张？用layout_device="cpu"把版面检测挪到 CPU，GPU 专供 OCR 推理。

掌握GlmOcr类与parse函数后，GLM-OCR Python API 的完整能力版图就打开了：单行调用、批量流式、PDF 页范围、结果落盘与结构化输出，覆盖绝大多数文档解析场景。更多 CLI 用法与服务部署方式，可查阅仓库内 README_zh.md 与 skills/glmocr/SKILL.md。

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