glmocr-table

GLM-OCR 表格识别技能 / GLM-OCR 表格识别技能

使用智谱 GLM-OCR 版面解析 API 从图片和 PDF 中提取表格，并将其转换为 Markdown 格式。

使用场景 / 使用场景

• 从图片或扫描件中提取表格 / 从图片或扫描件中提取表格
• 将表格图片转换为 Markdown 或 Excel 格式 / 将表格图片转为 Markdown 或可编辑格式
• 识别含合并单元格的复杂表格 / 识别含合并单元格的复杂表格
• 解析财务报表、发票和带表格的报告 / 解析财务报表、发票、带表格的报告
• 用户提到“extract table”“recognize table”“表格识别”“提取表格”或“表格 OCR”“表格转文字”

核心特性 / 核心特性

• 支持复杂表格：可处理合并单元格、嵌套表格和多行表头
• Markdown 输出：表格以整洁的 Markdown 格式输出，便于编辑和转换
• 多页 PDF：支持从多页 PDF 文档中批量提取
• 本地文件和 URL：支持本地文件和远程 URL

资源链接 / 资源链接

资源	链接
获取 API 密钥	智谱开放平台 API Keys
API 文档	版面解析 / 版面解析

前置条件 / 前置条件

API 密钥配置 / API 密钥配置（必需 / 必需）

脚本通过 ZHIPU_API_KEY 环境变量获取密钥，可与其他智谱技能复用同一个 key。 此脚本从 ZHIPU_API_KEY 环境变量读取密钥。是否在智谱技能之间复用同一个密钥由你决定。

获取密钥 / 获取密钥： 访问 智谱开放平台 API Keys 创建或复制密钥。

配置方式 / 配置方式（任选一种）：

1. 全局配置（推荐） / 全局配置（推荐）： 在 openclaw.json 的 env.vars 中设置一次，所有智谱技能都将共享该密钥：

   {
     "env": {
       "vars": {
         "ZHIPU_API_KEY": "你的密钥"
       }
     }
   }
   

2. 技能级配置 / 技能级配置： 在 openclaw.json 中仅为此技能设置：

   {
     "skills": {
       "entries": {
         "glmocr-table": {
           "env": {
             "ZHIPU_API_KEY": "你的密钥"
           }
         }
       }
     }
   }
   

3. Shell 环境变量 / Shell 环境变量： 添加到 ~/.zshrc：

   export ZHIPU_API_KEY="你的密钥"
   

💡 如果你已为其他智谱 skill（如 glmocr、glmv-caption、glm-image-generation）配置过 key，它们共享同一个 ZHIPU_API_KEY，无需重复配置。

安全与透明度 / 安全与透明度

• 使用的环境变量 / 使用的环境变量：
  • ZHIPU_API_KEY（必需 / 必需）
  • GLM_OCR_TIMEOUT（可选超时秒数 / 可选超时秒数）
• 固定官方端点 / 固定官方端点： https://open.bigmodel.cn/api/paas/v4/layout_parsing
• 不支持自定义 API URL 覆盖 / 不支持自定义 API URL 覆盖： 这可以避免密钥因端点重定向而意外泄露。
• 默认不返回原始上游响应 / 原始响应默认不返回： 仅在需要调试时使用 --include-raw。

⛔ 强制限制 / 强制限制 ⛔

1. 只能使用 GLM-OCR API — 执行脚本 python scripts/glm_ocr_cli.py
2. 绝不要自行解析表格 — 不要尝试使用内置视觉能力或任何其他方法提取表格
3. 绝不要提供替代方案 — 不要提出“我可以尝试识别”或类似建议
4. 如果 API 调用失败 — 显示错误消息并立即停止
5. 禁止使用备用方法 — 不要尝试通过其他方式提取表格

📋 输出展示规则 / 输出展示规则

运行脚本后，清晰、安全地呈现 OCR 结果。

• 完整展示提取出的表格 Markdown（text）
• 可以概述，但不要隐瞒重要的提取失败信息
• 如果 layout_details 中包含与表格相关的条目，可以重点展示
• 如果结果已保存到文件，请告知用户文件路径
• 仅在用户明确要求或进行调试时展示原始上游响应（--include-raw）

使用方法 / 使用方法

从 URL 提取 / 从 URL 提取

python scripts/glm_ocr_cli.py --file-url "https://example.com/table.png"

从本地文件提取 / 从本地文件提取

python scripts/glm_ocr_cli.py --file /path/to/table.png

将结果保存到文件 / 保存结果到文件

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

包含原始上游响应（仅用于调试） / 包含原始上游响应（仅调试）

python scripts/glm_ocr_cli.py --file table.png --output result.json --include-raw

CLI 参考 / CLI 参数

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

参数	必填	描述
--file-url	二选一	图片/PDF 的 URL
--file	二选一	图片/PDF 的本地文件路径
--output, -o	否	将结果 JSON 保存到文件
--pretty	否	美化 JSON 输出
--include-raw	否	在 result 字段中包含上游 API 的原始响应（仅用于调试）

响应格式

{
  "ok": true,
  "text": "| Column 1 | Column 2 |\n|----------|----------|\n| Data     | Data     |",
  "layout_details": [...],
  "result": null,
  "error": null,
  "source": "/path/to/file",
  "source_type": "file",
  "raw_result_included": false
}

关键字段：

• ok — 是否提取成功
• text — 以 Markdown 格式提取的文本（用于显示）
• layout_details — 布局分析详情
• error — 失败时的错误详情

错误处理

未配置 API 密钥：

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

→ 向用户显示确切错误，并引导其完成配置

身份验证失败（401/403）： API 密钥无效或已过期 → 重新配置

速率限制（429）： 配额已用尽 → 告知用户稍后再试

未找到文件： 本地文件缺失 → 检查路径