glmocr-table

用途

GLM-OCR 表格识别技能（glmocr-table）是智谱 GLM-OCR 的官方技能，用于从图片和 PDF 中识别并提取表格，转换为 Markdown 格式。它通过智谱 GLM-OCR 版面解析 API 完成表格识别与提取。

适用场景包括：

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

主要能力

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

使用方式

前置条件：API Key 配置（必需）

脚本通过 ZHIPU_API_KEY 环境变量获取密钥，可与其他智谱技能复用同一个 key。

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

配置方式（任选一种）：

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

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

Skill 级别配置：在 openclaw.json 中仅为该技能设置：

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

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

export ZHIPU_API_KEY="你的密钥"

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

命令行调用

从 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 参数

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：失败时的错误详情

输出展示规则

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

完整展示提取出的表格 Markdown（文本）
允许摘要，但不要隐藏重要的提取失败信息
如果 layout_details 包含表格相关条目，可以高亮显示
如果结果文件已保存，告知用户文件路径
仅在明确要求或调试时（--include-raw）展示原始上游响应

安全与透明度

使用的环境变量：

ZHIPU_API_KEY（必需）
GLM_OCR_TIMEOUT（可选超时秒数）

固定官方端点：https://open.bigmodel.cn/api/paas/v4/layout_parsing

不支持自定义 API URL 覆盖：以避免通过重定向端点意外泄露密钥。

原始上游响应默认不返回：仅在需要调试时使用 --include-raw。

限制与强制约束

仅使用 GLM-OCR API：执行脚本 python scripts/glm_ocr_cli.py
绝不自行解析表格：不要尝试使用内置视觉或其他方法提取表格
绝不提供替代方案：不要建议“我可以尝试识别”等类似做法
如果 API 失败：显示错误信息并立即停止
无回退方法：不要尝试以任何其他方式提取表格

错误处理

API key 未配置：提示 ZHIPU_API_KEY not configured，并引导至 https://bigmodel.cn/usercenter/proj-mgmt/apikeys 配置
认证失败（401/403）：API key 无效或过期，需重新配置
限流（429）：配额耗尽，提示用户等待
文件未找到：本地文件缺失，检查路径

资源链接

获取 API Key：智谱开放平台 API Keys
API 文档：Layout Parsing / 版面解析