Google Distributed Cloud（GDC）エアギャップの Vertex AI の光学式文字認識（OCR）サービスは、PDF ファイルと TIFF ファイルからテキストを検出して抽出します。ローカル ファイルをインライン リクエストで BatchAnnotateFiles API メソッドに送信することも、バケットに保存されているファイルを AsyncBatchAnnotateFiles API メソッドで非同期に処理することもできます。BatchAnnotateFiles API メソッドは、バッチ呼び出しごとに 1 つのリクエストをサポートします。
始める前に
ファイル内のテキストを検出するには、IAM プロジェクト管理者に連絡して、プロジェクトの名前空間で AI OCR デベロッパー（ai-ocr-developer）ロールをリクエストしてください。
このロールの詳細については、IAM 権限を準備するをご覧ください。
OCR API を使用するには、OCR API が有効になっているプロジェクトと適切な認証情報が必要です。また、この API の呼び出しを支援するクライアント ライブラリをインストールすることもできます。詳細については、文字認識プロジェクトを設定するをご覧ください。
インライン リクエストでテキストを検出する
BatchAnnotateFiles メソッドは、PDF ファイルまたは TIFF ファイルのバッチからテキストを検出します。テキストを検出するファイルを、API リクエストのコンテンツとして直接送信します。システムは、検出されたテキストを JSON 形式で API レスポンスに返します。
API リクエストの JSON 本文のフィールドに値を指定する必要があります。次の表に、テキスト検出リクエストに BatchAnnotateFiles API メソッドを使用するときに指定する必要があるリクエスト本文のフィールドの説明を示します。
| リクエスト本文のフィールド | フィールドの説明 |
|---|---|
content |
検出するテキストを含むファイル。バイナリ ファイルの内容の Base64 表現（ASCII 文字列）を指定します。 |
mime_type |
ソース ファイル形式。次のいずれかの値に設定する必要があります。
|
type |
ファイルから必要なテキスト検出のタイプ。 次の 2 つのアノテーション機能のいずれかを指定します。
|
language_hints |
省略可。テキスト検出に使用する言語のリスト。 このフィールドの値が空の場合、システムは言語の自動検出として解釈します。 ラテン アルファベット系の言語の場合、 language_hints フィールドを設定する必要はありません。ファイル内のテキストの言語がわかっている場合は、ヒントを設定すると結果が改善されます。 |
pages |
省略可。テキスト検出のために処理するファイルのページ数。 指定できるページ数は最大 5 ページです。ページ数を指定しない場合、ファイルの最初の 5 ページが処理されます。 |
完全な JSON 表現については、AnnotateFileRequest をご覧ください。
インライン API リクエストを送信する
REST API メソッドを使用して、OCR 事前トレーニング済み API にリクエストを送信します。それ以外の場合は、Python スクリプトから OCR 事前トレーニング済み API を操作して、PDF ファイルまたは TIFF ファイルからテキストを検出します。
次の例は、OCR を使用してファイル内のテキストを検出する方法を示しています。
REST
REST API メソッドを使用してファイル内のテキストを検出する手順は次のとおりです。
リクエスト本文用に次の
request.jsonファイルを保存します。cat <<- EOF > request.json { "requests": [ { "input_config": { "content": "BASE64_ENCODED_FILE", "mime_type": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "image_context": { "language_hints": [ "LANGUAGE_HINT" ] }, "pages": [] } ] } EOF次のように置き換えます。
BASE64_ENCODED_FILE: バイナリ ファイル コンテンツの Base64 表現（ASCII 文字列）。この文字列は、/9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==のような文字で始まります。FEATURE_TYPE: ファイルから必要なテキスト検出のタイプ。使用できる値は、TEXT_DETECTIONまたはDOCUMENT_TEXT_DETECTIONです。LANGUAGE_HINT: テキスト検出の言語ヒントとして使用する BCP 47 言語タグ（en-t-i0-handwritなど）。このフィールドは省略可能です。空の値は、言語の自動検出として解釈されます。
次のリクエストを行います。
curl
curl -X POST \ -H "Authorization: Bearer TOKEN" \ -H "x-goog-user-project: projects/PROJECT_ID" \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ https://ENDPOINT/v1/files:annotate次のように置き換えます。
TOKEN: 取得した認証トークン。PROJECT_ID: プロジェクト ID。ENDPOINT: 組織で使用する OCR エンドポイント。詳細については、サービス ステータスとエンドポイントを表示するをご覧ください。
PowerShell
$headers = @{ "Authorization" = "Bearer TOKEN" "x-goog-user-project" = "projects/PROJECT_ID" } Invoke-WebRequest ` -Method POST ` -Headers $headers ` -ContentType "application/json; charset=utf-8" ` -InFile request.json ` -Uri "https://ENDPOINT/v1/files:annotate" | Select-Object -Expand Content次のように置き換えます。
TOKEN: 取得した認証トークン。PROJECT_ID: プロジェクト ID。ENDPOINT: 組織で使用する OCR エンドポイント。詳細については、サービス ステータスとエンドポイントを表示するをご覧ください。
Python
Python スクリプトから OCR サービスを使用してファイル内のテキストを検出する手順は次のとおりです。
作成した Python スクリプトに次のコードを追加します。
from google.cloud import vision import google.auth from google.auth.transport import requests from google.api_core.client_options import ClientOptions audience = "https://ENDPOINT:443" api_endpoint="ENDPOINT:443" def vision_client(creds): opts = ClientOptions(api_endpoint=api_endpoint) return vision.ImageAnnotatorClient(credentials=creds, client_options=opts) def main(): creds = None try: creds, project_id = google.auth.default() creds = creds.with_gdch_audience(audience) req = requests.Request() creds.refresh(req) except Exception as e: print("Caught exception" + str(e)) raise e return creds def vision_func(creds): vc = vision_client(creds) input_config = {"content": "BASE64_ENCODED_FILE"} features = [{"type_": vision.Feature.Type.FEATURE_TYPE}] # Each requests element corresponds to a single file. To annotate more # files, create a request element for each file and add it to # the array of requests req = {"input_config": input_config, "features": features} metadata = [("x-goog-user-project", "projects/PROJECT_ID")] resp = vc.annotate_file(req,metadata=metadata) print(resp) if __name__=="__main__": creds = main() vision_func(creds)次のように置き換えます。
ENDPOINT: 組織で使用する OCR エンドポイント。詳細については、サービス ステータスとエンドポイントを表示するをご覧ください。BASE64_ENCODED_FILE: ファイル コンテンツの Base64 表現（ASCII 文字列）。この文字列は、/9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==のような文字で始まります。FEATURE_TYPE: ファイルから必要なテキスト検出のタイプ。使用できる値は、TEXT_DETECTIONまたはDOCUMENT_TEXT_DETECTIONです。PROJECT_ID: プロジェクト ID。
Python スクリプトを保存します。
Python スクリプトを実行して、ファイル内のテキストを検出します。
python SCRIPT_NAMESCRIPT_NAMEは、Python スクリプトに付けた名前（vision.pyなど）に置き換えます。
オフライン リクエストでテキストを検出する
AsyncBatchAnnotateFiles メソッドは、オフライン（非同期）リクエストを実行して、PDF ファイルまたは TIFF ファイルのバッチからテキストを検出します。ファイルには複数のページが含まれている場合があります。また、各ページに複数の画像が存在することもあります。ソースファイルは、Distributed Cloud プロジェクトのストレージ バケットに存在する必要があります。システムは、検出されたテキストを JSON 形式でストレージ バケットに保存します。
OCR サービスはオフライン処理を開始し、ファイルに対してテキスト検出を実行する長時間実行プロセスの ID を返します。返された ID を使用して、オフライン処理のステータスを追跡できます。進行中のオペレーションが多すぎる場合、オフライン処理がすぐに開始されないことがあります。
API リクエストの JSON 本文のフィールドに値を指定する必要があります。次の表に、テキスト検出リクエストに AsyncBatchAnnotateFiles API メソッドを使用するときに指定する必要があるリクエスト本文のフィールドの説明を示します。
| リクエスト本文のフィールド | フィールドの説明 |
|---|---|
gcs_source.uri |
Distributed Cloud プロジェクトのストレージ バケット内の有効なソースファイル（PDF または TIFF）への URI パス。 このファイルには、検出するテキストが含まれています。 リクエスト元のユーザーまたはサービス アカウントには、少なくともファイルに対する読み取り権限が必要です。 |
mime_type |
ソース ファイル形式。次のいずれかの値に設定する必要があります。
|
type |
ファイルから必要なテキスト検出のタイプ。 次の 2 つのアノテーション機能のいずれかを指定します。
|
gcs_destination.uri |
出力ファイルを保存する Distributed Cloud クラウド プロジェクトのストレージ バケットの URI パス。 このロケーションは、検出結果を保存する場所です。 リクエスト元のユーザーまたはサービス アカウントには、バケットへの書き込み権限が必要です。 |
ソースファイルをストレージ バケットに保存する
リクエストを送信する前に、OCR サービス アカウントに入力バケットに対する読み取り権限と出力バケットに対する書き込み権限があることを確認する必要があります。
入力バケットと出力バケットは、異なるプロジェクトの名前空間に存在してもかまいません。エラー（結果が誤ったバケットに保存されるなど）を防ぐため、同じ入力バケットと出力バケットを使用することをおすすめします。
テキストを検出するファイルをストレージ バケットに保存する手順は次のとおりです。
- オブジェクト ストレージ用に gdcloud CLI を構成する。
プロジェクトの名前空間にストレージ バケットを作成します。
Standardストレージ クラスを使用します。ストレージ バケットを作成するには、プロジェクトの名前空間に
Bucketリソースをデプロイします。apiVersion: object.gdc.goog/v1 kind: Bucket metadata: name: ocr-async-bucket namespace: PROJECT_NAMESPACE spec: description: bucket for async ocr storageClass: Standard bucketPolicy: lockingPolicy: defaultObjectRetentionDays: 90OCR サービスで使用されるサービス アカウント（
g-vai-ocr-sie-sa）に、バケットに対するread権限とwrite権限を付与します。カスタム リソースを使用してロールとロール バインディングを作成する手順は次のとおりです。
プロジェクトの名前空間に
Roleリソースをデプロイして、ロールを作成します。apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: ocr-async-reader-writer namespace: PROJECT_NAMESPACE rules: - apiGroups: - object.gdc.goog resources: - buckets verbs: - read-object - write-objectプロジェクトの Namespace に
RoleBindingリソースをデプロイして、ロール バインディングを作成します。apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: ocr-async-reader-writer-rolebinding namespace: PROJECT_NAMESPACE roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: ocr-async-reader-writer subjects: - kind: ServiceAccount name: g-vai-ocr-sie-sa namespace: g-vai-ocr-sie
作成したストレージ バケットにファイルをアップロードします。詳細については、プロジェクトでストレージ オブジェクトをアップロードおよびダウンロードするをご覧ください。
オフライン API リクエストを送信する
REST API メソッドを使用して、OCR 事前トレーニング済み API にリクエストを送信します。それ以外の場合は、Python スクリプトから OCR 事前トレーニング済み API を操作して、PDF ファイルまたは TIFF ファイルからテキストを検出します。
次の例は、OCR を使用してファイル内のテキストを検出する方法を示しています。
REST
REST API メソッドを使用してファイル内のテキストを検出する手順は次のとおりです。
リクエスト本文用に次の
request.jsonファイルを保存します。cat <<- EOF > request.json { "parent": "PROJECT_ID", "requests":[ { "input_config": { "gcs_source": { "uri": "SOURCE_FILE" }, "mime_type": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "output_config": { "gcs_destination": { "uri": "DESTINATION_BUCKET" } } } ] } EOF次のように置き換えます。
PROJECT_ID: プロジェクト ID。SOURCE_FILE: Distributed Cloud プロジェクトのストレージ バケット内の有効なソースファイル（PDF または TIFF）への URI パス。FEATURE_TYPE: ファイルから必要なテキスト検出のタイプ。使用できる値は、TEXT_DETECTIONまたはDOCUMENT_TEXT_DETECTIONです。DESTINATION_BUCKET: 出力ファイルを保存する Distributed Cloud プロジェクトのストレージ バケットの URI パス。
次のリクエストを行います。
curl
curl -X POST \ -H "Authorization: Bearer TOKEN" \ -H "x-goog-user-project: projects/PROJECT_ID" \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ https://ENDPOINT/v1/files:asyncBatchAnnotate次のように置き換えます。
TOKEN: 取得した認証トークン。PROJECT_ID: プロジェクト ID。ENDPOINT: 組織で使用する OCR エンドポイント。詳細については、サービス ステータスとエンドポイントを表示するをご覧ください。
PowerShell
$headers = @{ "Authorization" = "Bearer TOKEN" "x-goog-user-project" = "projects/PROJECT_ID" } Invoke-WebRequest ` -Method POST ` -Headers $headers ` -ContentType "application/json; charset=utf-8" ` -InFile request.json ` -Uri "https://ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content次のように置き換えます。
TOKEN: 取得した認証トークン。PROJECT_ID: プロジェクト ID。ENDPOINT: 組織で使用する OCR エンドポイント。詳細については、サービス ステータスとエンドポイントを表示するをご覧ください。
Python
Python スクリプトから OCR サービスを使用してファイル内のテキストを検出する手順は次のとおりです。
作成した Python スクリプトに次のコードを追加します。
from google.cloud import vision import google.auth from google.auth.transport import requests from google.api_core.client_options import ClientOptions audience = "https://ENDPOINT:443" api_endpoint="ENDPOINT:443" def vision_client(creds): opts = ClientOptions(api_endpoint=api_endpoint) return vision.ImageAnnotatorClient(credentials=creds, client_options=opts) def vision_func_async(creds): vc = vision_client(creds) features = [{"type_": vision.Feature.Type.FEATURE_TYPE}] input_config = {"gcs_source":{"uri":"SOURCE_FILE"},"mime_type": "application/pdf"} output_config = {"gcs_destination": {"uri": "DESTINATION_BUCKET"}} req = {"input_config": input_config, "output_config": output_config, "features":features} reqs = {"requests":[req],"parent":"PROJECT_ID"} metadata = [("x-goog-user-project", "projects/PROJECT_ID")] operation = vc.async_batch_annotate_files(request=reqs, metadata=metadata) lro = operation.operation resp = operation.result() def main(): creds = None try: creds, project_id = google.auth.default() creds = creds.with_gdch_audience(audience) req = requests.Request() creds.refresh(req) except Exception as e: print("Caught exception" + str(e)) raise e return creds if __name__=="__main__": creds = main() vision_func_async(creds)次のように置き換えます。
ENDPOINT: 組織で使用する OCR エンドポイント。詳細については、サービス ステータスとエンドポイントを表示するをご覧ください。FEATURE_TYPE: ファイルから必要なテキスト検出のタイプ。使用できる値は、TEXT_DETECTIONまたはDOCUMENT_TEXT_DETECTIONです。SOURCE_FILE: Distributed Cloud プロジェクトのストレージ バケット内の有効なソースファイル（PDF または TIFF）への URI パス。DESTINATION_BUCKET: 出力ファイルを保存する Distributed Cloud プロジェクトのストレージ バケットの URI パス。PROJECT_ID: プロジェクト ID。
Python スクリプトを保存します。
Python スクリプトを実行して、ファイル内のテキストを検出します。
python SCRIPT_NAMESCRIPT_NAMEは、Python スクリプトに付けた名前（vision.pyなど）に置き換えます。
AsyncBatchAnnotateFiles メソッドから返されたオペレーション名を使用して、オペレーションのステータスを確認できます。
オペレーションのステータスを取得する
get メソッドは、テキスト検出のオフライン リクエストなど、長時間実行オペレーションの最新の状態を返します。次の例のように、このメソッドを使用してオペレーションのステータスを確認します。
curl -X GET "http://ENDPOINT/v1/OPERATION_NAME"
OPERATION_NAME は、オフライン リクエストを行ったときに AsyncBatchAnnotateFiles メソッドから返されたオペレーション名に置き換えます。
処理の一覧を表示します
list メソッドは、リクエストで指定されたフィルタに一致するオペレーションのリストを返します。このメソッドは、特定のプロジェクトからオペレーションを返すことができます。list メソッドを呼び出すには、次の例のようにプロジェクト ID と OCR エンドポイントを指定します。
curl -X GET "http://ENDPOINT/v1/PROJECT_ID?page_size=10"