document-granular-decompose

ドキュメントの粒度を保った分解

主な目標

• POST /mineru_with_images を通じてローカルドキュメントを解析します。
• 常に return_txt=true を強制します。
• エンドポイント、リクエストの認証情報、モデルのルーティングに関する環境変数を読み取ります。
  • UNSTRUCTURED_API_BASE_URL（例：https://your-unstructured-host:7770）
  • UNSTRUCTURED_AUTH_TOKEN
  • UNSTRUCTURED_PROVIDER（任意）
  • UNSTRUCTURED_MODEL（任意）
• プレーンテキストのフルテキストのみを返します（API の txt を優先し、存在しない場合は result[].text を連結します）。

実行条件

• PDF／Office／画像ファイルから、信頼性の高いドキュメントのフルテキスト抽出が必要な場合。
• 画像対応の MinerU 解析が必要で、後続のチャンク分割／検索／要約にはテキスト出力のみを使用する場合。
• プロバイダー／モデル／トークンの入力を、場当たり的なコマンドパラメーターではなく環境変数で標準化する場合。

ワークフロー

1. 環境変数を準備します。

export UNSTRUCTURED_AUTH_TOKEN="your-fastapi-bearer-token"
export UNSTRUCTURED_API_BASE_URL="https://your-unstructured-host:7770"
# Optional routing overrides. Omit them to let the server choose its defaults.
export UNSTRUCTURED_PROVIDER="vllm"
export UNSTRUCTURED_MODEL="Qwen/Qwen3.5-122B-A10B-FP8"

2. 抽出を実行し、フルテキストを標準出力に出力します。

python3 scripts/mineru_fulltext_extract.py \
  --file "/absolute/path/to/document.pdf"

3. 必要に応じてフルテキストをローカルファイルに保存します。

python3 scripts/mineru_fulltext_extract.py \
  --file "/absolute/path/to/document.pdf" \
  --output "/absolute/path/to/fulltext.txt"

リクエストの仕様

• エンドポイントの解決順序：
  • 指定されている場合は --api-url
  • それ以外の場合は UNSTRUCTURED_API_BASE_URL + /mineru_with_images
  • どちらも指定されていない場合は、不足している環境変数のエラーを出して即座に終了します
• メソッド：POST multipart form。
• クエリパラメーター：
  • return_txt=true を強制します（スクリプトで常に設定します）。
• 送信するフォームフィールド：
  • file（必須）
  • provider（任意。UNSTRUCTURED_PROVIDER が設定されている場合）
  • model（任意。UNSTRUCTURED_MODEL が設定されている場合）
• 送信するヘッダー：
  • Authorization: Bearer $UNSTRUCTURED_AUTH_TOKEN

対応ファイル形式（厳密）

• 対応ファイル形式：
  • .bmp, .doc, .docm, .docx, .dot, .dotx, .gif, .jp2, .jpeg, .jpg, .odp, .odt, .pdf, .png, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .tiff, .webp, .xls, .xlsm, .xlsx, .xlt, .xltx
• Office 形式：
  • .doc, .docm, .docx, .dot, .dotx, .odp, .odt, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .xls, .xlsm, .xlsx, .xlt, .xltx
• それ以外の拡張子は、API リクエストを送信する前に拒否されます。

出力ルール

• 成功時の出力はプレーンテキストのフルテキストのみとします。
• 確認済みの上流 Markdown のアンダースコアエスケープ（\_ から _）を、対応する両方のレスポンス形式で正規化します。それ以外のバックスラッシュとエスケープは保持します。
• フルテキストの取得元の優先順位：
  1. response.txt
  2. 空ではない response.result[].text を空行で連結
• ユーザーがデバッグを明示的に要求しない限り、チャンクのメタデータ／JSON は出力しません。

エラー処理

• 必須の環境変数（UNSTRUCTURED_API_BASE_URL、UNSTRUCTURED_AUTH_TOKEN）がない場合は、対処方法を示すメッセージを出して即座に終了します。
• UNSTRUCTURED_PROVIDER または UNSTRUCTURED_MODEL がない場合は、フォームフィールドを省略し、サービスにデフォルト値を選択させます。
• HTTP 401／403：トークン／認証の問題を報告します。
• HTTP 4xx／5xx：ステータスと、取得可能な場合は API エラー本文を出力します。
• レスポンスにテキストがない場合は、スキーマ不一致エラーを明示して終了します。

参照資料

• references/env.md
• references/request-response.md

アセット

• assets/config.example.env

スクリプト

• scripts/mineru_fulltext_extract.py