ファイル内のテキストを検出する

Google Distributed Cloud（GDC）エアギャップ上の Vertex AI の光学式文字認識（OCR）サービスは、次の 2 つの API メソッドを使用して PDF ファイルと TIFF ファイルのテキストを検出します。

このページでは、Distributed Cloud で OCR API を使用してファイル内のテキストを検出する方法について説明します。

始める前に

OCR API の使用を開始するには、OCR API が有効になっているプロジェクトと適切な認証情報が必要です。また、API の呼び出しを支援するクライアント ライブラリをインストールすることもできます。詳細については、文字認識プロジェクトを設定するをご覧ください。

インライン リクエストでテキストを検出する

BatchAnnotateFiles メソッドは、PDF ファイルまたは TIFF ファイルのバッチからテキストを検出します。テキストを検出するファイルを、API リクエストのコンテンツとして直接送信します。システムは、検出されたテキストを JSON 形式で API レスポンスとして返します。

API リクエストの JSON 本文のフィールドに値を指定する必要があります。次の表に、テキスト検出リクエストで BatchAnnotateFiles API メソッドを使用する場合に指定する必要があるリクエスト本文のフィールドの説明を示します。

リクエスト本文のフィールド フィールドの説明
content 検出するテキストを含むファイル。バイナリ ファイル コンテンツの Base64 表現（ASCII 文字列）を指定します。
mime_type ソース ファイル形式。次のいずれかの値に設定する必要があります。
  • PDF ファイルの application/pdf
  • TIFF ファイルの image/tiff
type ファイルから検出する必要があるテキストの種類。

次の 2 つのアノテーション機能のいずれかを指定します。
  • TEXT_DETECTION は、任意のファイルからテキストを検出、抽出します。JSON レスポンスには、抽出された文字列、個々の単語、それらの境界ボックスが含まれます。
  • DOCUMENT_TEXT_DETECTION はファイルからテキストを抽出しますが、サービスは高密度のテキストやドキュメントに応じてレスポンスを最適化します。ページ、ブロック、段落、単語、改行の情報が JSON に含まれます。
これらのアノテーション機能の詳細については、光学文字認識機能をご覧ください。
language_hints 省略可。テキスト検出に使用する言語のリスト。

このフィールドの値が空の場合、システムは自動言語検出と解釈します。

ラテン アルファベット系の言語の場合、language_hints フィールドを設定する必要はありません。

ファイル内のテキストの言語がわかっている場合は、ヒントを設定すると結果が改善されます。
pages 省略可。テキスト検出のために処理するファイルのページ数。

指定できるページ数の上限は 5 ページです。ページ数を指定しない場合、サービスはファイルの最初の 5 ページを処理します。

完全な JSON 表現については、AnnotateFileRequest をご覧ください。

インライン API リクエストを作成する

REST API メソッドを使用して、OCR 事前トレーニング済み API にリクエストを送信します。それ以外の場合は、Python スクリプトから OCR 事前トレーニング済み API を操作して、PDF ファイルまたは TIFF ファイルからテキストを検出します。

次の例は、OCR を使用してファイル内のテキストを検出する方法を示しています。

REST

REST API メソッドを使用してファイル内のテキストを検出する手順は次のとおりです。

  1. 次の 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_1",
          "LANGUAGE_HINT_2",
          ...
        ]
      },
      "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 など）。このフィールドは省略可能です。空の値は自動言語検出として解釈されます。

  2. 認証トークンを取得します。

  3. 次のリクエストを行います。

    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

    次のように置き換えます。

    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 "ENDPOINT/v1/files:annotate" | Select-Object -Expand Content

    次のように置き換えます。

Python

Python スクリプトから OCR サービスを使用してファイル内のテキストを検出する手順は次のとおりです。

  1. OCR クライアント ライブラリの最新バージョンをインストールします。

  2. Python スクリプトに必要な環境変数を設定します。

  3. API リクエストを認証します。

  4. 作成した 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)
    print("Got token: ")
    print(creds.token)
  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。

  5. Python スクリプトを保存します。

  6. Python スクリプトを実行して、ファイル内のテキストを検出します。

    python SCRIPT_NAME

    SCRIPT_NAME は、Python スクリプトに付けた名前（vision.py など）に置き換えます。

オフライン リクエストでテキストを検出する

AsyncBatchAnnotateFiles メソッドは、オフライン（非同期）リクエストを実行して、PDF または TIFF ファイルのバッチからテキストを検出します。ファイルには複数のページが含まれている場合があります。また、各ページに複数の画像が存在することもあります。ソースファイルは、Distributed Cloud プロジェクトのストレージ バケットに存在する必要があります。検出されたテキストは、JSON 形式でストレージ バケットに保存されます。

OCR サービスはオフライン処理を開始し、ファイルでテキスト検出を行う長時間実行プロセスの ID を返します。返された ID を使用して、オフライン処理のステータスを追跡できます。進行中のオペレーションが多すぎると、オフライン処理がすぐに開始されないことがあります。

API リクエストの JSON 本文のフィールドに値を指定する必要があります。次の表に、テキスト検出リクエストで AsyncBatchAnnotateFiles API メソッドを使用する場合に指定する必要があるリクエスト本文のフィールドの説明を示します。

リクエスト本文のフィールド フィールドの説明
s3_source.uri Distributed Cloud プロジェクトのストレージ バケット内の有効なソースファイル（PDF または TIFF）の URI パス。

このファイルには、検出するテキストが含まれています。

リクエスト元のユーザーまたはサービス アカウントには、少なくともファイルに対する読み取り権限が必要です。
mime_type ソース ファイル形式。次のいずれかの値に設定する必要があります。
  • PDF ファイルの application/pdf
  • TIFF ファイルの image/tiff
type ファイルから検出する必要があるテキストの種類。

次の 2 つのアノテーション機能のいずれかを指定します。
  • TEXT_DETECTION は、任意のファイルからテキストを検出、抽出します。JSON レスポンスには、抽出された文字列、個々の単語、それらの境界ボックスが含まれます。
  • DOCUMENT_TEXT_DETECTION はファイルからテキストを抽出しますが、サービスは高密度のテキストやドキュメントに応じてレスポンスを最適化します。ページ、ブロック、段落、単語、改行の情報が JSON に含まれます。
これらのアノテーション機能の詳細については、光学文字認識機能をご覧ください。
s3_destination.uri 出力ファイルを保存する Distributed Cloud プロジェクトのストレージ バケットの URI パス。

この場所は、検出結果を保存する場所です。

リクエスト元のユーザーまたはサービス アカウントには、バケットへの書き込み権限が必要です。

ソースファイルをストレージ バケットに保存する

リクエストを送信する前に、OCR サービス アカウントに入力バケットに対する読み取り権限と出力バケットに対する書き込み権限があることを確認する必要があります。

入力バケットと出力バケットは、異なるプロジェクト名前空間に配置できます。入力バケットと出力バケットを同じにすると、結果が誤ったバケットに保存されるなどのエラーを防ぐことができます。

テキストを検出するファイルをストレージ バケットに保存する手順は次のとおりです。

  1. オブジェクト ストレージ用に gdcloud CLI を構成します。

  2. プロジェクト Namespace にストレージ バケットを作成します。Standard ストレージ クラスを使用します。

    ストレージ バケットを作成するには、プロジェクト Namespace に 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: 90

  3. OCR サービスで使用されるサービス アカウント（g-vai-ocr-sie-sa）に、バケットに対する read 権限と write 権限を付与します。

    次の手順に沿って、カスタム リソースを使用してロールとロール バインディングを作成します。

    1. プロジェクト Namespace に 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

    2. プロジェクト 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

  4. 作成したストレージ バケットにファイルをアップロードします。詳細については、プロジェクトでストレージ オブジェクトをアップロードしてダウンロードするをご覧ください。

オフライン API リクエストを作成する

REST API メソッドを使用して、OCR 事前トレーニング済み API にリクエストを送信します。それ以外の場合は、Python スクリプトから OCR 事前トレーニング済み API を操作して、PDF ファイルまたは TIFF ファイルからテキストを検出します。

次の例は、OCR を使用してファイル内のテキストを検出する方法を示しています。

REST

REST API メソッドを使用してファイル内のテキストを検出する手順は次のとおりです。

  1. 次の request.json ファイルをリクエスト本文として保存します。

    cat <<- EOF > request.json
{
  "parent": PROJECT_ID,
  "requests":[
    {
      "input_config": {
        "s3_source": {
          "uri": "SOURCE_FILE"
        },
        "mime_type": "application/pdf"
      },
      "features": [
        {
          "type": "FEATURE_TYPE"
        }
      ],
      "output_config": {
        "s3_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 パス。

  2. 認証トークンを取得します。

  3. 次のリクエストを行います。

    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

    次のように置き換えます。

    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 "ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content

    次のように置き換えます。

Python

Python スクリプトから OCR サービスを使用してファイル内のテキストを検出する手順は次のとおりです。

  1. OCR クライアント ライブラリの最新バージョンをインストールします。

  2. Python スクリプトに必要な環境変数を設定します。

  3. API リクエストを認証します。

  4. 作成した 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_func_async(creds):
  vc = vision_client(creds)
  features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
  input_config = {"s3_source":{"uri":SOURCE_FILE},"mime_type": "application/pdf"}
  output_config = {"s3_destination": {"uri": DESTINATION_BUKET}}
  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)
    print("Got token: ")
    print(creds.token)
  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。

  5. Python スクリプトを保存します。

  6. Python スクリプトを実行して、ファイル内のテキストを検出します。

    python SCRIPT_NAME

    SCRIPT_NAME は、Python スクリプトに付けた名前（vision.py など）に置き換えます。

AsyncBatchAnnotateFiles メソッドが返したオペレーション名を使用して、オペレーションのステータスを確認できます。

オペレーションのステータスを取得する

get メソッドは、テキスト検出のオフライン リクエストなどの長時間実行オペレーションの最新の状態を返します。このメソッドを使用して、次の例のようにオペレーションのステータスを確認します。

curl -X GET "http://ENDPOINT/v1/OPERATION_NAME"

OPERATION_NAME は、オフライン リクエストを行ったときに AsyncBatchAnnotateFiles メソッドが返したオペレーション名に置き換えます。

処理の一覧を表示します

list メソッドは、リクエストで指定されたフィルタに一致するオペレーションのリストを返します。このメソッドは、特定のプロジェクトのオペレーションを返すことができます。リストメソッドを呼び出すには、次の例のようにプロジェクト ID と OCR エンドポイントを指定します。

curl -X GET "http://ENDPOINT/v1/PROJECT_ID?page_size=10"