alibabacloud-docmind-parse

DocMind 文書解析

2 つの呼び出しモード

1. 無料モード（V2 API 直接アクセス）：DOCMIND_V2_ENDPOINT 環境変数でエンドポイントを設定します。1 日あたりの無料利用枠には上限があります。
2. Alibaba Cloud POP モード：デフォルトの認証情報チェーンを通じて認証情報が自動的に取得されます。月 3,000 ページまで無料で、それを超えると従量課金となります。

ルーティング戦略

• Alibaba Cloud のデフォルト認証情報チェーンが利用可能な場合は、POP モードを優先します。
• 認証情報を利用できず、DOCMIND_V2_ENDPOINT が設定されている場合は、V2 無料モードを使用します。
• 無料利用枠を使い切った場合は、Alibaba Cloud DocMind サービスを有効化するようユーザーに促します。

環境変数

変数	説明	必須
DOCMIND_V2_ENDPOINT	V2 API サービスのエンドポイント（ドメインまたは IP）。デフォルトは docmind.aliyuncs.com です	任意

POP モードでは、Alibaba Cloud のデフォルト認証情報チェーン（環境変数、設定ファイル、ECS RAM ロールなど）を通じて認証情報が自動的に取得されるため、手動で管理する必要はありません。

---

使用方法

python scripts/docmind_parse.py <file_path_or_url> [options]

パラメーター

パラメーター	説明	デフォルト
<file_path_or_url>	ローカルファイルのパスまたはファイル URL	必須
--mode	呼び出しモード：auto、v2、pop	auto
--enhancement	強化モード：VLM、LLM、DIGITAL、OCR、AUTO	なし
--output	出力形式：markdown、json、html	markdown
--pages	解析するページ範囲（例：1-5）	すべて
--output-file	出力ファイルのパス	標準出力
--head-foot	ヘッダーとフッターを解析します	無効
--user-prompt	カスタムユーザープロンプト	なし
--option	文書解析オプション	なし
--markdown-table	テーブルの出力形式：html、markdown	なし
--markdown-image	画像の出力形式：html、markdown	なし
--file-ext	ファイル拡張子（fileName の代替）	自動検出

例

# Parse a URL (auto-select mode)
python scripts/docmind_parse.py https://example.com/doc.pdf

# Parse with VLM enhancement
python scripts/docmind_parse.py https://example.com/doc.pdf --enhancement VLM

# Parse the first 5 pages, output to a Markdown file
python scripts/docmind_parse.py ./report.pdf --pages 1-5 --output-file result.md

# Parse a local file via V2 mode (auto base64 encoding)
python scripts/docmind_parse.py ./contract.pdf --mode v2

# Parse with custom table/image output formats
python scripts/docmind_parse.py https://example.com/doc.pdf --markdown-table markdown --markdown-image html

# Parse headers and footers with a custom prompt
python scripts/docmind_parse.py https://example.com/doc.pdf --head-foot --user-prompt "Extract all footnotes"

# Force Alibaba Cloud POP mode
python scripts/docmind_parse.py ./contract.pdf --mode pop

---

V2 API 直接アクセス（無料モード）

URL とローカルファイル（base64）の両方のアップロードに対応しています。リクエストボディは Document、Processing、Output、Notification の 4 つのブロックで構成されます。

送信エンドポイント

POST {DOCMIND_V2_ENDPOINT}/skill/submit

完全なリクエストスキーマ：

{
  "document": {
    "fileUrl": "https://example.com/doc.pdf",
    "fileBase64": "<base64-encoded file content, alternative to fileUrl>",
    "fileName": "doc.pdf",
    "fileNameExtension": "pdf"
  },
  "processing": {
    "enhancementMode": "VLM",
    "pageIndex": "1-5",
    "headFoot": false,
    "userPrompt": "Custom prompt",
    "option": "parsing-option"
  },
  "output": {
    "outputFormat": ["markdown"],
    "markdownTable": ["html"],
    "markdownImage": ["html"],
    "docExtraParameters": {"key": "value"},
    "extraParameters": "audio-video-extra-params",
    "ossConfig": {
      "bucket": "my-bucket",
      "endpoint": "oss-cn-hangzhou.aliyuncs.com",
      "accessKeyId": "...",
      "accessKeySecret": "...",
      "securityToken": "..."
    }
  },
  "notification": {
    "enableEventCallback": false
  }
}

document.fileUrl と document.fileBase64 は同時に指定できません。V2 モードでローカルファイルを解析する場合、スクリプトがファイルを自動的に読み込み、base64 にエンコードします。fileNameExtension を明示的に指定しない場合は、ファイル拡張子から自動検出されます。

レスポンス：

{
  "success": true,
  "data": { "bizId": "docmind-20260519-xxxx" }
}

クエリエンドポイント

POST {DOCMIND_V2_ENDPOINT}/skill/query

{
  "bizId": "docmind-20260519-xxxx",
  "layoutStepSize": 100,
  "layoutNum": 0
}

レスポンス（成功時）：

{
  "success": true,
  "data": {
    "status": "success",
    "processing": 100.0,
    "layouts": [ ... ]
  }
}

レート制限：IP あたり毎秒最大 5 タスク、全体の上限は 20 です。

---

Alibaba Cloud POP 呼び出し

デフォルトの認証情報チェーンを使用してクライアントを初期化する、3 ステップの非同期ワークフローです。

1. タスクを送信 - SubmitDocParserJob / SubmitDocParserJobAdvance
2. ステータスを照会 - QueryDocParserStatus（成功または失敗になるまでポーリング）
3. 結果を取得 - GetDocParserResult（LayoutNum + LayoutStepSize によるページネーションで段階的に取得）

POP エンドポイント：docmind-api.cn-hangzhou.aliyuncs.com、API バージョン：2022-07-11

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_docmind_api20220711.client import Client as DocMindClient

cred = CredClient()
config = open_api_models.Config(
    credential=cred,
    endpoint="docmind-api.cn-hangzhou.aliyuncs.com",
    user_agent="AlibabaCloud-Agent-Skills/alibabacloud-docmind-parse/" + os.environ.get("SKILL_SESSION_ID", "unknown")
)
client = DocMindClient(config)

---

利用枠

モード	無料利用枠	上限到達後
V2 API 直接アクセス	1 日あたりの利用枠に上限あり	Alibaba Cloud サービスの有効化を促します
Alibaba Cloud POP	月 3,000 ページ	自動的に従量課金

利用枠を使い切った場合は、サービスを有効化するために https://docmind.console.aliyun.com/doc-overview にアクセスするようユーザーに促します。

---

エラー処理

エラーコード	意味	解決方法
QuotaExhausted / Throttling	クォータ超過、またはレート制限	Alibaba Cloud サービスを有効化するよう案内します
FileUrlLegal	ファイル URL が無効です	URL が一般公開されていることを確認します
InvalidFileFormat	サポートされていないファイル形式です	サポート対象の形式一覧を表示します
FileSizeExceeded	ファイルサイズが大きすぎます	V2 の上限は 5 MB、POP の上限は 150 MB です
OssAccessDeniedError / HTTP 403	URL が非公開またはアクセス制限のある OSS リソースを指しています	以下の事前検証ルールを参照してください

事前検証と例外処理

スクリプトを実行する前に、エージェントは必ず以下の確認を行ってください。

1. ローカルファイルパスの検証：入力がローカルファイルパスの場合は、スクリプトを呼び出す前にファイルが存在し、読み取り可能であることを確認してください。ファイルが存在しない場合は、直ちに処理を中止し、パスを確認するようユーザーに依頼してください。ファイル欠落エラーを回避するために、エージェントがファイルを作成、捏造、または代用しては絶対にいけません。

2. 非公開 URL の検出：入力が URL で、V2 モードで OssAccessDeniedError または HTTP 403 が返された場合、その URL は非公開であるか、認証が必要である可能性があります。この場合：

   • URL が一般公開されていないことをユーザーに伝えます。
   • 一般公開されている URL を提供するか、ファイルをローカルにダウンロードし、ローカルパスを指定して再実行するようユーザーに依頼します。スクリプトはファイルを自動的に base64 にエンコードし、V2 経由でアップロードします（--mode v2 は base64 エンコードを透過的に処理します）。

3. ネットワークに接続できない場合：スクリプトで接続エラー（例：ConnectionError、ConnectionRefused）が発生した場合は、以下を確認してください。

   • 現在の環境から DOCMIND_V2_ENDPOINT（デフォルトは docmind.aliyuncs.com）に接続できること。
   • プロキシ設定やファイアウォールルールによって、外部への HTTPS 通信がブロックされていないこと。

---

サポート対象のファイル形式

• ドキュメント：PDF、Word（doc/docx）、PPT（ppt/pptx）、Excel（xls/xlsx/xlsm）
• 画像：JPG、JPEG、PNG、BMP、GIF
• その他：Markdown、HTML、EPUB、MOBI、RTF、TXT
• 音声／動画（POP モードのみ）：MP4、MKV、AVI、MOV、WMV、MP3、WAV、AAC

---

出力形式

Markdown 出力

各レイアウトブロックの markdownContent フィールドを連結します。表は HTML テーブルとして埋め込まれます。

JSON 出力

type／subType、text、markdownContent、pageNum、index、pos などのフィールドを含む、生のレイアウト構造化データです。

---

可観測性

すべての送信 HTTP リクエスト（V2 API および Alibaba Cloud POP SDK）には、以下の User-Agent ヘッダーが設定されます。

AlibabaCloud-Agent-Skills/alibabacloud-docmind-parse/{session-id}

{session-id} の値は、実行時に SKILL_SESSION_ID 環境変数から読み取られます。この変数が設定されていない場合、値は unknown になります。

コンポーネント	値
UA テンプレート	AlibabaCloud-Agent-Skills/alibabacloud-docmind-parse/{session-id}
session-id の参照元	SKILL_SESSION_ID 環境変数
フォールバック	unknown
環境変数の例	export SKILL_SESSION_ID=agent-abc123-session-xyz

同じ SKILL_SESSION_ID の値を共有するすべてのスキル呼び出しは、サーバー側のログで単一のセッションとして関連付けられます。

---

依存関係のインストール

# POP mode
pip install "alibabacloud-docmind-api20220711>=1.0.0" \
            "alibabacloud-credentials>=1.0.0" \
            "alibabacloud-tea-openapi>=0.3.8" \
            "alibabacloud-tea-util>=0.3.0" \
            "alibabacloud-gateway-pop>=0.1.0"

# V2 mode
pip install "requests>=2.20.0"