本頁面由 Cloud Translation API 翻譯而成。

偵測檔案中的文字

Google Distributed Cloud (GDC) air-gapped 上的 Vertex AI 光學字元辨識 (OCR) 服務，會使用下列兩種 API 方法偵測 PDF 和 TIFF 檔案中的文字：

BatchAnnotateFiles：使用內嵌要求偵測文字。
AsyncBatchAnnotateFiles：透過離線 (非同步) 要求偵測文字。

本頁說明如何使用 Distributed Cloud 的 OCR API 偵測檔案中的文字。

事前準備

您必須先準備一個專案，並啟用 OCR API 和適當的憑證，才能開始使用 OCR API。您也可以安裝用戶端程式庫，協助您呼叫 API。詳情請參閱「設定字元辨識專案」。

使用內嵌要求偵測文字

BatchAnnotateFiles 方法會從批次的 PDF 或 TIFF 檔案中偵測文字。您直接在 API 要求中傳送要偵測文字的檔案做為內容。系統會在 API 回應中，以 JSON 格式傳回偵測到的文字。

您必須在 API 要求的 JSON 主體中指定欄位值。下表說明使用 BatchAnnotateFiles API 方法發出文字偵測要求時，必須提供的要求主體欄位：

要求主體欄位	欄位說明
`content`	要偵測文字的檔案。您提供二進位檔案內容的 Base64 表示法 (ASCII 字串)。注意：您只能處理儲存在 Distributed Cloud 環境中的本機檔案。
`mime_type`	這是來源檔案類型你必須將其設為下列其中一個值： `application/pdf` PDF 檔案 TIFF 檔案的 `image/tiff`
`type`	您要從檔案中偵測的文字類型。指定其中一個註解功能： `TEXT_DETECTION` 可偵測並擷取任何檔案中的文字。JSON 回應包含擷取的字串、個別字詞及其周框。 `DOCUMENT_TEXT_DETECTION` 也會從檔案中擷取文字，但這項服務會針對密集文字和文件最佳化回覆內容。JSON 檔案包含頁面、區塊、段落、字詞和換行資訊。如要進一步瞭解這些註解功能，請參閱「光學字元辨識功能」。
`language_hints`	(選用步驟) 用於文字偵測的語言清單。如果這個欄位的值為空白，系統會解讀為自動偵測語言。如果語言採用拉丁字母，則不需要設定 `language_hints` 欄位。如果知道檔案中的文字語言，設定提示可提升結果品質。語言提示的運作方式為何？ `language_hints` 格式遵循下列 `BCP 47` 語言代碼格式設定規範： `language` ["-" `script`] ["-" `region`] ("-" `variant`) ("-" `extension`) ["-" `privateuse`]。舉例來說，語言提示「`en`-`t`-`i0`-`handwrit`」指定了英文 (`en`)、轉換擴充功能單例 (`t`)、輸入法引擎轉換擴充功能代碼 (`i0`) 和手寫轉換代碼 (`handwrit`)。這大致上表示語言是「從手寫轉換的英文」。您不需要指定指令碼代碼，因為「`en`」語言代表 `Latn`。如需支援的語言清單，請參閱「支援的語言」一文。
`pages`	(選用步驟) 要處理的檔案頁數，用於文字偵測。最多可指定五個網頁。如未指定頁數，服務會處理檔案的前五頁。

如要瞭解完整的 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_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。這個欄位為選填，系統會將空白值解讀為自動偵測語言。

取得驗證權杖。

提出要求：

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

更改下列內容：

TOKEN：您取得的驗證權杖。
ENDPOINT：貴機構使用的 OCR 端點。詳情請參閱服務狀態和端點。

Python

請按照下列步驟，透過 Python 指令碼使用 OCR 服務偵測檔案中的文字：

安裝最新版 OCR 用戶端程式庫。
在 Python 指令碼中設定必要的環境變數。
驗證 API 要求。

在您建立的 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。

儲存 Python 指令碼。
執行 Python 指令碼，偵測檔案中的文字：
```
python SCRIPT_NAME
```
將 SCRIPT_NAME 替換為您為 Python 指令碼提供的名稱，例如 vision.py。

透過離線要求偵測文字

AsyncBatchAnnotateFiles 方法會執行離線 (非同步) 要求，偵測一批 PDF 或 TIFF 檔案中的文字。檔案可能包含多個頁面，每個頁面有多張圖片。來源檔案必須位於 Distributed Cloud 專案的儲存空間值區中。系統會將偵測到的文字以 JSON 格式儲存至儲存空間 bucket。

OCR 服務會啟動離線處理程序，並傳回對檔案執行文字偵測的長期執行程序 ID。您可以使用傳回的 ID 追蹤離線處理狀態。如果正在進行的作業過多，離線處理程序可能不會立即啟動。

您必須在 API 要求的 JSON 主體中指定欄位值。下表說明使用 AsyncBatchAnnotateFiles API 方法發出文字偵測要求時，必須提供的要求主體欄位：

要求主體欄位	欄位說明
`s3_source.uri`	Distributed Cloud 專案儲存空間 bucket 中有效來源檔案 (PDF 或 TIFF) 的 URI 路徑。這個檔案包含您要偵測的文字。要求存取檔案的使用者或服務帳戶，至少須具備檔案的讀取權限。
`mime_type`	這是來源檔案類型你必須將其設為下列其中一個值： `application/pdf` PDF 檔案 TIFF 檔案的 `image/tiff`
`type`	您要從檔案中偵測的文字類型。指定其中一個註解功能： `TEXT_DETECTION` 可偵測並擷取任何檔案中的文字。JSON 回應包含擷取的字串、個別字詞及其周框。 `DOCUMENT_TEXT_DETECTION` 也會從檔案中擷取文字，但這項服務會針對密集文字和文件最佳化回覆內容。JSON 檔案包含頁面、區塊、段落、字詞和換行資訊。如要進一步瞭解這些註解功能，請參閱「光學字元辨識功能」。
`s3_destination.uri`	Distributed Cloud 專案的儲存空間 bucket URI 路徑，用於儲存輸出檔案。這個位置是您要儲存偵測結果的位置。要求的使用者或服務帳戶必須具備值區的寫入權限。

將來源檔案儲存在儲存空間 bucket 中

傳送要求前，請務必確認 OCR 服務帳戶具備輸入值區的讀取權限，以及輸出值區的寫入權限。

輸入和輸出值區可以不同，且位於不同的專案命名空間。建議使用相同的輸入和輸出值區，以免發生錯誤，例如將結果儲存在錯誤的值區中。

如要將要偵測文字的檔案儲存到儲存空間值區，請按照下列步驟操作：

設定物件儲存空間的 gcloud CLI。

在專案命名空間中建立儲存空間 bucket。使用 Standard 儲存空間類別。

您可以在專案命名空間中部署 Bucket 資源，藉此建立 Storage 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

將 bucket 的 read 和 write 權限授予 OCR 服務使用的服務帳戶 (g-vai-ocr-sie-sa)。

您可以按照下列步驟，使用自訂資源建立角色和角色繫結：

在專案命名空間中部署 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

在專案命名空間中部署 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

將檔案上傳至您建立的儲存空間 bucket。詳情請參閱「在專案中上傳及下載儲存空間物件」。

提出離線 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": {
        "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 專案的儲存空間 bucket 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 "ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content

更改下列內容：

TOKEN：您取得的驗證權杖。
ENDPOINT：貴機構使用的 OCR 端點。詳情請參閱服務狀態和端點。

Python

請按照下列步驟，透過 Python 指令碼使用 OCR 服務偵測檔案中的文字：

安裝最新版 OCR 用戶端程式庫。
在 Python 指令碼中設定必要的環境變數。
驗證 API 要求。

在您建立的 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 專案的儲存空間 bucket URI 路徑，用於儲存輸出檔案。
PROJECT_ID：您的專案 ID。

儲存 Python 指令碼。
執行 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"

偵測檔案中的文字 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

使用內嵌要求偵測文字

提出內嵌 API 要求

REST

curl

PowerShell

Python

透過離線要求偵測文字

將來源檔案儲存在儲存空間 bucket 中

提出離線 API 要求

REST

curl

PowerShell

Python

取得作業狀態

列出作業

偵測檔案中的文字