실적 평가

Document AI는 프로세서의 예측 성능을 결정하는 데 도움이 되도록 정밀도 및 재현율과 같은 평가 측정항목을 생성합니다.

이러한 평가 측정항목은 프로세서에서 반환된 항목 (예측)을 테스트 문서의 주석과 비교하여 생성됩니다. 프로세서에 테스트 세트가 없는 경우 먼저 데이터 세트를 만들고 테스트 문서에 라벨을 지정해야 합니다.

평가 실행

프로세서 버전을 학습하거나 업트레인할 때마다 평가가 자동으로 실행됩니다.

평가를 수동으로 실행할 수도 있습니다. 테스트 세트를 수정한 후 업데이트된 측정항목을 생성하거나 사전 학습된 프로세서 버전을 평가하는 경우에 필요합니다.

참고: 프로세서 버전에서 라벨을 추출할 수 없거나 (예: 학습 시 라벨이 사용 중지됨) 테스트 세트에 해당 라벨의 주석이 포함되지 않은 경우 Document AI는 라벨의 평가 측정항목을 계산할 수 없으며 계산하지도 않습니다. 이러한 라벨은 집계된 측정항목에 포함되지 않습니다.

웹 UI

1. Google Cloud 콘솔에서 프로세서 페이지로 이동하여 프로세서를 선택합니다.

   프로세서 페이지로 이동

2. 평가 및 테스트 탭에서 평가할 프로세서의 버전을 선택한 다음 새 평가 실행을 클릭합니다.

완료되면 페이지에 모든 라벨과 각 개별 라벨의 평가 측정항목이 포함됩니다.

Python

자세한 내용은 Document AI Python API 참조 문서를 참고하세요.

Document AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID'
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'
# gcs_input_uri = # Format: gs://bucket/directory/


def evaluate_processor_version_sample(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version_id: str,
    gcs_input_uri: str,
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    evaluation_documents = documentai.BatchDocumentsInputConfig(
        gcs_prefix=documentai.GcsPrefix(gcs_uri_prefix=gcs_input_uri)
    )

    # NOTE: Alternatively, specify a list of GCS Documents
    #
    # gcs_input_uri = "gs://bucket/directory/file.pdf"
    # input_mime_type = "application/pdf"
    #
    # gcs_document = documentai.GcsDocument(
    #     gcs_uri=gcs_input_uri, mime_type=input_mime_type
    # )
    # gcs_documents = [gcs_document]
    # evaluation_documents = documentai.BatchDocumentsInputConfig(
    #     gcs_documents=documentai.GcsDocuments(documents=gcs_documents)
    # )
    #

    request = documentai.EvaluateProcessorVersionRequest(
        processor_version=name,
        evaluation_documents=evaluation_documents,
    )

    # Make EvaluateProcessorVersion request
    # Continually polls the operation until it is complete.
    # This could take some time for larger files
    operation = client.evaluate_processor_version(request=request)
    # Print operation details
    # Format: projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID
    print(f"Waiting for operation {operation.operation.name} to complete...")
    # Wait for operation to complete
    response = documentai.EvaluateProcessorVersionResponse(operation.result())

    # After the operation is complete,
    # Print evaluation ID from operation response
    print(f"Evaluation Complete: {response.evaluation}")

평가 결과 가져오기

웹 UI

1. Google Cloud 콘솔에서 프로세서 페이지로 이동하여 프로세서를 선택합니다.

   프로세서 페이지로 이동

2. 평가 및 테스트 탭에서 프로세서의 버전을 선택하여 평가를 확인합니다.

완료되면 페이지에 모든 라벨과 각 개별 라벨의 평가 측정항목이 포함됩니다.

Python

자세한 내용은 Document AI Python API 참조 문서를 참고하세요.

Document AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'
# evaluation_id = 'YOUR_EVALUATION_ID'


def get_evaluation_sample(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version_id: str,
    evaluation_id: str,
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the evaluation
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    evaluation_name = client.evaluation_path(
        project_id, location, processor_id, processor_version_id, evaluation_id
    )
    # Make GetEvaluation request
    evaluation = client.get_evaluation(name=evaluation_name)

    create_time = evaluation.create_time
    document_counters = evaluation.document_counters

    # Print the Evaluation Information
    # Refer to https://cloud.google.com/document-ai/docs/reference/rest/v1beta3/projects.locations.processors.processorVersions.evaluations
    # for more information on the available evaluation data
    print(f"Create Time: {create_time}")
    print(f"Input Documents: {document_counters.input_documents_count}")
    print(f"\tInvalid Documents: {document_counters.invalid_documents_count}")
    print(f"\tFailed Documents: {document_counters.failed_documents_count}")
    print(f"\tEvaluated Documents: {document_counters.evaluated_documents_count}")

프로세서 버전의 모든 평가 나열

Python

자세한 내용은 Document AI Python API 참조 문서를 참고하세요.

Document AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def list_evaluations_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    parent = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    evaluations = client.list_evaluations(parent=parent)

    # Print the Evaluation Information
    # Refer to https://cloud.google.com/document-ai/docs/reference/rest/v1beta3/projects.locations.processors.processorVersions.evaluations
    # for more information on the available evaluation data
    print(f"Evaluations for Processor Version {parent}")

    for evaluation in evaluations:
        print(f"Name: {evaluation.name}")
        print(f"\tCreate Time: {evaluation.create_time}\n")

모든 라벨의 평가 측정항목

모든 라벨의 측정항목은 모든 라벨에 걸쳐 데이터 세트의 참양성, 거짓양성, 거짓음성 수를 기반으로 계산되므로 각 라벨이 데이터 세트에 표시되는 횟수에 따라 가중치가 적용됩니다. 이러한 용어의 정의는 개별 라벨의 평가 측정항목을 참고하세요.

• 정밀도: 테스트 세트의 주석과 일치하는 예측의 비율입니다. True Positives / (True Positives + False Positives)로 정의됨

• 재현율: 테스트 세트에서 올바르게 예측된 주석의 비율입니다. True Positives / (True Positives + False Negatives)로 정의됨

• F1 점수: 정밀도와 재현율의 조화 평균으로, 정밀도와 재현율을 단일 측정항목으로 결합하여 두 항목에 동일한 가중치를 부여합니다. 2 * (Precision * Recall) / (Precision + Recall)로 정의됨

참고: Document AI는 정확도 측정항목을 제공하지 않습니다. 정확도 측정항목은 올바르게 예측된 인스턴스의 비율로 정의되는 경우가 많지만, 1) 일부 라벨이 테스트 세트에 표시되지 않을 수 있고 (예: 선택사항 필드) 2) 단일 라벨에 여러 값이 있을 수 있으므로 (예: 인보이스에 있는 광고 항목) 의미가 떨어집니다. 반면 F1은 정확도와 대략적으로 동일하다고 간주할 수 있지만 이러한 시나리오를 더 의미 있게 수용합니다.

개별 라벨의 평가 측정항목

• 참양성: 테스트 문서의 주석과 일치하는 예측된 항목입니다. 자세한 내용은 일치 동작을 참고하세요.

• 거짓양성: 테스트 문서의 주석과 일치하지 않는 예측된 항목입니다.

• 거짓 음성: 테스트 문서의 주석 중 예측된 항목과 일치하지 않는 주석입니다.

  • 거짓음성 (임계값 미만): 예측된 항목과 일치하는 테스트 문서의 주석이지만 예측된 항목의 신뢰도 값이 지정된 신뢰도 임계값 미만입니다.

참고: 거짓양성과 거짓음성은 상호 배타적이지 않습니다. 예를 들어 예측된 항목에 테스트 세트에 잘못된 주석이 있더라도 해당하는 주석이 있는 경우 예측된 항목에 거짓양성이 1개, 주석에 거짓음성이 1개 있습니다. 주석이 없는 예측된 항목은 거짓양성일 뿐입니다. 연결된 예측이 없는 주석은 거짓 음성일 뿐입니다.

도움말: checkbox 추출 품질이 충분하지 않은 경우 양식 파서를 통해 문서를 실행해 보세요. 양식 파서는 체크박스 추출의 품질을 높일 수 있는 정보를 추출합니다. 특히 양식 파서는 체크박스 주위에 경계 상자를 자동으로 그릴 수 있지만 수동으로 그린 경계 상자는 일관성이 떨어질 수 있습니다. 이렇게 하려면 양식 파서를 사용하여 문서를 처리한 다음 처리된 문서를 가져와 다시 주석을 추가합니다.

신뢰도 기준

평가 로직은 예측이 올바르더라도 지정된 신뢰도 기준점 미만인 신뢰도의 예측은 무시합니다. Document AI는 신뢰도 임곗값을 더 낮게 설정하면 일치하는 주석인 거짓음성 (임곗값 미만) 목록을 제공합니다.

Document AI는 F1 점수를 극대화하는 최적의 임곗값을 자동으로 계산하고 기본적으로 신뢰도 임곗값을 이 최적의 값으로 설정합니다.

참고: 최적의 임곗값이 여러 개 있는 경우 (최대 F1 점수가 동일함) 가장 낮은 값이 선택됩니다.

슬라이더 막대를 움직여 원하는 신뢰도 임곗값을 자유롭게 선택할 수 있습니다. 일반적으로 신뢰도 기준점이 높을수록 다음과 같은 결과가 나타납니다.

• 예측이 정확할 가능성이 더 높기 때문에 정밀도가 높습니다.
• 예측이 적기 때문에 재현율이 낮습니다.

표 형식 항목

상위 라벨의 측정항목은 하위 측정항목의 평균을 직접 구하는 것이 아니라 모든 하위 라벨에 상위 라벨의 신뢰도 기준을 적용하고 결과를 집계하여 계산됩니다.

상위 요소의 최적 임곗값은 모든 하위 요소에 적용할 때 상위 요소의 최대 F1 점수를 산출하는 신뢰도 임곗값 값입니다.

일치 동작

예측된 항목이 주석과 일치하는 경우는 다음과 같습니다.

• 예측된 항목의 유형(entity.type)이 주석의 라벨 이름과 일치함
• 예측된 항목의 값(entity.mention_text 또는 entity.normalized_value.text)이 주석의 텍스트 값과 일치하며, 유사 검색이 사용 설정된 경우 이에 따릅니다.

일치에 사용되는 것은 유형과 텍스트 값뿐입니다. 텍스트 앵커 및 경계 상자와 같은 기타 정보 (아래에 설명된 표 형식의 항목 제외)는 사용되지 않습니다.

참고: 일부 신원 프로세서는 텍스트가 없고 신분증 문서에서 사람의 초상화가 있는 위치를 나타내는 경계 상자만으로 구성된 초상화 항목을 추출합니다. 텍스트가 없으므로 세로 라벨과 항목은 평가되지 않습니다.

단일 발생 라벨과 다중 발생 라벨 비교

단일 발생 라벨은 동일한 문서에 값이 여러 번 주석으로 추가되더라도 문서당 하나의 값 (예: 인보이스 ID)을 갖습니다 (예: 인보이스 ID가 동일한 문서의 모든 페이지에 표시됨). 여러 주석의 텍스트가 다르더라도 동일한 것으로 간주됩니다. 즉, 예측된 항목이 주석과 일치하면 일치로 간주됩니다. 추가 주석은 중복 멘션으로 간주되며 참양성, 거짓양성 또는 거짓음성 집계에 기여하지 않습니다.

중복 라벨은 여러 개의 서로 다른 값을 가질 수 있습니다. 따라서 각 예측된 항목과 주석은 별도로 고려되고 일치됩니다. 문서에 다중 발생 라벨에 관한 주석이 N개 포함되어 있으면 예측된 항목과 N개의 일치가 있을 수 있습니다. 각 예측된 개체와 주석은 참양성, 거짓양성 또는 거짓음성으로 독립적으로 집계됩니다.

퍼지 일치

유사 검색 전환 버튼을 사용하면 일부 검색 규칙을 강화하거나 완화하여 검색 결과 수를 줄이거나 늘릴 수 있습니다.

예를 들어 모호한 일치가 없으면 문자열 ABC은 대소문자 때문에 abc와 일치하지 않습니다. 하지만 퍼지 일치를 사용하면 일치합니다.

퍼지 일치가 사용 설정되면 다음과 같이 규칙이 변경됩니다.

• 공백 정규화: 선행 및 후행 공백을 삭제하고 연속된 중간 공백 (줄바꿈 포함)을 단일 공백으로 축약합니다.

• 선행/후행 구두점 삭제: 다음과 같은 선행/후행 구두점 문자 !,.:;-"?|를 삭제합니다.

• 대소문자 구분 불필요 일치: 모든 문자를 소문자로 변환합니다.

• 금액 표준화: 데이터 유형이 money인 라벨의 경우 앞뒤 통화 기호를 삭제합니다.

참고: 숫자 값에는 유사 검색을 사용할 수 없습니다. 예를 들어 퍼지 일치가 사용 설정되어 있더라도 1과 1.00는 일치하지 않습니다.

표 형식 항목

상위 항목 및 주석에는 텍스트 값이 없으며 하위 항목의 결합된 경계 상자를 기준으로 일치합니다. 예측된 상위 요소와 주석이 추가된 상위 요소가 하나씩만 있는 경우 둘은 경계 상자에 관계없이 자동으로 일치합니다.

상위 요소가 일치하면 하위 요소는 테이블 외 항목인 것처럼 일치합니다. 상위 요소가 일치하지 않으면 Document AI는 하위 요소를 일치시키려고 시도하지 않습니다. 즉, 상위 항목이 일치하지 않으면 텍스트 콘텐츠가 동일하더라도 하위 항목이 잘못된 것으로 간주될 수 있습니다.

상위 / 하위 항목은 미리보기 기능이며 중첩 레이어가 하나인 표에만 지원됩니다.

평가 측정항목 내보내기

1. Google Cloud 콘솔에서 프로세서 페이지로 이동하여 프로세서를 선택합니다.

   프로세서 페이지로 이동

2. 평가 및 테스트 탭에서 측정항목 다운로드를 클릭하여 평가 측정항목을 JSON 파일로 다운로드합니다.

참고: 내보낸 측정항목은 내보낼 때의 신뢰도 기준점 슬라이더 값을 기준으로 합니다.