이 페이지는 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 문자열)을 제공합니다. 참고: 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`	(선택사항) 텍스트 감지를 위해 처리할 파일의 페이지 수입니다. 지정할 수 있는 최대 페이지 수는 5개입니다. 페이지 수를 지정하지 않으면 서비스에서 파일의 처음 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 파일 배치에서 텍스트를 감지합니다. 파일에는 여러 페이지와 페이지당 여러 이미지가 포함될 수 있습니다. 소스 파일은 Distributed Cloud 프로젝트의 스토리지 버킷에 있어야 합니다. 시스템은 감지된 텍스트를 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 요청하기

다음 예는 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 프로젝트의 스토리지 버킷 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 프로젝트의 스토리지 버킷 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

오프라인 요청으로 텍스트 감지

스토리지 버킷에 소스 파일 저장

오프라인 API 요청하기

REST

curl

PowerShell

Python

작업 상태 가져오기

작업 나열

파일에서 텍스트 감지