此页面由 Cloud Translation API 翻译。

检测文件中的文本

Google Distributed Cloud (GDC) 空气隔离环境中的 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 字符串）。注意：您只能处理本地存储在分布式云环境中的文件。
`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`	可选。要处理的文件页数，用于文本检测。您可以指定的最大页数为 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_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 文件中的文本。这些文件可能包含多页，每页可能包含多张图片。源文件必须位于分布式云项目的存储桶中。系统会将检测到的文本以 JSON 格式保存到存储桶中。

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

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

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

获取操作的状态

列出操作

检测文件中的文本