OpenClaw 技能: glmocr

通过 GLM-OCR SDK 解析文档（图片、PDF、扫描件）。

📌 按需加载：此技能仅需在环境中设置 ZHIPUAPIKEY，无需 YAML 配置文件或 GPU。

⚡ 快速开始

bash

安装

pip install glmocr

设置 API 密钥（一次性）

export ZHIPUAPIKEY=sk-xxx

或在工作目录的 .env 文件中添加：

echo ZHIPUAPIKEY=sk-xxx >> .env

python

一行代码

import glmocr
result = glmocr.parse(document.pdf)
print(result.markdown_result)
print(result.to_dict())

bash

CLI — 直接传入 API 密钥（无需设置环境变量）

glmocr parse image.png --api-key sk-xxx

或从特定 .env 文件加载

glmocr parse image.png --env-file /path/to/.env

或依赖环境变量 / 自动发现的 .env（一次性设置，后续省略）

glmocr parse image.png glmocr parse ./scans/ --output ./output/ --stdout

---

配置优先级

构造函数参数 > os.environ > .env 文件 > config.yaml > 内置默认值

代理通过构造函数参数或环境变量覆盖所有配置 — 无需编辑 YAML。

关键环境变量

变量	描述	示例
ZHIPUAPIKEY	API 密钥（MaaS 必需）	sk-abc123
GLMOCR_MODEL

模型名称 | glm-ocr | | GLMOCR_TIMEOUT | 请求超时时间（秒） | 600 | | GLMOCRENABLELAYOUT | 启用/禁用布局检测 | true | | GLMOCRLOGLEVEL | DEBUG / INFO / WARNING / ERROR | INFO |

---

Python API

便捷函数（单次调用）

python
import glmocr

单个文件 → PipelineResult

result = glmocr.parse(invoice.png)

多个文件 → list[PipelineResult]

results = glmocr.parse([page1.png, page2.png, report.pdf])

基于类的方式（多次调用 / 资源复用）

python
from glmocr import GlmOcr

parser = GlmOcr(api_key=sk-xxx) # 模式自动设置为 maas
parser = GlmOcr(mode=maas) # 从环境变量读取 ZHIPUAPIKEY

始终使用上下文管理器或调用 .close()

with GlmOcr(api_key=sk-xxx) as parser: result = parser.parse(document.png) print(result.markdown_result)

parser.close() # 如果未使用 with

构造函数参数

参数	类型	描述
apikey	str	API 密钥。提供此参数会自动启用 MaaS 模式。
apiurl

str | 覆盖 MaaS 端点 URL | | model | str | 覆盖模型名称 | | timeout | int | 请求超时时间（秒，默认：600） | | enable_layout | bool | 启用布局检测 | | log_level | str | 日志级别 |

---

使用 PipelineResult

字段

python
result.markdown_result # str — 完整文档的 Markdown 格式
result.json_result # list[list[dict]] — 每页的结构化区域
result.original_images # list[str] — 输入图片的绝对路径

json_result 结构

页面列表 → 每页的区域列表：

json
[
[
{
index: 0,
label: title,
content: 2024年度报告,
bbox_2d: [100, 50, 900, 120]
},
{
index: 1,
label: table,
content: | Q1 | Q2 |\n|---|---|\n| 120 | 145 |,
bbox_2d: [100, 140, 900, 400]
}
]
]

边界框（bbox_2d）：[x1, y1, x2, y2]，归一化到 0–1000 范围。

区域标签：title、text、table、figure、formula、header、footer、page_number、reference、seal

序列化

python

字典（可 JSON 序列化，用于传递给其他工具）

d = result.to_dict()

键：jsonresult, markdownresult, originalimages, usage (MaaS), datainfo (MaaS)

JSON 字符串

jsonstr = result.tojson() # 美化打印，ensure_ascii=False jsonstr = result.tojson(indent=None) # 紧凑单行

保存到磁盘：写入 /.json + /.md + layout_vis/

result.save(output_dir=./output) result.save(outputdir=./output, savelayout_visualization=False)

错误处理

SDK 不会因 MaaS 错误而抛出异常 — 检查 to_dict() 中是否有 error 键：

python
result = parser.parse(image.png)
d = result.to_dict()
if error in d:
# 处理失败
print(OCR 失败：, d[error])
else:
print(d[markdown_result])

---

CLI 参考

代理首选接口：大多数操作使用 CLI。在环境中一次性设置 ZHIPUAPIKEY，然后按需调用。

支持的输入格式：.jpg、.jpeg、.png、.bmp、.gif、.webp、.pdf

基本用法

bash

解析单个文件 → 保存到 ./output//

MaaS 模式为默认；必须设置 ZHIPUAPIKEY（或使用 --api-key）

glmocr parse image.png

直接传入 API 密钥，无需任何环境设置

glmocr parse image.png --api-key sk-xxx

解析目录 → 将每个文件保存到 ./output//

glmocr parse ./scans/

使用自托管 vLLM/SGLang 替代云端

glmocr parse image.png --mode selfhosted

指定输出目录

glmocr parse image.png --output ./results/

在终端中读取结果（代理友好）

bash

将 Markdown + JSON 打印到标准输出（同时保存到磁盘）

glmocr parse image.png --stdout

仅打印到标准输出 — 不写入任何文件

glmocr parse image.png --stdout --no-save

仅 JSON（不输出 Markdown）

glmocr parse image.png --stdout --json-only

将 JSON 通过管道传递给 jq 进行结构化提取

glmocr parse image.png --stdout --json-only --no-save | jq .[0] | map(select(.label==table))

保存控制

bash

跳过布局可视化图片（更快，输出更小）

glmocr parse image.png --no-layout-vis

解析并仅保存 JSON + Markdown，跳过布局可视化

glmocr parse image.png --no-layout-vis --output ./results/

批量处理

bash

文件夹中的所有图片

glmocr parse ./invoice_scans/ --output ./parsed/ --no-layout-vis

在日志中显示进度

glmocr parse ./docs/ --output ./parsed/ --log-level INFO

调试

bash
glmocr parse image.png --log-level DEBUG

完整标志参考

标志	默认值	描述
--api-key / -k	环境变量	MaaS 模式的 API 密钥（覆盖 ZHIPUAPIKEY）
--mode

maas | maas（云端，默认）或 selfhosted（本地 GPU）| | --env-file | 自动 | .env 文件路径（默认：从当前工作目录自动发现）| | --output / -o