GSP927

概要

Document AI API は、文書やメールなどの非構造化データを対象に、データを簡単に理解、分析、利用できるようにするドキュメント理解のためのソリューションです。

このラボでは、Cloud Storage にアップロードされたドキュメントを自動的に分析するドキュメント処理パイプラインを構築します。このパイプラインでは、Document AI フォーム プロセッサを利用する Cloud Run 関数でデータを抽出して BigQuery に保存します。フォームに住所フィールドが含まれている場合、住所データは Pub/Sub トピックに送信されます。これにより、もう一つの Cloud Run 関数がトリガーされます。この関数は Geocoding API を使用して座標を追加し、結果を BigQuery に書き込みます。

このシンプルなパイプラインでは、一般用フォーム プロセッサを使用して、ラベル付き住所フィールドなどの基本的なフォームデータを検出します。より複雑なドキュメントに対しては、Document AI には、明示的なラベルがなくても詳細な情報を抽出する特殊なパーサー（このラボの範囲には含まれていません）が用意されています。たとえば、Invoice Parser は、一般的な請求書のレイアウトを理解することで、ラベルのない請求書から住所やサプライヤーの詳細を特定できます。

作成する全体的なアーキテクチャは次のようになります。

1. 住所データを含むフォームを Cloud Storage にアップロードする。
2. アップロードにより、フォームを処理する Cloud Run 関数呼び出しがトリガーされる。
3. Document AI が Cloud Run 関数から呼び出される。
4. Document AI の JSON データが Cloud Storage に保存される。
5. Cloud Run 関数によってフォームデータが BigQuery に書き込まれる。
6. Cloud Run 関数が住所を Pub/Sub トピックに送信する。
7. Pub/Sub メッセージによって、GeoCode 処理用の Cloud Run 関数がトリガーされる。
8. Geocoding API が Cloud Run 関数から呼び出される。
9. ジオコーディング データが Cloud Run 関数によって BigQuery に書き込まれる。

このアーキテクチャ例では、Cloud Run functions を使用して簡単なパイプラインを実装していますが、Document AI API 呼び出しが Cloud Run functions でサポートされているタイムアウトを超える可能性があるため、本番環境では Cloud Run functions は推奨されません。より堅牢なサーバーレス ソリューションとして、Cloud Tasks をおすすめします。

学習内容

このラボでは、次の方法について学びます。

• Document AI API を有効にする。
• Document AI API、BigQuery API、Cloud Storage API、Pub/Sub API を使用する Cloud Run 関数をデプロイする。

Cloud Run 関数を次のように構成します。

• ドキュメントが Cloud Storage にアップロードされたときにトリガーする。
• Python 用の Document AI クライアント ライブラリを使用する。
• Pub/Sub メッセージが作成されたときにトリガーする。

設定と要件

[ラボを開始] ボタンをクリックする前に

こちらの説明をお読みください。ラボには時間制限があり、一時停止することはできません。タイマーは、Google Cloud のリソースを利用できる時間を示しており、[ラボを開始] をクリックするとスタートします。

このハンズオンラボでは、シミュレーションやデモ環境ではなく実際のクラウド環境を使って、ラボのアクティビティを行います。そのため、ラボの受講中に Google Cloud にログインおよびアクセスするための、新しい一時的な認証情報が提供されます。

このラボを完了するためには、下記が必要です。

• 標準的なインターネット ブラウザ（Chrome を推奨）

注: このラボの実行には、シークレット モード（推奨）またはシークレット ブラウジング ウィンドウを使用してください。これにより、個人アカウントと受講者アカウント間の競合を防ぎ、個人アカウントに追加料金が発生しないようにすることができます。

• ラボを完了するための時間（開始後は一時停止できません）

注: このラボでは、受講者アカウントのみを使用してください。別の Google Cloud アカウントを使用すると、そのアカウントに料金が発生する可能性があります。

Cloud Shell をアクティブにする

Cloud Shell は、開発ツールと一緒に読み込まれる仮想マシンです。5 GB の永続ホーム ディレクトリが用意されており、Google Cloud で稼働します。Cloud Shell を使用すると、コマンドラインで Google Cloud リソースにアクセスできます。

1. Google Cloud コンソールの上部にある「Cloud Shell をアクティブにする」アイコン をクリックします。

2. ウィンドウで次の操作を行います。

   • Cloud Shell 情報ウィンドウで操作を進めます。
   • Cloud Shell が認証情報を使用して Google Cloud API を呼び出すことを承認します。

接続した時点で認証が完了しており、プロジェクトに各自の Project_ID、 が設定されます。出力には、このセッションの PROJECT_ID を宣言する次の行が含まれています。

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud は Google Cloud のコマンドライン ツールです。このツールは、Cloud Shell にプリインストールされており、タブ補完がサポートされています。

3. （省略可）次のコマンドを使用すると、有効なアカウント名を一覧表示できます。

gcloud auth list

4. [承認] をクリックします。

出力:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. （省略可）次のコマンドを使用すると、プロジェクト ID を一覧表示できます。

gcloud config list project

出力:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注: Google Cloud における gcloud ドキュメントの全文については、gcloud CLI の概要ガイドをご覧ください。

タスク 1. API を有効にして API キーを作成する

このラボでは、Document AI、Cloud Run functions、Cloud Build、Geocoding の API を有効にしてから、Geocoding Cloud Run 関数で必要な API キーを作成する必要があります。

1. Google Cloud コンソールの上部にある「Cloud Shell をアクティブにする」アイコン をクリックします。

2. Cloud Shell で次のコマンドを入力して、ラボに必要な API を有効にします。

gcloud services enable documentai.googleapis.com gcloud services enable cloudfunctions.googleapis.com gcloud services enable cloudbuild.googleapis.com gcloud services enable geocoding-backend.googleapis.com

3. コンソールのナビゲーション メニュー（）で、[API とサービス] > [認証情報] をクリックします。

4. [認証情報の作成] を選択し、プルダウン メニューから [API キー] を選択します。

[作成された API キー] ダイアログ ボックスに、新たに作成されたキーが表示されます。API キーは、大文字、小文字、数字、ダッシュを含む長い文字列です（例: a4db08b757294ea94c08f2df493465a1）。

5. [アクション] の下にあるその他アイコンをクリックし、ダイアログ ボックスで [API キーを編集] をクリックします。

6. [API の制限] セクションで [キーを制限] を選択し、新しい API キーの API 制限を追加します。

7. [API を選択] プルダウンをクリックし、フィルタ ボックスに「Geocoding API」と入力します。

8. [Geocoding API] を選択して、[OK] をクリックします。

9. [保存] をクリックします。

注: [キーを制限] プルダウン リストに [Geocoding API] が表示されない場合は、ページを更新して、利用可能な API のリストを更新してください。 必要な API がすべて有効になっていることを確認します。

タスク 2. ラボのソースコードをダウンロードする

このタスクでは、ソースファイルを Cloud Shell にコピーします。これらのファイルには、Cloud Run 関数のソースコードと、ラボで作成する BigQuery テーブルのスキーマが含まれています。

1. Cloud Shell で次のコマンドを入力して、このラボのソースコードをダウンロードします。

mkdir ./documentai-pipeline-demo gcloud storage cp -r \ gs://spls/gsp927/documentai-pipeline-demo/* \ ~/documentai-pipeline-demo/

タスク 3. フォーム プロセッサを作成する

Document AI の専用パーサーである Form Parser を使用して、Document AI Platform で使用する汎用フォーム プロセッサのインスタンスを作成します。この汎用フォーム プロセッサでは、あらゆる種類のドキュメントを処理でき、ドキュメント内の識別可能なテキスト要素がすべて抽出されます。タイプされたテキストだけでなく手書きのテキストも処理でき、さまざまな向きのテキスト、多数の言語に対応可能です。また、フォームデータ要素の相互関係を理解するので、テキストラベルのあるフォーム フィールドの Key-Value ペアを抽出可能です。

1. Google Cloud コンソールの検索バーに「Document AI」と入力し、プロダクト ページの検索結果をクリックします。

2. [プロセッサを確認] をクリックし、[Form パーサー] をクリックして新しいプロセッサを作成します。

3. プロセッサ名に「form-processor」を指定して、リージョンの一覧から [US（米国）] を選択します。

4. [作成] をクリックして、プロセッサを作成します。

このラボの後半で、このプロセッサのプロセッサ ID とロケーションを使用して Cloud Run 関数を構成します。これにより、Cloud Run 関数はこの特定のプロセッサを使用してサンプル請求書を処理します。

タスク 4. Cloud Storage バケットと BigQuery データセットを作成する

このセクションでは、ドキュメント処理パイプラインに必要な Google Cloud リソースを作成して、環境を準備します。

入力、出力、アーカイブ用の Cloud Storage バケットを作成する

ドキュメント処理パイプラインの入力、出力、アーカイブ用の Cloud Storage バケットを作成します。

1. Cloud Shell で次のコマンドを入力して、ラボ用の Cloud Storage バケットを作成します。

export PROJECT_ID=$(gcloud config get-value core/project) export BUCKET_LOCATION="{{{my_primary_project.default_region|REGION}}}" gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-input-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-output-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-archived-invoices

BigQuery のデータセットとテーブルを作成する

データ処理パイプラインに必要な BigQuery データセットと 3 つの出力テーブルを作成します。

1. Cloud Shell で次のコマンドを入力して、ラボ用の BigQuery テーブルを作成します。

bq --location="US" mk -d \ --description "Form Parser Results" \ ${PROJECT_ID}:invoice_parser_results cd ~/documentai-pipeline-demo/scripts/table-schema/ bq mk --table \ invoice_parser_results.doc_ai_extracted_entities \ doc_ai_extracted_entities.json bq mk --table \ invoice_parser_results.geocode_details \ geocode_details.json

Cloud コンソールで BigQuery に移動し、BigQuery SQL ワークスペースを使用して invoice_parser_results データセット内のテーブルのスキーマを調べることができます。

Pub/Sub トピックを作成する

処理パイプラインで Geocoding API のデータ拡充オペレーションをトリガーするために使用する、Pub/Sub トピックを初期化します。

1. Cloud Shell で次のコマンドを入力して、ラボ用の Pub/Sub トピックを作成します。

export GEO_CODE_REQUEST_PUBSUB_TOPIC=geocode_request gcloud pubsub topics \ create ${GEO_CODE_REQUEST_PUBSUB_TOPIC} BigQuery データセット、Cloud Storage バケット、Pub/Sub トピックが作成されていることを確認します。

タスク 5. Cloud Run 関数を作成する

データ処理パイプラインが Cloud Storage にアップロードされた請求書を処理するために使用する 2 つの Cloud Run 関数を作成します。これらの関数は、Document AI API を使用して未加工のドキュメントからフォームデータを抽出し、GeoCode API を使用してドキュメントから抽出された住所情報に関する位置情報を取得します。

2 つの Cloud Run 関数のソースコードは、コードエディタまたは他の任意のエディタを使用して確認できます。Cloud Run 関数は、Cloud Shell の次のフォルダに保存されます。

• 請求書の処理 - scripts/cloud-functions/process-invoices
• 住所のジオコーディング - scripts/cloud-functions/geocode-addresses

メインの Cloud Run 関数である process-invoices は、先ほど作成した入力ファイル ストレージ バケットにファイルがアップロードされるとトリガーされます。

関数フォルダ scripts/cloud-functions/process-invoices には、Cloud Run 関数 process-invoices を作成するために使用される 2 つのファイルが含まれています。

requirements.txt ファイルでは、関数に必要な Python ライブラリを指定します。これには、Document AI クライアント ライブラリだけでなく、Cloud Storage からファイルを読み取り、BigQuery にデータを保存し、ソリューション パイプラインの残りの関数をトリガーするメッセージを Pub/Sub に書き込むために Python コードで必要な他の Google Cloud ライブラリも含まれます。

Python ファイル main.py には、Document AI、BigQuery、Pub/Sub の各 API クライアントを作成する Cloud Run 関数のコードと、ドキュメントを処理するための次の内部関数が含まれています。

• write_to_bq - 辞書オブジェクトを BigQuery テーブルに書き込みます。この関数を呼び出す前に、スキーマが有効であることを確認する必要があります。
• get_text - フォーム名と値のテキスト アンカーを、ドキュメント内のスキャンされたテキストにマッピングします。これにより、関数はサプライヤー名や住所などの特定のフォーム要素を識別し、関連する値を抽出できます。専用の Document AI プロセッサは、そのコンテキスト情報をエンティティ プロパティに直接提供します。
• process_invoice - 非同期の Document-AI クライアント API を使用して、Cloud Storage からファイルを読み取り、次のように処理します。
  • Cloud Run 関数呼び出しをトリガーしたファイルを処理する非同期リクエストを作成します。
  • フォームデータを処理して請求書フィールドを抽出し、事前定義されたスキーマの一部である特定のフィールドのみを辞書に保存します。
  • Pub/Sub メッセージをパブリッシュして、ドキュメントから抽出された住所フォームデータを使用して Geocoding Cloud Run 関数をトリガーします。
  • フォームデータを BigQuery テーブルに書き込みます。
  • 非同期 Document AI API 呼び出しで作成された中間（出力）ファイルを削除します。
  • 入力ファイルをアーカイブ バケットにコピーします。
  • 処理済みの入力ファイルを削除します。

Cloud Run 関数 process_invoices は、次のフォーム フィールド名で検出されたフォームデータのみを処理します。

• input_file_name
• address
• supplier
• invoice_number
• purchase_order
• date
• due_date
• subtotal
• tax
• total

もう一つの Cloud Run 関数である geocode-addresses は、新しいメッセージが Pub/Sub トピックに到着するとトリガーされ、Pub/Sub メッセージからパラメータ データを抽出します。

Cloud Storage にアップロードされたドキュメントを処理する Cloud Run 関数を作成する

Document AI フォーム プロセッサを使用して、Cloud Storage バケットにアップロードされたフォーム ドキュメントを解析する Cloud Run 関数を作成します。

1. 次のコマンドを実行して、プロジェクトの Cloud Storage サービス エージェントのメールアドレスを取得します。

gcloud storage service-agent --project=$PROJECT_ID

2. 次のコマンドを実行して、必要な権限を Cloud Storage サービス アカウントに付与します。

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") gcloud iam service-accounts create "service-$PROJECT_NUMBER" \ --display-name "Cloud Storage Service Account" || true gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/pubsub.publisher" gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator" 注: Cloud Storage サービス アカウントが存在する場合は、エラーを無視できます。

3. 次のように請求書プロセッサの Cloud Run 関数を作成します。

cd ~/documentai-pipeline-demo/scripts export CLOUD_FUNCTION_LOCATION="{{{my_primary_project.default_region|REGION}}}" gcloud functions deploy process-invoices \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_invoice \ --runtime=python39 \ --source=cloud-functions/process-invoices \ --timeout=400 \ --env-vars-file=cloud-functions/process-invoices/.env.yaml \ --trigger-resource=gs://${PROJECT_ID}-input-invoices \ --trigger-event=google.storage.object.finalize 注: 権限エラーでコマンドが失敗した場合は、1 分待ってからもう一度お試しください。

住所からジオコード データを検索する Cloud Run 関数を作成する

Pub/Sub メッセージから住所データを受け取り、Geocoding API を使用して住所を正確に特定する Cloud Run 関数を作成します。

1. 次のように、Geocoding Cloud Run 関数を作成します。

cd ~/documentai-pipeline-demo/scripts gcloud functions deploy geocode-addresses \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_address \ --runtime=python39 \ --source=cloud-functions/geocode-addresses \ --timeout=60 \ --env-vars-file=cloud-functions/geocode-addresses/.env.yaml \ --trigger-topic=${GEO_CODE_REQUEST_PUBSUB_TOPIC}

タスク 6. Cloud Run 関数の環境変数を編集する

このタスクでは、Cloud コンソールで各関数の環境変数を編集してラボ固有のパラメータを反映させます。これで Cloud Run 関数の構成が完了します。

Cloud Run 関数 process-invoices の環境変数を編集する

process-invoices 関数の Cloud Run 関数環境変数を設定します。

1. Cloud コンソールの検索バーに「Cloud Run functions」と入力し、プロダクト ページの検索結果をクリックします。

Cloud Run コンソールにリダイレクトされるので、[Cloud Run 関数（第 1 世代）に移動する] をクリックして、デプロイされた関数 process-invoices と geocode-addresses を確認します。

注: [Cloud Run 関数（第 1 世代）に移動する] のリンクが表示されない場合は、Cloud Run コンソールを更新してください。

2. Cloud Run 関数 process-invoices をクリックして、管理ページを開きます。
3. [編集] をクリックします。
4. [ランタイム、ビルド、接続、セキュリティの設定] をクリックして、そのセクションを開きます。
5. [ランタイム環境変数] で、GCP_PROJECT 変数と、プロジェクト ID に一致する値を追加します。
6. [ランタイム環境変数] で、PROCESSOR_ID の値を、先ほど作成した請求書プロセッサの ID と一致するように更新します。
7. [ランタイム環境変数] で、PARSER_LOCATION の値を、先ほど作成した請求書プロセッサのリージョンと一致するように更新します。us または eu になります。このパラメータは必ず小文字にしてください。
8. [次へ] をクリックして [.env.yaml] を選択し、請求書プロセッサの PROCESSOR_ID、PARSER_LOCATION、GCP_PROJECT の値をもう一度更新します。

9. [デプロイ] をクリックします。

Cloud Run 関数 Process Invoices をデプロイする

Cloud Run 関数 geocode-addresses の環境変数を編集する

GeoCode データ拡充関数の Cloud Run 関数環境変数を設定します。

1. Cloud Run 関数 geocode-addresses をクリックして、管理ページを開きます。
2. [編集] をクリックします。
3. [ランタイム、ビルド、接続、セキュリティの設定] をクリックして、そのセクションを開きます。
4. [ランタイム環境変数] で、API_key の値をタスク 1 で作成した API キーの値と一致するように更新します。
5. [次へ] をクリックして [.env.yaml] を選択し、API_key の値を前の手順で設定した API キーの値と一致するように更新します。
6. [デプロイ] をクリックします。

Cloud Run 関数 Geocode Addresses をデプロイする

タスク 7. エンドツーエンドのソリューションをテストして検証する

テストデータを Cloud Storage にアップロードし、パイプラインでドキュメントが処理されて抽出されたデータが強化されていく進行状況をモニタリングします。

1. Cloud Shell で次のコマンドを入力して、Cloud Run 関数 process-invoices をトリガーするサンプル フォームを Cloud Storage バケットにアップロードします。

export PROJECT_ID=$(gcloud config get-value core/project) gsutil cp gs://spls/gsp927/documentai-pipeline-demo/sample-files/* gs://${PROJECT_ID}-input-invoices/

2. Cloud コンソールの検索バーに「Cloud Run functions」と入力し、プロダクト ページの検索結果をクリックします。
3. Cloud Run 関数 process-invoices をクリックして、管理ページを開きます。
4. [ログ] をクリックします。

関数の作成と環境変数を構成するための更新に関連するイベントが表示されます。続いて、処理されるファイルの詳細と、Document AI によって検出されたデータを示すイベントが表示されます。

LoadJob で関数の実行が終了したことを示す最終イベントが表示されるまで、イベントを監視します。エラーが報告された場合は、前のセクションの .env.yaml ファイルで設定したパラメータが正しいことを再確認してください。特に、プロセッサ ID、ロケーション、プロジェクト ID が有効であることを確認してください。イベントリストは自動的には更新されません。

処理の最後に、BigQuery テーブルに Document AI で抽出されたエンティティと、Geocoding API によって提供された拡充データ（Document AI プロセッサが、アップロードされたドキュメントで住所データを検出した場合のみ）が入力されます。

BigQuery コンソールを開く

1. Google Cloud コンソールで、ナビゲーション メニュー > [BigQuery] を選択します。

[Cloud コンソールの BigQuery へようこそ] メッセージ ボックスが開きます。このメッセージ ボックスには、クイックスタート ガイドとリリースノートへのリンクが表示されます。

2. [完了] をクリックします。

BigQuery コンソールが開きます。

3. [エクスプローラ] でプロジェクト ID を開きます。

4. [invoice_parser_results] を開きます。

5. [doc_ai_extracted_entities] を選択して [プレビュー] をクリックします。

請求書プロセッサによって請求書から抽出されたフォーム情報が表示され、住所情報とサプライヤー名が検出されていることがわかります。

6. [geocode_details] を選択して [プレビュー] をクリックします。

Document AI で抽出できた住所データを含む請求書ごとに、書式設定済みの住所、緯度、経度が表示されます。

エンドツーエンドのパイプラインがフォームデータと住所データを処理したことを確認します。

お疲れさまでした

Document AI API と他の Google Cloud サービスを使用して、エンドツーエンドの請求書処理パイプラインを構築できました。このラボでは、Document AI API を有効にし、Document AI API、BigQuery API、Cloud Storage API、Pub/Sub API を使用する Cloud Run 関数をデプロイし、ドキュメントが Cloud Storage にアップロードされたときにトリガーされるように Cloud Run 関数を構成しました。また、Python 用の Document AI クライアント ライブラリを使用し、Pub/Sub メッセージが作成されたときにトリガーされるように Cloud Run 関数を構成しました。

次のステップと詳細情報

• このフォーム認証の詳細については、ガイドをご覧ください。

Google Cloud トレーニングと認定資格

Google Cloud トレーニングと認定資格を通して、Google Cloud 技術を最大限に活用できるようになります。必要な技術スキルとベスト プラクティスについて取り扱うクラスでは、学習を継続的に進めることができます。トレーニングは基礎レベルから上級レベルまであり、オンデマンド、ライブ、バーチャル参加など、多忙なスケジュールにも対応できるオプションが用意されています。認定資格を取得することで、Google Cloud テクノロジーに関するスキルと知識を証明できます。

マニュアルの最終更新日: 2025 年 8 月 26 日

ラボの最終テスト日: 2025 年 7 月 29 日

Copyright 2025 Google LLC. All rights reserved. Google および Google のロゴは Google LLC の商標です。その他すべての企業名および商品名はそれぞれ各社の商標または登録商標です。