glmocr-formula

GLM-OCR 公式识别技能 / GLM-OCR 公式识别技能

使用智谱 GLM-OCR 版面解析 API 识别图像和 PDF 中的数学公式，并将其转换为 LaTeX 格式。

使用场景 / 使用场景

• 从图片或扫描件中提取数学公式 / 从图片或扫描件中提取数学公式
• 将公式图片转换为 LaTeX / 将公式图片转为 LaTeX 格式
• 识别复杂方程、积分、矩阵 / 识别复杂方程、积分、矩阵
• 解析含公式的论文、教材、试卷 / 解析含公式的论文、教材、试卷
• 用户提及“公式 OCR”“提取公式”“公式识别”“公式 OCR”“提取公式”“图片转 LaTeX”

核心特性 / 核心特性

• 复杂公式支持：支持积分、求和、矩阵、分数、根式
• LaTeX 输出：公式以 LaTeX 格式输出，可直接用于文档
• 行内公式和块级公式：可识别行内公式和独立显示的公式
• 混合内容：可处理同时包含文本和公式的文档
• 本地文件和 URL：支持本地文件和远程 URL

资源链接 / 资源链接

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

前置条件 / 前置条件

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

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

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

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

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

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

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

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

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

   export ZHIPU_API_KEY="你的密钥"
   

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

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

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

⛔ 强制限制 / 强制限制 ⛔

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

📋 输出展示规则

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

• 完整展示提取的文本／公式（text）
• 可以进行摘要，但不得隐瞒重要的提取失败情况
• 如果 layout_details 中包含与公式相关的条目，可以重点展示
• 如果结果文件已保存，请告知用户文件路径
• 仅在用户明确要求或调试时展示上游原始响应（--include-raw）

⚠️ LaTeX 渲染注意：

OCR API 会以 LaTeX 格式返回公式（例如 $\frac{1}{2}$、$\theta^{x+1}$）。由于大多数聊天平台无法渲染 LaTeX，首次使用时应询问用户一次：

“OCR 结果包含 LaTeX 公式，需要我将公式转换为易读的 Unicode 格式展示，还是保留原始 LaTeX？”

记住用户的选择，并在本次会话的其余时间内遵循。后续调用时不要再次询问，除非用户明确更改偏好。

• 用户选择易读格式 → 将 LaTeX 转换为 Unicode／纯文本：

LaTeX	Unicode／纯文本
$\frac{a}{b}$	a/b
$x^{n}$	x^n
$x_{i}$	xᵢ
$\sqrt{x}$	√x
$\theta$	θ
$\phi$	φ
$\therefore$	∴
$\Rightarrow$	⇒
$\left\{ \begin{array}{l} ... \end{array} \right.$	⎧ line1 ⎨ line2 ⎩
$\textcircled{1}$	①
$\in$	∈
$\infty$	∞
$\ln$	ln
$\leq$ / $\geq$	≤ / ≥

• 用户选择原始 LaTeX → 直接展示原始 LaTeX 输出；如果使用了 --output，提醒用户原始数据也保存在输出文件中。

使用方法

从 URL 提取

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

从本地文件提取

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

保存结果到文件

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

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

python scripts/glm_ocr_cli.py --file formula.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": "Extracted formulas and text in Markdown/LaTeX...",
  "layout_details": [...],
  "result": null,
  "error": null,
  "source": "/path/to/file",
  "source_type": "file",
  "raw_result_included": false
}

关键字段：

• ok — 提取是否成功
• text — 使用 LaTeX 公式的 Markdown 格式提取文本
• layout_details — 布局分析详情
• error — 失败时的错误详情

错误处理

未配置 API key：

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

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

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

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

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