name: glmocr-sdk
description: |
    Trigger when: (1) User wants to extract text, tables, formulas, or structured data from images/PDFs/scanned documents, (2) User mentions "OCR", "文字识别", "文档解析", (3) User has a document (screenshot, scanned page, invoice, paper, whiteboard photo) and needs its content in structured form, (4) User asks to parse, digitize, or extract content from a visual document.

    Invokes the GLM-OCR SDK (pip install glmocr) to parse documents via Zhipu's cloud API. No GPU required. Returns structured JSON (regions with labels + bounding boxes) and Markdown. Agent can operate entirely via CLI — no YAML files needed.

    NOT for: real-time camera feeds, audio transcription, or non-document images (photos, illustrations).
metadata:
    openclaw:
        requires:
            env:
                - ZHIPU_API_KEY
        primaryEnv: ZHIPU_API_KEY
        emoji: "\U0001F4C4"
        homepage: https://github.com/zai-org/GLM-OCR/tree/main/skills/sdk

OpenClaw 技能: glmocr

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

📌 按需使用：此技能仅需在环境中设置 ZHIPU_API_KEY，无需 YAML 配置文件或 GPU。

⚡ 快速开始

# 安装
pip install glmocr

# 设置 API 密钥（一次即可）
export ZHIPU_API_KEY=sk-xxx
# 或添加到工作目录下的 .env 文件：
echo "ZHIPU_API_KEY=sk-xxx" >> .env

# 一行代码
import glmocr
result = glmocr.parse("document.pdf")
print(result.markdown_result)
print(result.to_dict())

# 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。

关键环境变量

---

Python API

便捷函数（单次调用）

import glmocr

# 单个文件 → PipelineResult
result = glmocr.parse("invoice.png")

# 多个文件 → list[PipelineResult]
results = glmocr.parse(["page1.png", "page2.png", "report.pdf"])

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

from glmocr import GlmOcr

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

# 始终使用上下文管理器或调用 .close()
with GlmOcr(api_key="sk-xxx") as parser:
    result = parser.parse("document.png")
    print(result.markdown_result)

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

构造函数参数

---

使用 PipelineResult

字段

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

json_result 结构

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

[
  [
    {
      "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

序列化

# 字典（可 JSON 序列化，用于传递给其他工具）
d = result.to_dict()
# 键：json_result, markdown_result, original_images, usage (MaaS), data_info (MaaS)

# JSON 字符串
json_str = result.to_json()                 # 美化打印，ensure_ascii=False
json_str = result.to_json(indent=None)      # 紧凑单行

# 保存到磁盘：写入 <stem>/<stem>.json + <stem>/<stem>.md + layout_vis/
result.save(output_dir="./output")
result.save(output_dir="./output", save_layout_visualization=False)

错误处理

SDK 不会因 MaaS 错误而抛出异常——请检查 to_dict() 的 "error" 键：

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

---

CLI 参考

智能体首选接口：大多数操作请使用 CLI。在环境中设置 ZHIPU_API_KEY 一次，然后按需调用。

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

基本用法

# 解析单个文件 → 保存到 ./output/<stem>/
# MaaS 模式为默认；必须设置 ZHIPU_API_KEY（或使用 --api-key）
glmocr parse image.png

# 直接传递 API 密钥，无需任何环境设置
glmocr parse image.png --api-key sk-xxx

# 解析目录 → 将每个文件保存到 ./output/<stem>/
glmocr parse ./scans/

# 使用自托管的 vLLM/SGLang 代替云端
glmocr parse image.png --mode selfhosted

# 指定输出目录
glmocr parse image.png --output ./results/

在终端中读取结果（智能体友好）

# 将 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"))'

保存控制

# 跳过版面可视化图像（更快，输出更小）
glmocr parse image.png --no-layout-vis

# 解析并仅保存 JSON + Markdown，跳过版面可视化
glmocr parse image.png --no-layout-vis --output ./results/

批量处理

# 文件夹中的所有图像
glmocr parse ./invoice_scans/ --output ./parsed/ --no-layout-vis

# 在日志中显示进度
glmocr parse ./docs/ --output ./parsed/ --log-level INFO

调试

glmocr parse image.png --log-level DEBUG

完整标志参考

---

典型智能体工作流

接收文档路径 / URL
       │
       ▼
glmocr.parse(path)            ← 单次调用，处理 PDF/图片
       │
       ▼
result.to_dict()              ← 可安全作为工具输出传递
       │
       ├── markdown_result    → 交给 LLM 阅读/总结
       └── json_result        → 结构化提取（表格、公式、按标签划分的区域）

按标签过滤

result = glmocr.parse("report.png")
regions = result.json_result[0]  # 第一页

tables = [r for r in regions if r["label"] == "table"]
formulas = [r for r in regions if r["label"] == "formula"]
body_text = [r for r in regions if r["label"] == "text"]

多页 PDF → 逐页迭代

with GlmOcr(api_key="sk-xxx") as parser:
    result = parser.parse("document.pdf")   # 所有页面都在一个 PipelineResult 中
    for page_idx, page_regions in enumerate(result.json_result):
        print(f"第 {page_idx + 1} 页：{len(page_regions)} 个区域")
        for region in page_regions:
            print(f"  [{region['label']}] {region['content'][:60]}")

程序化配置（无需环境变量）

from glmocr.config import GlmOcrConfig

cfg = GlmOcrConfig.from_env(
    api_key="sk-xxx",
    mode="maas",
    timeout=600,
    log_level="DEBUG",
)

---

输出目录结构

执行 result.save(output_dir) 后：

output_dir/
  <image_stem>/
    <image_stem>.json         ← 结构化区域
    <image_stem>.md           ← 完整 Markdown（包含裁剪后的图片）
    imgs/                     ← Markdown 中引用的裁剪图片
    layout_vis/               ← 版面检测叠加图像（如果启用）
      <image_stem>.jpg

---

常见陷阱

• ZHIPU_API_KEY 未设置：SDK 默认使用 MaaS 模式。没有密钥时，parse() 将失败并显示清晰的错误消息和快速修复说明。通过 export ZHIPU_API_KEY=sk-xxx 设置，或添加到 .env 文件，或在 CLI 中传递 --api-key sk-xxx。
• 大型 PDF：默认超时为 600 秒。对于非常长的文档，请使用 timeout=1200 增加超时。
• result.json_result 是字符串：当模型返回格式错误的 JSON 时会发生。SDK 保留原始字符串——手动解析或记录它。