GLM-OCR Skill 实战指南：用一行 CLI 命令完成图片与 PDF 的高精度文本提取

• 人工智能
• 大模型
• 计算机视觉
• OCR
• 本地部署
• AI 技能

GLM-OCR Skill（位于 skills/glmocr/SKILL.md）是 GLM-OCR 开源项目面向 AI Agent 与开发者提供的即插即用技能包：只需配置ZHIPU_API_KEY并调用一个 Python 脚本，即可通过官方 Layout Parsing API 从本地图片、远程 URL 甚至 PDF 中提取 Markdown 文本，同时获得表格、公式与手写文字的识别能力。读完本文，你将掌握 Skill 的完整安装配置流程、glm_ocr_cli.py的全部命令行参数与返回结构、底层请求封装原理，以及常见错误的排查与处理方案。

Skill 是什么：定位与核心能力

GLM-OCR 是一个面向复杂文档理解场景的多模态 OCR 模型。项目 README 在 2026.3.12 的更新中正式推出了"agent-friendly Skill 模式"：用户只需pip install glmocr并设置 API Key，无需 GPU 与 YAML 配置，即可通过 CLI 或 Python 直接使用。本 Skill 正是这套能力的落地方案之一，它不依赖本地模型部署，而是将请求转发给智谱云端的 Layout Parsing 接口完成识别。

适用场景（When to Use）

根据 SKILL.md 的定义，以下需求均可直接调用本 Skill：

• 从图片中提取文本（支持 PNG、JPG、PDF 格式）
• 将截图转换为文本
• 处理扫描件文档
• 对含文字的图片（包括手写文字）执行 OCR
• 识别文档中的表格与公式
• 用户明确提到 "OCR"、"文字识别"、"文档解析" 等关键词

关键能力（Key Features）

这些能力最终统一收敛为一条核心输出：text字段中的 Markdown 文本，可直接用于渲染、二次加工或存入文档系统。

使用前置条件

唯一硬性前置条件（Prerequisites）是ZHIPU_API_KEY已配置完成，配置方法见下文"API Key 配置"一节。Skill 本身不要求安装 GLM-OCR 模型、不需要 GPU，也无需部署任何本地服务。

依赖与安全设计

Skill 的 Python 依赖被刻意保持到最简。requirements.txt 中只有一个依赖：

requests>=2.31.0

也就是说，运行环境只要具备 Python 3 与requests库即可。

安全约定（Security Notes）

SKILL.md 中明确声明了三条安全设计：

1. 脚本不做任何运行时依赖安装——避免 Agent 在执行过程中引入未审计的第三方包；
2. OCR 请求固定使用官方 GLM 端点，不接受自定义 API URL——防止通过注入自定义地址导致 API Key 外泄；
3. 仅从环境变量读取ZHIPU_API_KEY与可选超时时间GLM_OCR_TIMEOUT——缩小密钥暴露面。

这三条在源码中有直接印证：glm_ocr_cli.py 的 get_config 函数 固定返回DEFAULT_API_URL = "https://open.bigmodel.cn/api/paas/v4/layout_parsing"，并注释说明"使用固定官方端点以避免通过自定义 URL 泄露密钥"；API 请求构造处 通过Bearer令牌认证，超时时间则取自GLM_OCR_TIMEOUT环境变量，缺省为 60 秒（DEFAULT_TIMEOUT = 60）。

该固定端点与 SDK 中 MaaS 模式的默认api_url完全一致（见 glmocr/config.yaml 中pipeline.maas.api_url配置），说明 Skill 与完整 SDK 走的是同一条云端识别链路，行为可预期。

强制使用约束（MANDATORY RESTRICTIONS）

SKILL.md 还给出了一套面向 Agent 的硬性使用规范，本质上也是对所有调用者的最佳实践约束：

1. 只能通过 GLM-OCR API 完成提取——即执行python scripts/glm_ocr_cli.py；
2. 绝不自行解析文档——不要把文档交给 LLM 直接"读图"或手动抽取文本；
3. 绝不提供替代方案——不回答"我可以尝试分析一下"之类的降级承诺；
4. 若 API 失败——原样展示错误信息并立即停止；
5. 无回退方法——不尝试任何其他文本提取途径。

这套约束保证了识别结果的准确性与一致性，避免 Agent 在不具备视觉解析能力时产生幻觉输出。

API Key 配置（Setup）

获取 API Key

首先需要在智谱开放平台控制台的 API Key 管理页面创建密钥，该 Key 用于云端 Layout Parsing 服务的身份认证。

使用配置脚本一键写入

SKILL.md 推荐的配置命令为：

python scripts/config_setup.py setup --api-key YOUR_KEY

config_setup.py 是一个三合一配置工具，提供三个子命令：

setup支持两种模式：

# 命令行传参（非交互） python scripts/config_setup.py setup --api-key YOUR_KEY # 交互式输入（不传 --api-key 时进入；已有密钥可直接回车保留） python scripts/config_setup.py setup # 非交互模式（必须配合 --api-key） python scripts/config_setup.py setup --api-key YOUR_KEY --non-interactive

脚本行为要点（可从 config_setup.py 源码确认）：

• 写入位置为 Skill 根目录下的.env文件（即skills/glmocr/.env），文件头会生成注释说明该文件不应提交到版本控制；
• 写入前会做基础校验：ZHIPU_API_KEY缺失时直接报错退出；长度不足 10 位时输出警告；
• show与validate子命令可用于事后核对配置是否正确落盘；
• 若 Skill 目录存在.gitignore且未包含.env，脚本会提示补充，防止密钥入库。

手动配置.env的等价方式

不运行脚本也可以手工创建skills/glmocr/.env文件：

# skills/glmocr/.env ZHIPU_API_KEY=your-api-key GLM_OCR_TIMEOUT=120 # 可选，覆盖默认 60 秒超时

glm_ocr_cli.py 的 _load_env 函数 会在首次读取配置时自动加载 Skill 根目录（Path(__file__).parent.parent，即skills/glmocr/）下的.env文件，解析KEY=VALUE形式的行并写入进程环境；已存在的系统环境变量优先，不会被.env覆盖。因此你也可以在 shell 中直接export ZHIPU_API_KEY=...而不使用.env文件。

命令行使用详解（How to Use）

所有命令均以 Skill 根目录（skills/glmocr/）为相对路径基准执行。

从 URL 提取

python scripts/glm_ocr_cli.py --file-url "URL provided by user"

适用于图片托管在公网（如https://example.com/image.jpg）的场景，脚本直接将该 URL 作为file字段提交给 API。

从本地文件提取

python scripts/glm_ocr_cli.py --file /path/to/image.jpg

本地文件会被读取为字节流并转成data:<mime>;base64,...形式的 Data URI 再上传，MIME 类型由mimetypes.guess_type自动推断，无法推断时回退为application/octet-stream（见 glm_ocr_cli.py 的 _encode_file 函数）。

保存结果到文件（推荐）

python scripts/glm_ocr_cli.py --file-url "URL" --output result.json

不指定--output时结果打印到标准输出，脚本还会在 stderr 中提示Tip: Use --output result.json to save the result；指定后结果写入 JSON 文件（自动创建父目录），并打印Result saved to: <绝对路径>。

格式化输出

python scripts/glm_ocr_cli.py --file photo.png --output result.json --pretty

--pretty会让 JSON 以缩进 2 空格的美化形式输出（源码中indent = 2 if args.pretty else None），便于阅读与调试。

CLI 参数参考

SKILL.md 给出的完整 CLI 签名：

python {baseDir}/scripts/glm_ocr_cli.py (--file-url URL | --file PATH) [--output FILE] [--pretty]

两个输入参数被定义为互斥且必选其一的参数组（源码见 glm_ocr_cli.py 的 main 函数 中add_mutually_exclusive_group(required=True)），因此不能同时传入--file-url与--file，也不能两者都缺。

命令的退出码设计为：识别成功退出 0，失败退出 1；若--output目标路径不可写则退出 5（见 main 函数结尾），可在 CI 或自动化脚本中直接利用。

底层调用链与请求原理

理解 CLI 背后发生了什么，有助于排查问题和扩展功能。整个调用链在 glm_ocr_cli.py 的 extract_text 函数 中清晰可见：

1. 配置读取：get_config()检查ZHIPU_API_KEY，缺失时抛出CONFIG_ERROR；
2. 输入判定：_is_url()通过urlparse判断输入是否为http/httpsURL；本地路径则调用_encode_file()转为 base64 Data URI；
3. 构造请求体：组装model、file、return_crop_images、need_layout_visualization、start_page_id、end_page_id六个字段；
4. 发送请求：_make_api_request()携带Authorization: Bearer <key>调用 Layout Parsing 端点；
5. 解析响应：_extract_text()从响应中提取 Markdown 文本；
6. 组装信封：返回统一的{ok, text, layout_details, result, error, source, source_type}结构。

请求体默认参数

extract_text还暴露了若干可编程选项（源码中的**options），它们对应的请求字段默认值如下：

其中start_page_id/end_page_id仅对 PDF 输入有意义，用于限制解析的页码范围，避免大文档造成超时或消耗过多 token。

响应文本的两种格式兼容

glm_ocr_cli.py 的 _extract_text 函数 对 API 响应做了双格式兼容：优先读取顶层md_results字符串；若不存在，则尝试读取嵌套data.md_results。两种格式都缺失时抛出ValueError并转为API_ERROR，保证了 SDK 与原生 API 不同返回风格的兼容性。

响应格式详解（Response Format）

无论是 CLI 输出还是 Python 调用，返回值都是统一的标准信封结构。完整规范见 output_schema.md，核心结构如下：

{ "ok": true, "text": "# Extracted text in Markdown...", "layout_details": [[...]], "result": { "raw_api_response": "..." }, "error": null, "source": "/path/to/file.jpg", "source_type": "file" }

字段说明

原始 API 响应（result 字段）

result字段内的原始响应遵循 GLM-OCR Layout Parsing API 格式：

{ "md_results": "Extracted text content in Markdown format...", "layout_details": [ { "type": "table", "bbox": [x1, y1, x2, y2], "cells": [...] }, { "type": "formula", "bbox": [x1, y1, x2, y2], "text": "LaTeX formula..." } ], "usage": { "prompt_tokens": 1000, "completion_tokens": 500, "total_tokens": 1500 } }

• md_results：Markdown 格式的文本提取结果；
• layout_details：带边界框（bbox）与元素分类的详细布局分析；
• usage：token 用量统计（提示 token、生成 token、合计）。

错误码表

output_schema.md 定义了三个顶层错误码：

Python 编程接口用法

除了命令行，extract_text可直接在 Python 中以函数形式使用：

from glm_ocr_cli import extract_text result = extract_text("https://example.com/image.jpg") if result["ok"]: print(result["text"]) else: print(f"Error: {result['error']['message']}")

读取原始响应中的 token 用量：

result = extract_text("https://example.com/image.jpg") if result["ok"]: raw_response = result["result"] usage = raw_response.get("usage", {}) print(f"Tokens used: {usage.get('total_tokens', 0)}")

同时检查输入源类型：

result = extract_text("https://example.com/document.jpg") if result["ok"]: print(f"Source type: {result['source_type']}") print(f"Text: {result['text']}")

编程方式可额外透传model、return_crop_images、need_layout_visualization、start_page_id、end_page_id等参数，比 CLI 更灵活，适合嵌入批量处理脚本或后端服务。

错误处理与排查指南

SKILL.md 对常见失败场景给出了明确的处理指引，以下是完整对照表：

API Key 未配置

Error: ZHIPU_API_KEY not configured. Get your API key at: https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys

→ 将错误原样展示给用户，引导其完成 API Key 配置。该提示由 get_config 函数 抛出，对应的信封错误码为CONFIG_ERROR。

认证失败（401/403）

API Key 无效或已过期，响应会包含Authentication failed (401/403): <详情>。→ 引导用户到控制台重新生成密钥并重新配置。

限流（429）

配额耗尽，响应为API rate limit exceeded (429): <详情>。→ 告知用户等待配额恢复或升级额度后再试。源码中 HTTP 状态码分支处理 对 401/403、429、5xx 分别给出语义化错误信息。

文件不存在

本地文件缺失时返回File not found: <path>，对应的信封错误码为INPUT_ERROR。→ 检查路径是否正确、文件是否为常规文件（目录会被判定为Not a regular file）。

其他边界情况

• 请求超时：默认 60 秒，可通过GLM_OCR_TIMEOUT环境变量调大，超时错误为API request timed out after <n>s；
• 服务端错误（5xx）：返回API service error (<code>): <详情>；
• 响应 JSON 非法：返回Invalid JSON response: <前200字符>；
• 依赖缺失：未安装requests时脚本会提示pip install -r scripts/requirements.txt并以退出码 2 终止（见 导入检查）。

所有运行时错误最终都会被封装为{"ok": false, "error": {"code": ..., "message": ...}}信封，方便调用方统一处理。

最佳实践与下游应用建议

1. 始终使用--output落盘：CLI 默认将 JSON 打印到 stdout，长文档输出可能被终端截断；保存到文件后可反复读取text字段做后续处理。
2. 对长 PDF 控制页码范围：通过 Python 接口传入start_page_id/end_page_id，只解析需要的页，节省 token 并缩短响应时间。
3. 按需开启布局可视化：layout_details仅在need_layout_visualization=true时返回；不需要定位信息时保持默认关闭，可降低响应体积。
4. 合理设置超时：大批量或大文件场景建议调大GLM_OCR_TIMEOUT，避免误判超时。
5. 善用 Markdown 输出：text字段是标准 Markdown——表格已是 Markdown 表格、公式已是 LaTeX，可直接渲染为网页、导入文档系统，或继续喂给 RAG 与 LLM 做结构化理解，与项目仓库中examples/result/目录下展示的 Markdown 产物形态一致。

参考资源

• SKILL.md —— 技能主文档（本文核心依据）
• output_schema.md —— 输出格式详细规范
• glm_ocr_cli.py —— CLI 与extract_text完整实现
• config_setup.py —— 环境配置工具实现
• requirements.txt —— 运行时依赖清单
• glmocr/config.yaml —— SDK 全量配置（含 MaaS 端点、重试、布局参数）
• README.md —— 项目总览与 SDK 安装、MaaS/自托管两种使用方式

• 人工智能
• 大模型
• 计算机视觉
• OCR
• 本地部署
• AI 技能