GSP924

概要

Document AI API は、文書やメールなどの非構造化データを対象に、データを簡単に理解、分析、利用できるようにするドキュメント理解のためのソリューションです。このラボで使用する一般用フォーム プロセッサを使用すると、簡単なドキュメントから Key-Value ペアを抽出できます。

このラボでは、Document AI を使用してドキュメント パーサーを作成する方法、Google Cloud を介して Cloud コンソールとコマンドラインを使用して処理するドキュメントを送信する方法、Python を使用して同期 API 呼び出しを行う方法を学びます。

学習内容

次のタスクの実行方法について学びます。

• コンソールを使用して Document AI プロセッサを作成し、テストする。
• コマンドラインを使用して Document AI プロセッサをテストする。
• Python を使用して Document AI 同期 API 呼び出しをテストする。

設定と要件

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

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

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

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

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

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

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

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

ラボを開始して Google Cloud コンソールにログインする方法

1. [ラボを開始] ボタンをクリックします。ラボの料金をお支払いいただく必要がある場合は、表示されるダイアログでお支払い方法を選択してください。 右側の [ラボの設定とアクセス] パネルには、以下が表示されます。

   • [Google Cloud コンソールを開く] ボタン
   • このラボで使用する一時的な認証情報（ユーザー名とパスワード）
   • このラボを行うために必要なその他の情報（ある場合）

   ラボのタイマーはページの上部に表示され、残り時間が示されます。

2. [Google Cloud コンソールを開く] をクリックします（Chrome ブラウザを使用している場合は、右クリックして [シークレット ウィンドウで開く] を選択します）。

   ラボでリソースがスピンアップし、別のタブで [ログイン] ページが表示されます。

   ヒント: タブをそれぞれ別のウィンドウで開き、並べて表示しておきましょう。

   注: [アカウントの選択] ダイアログが表示された場合は、[別のアカウントを使用] をクリックします。

3. 必要に応じて、下のユーザー名をコピーして、[ログイン] ダイアログに貼り付けます。

   {{{user_0.username | "Username"}}}

   [ラボの設定とアクセス] パネルでもユーザー名を確認できます。

4. [次へ] をクリックします。

5. 以下のパスワードをコピーして、[ようこそ] ダイアログに貼り付けます。

   {{{user_0.password | "Password"}}}

   [ラボの設定とアクセス] パネルでもパスワードを確認できます。

6. [次へ] をクリックします。

   重要: ラボで指定された認証情報を使用する必要があります。ご自身の Google Cloud アカウントの認証情報は使用しないでください。 注: このラボでご自身の Google Cloud アカウントを使用すると、追加料金が発生する場合があります。

7. その後のページはクリックして先に進みます。

   • 利用規約に同意します。
   • 一時的なアカウントなので、復元オプションや 2 要素認証プロセスは設定しないでください。
   • 無料トライアルには登録しないでください。

しばらくすると、このタブで Google Cloud コンソールが開きます。

注: 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. Cloud Document AI API を有効にする

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

Cloud Document AI API を有効にする

Document AI を使用するには、API を有効にする必要があります。

1. ナビゲーション メニュー（）から、[API とサービス] > [ライブラリ] をクリックします。

2. 「Cloud Document AI API」を検索して [有効にする] ボタンをクリックし、Google Cloud プロジェクトで API を使用できるようにします。

Cloud Document AI API がすでに有効になっている場合は、[管理] ボタンが表示され、ラボの作業を進めることができます。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。

有効化された Cloud Document AI API

タスク 2. 一般用フォーム プロセッサを作成してテストする

次に、Document AI フォーム パーサーを使用して Document AI プロセッサを作成します。

プロセッサを作成する

1. コンソールのナビゲーション メニュー（）で、[Document AI] > [概要] をクリックします。

2. [プロセッサを確認] をクリックします。

3. 一般タイプのプロセッサの [フォーム パーサー] をクリックします。

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

5. [作成] をクリックして、form-parser 一般用プロセッサを作成します。

プロセッサが作成されて、プロセッサの詳細ページにプロセッサの ID、ステータス、予測エンドポイントが表示されます。

6. 今後のタスクで curl を使用して API の POST 呼び出しを行う際に使用するので、プロセッサ ID をメモしておきます。

サンプル フォームをダウンロードする

このタスクでは、Cloud Storage からサンプル フォームをダウンロードします。次のタスクでこのフォームをアップロードするには、まずローカルマシンにダウンロードする必要があります。

1. form.pdf ファイルをローカルマシンにダウンロードします。

ファイルが直接ダウンロードされます。ファイルがブラウザで開いた場合は、ブラウザのファイル操作機能を使用してファイルをダウンロードします。form.pdf ファイルは、手書きのサンプルデータを含む HEALTH INTAKE FORM です。

Document AI 処理用フォームをアップロードする

次に、ダウンロードしたサンプル フォームを form-parser プロセッサにアップロードします。その後、分析が行われ、結果がコンソールに表示されます。

1. [form-parser] ページで、[テスト ドキュメントをアップロード] ボタンをクリックします。ダイアログがポップアップ表示されるので、前のタスクでダウンロードしたファイルをアップロード用に選択します。

進行状況バーに分析プロセスの完了レベルが示され、最終的に結果が表示されます。一般用プロセッサがフォームのデータを Key-Value ペアのセットとして取り込んでいることがわかります。

ソース ドキュメントから解析された Key-Value ペアがコンソールに表示されます。左側のペインにデータが一覧表示され、右側のペインには解析されたドキュメントのソースの場所が青い長方形でハイライト表示されます。出力を確認し、結果をソースデータと比較します。

このタスクでは、コマンドラインから API 呼び出しを行って、Document AI の一般用フォーム プロセッサをテストします。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。

一般用フォーム プロセッサを作成してテストする

タスク 3. ラボ インスタンスを設定する

このセクションでは、Document AI API を使用するラボ インスタンスを設定します。

SSH を使用してラボ VM インスタンスに接続する

ラボの残りのタスクは、document-ai-dev というラボ VM で実行します。

1. ナビゲーション メニュー（）から、[Compute Engine] > [VM インスタンス] をクリックします。

2. document-ai-dev という VM インスタンスの [SSH] リンクをクリックします。

このステップには、タスク 1 で作成したプロセッサの Document AI プロセッサ ID が必要です。保存していなかった場合は、Cloud コンソールのタブで以下の操作を行います。

• ナビゲーション メニュー（）を開きます。
• [Document AI] > [プロセッサ] をクリックします。
• プロセッサの名前をクリックして、詳細ページを開きます。
• ここで、プロセッサ ID をコピーできます。

3. SSH セッションで、Document AI プロセッサ ID を格納する環境変数を作成します。[your processor id] のプレースホルダを置き換える必要があります。

export PROCESSOR_ID=[your processor id]

4. SSH セッションで、環境変数に Document AI プロセッサ ID が含まれていることを確認します。

echo Your processor ID is:$PROCESSOR_ID

5. これにより、以下のようなプロセッサ ID が出力されます。

Your processor ID is:4897d834d2f4415d

このラボの残りのタスクでは、この SSH セッションを使用します。

API リクエストを認証する

Document AI API にリクエストを送信するには、有効な認証情報を提供する必要があります。このタスクでは、サービス アカウントを作成し、そのサービス アカウントに付与される権限をラボに必要なものに制限し、その後、Document AI API リクエストの認証に使用できる認証情報をそのアカウントに対して生成します。

1. このラボ全体を通して使用するプロジェクト ID を使って環境変数を設定します。

export PROJECT_ID=$(gcloud config get-value core/project)

2. Document AI API にアクセスする新しいサービス アカウントを作成します。

export SA_NAME="document-ai-service-account" gcloud iam service-accounts create $SA_NAME --display-name $SA_NAME

3. サービス アカウントを Document AI API ユーザーロールにバインドします。

gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:$SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/documentai.apiUser"

4. 新しいサービス アカウントとしてログインするために使用する認証情報を作成し、作業ディレクトリの key.json という名前の JSON ファイルに保存します。

gcloud iam service-accounts keys create key.json \ --iam-account $SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com

5. ライブラリが認証情報を検索する際に使用する環境変数 GOOGLE_APPLICATION_CREDENTIALS を、認証情報ファイルを指すように設定します。

export GOOGLE_APPLICATION_CREDENTIALS="$PWD/key.json"

6. 環境変数 GOOGLE_APPLICATION_CREDENTIALS が、先ほど作成した認証情報 JSON ファイルのフルパスに設定されていることを確認します。

echo $GOOGLE_APPLICATION_CREDENTIALS

この環境変数は、コマンドを実行する際に使用する認証情報を指定するため、gcloud コマンドライン ツールで使用されます。このフォーム認証について詳しくは、アプリケーションのデフォルト認証情報のガイドをご覧ください。

サンプル フォームを VM インスタンスにダウンロードする

これで、サンプル フォームをダウンロードし、それを base64 エンコードして Document AI API に送信できます。

1. SSH ウィンドウで以下のコマンドを入力し、サンプル フォームを作業ディレクトリにダウンロードします。

gsutil cp gs://spls/gsp924/health-intake-form.pdf .

2. 処理用に base64 エンコードされたフォームを送信する JSON リクエスト ファイルを作成します。

echo '{"inlineDocument": {"mimeType": "application/pdf","content": "' > temp.json base64 health-intake-form.pdf >> temp.json echo '"}}' >> temp.json cat temp.json | tr -d \\n > request.json

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。

API リクエストを認証し、サンプル フォームをダウンロードする

タスク 4. curl を使用して同期ドキュメント処理リクエストを作成する

このタスクでは、curl を使用して同期 Document AI API エンドポイントを呼び出し、サンプル ドキュメントを処理します。

1. curl を使用して処理用のフォームを送信します。結果は output.json に保存されます。

export LOCATION="us" export PROJECT_ID=$(gcloud config get-value core/project) curl -X POST \ -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ https://${LOCATION}-documentai.googleapis.com/v1beta3/projects/${PROJECT_ID}/locations/${LOCATION}/processors/${PROCESSOR_ID}:process > output.json

2. output.json ファイルに API 呼び出しの結果が含まれていることを確認します。

cat output.json 認証エラーが発生した場合は、環境変数 GOOGLE_APPLICATION_CREDENTIALS が、先ほど作成した認証情報 JSON ファイルを指すように設定されていることを確認してください。IAM ポリシーが伝播するまで数分かかる場合があります。エラーが発生した場合は、もう一度お試しください。

Cloud IAM サービス アカウントのアクセス トークンは、その場で生成され、Authorization: HTTP ヘッダーを使用して API に渡されます。レスポンスには、ファイル output.json に保存される JSON 形式のデータが含まれます。

フォーム エンティティを抽出する

次に、サンプル フォームから抽出された情報をいくつか見てみましょう。

1. ドキュメントで検出された未加工のテキストを以下のように抽出します。

sudo apt-get update sudo apt-get install jq cat output.json | jq -r ".document.text"

アップロードされたドキュメントで検出されたすべてのテキストが一覧表示されます。

2. フォーム プロセッサによって検出されたフォーム フィールドのリストを抽出します。

cat output.json | jq -r ".document.pages[].formFields"

ドキュメントで検出されたすべてのフォーム フィールドのオブジェクト データが一覧表示されます。各フォームの textAnchor.startIndex 値と textAnchor.endIndex 値を使用することで、検出されたフォームの名前を document.text フィールドで特定できます。次のタスクで使用する Python スクリプトが、このマッピングを行います。

JSON ファイルは、base64 エンコードされたソース ドキュメントに加え、検出されたすべてのテキストとドキュメントのプロパティを含むため、かなり大きくなります。JSON ファイルは、テキスト エディタで開くか、jq などの JSON クエリツールを使用して調べることができます。

ドキュメントが Document AI API によって処理されたことを確認する

タスク 5. Python クライアント ライブラリを使用して Document AI フォーム プロセッサをテストする

Python Document AI クライアント ライブラリを使用して、Document AI API の同期呼び出しを行います。

次に、同期エンドポイントを使用してドキュメントを処理します。一度に大量のドキュメントを処理する場合は、非同期 API を使用できます。Document AI API を使用する方法について詳しくは、ガイドをご覧ください。

Python スクリプトを直接実行したい場合は、適切な認証情報をスクリプトに提供する必要があります。これにより、スクリプトは正しい権限で構成されたサービス アカウントを使用して API を呼び出すことができます。この認証形式の構成方法について詳しくは、サービス アカウントとしての認証に関するドキュメントをご覧ください。

Document AI Python クライアントを使用するように VM インスタンスを構成する

次に、Python Google Cloud クライアント ライブラリを VM インスタンスにインストールします。

1. SSH ターミナル シェルに以下のコマンドを入力して、ラボファイルを VM インスタンスにインポートします。

gsutil cp gs://spls/gsp924/synchronous_doc_ai.py .

2. 以下のコマンドを入力して、Document AI に必要な Python クライアント ライブラリと、このラボに必要なその他のライブラリをインストールします。

sudo apt install python3-pip python3 -m pip install --upgrade google-cloud-documentai google-cloud-storage prettytable

[Do you want to continue? (Y/n)] というメッセージが表示されたら、「Y」と入力します。

ライブラリが正常にインストールされたことが出力に示されます。

Document AI API Python コードを確認する

サンプル ファイルで Python コードを少し時間をかけて確認してください。vi や nano などお好みのエディタを使用して、SSH セッションでコードを確認できます。または、前のセクションのコマンドを使用してサンプルコードを Cloud Shell にコピーし、必要に応じてコードエディタを使用してソースコードを表示することもできます。

1. 最初の 2 つのコードブロックでは、必要なライブラリをインポートし、パラメータを解析して、Document AI プロセッサと入力データを識別する変数を初期化します。

import argparse from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage from prettytable import PrettyTable parser = argparse.ArgumentParser() parser.add_argument("-P", "--project_id", help="Google Cloud Project ID") parser.add_argument("-D", "--processor_id", help="Document AI Processor ID") parser.add_argument("-F", "--file_name", help="Input file name", default="form.pdf") parser.add_argument("-L", "--location", help="Processor Location", default="us") args = parser.parse_args()

2. process_document 関数は、Document AI プロセッサの同期呼び出しに使用されます。この関数は Document AI API クライアント オブジェクトを作成します。

API 呼び出しに必要なプロセッサ名が project_id、location、processor_id の各パラメータを使用して作成され、処理対象のドキュメントが読み込まれて mime_type 構造に格納されます。

プロセッサ名とドキュメントは Document API クライアント オブジェクトに渡され、API の同期呼び出しが行われます。リクエストが成功すると、返されるドキュメント オブジェクトのプロパティに、Document AI プロセッサによって検出されたデータが含まれていることが確認できます。

def process_document(project_id, location, processor_id, file_path ): # クライアントをインスタンス化します client = documentai.DocumentProcessorServiceClient() # プロセッサの完全なリソース名。例: # projects/project-id/locations/location/processor/processor-id # まず Cloud コンソールで新しいプロセッサを作成する必要があります name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" # ファイルをメモリに読み込みます with open(file_path, "rb") as image: image_content = image.read() # ドキュメント オブジェクトを作成します document = {"content": image_content, "mime_type": "application/pdf"} # 処理リクエストを構成します request = {"name": name, "document": document} # Document AI クライアントの同期エンドポイントを使用してリクエストを処理します result = client.process_document(request=request) return result.document

3. 次に、スクリプトは必要なパラメータを使用して process_document 関数を呼び出し、レスポンスを document 変数に保存します。

document = process_document(args.project_id,args.location,args.processor_id,args.file_name )

4. 最後のコードブロックでは、ドキュメント内で検出されたすべてのテキストを含む .text プロパティを出力し、フォーム パーサーによって検出された各フォーム フィールドのテキスト アンカー データを使用してフォーム情報を表示します。

print("Document processing complete.") # 元のテキストを出力します print("Text: \n{}\n".format(document.text)) # 指定された要素のオブジェクト ディクショナリを取得する関数を定義します def get_text(doc_element: dict, document: dict): """ Document AI はドキュメント テキスト内のオフセットによってフォーム フィールドを識別します。この関数では、オフセットをテキスト スニペットに変換します。""" response = "" # テキスト セグメントが複数行にわたる場合は、 # 異なるテキスト セグメントに格納されます for segment in doc_element.text_anchor.text_segments: start_index = ( int(segment.start_index) if segment in doc_element.text_anchor.text_segments else 0 ) end_index = int(segment.end_index) response += document.text[start_index:end_index] return response # 各 Key-Value ペアとその信頼スコアを取得します document_pages = document.pages print("Form data detected:\n") # 各ページで各フォーム フィールドを取得し、フィールド名、値、信頼スコアを表示します for page in document_pages: print("Page Number:{}".format(page.page_number)) for form_field in page.form_fields: fieldName=get_text(form_field.field_name,document) nameConfidence = round(form_field.field_name.confidence,4) fieldValue = get_text(form_field.field_value,document) valueConfidence = round(form_field.field_value.confidence,4) print(fieldName+fieldValue +" (Confidence Scores: (Name) "+str(nameConfidence)+", (Value) "+str(valueConfidence)+")\n")

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。

Document AI フォーム プロセッサをテストする

タスク 6. Document AI Python コードを実行する

サンプルコードを実行し、以前と同じファイルを処理します。

1. プロジェクト ID と IAM サービス アカウント認証情報ファイルの環境変数を作成します。

export PROJECT_ID=$(gcloud config get-value core/project) export GOOGLE_APPLICATION_CREDENTIALS="$PWD/key.json"

2. 必要なパラメータを指定して、synchronous_doc_ai.py Python プログラムを呼び出します。

python3 synchronous_doc_ai.py \ --project_id=$PROJECT_ID \ --processor_id=$PROCESSOR_ID \ --location=us \ --file_name=health-intake-form.pdf | tee results.txt

次のテキスト ブロックが出力されます。FakeDoc M.D. HEALTH INTAKE FORM Please fill out the questionnaire carefully. The information you provide will be used to complete your health profile and will be kept confidential. Date: Sally Walker Name: 9/14/19 ...

最初のテキスト ブロックは、ドキュメント内のすべてのテキストを含む単一のテキスト要素です。このテキスト ブロックにはフォームベースのデータに関する認識が含まれていないため、Date や Name などのエントリがこの未加工のテキスト値に混在しています。

次に、form-parser がドキュメント構造から推測したフォームデータを使用して、より構造化されたデータのビューを出力します。この構造化された出力には、フォーム フィールドの名前と値の信頼スコアも含まれます。このセクションの出力では、フォーム フィールド名と値の対応関係がよりわかりやすくなっています。たとえば、Date フォーム フィールドと Name フォーム フィールドが正しい値に対応付けられています。

Form data detected: Page Number:1 Phone #: (906) 917-3486 (Confidence Scores: (Name) 1.0, (Value) 1.0) ... Date: 9/14/19 (Confidence Scores: (Name) 0.9999, (Value) 0.9999) ... Name: Sally Walker (Confidence Scores: (Name) 0.9973, (Value) 0.9973) ...

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。

Document AI Python コードを実行する

お疲れさまでした

Document AI API を使用して、一般用フォーム プロセッサでドキュメントからデータを抽出することに成功しました。このラボでは、コンソールとコマンドラインを使用して Document AI プロセッサを作成してテストし、Python を使用して Document AI 同期 API 呼び出しを行いました。

次のステップと詳細情報

• 詳しくは、Cloud Document AI API ドキュメントをご覧ください。

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

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

マニュアルの最終更新日: 2026 年 3 月 10 日

ラボの最終テスト日: 2026 年 3 月 10 日

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