glmocr-formula

GLM-OCR 数式認識スキル / GLM-OCR 数式認識スキル

ZhiPu GLM-OCR のレイアウト解析 API を使用して、画像や PDF から数式を認識し、LaTeX 形式に変換します。

使用場面

• 画像やスキャンした文書から数式を抽出する
• 数式画像を LaTeX に変換する
• 複雑な方程式、積分、行列を認識する
• 数式を含む学術論文、教科書、試験問題を解析する
• ユーザーが「数式 OCR」「数式を抽出」「数式認識」「数式 OCR」「数式を抽出」「画像を LaTeX に変換」と言及した場合

主な機能

• 複雑な数式に対応：積分、総和、行列、分数、根号を処理します
• LaTeX 出力：数式は LaTeX 形式で出力され、文書ですぐに使用できます
• インライン数式とブロック数式：インライン形式とディスプレイ形式の数式を認識します
• 混在コンテンツ：テキストと数式の両方を含む文書を処理できます
• ローカルファイルと URL：ローカルファイルとリモート URL の両方に対応します

リソースリンク

リソース	リンク
API キーを取得	Zhipu オープンプラットフォーム API キー
API ドキュメント	レイアウト解析

前提条件

API キーの設定（必須）

スクリプトは ZHIPU_API_KEY 環境変数からキーを取得します。同じキーを他の Zhipu スキルと共有できます。 このスクリプトは ZHIPU_API_KEY 環境変数からキーを読み込みます。同じキーを Zhipu スキル間で再利用するかどうかは任意です。

キーの取得： Zhipu オープンプラットフォーム API キーにアクセスして、キーを作成またはコピーします。

設定方法（いずれかを選択）：

1. グローバル設定（推奨）： openclaw.json の env.vars に一度設定すると、すべての Zhipu スキルで共有されます：

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

2. スキル単位の設定： openclaw.json でこのスキルのみに設定します：

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

3. Shell 環境変数： ~/.zshrc に追加します：

   export ZHIPU_API_KEY="你的密钥"
   

💡 すでに他の Zhipu スキル（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 レンダリング / 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 から抽出 / 从 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 リファレンス / 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 キーが設定されていない場合:

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

→ 正確なエラーをユーザーに示し、設定するよう案内してください

認証に失敗した場合（401/403）: API キーが無効/期限切れ → 再設定してください

レート制限（429）: クォータが枯渇 → 待機するようユーザーに伝えてください

ファイルが見つからない場合: ローカルファイルが存在しない → パスを確認してください