오류 메시지

Document AI에서 발생한 몇 가지 오류를 해결하는 방법을 알아봅니다. 이 주제에서는 오류 메시지에 간단히 설명된 것 이상으로 추가 단계가 필요한 오류에 대해 설명합니다.

오류 처리 권장사항은 Cloud API 문서를 참고하세요.

권한

해결하려면 오류 메시지에 설명된 대로 몇 단계를 실행해야 합니다.

애플리케이션 기본 사용자 인증 정보를 사용할 수 없음

다음과 같은 메시지가 표시될 경우:

The Application Default Credentials are not available. They are
available if running in Compute Engine. Otherwise, the
environment variable GOOGLE_APPLICATION_CREDENTIALS must be defined
pointing to a file defining the credentials.
See https://developers.google.com/accounts/docs/application-default-credentials
for more information.

Document AI는 인증에 애플리케이션 기본 사용자 인증 정보를 사용합니다.

프로젝트의 서비스 계정이 있어야 하며 서비스 계정의 키(JSON 파일)를 개발 환경에 다운로드한 다음 JSON 파일 위치를 GOOGLE_APPLICATION_CREDENTIALS라는 환경 변수로 설정해야 합니다.

또한 Document AI API를 호출하는 컨텍스트 내에서 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용할 수 있어야 합니다. 예를 들어 터미널 세션 내에서 변수를 설정했는데 IDE의 디버거에서 코드를 실행하면 코드의 실행 컨텍스트가 변수에 액세스하지 못할 수 있습니다. 이러한 상황에서는 적절한 인증이 이루어지지 않아 Document AI 요청이 실패할 수 있습니다.

GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하는 방법에 대한 자세한 내용은 Document AI 빠른 시작 또는 애플리케이션 기본 사용자 인증 정보 사용에 대한 문서를 참고하세요.

권한 거부됨

다음과 같은 메시지가 표시될 경우:

ERROR: (gcloud.auth.application-default.print-access-token) File
(pointed by GOOGLE_APPLICATION_CREDENTIALS environment variable) does not exist!
{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 저장된 위치에 유효한 서비스 계정 키 JSON 파일이 있고 이 변수가 올바른 위치를 가리키고 있는지 확인합니다.

이 오류를 진단하려면 Document AI API를 호출하려는 폴더에서 서비스 계정 키 파일을 열어보세요.

cat $GOOGLE_APPLICATION_CREDENTIALS

'금지됨: 403 POST API를 사용한 적이 없거나 사용 중지했습니다'

다음과 같은 메시지가 표시될 경우:

Forbidden: 403 POST Document AI API has not been used in
project # before or it is disabled.
Enable it by visiting [url], then retry.
If you enabled this API recently, wait a few minutes for the action to
propagate and retry.
  1. 오류 메시지에 지정된 링크로 이동하여 Document AI API를 사용 설정합니다. 몇 분 정도 기다린 후 다시 시도합니다.
  2. GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 유효한 서비스 계정 키 JSON 파일이 저장되어 있는지 확인합니다. 이 오류를 진단하려면 Document AI API를 호출하려는 폴더에서 서비스 계정 키 파일을 열어보세요. 
    cat $GOOGLE_APPLICATION_CREDENTIALS

최종 출력을 작성하는 중에 오류가 발생했습니다.

일괄 처리 요청 결과를 수신할 때 다음과 같은 메시지가 표시되면 다음을 수행하세요.

{
  "name": "projects/project-name/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.document.v1beta1.OperationMetadata",
    "state": "SUCCEEDED",
    "createTime": "2019-09-19T02:02:15.885267760Z",
    "updateTime": "2019-09-19T02:02:31.896425001Z"
  },
  "done": true,
  "error": {
    "code": 5,
    "message": "Error writing final output to: gs://bucket-name/filename.json"
  }
}

서비스 계정에 Cloud Storage 버킷에서 객체를 만들 수 있는 올바른 권한이 없을 수 있습니다. 빠른 시작에 설명된 대로 서비스 계정에 올바른 권한을 할당했는지 확인합니다.

Cloud Storage 버킷 이름을 잘못 입력했을 수도 있습니다. 액세스하려는 버킷이 있는지 확인합니다.

P4SA가 Cloud Storage에 액세스할 수 없음

Document AI 제품별 서비스 계정 (P4SA)에 일부 Cloud Storage 리소스에 액세스할 권한이 없는 경우

message: "Cloud DocumentAI P4SA doesn't have access to this Cloud Storage resource:"

서비스 계정에서 Cloud Storage에 객체를 만들 수 없음

Document AI 제품별 서비스 계정 (P4SA)에 Cloud Storage에서 객체를 만들 권한이 없는 경우

message: "Service account service-123@gcp-sa-prod-dai-core.iam.gserviceaccount.com
         does not have permission storage.objects.create to create
         Google Cloud Storage object in bucket gs://foo."

Document AI 서비스 계정에 Cloud Storage 버킷에서 객체를 만들 수 있는 올바른 권한이 없을 수 있습니다. 교차 프로젝트 파일 액세스 설정에 설명된 대로 Document AI 서비스 계정에 올바른 권한을 할당했는지 확인합니다.

Cloud Storage 버킷 이름을 잘못 입력했을 수도 있습니다. 액세스하려는 버킷이 있는지 확인합니다.

호출자가 Cloud Storage에서 객체를 가져올 수 없음

Document AI API 호출자에게 Cloud Storage의 객체를 가져올 권한이 없는 경우

message: "The caller does not have permission storage.objects.get to get Google
         Cloud Storage objects in bucket gs://foo."

API 호출자에게 Cloud Storage 버킷의 객체를 가져올 올바른 권한이 없을 수 있습니다. 호출자에게 올바른 권한을 할당했는지 확인합니다.

Cloud Storage 버킷 이름을 잘못 입력했을 수도 있습니다. 액세스하려는 버킷이 있는지 확인합니다.

잘못된 인수

해결하려면 오류 메시지에 설명된 대로 몇 단계를 실행해야 합니다.

API 버전이 지원되지 않음

작업을 지원하지 않는 API 버전에 요청이 이루어진 경우

message: "The requested operation is unsupported for the API version."

지원되지 않는 프로세서 유형

지정된 프로세서 유형을 지원하지 않는 API 메서드에 요청이 이루어진 경우

message: "The requested operation is unsupported for the processor type: ${PROCESSOR_TYPE}."

잘못된 요청

API 요청이 이루어졌지만 요청 필드에 하나 이상의 위반이 있습니다. 각 위반은 google.rpc.BadRequest 세부정보에 field_violations로 캡처됩니다.

message: "Request contains an invalid argument."
details {
  [type.googleapis.com/google.rpc.BadRequest] {
    field_violations { field: "foo" description: "bar" }
  }
}

모든 문서를 일괄 처리하지 못함

일괄 처리 요청의 모든 문서를 처리할 수 없는 경우

message: "Failed to process all documents."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "FAILED_TO_PROCESS_ALL_DOCUMENTS"
    domain: "documentai.googleapis.com"
  }
}

문서 없음

문서가 필요하거나 예상되지만 제공되지 않는 경우(예: Cloud Storage URI로 문서를 가져오는 경우)

message: "No valid documents found in ${training|test} directory. Ensure files are in a supported MIME type. For details, see https://cloud.google.com/document-ai/docs/file-types."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "NO_DOCUMENTS"
    domain: "documentai.googleapis.com"
  }
}

gcsUriPrefix 및 gcsOutputConfig.gcsUri 매개변수는 gs://로 시작하고 후행 백슬래시 문자 (/)로 끝나야 합니다. 버킷 URI의 구성을 확인하세요.

예: gs://bucket/directory/

학습이 지원되지 않음

학습을 지원하지 않는 프로세서 유형에 학습 프로세서 버전 요청이 이루어진 경우

message: "Training is not supported on processor type: ${DOCUMENT_TYPE}_PROCESSOR."

선택한 문서가 없습니다.

문서가 필요하지만 데이터 세트에서 선택되지 않은 경우(예: 데이터 라벨링 작업을 만드는 경우)

message: No documents selected. Please select at least one document."
details {
  [type.googleapis.com/google.rpc.ErrorInfo]