Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

偵測檔案中的文字

Google Distributed Cloud (GDC) 實體隔離方案中的 Vertex AI 光學字元辨識 (OCR) 服務，可偵測並擷取 PDF 和 TIFF 檔案中的文字。您可以透過內嵌要求，將本機檔案傳送至 BatchAnnotateFiles API 方法，或使用 AsyncBatchAnnotateFiles API 方法，以非同步方式處理儲存在 bucket 中的檔案。BatchAnnotateFiles API 方法支援每次批次呼叫單一要求。

事前準備

如要偵測檔案中的文字，請與 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 字串)。注意：您只能處理儲存在 Distributed Cloud 環境本機的檔案。
`mime_type`	這是來源檔案類型您必須將其設為下列其中一個值： PDF 檔案的 `application/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"
        ]
      },
      "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 服務偵測檔案中的文字：

安裝最新版本的 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)
  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 雲端專案的 Storage bucket。系統會將偵測到的文字以 JSON 格式儲存至 Storage bucket。

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

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

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

將來源檔案儲存在 Storage bucket

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

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

請按照下列步驟，將要偵測文字的檔案儲存在 Storage bucket：

設定 gdcloud CLI 以使用物件儲存庫。

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

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

將檔案上傳至您建立的 Storage 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": {
        "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 雲端專案儲存空間 bucket 中有效來源檔案 (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 "https://ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content

更改下列內容：

TOKEN：您取得的驗證權杖。
PROJECT_ID：您的專案 ID。
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 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 雲端專案儲存空間 bucket 中有效來源檔案 (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 方法會傳回符合要求中指定篩選條件的作業清單。這個方法可以傳回特定專案的作業。如要呼叫 list 方法，請指定專案 ID 和 OCR 端點，如下例所示：

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

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

事前準備

使用內嵌要求偵測文字

提出內嵌 API 要求

REST

curl

PowerShell

Python

透過離線要求偵測文字

將來源檔案儲存在 Storage bucket

提出離線 API 要求

REST

curl

PowerShell

Python

取得作業狀態

列出作業

偵測檔案中的文字