Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

检测文件中的文本

Google Distributed Cloud (GDC) air-gapped 中 Vertex AI 的光学字符识别 (OCR) 服务可检测并从 PDF 和 TIFF 文件中提取文本。您可以在内嵌请求中将本地文件发送到 BatchAnnotateFiles API 方法，也可以使用 AsyncBatchAnnotateFiles API 方法异步处理存储在存储桶中的文件。BatchAnnotateFiles API 方法支持每个批量调用一个请求。

准备工作

如需检测文件中的文本，请与您的 IAM 项目管理员联系，请求在项目命名空间中授予 AI OCR Developer (ai-ocr-developer) 角色。

如需详细了解此角色，请参阅准备 IAM 权限。

在开始使用 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 文件） `image/tiff`（对于 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`	可选。文件中要处理以进行文本检测的页数。您最多可以指定 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 服务检测文件中的文本：

安装最新版本的 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 项目的存储桶中。系统会将检测到的文本以 JSON 格式保存到存储桶中。

OCR 服务会启动离线处理，并返回对文件执行文本检测的长时间运行进程的 ID。您可以使用返回的 ID 跟踪离线处理的状态。如果正在进行的操作过多，离线处理可能不会立即开始。

您必须为 API 请求的 JSON 正文中的字段指定值。下表介绍了在文本检测请求中使用 AsyncBatchAnnotateFiles API 方法时必须提供的请求正文字段：

请求正文字段	字段说明
`gcs_source.uri`	Distributed Cloud 项目存储桶中有效源文件（PDF 或 TIFF）的 URI 路径。此文件包含您要检测的文本。发出请求的用户或服务账号必须至少拥有该文件的读取权限。
`mime_type`	源文件类型。您必须将其设置为以下值之一： `application/pdf`（适用于 PDF 文件） `image/tiff`（对于 TIFF 文件）
`type`	您需要从文件中检测的文本类型。指定以下两个注解功能之一： `TEXT_DETECTION` 可检测并提取任何文件中的文本。JSON 响应包含提取的字符串、各个字词及其边界框。 `DOCUMENT_TEXT_DETECTION` 也会从文件中提取文本，但该服务会针对密集文本和文档优化回答。JSON 包含页面、文本块、段落、字词和换行信息。如需详细了解这些注解功能，请参阅光学字符识别功能。
`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: 90

向 OCR 服务使用的服务账号 (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

通过在项目命名空间中部署 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 服务检测文件中的文本：

安装最新版本的 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 云项目存储桶中有效源文件（PDF 或 TIFF）的 URI 路径。
DESTINATION_BUCKET：Distributed Cloud 项目中用于保存输出文件的存储桶的 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

通过离线请求检测文本

将源文件存储在存储桶中

发出离线 API 请求

REST

curl

PowerShell

Python

获取操作状态

列出操作

检测文件中的文本