Batch Transformで文書を一括解析する

Amazon SageMaker AIのBatch Transformを使用すると、Amazon S3に保存したPDFや画像をジョブ単位でまとめて解析できます。ジョブの開始時に推論用インスタンスが起動し、完了後に自動で終了するため、夜間バッチや大量文書の一括処理に適しています。

このページでは、AWS Marketplace版YomiToku-ProのDocument AnalyzerまたはTable Semantic Parserを使ってBatch Transformジョブを実行し、解析結果をYomiToku-Clientで用途に応じた形式へ変換するまでを説明します。

Document Analyzerの出力はMarkdown、CSV、HTMLへ変換できます。Table Semantic Parserの出力は、表のセル・Key-Value・グリッド・段落を保持するJSONとして、structured（既定）、simple、rawの3形式へ変換できます。

利用できる推論方式

AWS Marketplaceのモデルパッケージでは、リアルタイム推論とBatch Transformを利用できます。非同期推論は利用できません。

このページで行うこと

1. YomiToku-ProのAmazon SageMaker AIモデルを準備する
2. モデルの実行ロールへS3権限を設定する
3. 入力ファイルをS3へアップロードする
4. Batch Transformジョブを作成する
5. 出力された.outファイルをダウンロードする
6. YomiToku-ClientでMarkdownやCSVへ変換する

このページでは、次の値を例として使用します。実際の環境に合わせて読み替えてください。

項目	例
モデル名	yomitoku-pro-document-analyzer-lite
ジョブ名	yomitoku-pro-document-analyzer-lite-batch-0000
入力先	s3://YOUR_BUCKET/input/
出力先	s3://YOUR_BUCKET/output/
インスタンスタイプ	ml.g4dn.xlarge
リージョン	ap-northeast-1

表中のモデル名とジョブ名はDocument Analyzer Liteの例です。Table Semantic Parserを使う場合は、Table Semantic Parser製品から作成したモデル名（例: yomitoku-pro-table-semantic-parser）へ読み替えてください。

ジョブ名は実行ごとに変更してください

Batch Transformのジョブ名は、AWSアカウントとリージョン内で一意である必要があります。上記のジョブ名は初回実行用の例です。再実行時は末尾の番号や日時を変更してください。

事前準備

• AWS Marketplaceで利用するYomiToku-Pro製品をサブスクライブしていること
• サブスクライブしたモデルパッケージからAmazon SageMaker AIモデルを作成していること
• 入出力に使用するS3バケットがあること
• AWS CLIを使う場合は、認証情報とリージョンを設定していること

1. Amazon SageMaker AIモデルを準備する

モデルをまだ作成していない場合は、Amazon SageMaker AIモデルを作成するの手順で作成してください。Batch Transformで必要なのはモデルまでです。リアルタイム推論用のエンドポイント設定やエンドポイントは作成しません。

モデル名と、Batch Transformで使用するIAMロールを設定する

Model Package ARNを取得する

AWS CLIでモデルを作成する場合は、サブスクライブした製品のModel Package ARNが必要です。Amazon SageMaker AIコンソールの AWS Marketplace resources > モデルパッケージ から対象製品とバージョンを開き、Model Package ARNをコピーします。

YomiToku-Clientをインストール済みの場合は、次のコマンドから対象製品のモデルパッケージ一覧を開けます。

# 通常版
yomitoku-client sagemaker configure \
  --product document-analyzer \
  --region ap-northeast-1

# Lite版
yomitoku-client sagemaker configure \
  --product document-analyzer-lite \
  --region ap-northeast-1

# Table Semantic Parser
yomitoku-client sagemaker configure \
  --product table-semantic-parser \
  --region ap-northeast-1

製品とリージョンを確認してください

Document Analyzer、Document Analyzer Lite、Table Semantic Parserはそれぞれ別のMarketplace製品で、Model Package ARNも異なります。Batch Transformジョブと同じリージョンにある、利用する製品のARNを選択してください。

既存モデルのModel Package ARNは、次のコマンドでも確認できます。

aws sagemaker describe-model \
  --model-name YOUR_MODEL_NAME \
  --query 'PrimaryContainer.ModelPackageName' \
  --output text \
  --region ap-northeast-1

YomiToku-Pro - Document Analyzer Liteを利用する

Lite版は通常版とは別のAWS Marketplace製品です。Lite版製品をサブスクライブし、そのModel Package ARNからモデルを作成してください。環境変数やモデル名だけで通常版をLite版へ切り替えることはできません。

利用するAWS Marketplaceのモデルパッケージを選択する

YomiToku-Pro - Table Semantic Parserを利用する

Table Semantic ParserはDocument Analyzerとは別のAWS Marketplace製品です。YomiToku-Pro - Table Semantic Parserをサブスクライブし、そのModel Package ARNから専用モデルを作成してください。Document Analyzerのモデルを指定しても、Table Semantic Parserのcells、kv_items、gridsは出力されません。

AWS CLIでモデルを作成する場合は、configure --product table-semantic-parserで確認したARNをPrimaryContainer.ModelPackageNameへ設定します。Batch Transformジョブでは、そのモデル名（以下の例ではyomitoku-pro-table-semantic-parser）を指定します。

2. モデルの実行ロールへS3権限を設定する

S3へアクセスするのはモデル作成時の実行ロールです

Batch TransformがS3の入力ファイルを読み書きするときは、モデルの作成時に選択した実行ロール（Execution role）が使われます。AWSマネジメントコンソールへサインインしているAdminロールや、AWS CLIのプロファイルに付与したS3権限は使われません。

実行ロールは、Amazon SageMaker AIコンソールの Deployments & inference > モデル > 対象モデル にある Execution role ARNで確認できます。AWS CLIでは次のコマンドを実行します。

aws sagemaker describe-model \
  --model-name yomitoku-pro-document-analyzer-lite \
  --query ExecutionRoleArn \
  --output text \
  --region ap-northeast-1

実行ロールには、入力プレフィックスの一覧・読み取り権限と、出力プレフィックスへの書き込み権限を付与します。次は、s3://YOUR_BUCKET/input/から読み取り、s3://YOUR_BUCKET/output/へ書き込む場合の例です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR_BUCKET",
      "Condition": {
        "StringLike": {
          "s3:prefix": ["input", "input/*"]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::YOUR_BUCKET/input/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::YOUR_BUCKET/output/*"
    }
  ]
}

3. 入力ファイルをS3へアップロードする

次の例では、ローカルのinputディレクトリにあるPDFをアップロードします。

aws s3 cp ./input/ s3://YOUR_BUCKET/input/ \
  --recursive \
  --exclude "*" \
  --include "*.pdf"

入力形式に応じて、ジョブへ次のContent-Typeを指定します。

入力形式	Content-Type
PDF	application/pdf
JPEG	image/jpeg
PNG	image/png
TIFF	image/tiff

1つのジョブには同じ形式のファイルを入れてください

Content-Typeはジョブ全体で1つだけ指定します。PDFとPNGなど、形式の異なるファイルは入力プレフィックスまたはジョブを分けてください。また、出力プレフィックスは入力プレフィックスの外に設定してください。

4. Batch Transformジョブを作成する

AWSマネジメントコンソールを使う場合

1. 入力ファイルと同じリージョンのAmazon SageMaker AIコンソールを開きます。

2. Deployments & inference > バッチ変換ジョブ を開きます。

   

   Deployments & inferenceからバッチ変換ジョブを開く

3. バッチ変換ジョブを作成 を選択します。

4. ジョブ名とYomiToku-Proのモデル名を指定します。

5. 対応するインスタンスタイプとインスタンス数を指定します。最初は1台での動作確認を推奨します。

   

   ジョブ名、モデル、インスタンスを設定する

6. 入力データを次のように設定します。

   項目	設定値
   S3データタイプ	S3Prefix
   S3の場所	s3://YOUR_BUCKET/input/
   Content-Type	application/pdf
   圧縮タイプ	None
   分割タイプ	None

7. 出力データを次のように設定します。

   項目	設定値
   S3出力先	s3://YOUR_BUCKET/output/
   Accept	application/json
   結合方法	None

   

   S3の入力先、Content-Type、出力先を設定する

8. ジョブを作成します。

   

   ジョブが作成され、文書の解析が開始される

SplitType=Noneを指定すると、1つのPDFまたは画像が1回の推論リクエストとして渡されます。複数のファイルは複数のインスタンスで処理できますが、1つの大きなPDFが複数のインスタンスへ分割されるわけではありません。大きなPDFで処理時間が問題になる場合は、事前にファイルを分割してください。

AWS CLIを使う場合

次のコマンドはPDFを処理する例です。

aws sagemaker create-transform-job \
  --transform-job-name yomitoku-pro-document-analyzer-lite-batch-0000 \
  --model-name yomitoku-pro-document-analyzer-lite \
  --transform-input 'DataSource={S3DataSource={S3DataType=S3Prefix,S3Uri=s3://YOUR_BUCKET/input/}},ContentType=application/pdf,CompressionType=None,SplitType=None' \
  --transform-output 'S3OutputPath=s3://YOUR_BUCKET/output/,Accept=application/json,AssembleWith=None' \
  --transform-resources 'InstanceType=ml.g4dn.xlarge,InstanceCount=1' \
  --max-concurrent-transforms 1 \
  --max-payload-in-mb 100 \
  --region ap-northeast-1

MaxPayloadInMBの既定値は6 MB、設定可能な最大値は100 MBです。この例では6 MBを超えるPDFも処理できるよう、100 MBを指定しています。100 MBを超えるファイルは事前に分割してください。

JPEG、PNG、TIFFを処理するときは、ContentTypeを入力形式に合わせて変更します。

Table Semantic ParserでもBatch Transformの入出力設定は同じです。--model-nameだけを、Table Semantic Parser製品から作成したモデルへ変更します。

aws sagemaker create-transform-job \
  --transform-job-name yomitoku-pro-tsp-batch-0000 \
  --model-name yomitoku-pro-table-semantic-parser \
  --transform-input 'DataSource={S3DataSource={S3DataType=S3Prefix,S3Uri=s3://YOUR_BUCKET/input/}},ContentType=application/pdf,CompressionType=None,SplitType=None' \
  --transform-output 'S3OutputPath=s3://YOUR_BUCKET/output/,Accept=application/json,AssembleWith=None' \
  --transform-resources 'InstanceType=ml.g4dn.xlarge,InstanceCount=1' \
  --max-concurrent-transforms 1 \
  --max-payload-in-mb 100 \
  --region ap-northeast-1

ジョブの状態を確認する

aws sagemaker describe-transform-job \
  --transform-job-name yomitoku-pro-document-analyzer-lite-batch-0000 \
  --query '{Status:TransformJobStatus,FailureReason:FailureReason}' \
  --region ap-northeast-1

TransformJobStatusがCompletedになれば完了です。Failedの場合は、FailureReasonとAmazon CloudWatch Logsの/aws/sagemaker/TransformJobsを確認してください。

5. .outファイルを確認・ダウンロードする

出力先を一覧表示します。

aws s3 ls s3://YOUR_BUCKET/output/ --recursive

入力したオブジェクトごとに、元のファイル名に.outを付けたJSONファイルが作成されます。

入力: s3://YOUR_BUCKET/input/document.pdf
出力: s3://YOUR_BUCKET/output/document.pdf.out

入力プレフィックス以下にサブフォルダがある場合は、その階層に応じたサブフォルダへ保存されます。実際のS3 URIはaws s3 lsの結果で確認してください。

Table Semantic Parserの.outには、ページごとのtables、cells、kv_items、grids、paragraphs、wordsを含むraw解析結果が保存されます。このraw出力は、次節のconvertでstructuredまたはsimpleへ変換できるため、元データとして保管してください。

aws s3 cp \
  s3://YOUR_BUCKET/output/document.pdf.out \
  ./document.pdf.out

6. YomiToku-Clientで出力を変換する

Document Analyzerの.outを変換する

.outファイルにはYomiToku-Proの解析結果がJSON形式で保存されています。yomitoku-client convertを使用すると、再推論せずにMarkdown、CSV、HTMLへ変換できます。

yomitoku-client convert document.pdf.out \
  --format md,csv,html \
  --output-dir ./converted

元のPDFを保管している場合は、--srcを指定するとMarkdownやHTMLで使用する図の切り出し画像も出力できます。

yomitoku-client convert document.pdf.out \
  --format md,html \
  --src document.pdf \
  --output-dir ./converted

Table Semantic Parserの.outを変換する

Table Semantic Parserの出力を変換するときは、--api table-semantic-parserを指定します。出力形式はJSONのみです。オプションを省略すると、Key-Valueとグリッドのテキストに由来セルのID・座標を付けたstructured JSONを出力します。

# structured（既定）
yomitoku-client convert document.pdf.out \
  --api table-semantic-parser \
  --output-dir ./structured

# 座標やセル参照を除いたテキスト中心のsimple
yomitoku-client convert document.pdf.out \
  --api table-semantic-parser \
  --simple \
  --output-dir ./simple

# cells、words、セルID参照を保持するraw
yomitoku-client convert document.pdf.out \
  --api table-semantic-parser \
  --raw \
  --output-dir ./raw

ディレクトリを指定すると、配下の.outを一括変換できます。

yomitoku-client convert ./batch-output \
  --api table-semantic-parser \
  --simple \
  --output-dir ./converted

YomiToku Studioから保存した帳票テンプレートを適用する場合は、座標変換に使用する元画像またはPDFを--srcで指定します。--srcには単一ファイル、または元文書を同じ名前で保存したディレクトリを指定できます。

yomitoku-client convert document.pdf.out \
  --api table-semantic-parser \
  --src document.pdf \
  --studio-template templates/application.template.json \
  --simple \
  --output-dir ./corrected

--simpleと--rawは同時に指定できません。structuredとsimpleではcellsやwordsを省略するため、後から別形式へ変換またはテンプレートを適用する可能性がある場合は、Batch Transformの.outまたはraw JSONも保管してください。

ローカルでの確認だけでなく、実運用ではAWS LambdaなどでYomiToku-Clientを実行し、Batch Transformの出力を後続システム向けの形式へ変換する構成を想定しています。詳細はBatch Transform出力の変換を参照してください。

定期的に実行する場合

Batch Transform自体にはスケジュール機能がありません。定期実行する場合は、次のようにAWSサービスを組み合わせます。

EventBridge Scheduler
        ↓
Step Functions
        ↓
Amazon SageMaker AI Batch Transform
        ↓
出力先S3 ──→ AWS Lambda（YomiToku-Client）──→ 後続システム

EventBridge SchedulerからStep Functionsを起動し、Step FunctionsからBatch Transformジョブを作成します。ジョブ完了後は、AWS LambdaなどでYomiToku-Clientを実行してMarkdownやCSVへ変換できます。

定期実行で同じ入力プレフィックスを指定すると、既存ファイルも再処理されます。input/YYYY-MM-DD/のように実行単位でプレフィックスを分け、ジョブ名も実行ごとに変更してください。

トラブルシューティング

getObjectMetadataで403 Forbiddenになる

Got client error from S3 due to '403 Forbidden' processing getObjectMetadata

getObjectMetadataは、S3オブジェクトのサイズやContent-Typeを確認するHeadObject相当の処理です。s3:GetObjectMetadataというIAMアクションを追加する必要はありません。対象モデルの実行ロールに、入力オブジェクトへのs3:GetObjectがあるか確認してください。

コンソールから作成したモデルとAWS CLIから作成したモデルでは、実行ロールが異なることがあります。まずジョブのモデル名を確認し、続けてモデルのExecutionRoleArnを確認します。

aws sagemaker describe-transform-job \
  --transform-job-name YOUR_JOB_NAME \
  --query ModelName \
  --output text \
  --region ap-northeast-1

aws sagemaker describe-model \
  --model-name YOUR_MODEL_NAME \
  --query ExecutionRoleArn \
  --output text \
  --region ap-northeast-1

Unsupported content typeになる

TransformInput.ContentTypeと入力ファイルの形式が一致しているか確認してください。同じ入力プレフィックスへPDFと画像を混在させないでください。

出力ファイルが見つからない

aws s3 ls s3://YOUR_BUCKET/output/ --recursiveを実行し、出力プレフィックス以下を確認してください。入力キーの階層に応じたサブフォルダへ保存されている場合があります。

ジョブがFailedになる

describe-transform-jobのFailureReasonと、Amazon CloudWatch Logsの/aws/sagemaker/TransformJobsを確認してください。大きなファイルだけが失敗する場合は、ペイロードサイズや処理時間を切り分けるため、小さなPDFまたは画像で再実行してください。

関連ドキュメント

• YomiToku-ProをAmazon SageMaker AIへデプロイする
• Batch Transform出力を変換する
• Table Semantic Parserの出力形式
• YomiToku StudioテンプレートをPython APIで適用する
• Amazon SageMaker AIのBatch Transform