GSP925

概要

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

このラボでは、Python で Document AI API を使用して一般用のフォーム プロセッサ、ドキュメント OCR プロセッサなどのさまざまなプロセッサを作成し、その後 Python を使用して同期および非同期 API 呼び出しを行います。ラボでは Vertex AI Workbench インスタンスが自動的に作成され、これを JupyterLab ノートブックで使用して Document AI の Python クライアント モジュールを操作します。

目標

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

• Document AI API を有効にし、プロセッサを作成する
• Vertex AI Workbench インスタンスに Python のクライアント ライブラリをインストールする
• スキャンしたフォームのデータを Python を使って解析し、同期 API 呼び出しを行う
• スキャンしたフォームのデータを Python を使って解析し、非同期 API 呼び出しを行う

設定と要件

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

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

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

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

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

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

• ラボを完了するために十分な時間を確保してください。ラボをいったん開始すると一時停止することはできません。

注: すでに個人の Google Cloud アカウントやプロジェクトをお持ちの場合でも、このラボでは使用しないでください。アカウントへの追加料金が発生する可能性があります。

Cloud Shell をアクティブにする

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

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

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

Your Cloud Platform project in this session is set to YOUR_PROJECT_ID

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

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

gcloud auth list

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

4. 出力は次のようになります。

出力:

ACTIVE: * ACCOUNT: student-01-xxxxxxxxxxxx@qwiklabs.net To set the active account, run: $ gcloud config set account `ACCOUNT`

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

gcloud config list project

出力:

[core] project = <project_ID>

出力例:

[core] project = qwiklabs-gcp-44776a13dea667a6 注: Google Cloud における gcloud ドキュメントの全文については、gcloud CLI の概要ガイドをご覧ください。

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

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

Cloud Document AI API を有効にする

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

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

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

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

Cloud Document AI API が有効になっていることを確認する

一般用フォーム プロセッサを作成する

Document AI の Form Parser を使用して Document AI プロセッサを作成します。

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

2. [プロセッサを確認] をクリックして、一般タイプのプロセッサの [Form Parser] を選択します。

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

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

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

5. 今後のタスクで JupyterLab ノートブックの変数を更新するために必要になるので、プロセッサ ID をメモしておきます。

タスク 2. Document AI API 呼び出しを実行するよう Vertex AI Workbench インスタンスを構成する

次に、ラボの開始時に作成された Vertex AI Workbench インスタンスで実行中の JupyterLab に接続してから、今後のタスク用にこの環境を構成します。

1. Google Cloud コンソールのナビゲーション メニューで、[Vertex AI] > [ワークベンチ] をクリックします。

2. インスタンスを見つけて、[JupyterLab を開く] ボタンをクリックします。

Workbench インスタンスの JupyterLab インターフェースが新しいブラウザタブで開きます。

3. [ターミナル] をクリックして、Vertex AI Workbench インスタンスでターミナル シェルを開きます。

4. ターミナル シェルに次のコマンドを入力して、ラボファイルを Vertex AI Workbench インスタンスにインポートします。

gsutil cp {{{project_0.startup_script.notebook_files_path|notebook_files_path}}} .

5. ターミナル シェルに次のコマンドを入力して、Document AI に必要な Python クライアント ライブラリとその他の必要なライブラリをインストールします。

python -m pip install --upgrade google-cloud-core google-cloud-documentai google-cloud-storage prettytable

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

注: 権限関連のエラーが表示された場合は、コマンドを再実行して、ライブラリのインストールを正常に完了します。権限が適用されるまで数分かかる場合があります。

6. ターミナル シェルに次のコマンドを入力して、サンプルの医療機関の受け付けフォームをインポートします。

gsutil cp {{{project_0.startup_script.health_intake_form_path|form_path}}} form.pdf

7. ノートブック インターフェースで、 という JupyterLab ノートブックを開きます。

8. [Select Kernel] ダイアログで、使用可能なカーネルのリストから [Python 3] を選択します。

Vertex AI インスタンスが同期 Document AI API 呼び出し用に準備されていることを確認する

タスク 3. 同期ドキュメント処理リクエストを作成する

同期 Document AI API 呼び出しを使用して、ドキュメント処理呼び出しを行います。一度に大量のドキュメントを処理する場合は、後のタスクで取り上げる非同期 API を使用することもできます。

同期 Document AI API 呼び出しの Python コードを確認する

ノートブックで Python コードを確認します。

最初のコードブロックでは、必要なライブラリをインポートして、いくつかの変数を初期化します。

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage from prettytable import PrettyTable project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' file_path = 'form.pdf'

Set your Processor ID コードセルでは、プロセッサ ID を設定します。ノートブックでドキュメントを処理するには、事前にプロセッサ ID を手動で設定する必要があります。

processor_id = 'PROCESSOR_ID' # TODO: 有効なプロセッサ ID に置き換えます

このステップには、タスク 1 で作成したプロセッサの Document AI プロセッサ ID が必要です。

ヒント: プロセッサ ID を保存していなかった場合は、Cloud コンソールのタブでナビゲーション メニュー（）から [Document AI] > [マイプロセッサ] をクリックし、作成したプロセッサの名前をクリックして詳細ページを開きます。ここで、プロセッサ ID をコピーできます。

Process Document Function コードセルでは、Document AI プロセッサへの同期呼び出しに使用される process_document 関数を定義します。関数は Document AI API クライアント オブジェクトを作成します。

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

この関数は、ドキュメントの完全なプロセッサ名を含むリクエスト オブジェクトを作成し、このオブジェクトを Document AI API クライアントへの同期呼び出しのパラメータとして使用します。リクエストが成功すると、返されるドキュメント オブジェクトのプロパティに、フォームで検出されたエンティティが含まれていることが確認できます。

def process_document( project_id=project_id, location=location, processor_id=processor_id, file_path=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

Process Document コードセルでは、process_document 関数を呼び出して、レスポンスを document 変数に保存し、検出された未加工のテキストを出力します。すべてのプロセッサで、document.text プロパティのデータがレポートされます。

document=process_document() # 検出されたテキストをすべて出力します # すべてのドキュメント プロセッサでテキスト コンテンツを表示します print("Document processing complete.") print("Text: {}".format(document.text))

Get Text Function コードセルでは、get_text() 関数を定義します。この関数は、指定された要素の text_segments の text_anchor start_index と end_index プロパティを使って、指定された要素のテキストを取得します。この関数は、プロセッサによって該当するフォームデータが返される場合に、そのデータのフォーム名とフォーム値を取得するために使用されます。

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

Display Form Data セルでは、検出されたすべてのページを反復処理します。検出された form_field ごとに、get_text() 関数を使用してフィールド名とフィールド値を取得します。次に、これらの値を、対応する信頼スコアとともに出力します。フォームデータは、一般用の Form Parser または専用パーサーを使用するプロセッサでは返されますが、Document OCR パーサーで作成されたプロセッサでは返されません。

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")

Display Entity Data セルでは、ドキュメント オブジェクトからエンティティ データを抽出して、検出されたエンティティごとにエンティティ タイプ、値、信頼スコアの各プロパティを表示します。エンティティ データは、Procurement Expense パーサーなどの専用 Document AI パーサーを使用するプロセッサでのみ返されます。一般用の Form Parser と Document OCR パーサーでは、エンティティ データは返されません。

if 'entities' in dir(document): entities = document.entities # 各 Key-Value ペアとその信頼スコアを取得します table = PrettyTable(['Type', 'Value', 'Confidence']) for entity in entities: entity_type = entity.type_ value = entity.mention_text confience = round(entity.confidence,4) table.add_row([entity_type, value, confience]) print(table) else: print("Document does not contain entity data.")

タスク 4. 同期 Document AI Python コードを実行する

JupyterLab ノートブックで Document AI API への同期呼び出しを行うコードを実行します。

1. 2 つ目の Set your Processor ID コードセルでは、PROCESSOR_ID プレースホルダ テキストを、前のタスクで作成した form-parser プロセッサのプロセッサ ID に置き換えます。

2. 最初のセルを選択し、[Run] メニュー、[Run Selected Cell and All Below] の順にクリックして、ノートブックですべてのコードを実行します。

サンプルの医療機関の受け付けフォームを使用した場合は、フォームデータの出力セルに次のようなデータが表示されます。

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) ...

専用プロセッサを作成できる場合は、最後のセルでエンティティ データが表示されますが、それ以外の場合は空のテーブルが表示されます。

3. JupyterLab メニューで、[File]、[Save Notebook] の順にクリックして、進行状況を保存します。

ドキュメントが同期 Cloud Document AI API を使用して処理されたことを確認する

タスク 5. Document AI のドキュメント OCR プロセッサを作成する

このタスクでは、一般用 Document OCR パーサーを使用して、Document AI のプロセッサを作成します。

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

2. [プロセッサを確認] をクリックして、[Document OCR] の [プロセッサを作成] をクリックします。これは一般タイプのプロセッサです。

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

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

5. プロセッサ ID をメモしておきます。今後のタスクでこれを指定する必要があります。

タスク 6. 非同期 Document AI API 呼び出し用に環境を準備する

このタスクでは、サンプル JupyterLab ノートブックをアップロードして、非同期 Document AI API 呼び出しをテストし、ラボ向けのいくつかのサンプル フォームを非同期処理用に Cloud Storage にコピーします。

1. [ターミナル] タブをクリックして、Vertex AI Workbench インスタンスでターミナル シェルを再び開きます。

2. 入力ドキュメント用の Cloud Storage バケットを作成して、サンプル W2 フォームをバケットにコピーします。

export PROJECT_ID="$(gcloud config get-value core/project)" export BUCKET="${PROJECT_ID}"_doc_ai_async gsutil mb gs://${BUCKET} gsutil -m cp {{{project_0.startup_script.async_files_path|async_files_path}}} gs://${BUCKET}/input

3. ノートブック インターフェースで、 という JupyterLab ノートブックを開きます。

4. [Select Kernel] ダイアログで、使用可能なカーネルのリストから [Python 3] を選択します。

Vertex AI インスタンスが非同期 Document AI API 呼び出し用に準備されていることを確認する

タスク 7. 非同期ドキュメント処理リクエストを作成する

非同期 Document AI API 呼び出しの Python コードを確認する

ノートブックで Python コードを確認します。

最初のコードセルでは、必要なライブラリをインポートします。

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage import re import os import pandas as pd import simplejson as json

Set your Processor ID コードセルでは、プロセッサ ID を設定します。ノートブックでドキュメントを処理するには、事前にプロセッサ ID を手動で設定する必要があります。

processor_id = "PROCESSOR_ID" # TODO: 有効なプロセッサ ID に置き換えます

Set your variables コードセルでは、非同期呼び出しを行うために使用されるパラメータを定義します。これには、ソースデータと出力ファイルに使用される Cloud Storage バケット（入力および出力）のロケーションが含まれます。コードを実行する前に、このセルで、ラボの次のセクションの PROJECT_ID と PROCESSOR_ID のプレースホルダの値を更新します。他の変数にはプロセッサのロケーション、入力 Cloud Storage バケットと出力 Cloud Storage バケットのデフォルト値が含まれ、これらを変更する必要はありません。

project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' # プロセッサで 'us' ロケーションを使用しない場合は 'eu' に置き換えます gcs_input_bucket = project_id+"_doc_ai_async" # バケット名のみ。gs:// 接頭辞は不要です gcs_input_prefix = "input/" # 入力バケット フォルダ。例: input/ gcs_output_bucket = project_id+"_doc_ai_async" # バケット名のみ。gs:// 接頭辞は不要です gcs_output_prefix = "output/" # 出力バケット フォルダ。例: output/ timeout = 300

Define Google Cloud client objects コードセルでは、Document AI と Cloud Storage クライアントを初期化します。

client_options = {"api_endpoint": "{}-documentai.googleapis.com".format(location)} client = documentai.DocumentProcessorServiceClient(client_options=client_options) storage_client = storage.Client()

Create input configuration コードセルでは、入力構成として非同期 Document AI リクエストに渡される、ソースデータの入力構成配列パラメータを作成します。この配列には、入力 Cloud Storage ロケーションで検出されたファイルごとに、Cloud Storage のソース ロケーションと MIME タイプが格納されます。

blobs = storage_client.list_blobs(gcs_input_bucket, prefix=gcs_input_prefix) input_configs = [] print("Input Files:") for blob in blobs: if ".pdf" in blob.name: source = "gs://{bucket}/{name}".format(bucket = gcs_input_bucket, name = blob.name) print(source) input_config = documentai.types.document_processor_service.BatchProcessRequest.BatchInputConfig( gcs_source=source, mime_type="application/pdf" ) input_configs.append(input_config)

Create output configuration コードセルでは、出力 Cloud Storage バケットのロケーションを含む非同期リクエストの出力パラメータを作成し、Document AI バッチ出力構成としてこれを格納します。

destination_uri = f"gs://{gcs_output_bucket}/{gcs_output_prefix}" output_config = documentai.types.document_processor_service.BatchProcessRequest.BatchOutputConfig( gcs_destination=destination_uri )

Create the Document AI API request コードセルでは、入力および出力構成オブジェクトを使用して、非同期 Document AI バッチ処理リクエスト オブジェクトを作成します。

name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" request = documentai.types.document_processor_service.BatchProcessRequest( name=name, input_configs=input_configs, output_config=output_config, )

Start the batch (asynchronous) API operation コードセルでは、リクエスト オブジェクトを batch_process_documents() メソッドに渡すことで、非同期ドキュメント処理リクエストを作成します。これは非同期呼び出しであるため、result() メソッドを使用して、ノートブックがバックグラウンド非同期ジョブの完了まで待機するよう強制します。

operation = client.batch_process_documents(request) # オペレーションが完了するまで待機します operation.result(timeout=timeout) print ("Batch process completed.")

Fetch list of output files セルでは、destination_uri 変数で定義された出力バケット ロケーション内のオブジェクトを列挙します。

Display detected text from asynchronous output JSON files セルでは、Document AI ドキュメント オブジェクトとして見つかった各出力 JSON ファイルを読み込み、ドキュメント OCR プロセッサで検出されたテキストデータを出力します。

Display entity data セルでは、見つかったエンティティ データを表示します。ただし、エンティティ データは、専用パーサーを使って作成されたプロセッサの場合にのみ表示されます。このタスクで使用されている一般用 Document OCR パーサーでは、エンティティ データは表示されません。

非同期 Document AI Python コードを実行する

JupyterLab ノートブックに用意されているサンプルコードを使用して、Document AI バッチ処理リクエストでドキュメントを非同期に処理します。

1. 2 つ目のコードセルでは、PROCESSOR_ID プレースホルダ テキストを、前のステップで作成した form-parser プロセッサのプロセッサ ID に置き換えます。

2. 最初のセルを選択し、[Run] メニュー、[Run Selected Cell and All Below] の順にクリックして、ノートブックですべてのコードを実行します。

3. コードセルの実行中に、ノートブックのステップを追いながら、コードとコメント（非同期リクエスト オブジェクトの作成方法と使用方法を説明したもの）を確認しましょう。

ノートブックは、 Start the batch (asynchronous) API operation コードセルで非同期バッチ処理オペレーションが完了するまで 1～2 分待機します。バッチ処理 API 呼び出し自体が非同期ですが、ノートブックは result メソッドを使用して、非同期呼び出しが完了するまで待機するよう強制してから、出力データを列挙、表示します。

非同期ジョブに想定以上の時間がかかってタイムアウトした場合は、出力を表示するために残りのセルの再実行が必要になることがあります。これらは、Start the batch (asynchronous) API operation セルの後のセルです。

出力では、各ファイルで検出された Document AI データのテキストが一覧表示されます。Document OCR パーサーではフォームまたはエンティティ データが検出されないので、生成されるフォームまたはエンティティ データはありません。専用プロセッサを作成できる場合は、最後のセルによってエンティティ データが出力されます。

4. JupyterLab メニューで、[File]、[Save Notebook] の順にクリックして、進行状況を保存します。

Document processing complete. Text: 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 ... ドキュメントが非同期 Cloud Document AI API を使用して処理されたことを確認する

お疲れさまでした

Document AI API への同期呼び出しと非同期呼び出しを正常に行うことができました。このラボでは、Document AI API を有効にし、プロセッサを作成しました。Vertex AI Workbench インスタンスに Python 用のクライアント ライブラリをインストールし、Python を使ってスキャンしたフォームのデータを解析して同期 API 呼び出しと非同期 API 呼び出しを行いました。

クエストを完了する

このセルフペース ラボは、「Detect Manufacturing Defects using Visual Inspection AI」スキルバッジ クエストの一部です。クエストとは学習プログラムを構成する一連のラボのことで、完了すると成果が認められてバッジが贈られます。獲得したバッジをレジュメやソーシャル プラットフォームで共有し、#GoogleCloudBadge を使用して成果を公表しましょう。バッジは公開して、オンライン レジュメやソーシャル メディア アカウントにリンクできます。このラボの修了後、次のクエストに登録すれば、すぐにクレジットを受け取ることができます。受講可能なその他のクエストもご確認ください。

次のステップと詳細情報

• Document AI API を使用する方法について詳しくは、ガイドをご確認ください。

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

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

マニュアルの最終更新日: 2024 年 10 月 8 日

ラボの最終テスト日: 2024 年 10 月 8 日

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