Avaliar a performance

A Document AI gera métricas de avaliação, como precisão e recall, para ajudar você a determinar o desempenho preditivo dos processadores.

Essas métricas de avaliação são geradas com a comparação das entidades retornadas pelo processador (as previsões) com as anotações nos documentos de teste. Se o processador não tiver um conjunto de teste, primeiro crie um conjunto de dados e rotule os documentos de teste.

Executar uma avaliação

Uma avaliação é executada automaticamente sempre que você treina ou treina uma versão do processador.

Também é possível executar uma avaliação manualmente. Isso é necessário para gerar métricas atualizadas depois de modificar o conjunto de teste ou se você estiver avaliando uma versão de processador pré-treinada.

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}")

Receber os resultados de uma avaliação

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}")

Listar todas as avaliações de uma versão do processador

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")

Métricas de avaliação para todos os rótulos

As métricas de Todos os rótulos são calculadas com base no número de verdadeiros positivos, falsos positivos e falsos negativos no conjunto de dados em todos os rótulos. Portanto, elas são ponderadas pelo número de vezes que cada rótulo aparece no conjunto de dados. Para definições desses termos, consulte Métricas de avaliação para rótulos individuais.

• Precisão:a proporção de previsões que correspondem às anotações no conjunto de teste. Definido como True Positives / (True Positives + False Positives)

• Recall:a proporção de anotações no conjunto de teste que são previstas corretamente. Definido como True Positives / (True Positives + False Negatives)

• Pontuação F1:a média harmônica de precisão e recall, que combina as duas em uma única métrica, peso igual a ambas. Definido como 2 * (Precision * Recall) / (Precision + Recall)

Métricas de avaliação para rótulos individuais

• Verdadeiros positivos:as entidades previstas que correspondem a uma anotação no documento de teste. Para mais informações, consulte comportamento de correspondência.

• Falsos positivos:as entidades previstas que não correspondem a nenhuma anotação no documento de teste.

• Falsos negativos:as anotações no documento de teste que não correspondem a nenhuma das entidades previstas.

  • Falsos negativos (abaixo do limite): as anotações no documento de teste que corresponderiam a uma entidade prevista, mas o valor de confiança da entidade prevista está abaixo do limite especificado.

Limite de confiança

A lógica de avaliação ignora previsões com confiança abaixo do limite de confiança especificado, mesmo que a previsão esteja correta. A Document AI fornece uma lista de Falsos negativos (abaixo do limite), que são as anotações que teriam uma correspondência se o limite de confiança fosse definido como mais baixo.

A Document AI calcula automaticamente o limite ideal, que maximiza a pontuação F1, e define o limite de confiança como esse valor ideal por padrão.

Você pode escolher seu próprio limite de confiança movendo a barra deslizante. Em geral, um limite de confiança mais alto resulta em:

• maior precisão, porque as previsões têm mais chances de estarem corretas.
• recall menor, porque há menos previsões.

Entidades tabulares

As métricas de um rótulo pai não são calculadas fazendo a média direta das métricas filhas, mas aplicando o limite de confiança do rótulo pai a todos os rótulos filhos e agregando os resultados.

O limite ideal para o elemento pai é o valor do limite de confiança que, quando aplicado a todos os elementos filhos, gera a pontuação F1 máxima para o elemento pai.

Comportamento de correspondência

Uma entidade prevista corresponde a uma anotação se:

• o tipo da entidade prevista (entity.type) corresponde ao nome do rótulo da anotação
• o valor da entidade prevista (entity.mention_text ou entity.normalized_value.text) corresponde ao valor de texto da anotação, sujeito a correspondência aproximada se estiver ativada.

O tipo e o valor do texto são tudo o que é usado para correspondência. Outras informações, como âncoras de texto e caixas delimitadoras (exceto entidades tabulares descritas abaixo), não são usadas.

Rótulos de ocorrência única e múltipla

Os rótulos de ocorrência única têm um valor por documento (por exemplo, ID da fatura), mesmo que esse valor seja anotado várias vezes no mesmo documento (por exemplo, o ID da fatura aparece em todas as páginas do mesmo documento). Mesmo que as várias anotações tenham textos diferentes, elas são consideradas iguais. Em outras palavras, se uma entidade prevista corresponder a qualquer uma das anotações, ela será considerada uma correspondência. As anotações extras são consideradas menções duplicadas e não contribuem para nenhuma das contagens de verdadeiro positivo, falso positivo ou falso negativo.

Os rótulos de várias ocorrências podem ter valores diferentes. Assim, cada entidade e anotação prevista é considerada e correspondida separadamente. Se um documento tiver N anotações para um rótulo de várias ocorrências, poderá haver N correspondências com as entidades previstas. Cada entidade e anotação previstas são contadas de forma independente como um verdadeiro positivo, falso positivo ou falso negativo.

Correspondência difusa

Com a opção Correspondência aproximada, é possível restringir ou flexibilizar algumas das regras de correspondência para diminuir ou aumentar o número de correspondências.

Por exemplo, sem a correspondência aproximada, a string ABC não corresponde a abc devido ao uso de letras maiúsculas. Mas com a correspondência parcial, elas correspondem.

Quando a correspondência parcial está ativada, as mudanças na regra são as seguintes:

• Normalização de espaços em branco:remove os espaços em branco à esquerda e à direita e condensa espaços em branco intermediários consecutivos (incluindo novas linhas) em espaços únicos.

• Remoção de pontuação inicial/final:remove os seguintes caracteres de pontuação inicial/final !,.:;-"?|.

• Correspondência sem diferenciação de maiúsculas e minúsculas:converte todos os caracteres para minúsculas.

• Normalização de moeda:para rótulos com o tipo de dados money, remova os símbolos de moeda inicial e final.

Entidades tabulares

As entidades e anotações principais não têm valores de texto e são correspondidas com base nas caixas delimitadoras combinadas dos elementos filhos. Se houver apenas um elemento previsto e um anotado, eles serão correspondidos automaticamente, independentemente das caixas delimitadoras.

Depois que os pais são pareados, as crianças são pareadas como se fossem entidades não tabulares. Se os familiares não forem correspondentes, a Document AI não tentará corresponder as crianças. Isso significa que as entidades filhas podem ser consideradas incorretas, mesmo com o mesmo conteúdo de texto, se as entidades principais não forem correspondentes.

As entidades pai / filho são um recurso de prévia e só são compatíveis com tabelas que têm uma camada de aninhamento.

Exportar métricas de avaliação

1. No console Google Cloud , acesse a página Processadores e escolha seu processador.

   Acessar a página "Processadores"

2. Na guia Avaliar e testar, clique em Fazer o download das métricas para baixar as métricas de avaliação como um arquivo JSON.