Avaliar a performance

A Document AI gera métricas de avaliação, como precisão e recall, para ajudar 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 testes, primeiro crie um conjunto de dados e rotule os documentos de teste.

Execute 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.

Observação: a Document AI não calcula as métricas de avaliação de um rótulo se a versão do processador não conseguir extrair esse rótulo (por exemplo, se ele foi desativado no momento do treinamento) ou se o conjunto de teste não incluir anotações para esse rótulo. Esses rótulos não são incluídos nas métricas agregadas.

IU da Web

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

   Acessar a página "Processadores"

2. Na guia Avaliar e testar, selecione a Versão do processador a ser avaliada e clique em Executar nova avaliação.

Quando concluída, a página contém métricas de avaliação para todos os rótulos e para cada rótulo individual.

Python

Para mais informações, consulte a documentação de referência da API Document AI Python.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Conferir os resultados de uma avaliação

IU da Web

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

   Acessar a página "Processadores"

2. Na guia Avaliar e testar, selecione a Versão do processador para conferir a avaliação.

Quando concluída, a página contém métricas de avaliação para todos os rótulos e para cada rótulo individual.

Python

Para mais informações, consulte a documentação de referência da API Document AI Python.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Python

Para mais informações, consulte a documentação de referência da API Document AI Python.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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 de todos os rótulos

As métricas de Todos os rótulos são computadas com base no número de verdadeiros positivos, falsos positivos e falsos negativos no conjunto de dados em todos os rótulos e, portanto, 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 precisão e recall em uma única métrica, fornecendo peso igual para ambos. Definido como 2 * (Precision * Recall) / (Precision + Recall)

Observação: a Document AI não fornece uma métrica de precisão. A métrica de precisão, muitas vezes definida como a proporção de instâncias que são previstas corretamente, é menos significativa porque 1) nem todos os rótulos aparecem no conjunto de teste (por exemplo, campos opcionais) e 2) pode haver vários valores para um único rótulo (por exemplo, itens de linha em uma fatura). O F1, por outro lado, pode ser considerado aproximadamente equivalente à precisão, mas acomoda esses cenários de maneira mais significativa.

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

• Verdadeiro positivo: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 teriam correspondido a uma entidade prevista, mas o valor de confiança da entidade prevista está abaixo do limite de confiança especificado.

Observação: falsos positivos e falsos negativos não são mutuamente exclusivos. Por exemplo, se uma entidade prevista tiver uma anotação correspondente, embora incorreta, no conjunto de teste, haverá um falso positivo para a entidade prevista e um falso negativo para a anotação. Uma entidade prevista sem uma anotação é apenas um falso positivo. Uma anotação sem uma previsão associada é apenas um falso negativo.

Dica: se a qualidade da extração de checkbox não for alta o suficiente, considere executar os documentos pelo analisador de formulários. O Parser de formulários extrai informações que podem melhorar a qualidade da extração de caixas de seleção. Especificamente, o Parser de formulários pode desenhar automaticamente caixas delimitadoras em torno de caixas de seleção, enquanto as caixas delimitadoras desenhadas manualmente podem ser menos consistentes. Para fazer isso, processe seus documentos usando o analisador de formulários, depois import os documentos processados e anote-os novamente.

Limite de confiança

A lógica de avaliação ignora todas as previsões com confiança abaixo do limite de confiança especificado, mesmo que a previsão esteja correta. A Document AI oferece 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 menor.

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

Observação: se houver vários valores de limite ideais (com a mesma pontuação F1 máxima), o valor mais baixo será escolhido.

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 estar corretas.
• menor recall, porque há menos previsões.

Entidades tabulares

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

O limite ideal para o pai é o valor de limite de confiança que, quando aplicado a todos os filhos, gera a pontuação F1 máxima para o 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 ela estiver ativada.

O tipo e o valor de texto são usados para a correspondência. Outras informações, como âncoras de texto e caixas delimitadoras (com exceção das entidades tabulares descritas abaixo), não são usadas.

Observação: alguns processadores de identidade extraem uma entidade retrato, que consiste em nenhum texto e apenas uma caixa delimitadora que indica onde o retrato de uma pessoa está em um documento de identidade. Como ele não tem texto, os rótulos e entidades de retrato não são avaliados.

Rótulos de ocorrência única e de várias ocorrências

Os rótulos de ocorrência única têm um valor por documento (por exemplo, o 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 verdadeiros positivos, falsos positivos ou falsos negativos.

Os rótulos de várias ocorrências podem ter vários valores diferentes. Assim, cada entidade e anotação previstas são consideradas e correspondidas 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 verdadeiro positivo, falso positivo ou falso negativo.

Correspondência difusa

O botão Correspondência aproximada permite restringir ou relaxar algumas das regras de correspondência para diminuir ou aumentar o número de correspondências.

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

Quando a correspondência parcial está ativada, as regras mudam da seguinte forma:

• Normalização de espaços:remove espaços em branco iniciais e finais e condensa espaços em branco intermediários consecutivos (incluindo quebras de linha) em espaços únicos.

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

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

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

Observação: não é possível usar a correspondência aproximada em valores numéricos. Por exemplo, 1 e 1.00 não correspondem, mesmo quando a correspondência parcial está ativada.

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 filhos. Se houver apenas um pai previsto e um pai anotado, eles serão correspondidos automaticamente, independentemente das caixas de delimitações.

Depois que os pais são associados, os filhos são associados como se fossem entidades não tabulares. Se os pais não forem correspondentes, o Document AI não vai tentar fazer a correspondência dos filhos. Isso significa que as entidades filhas podem ser consideradas incorretas, mesmo com o mesmo conteúdo de texto, se as entidades mãe não forem correspondidas.

As entidades mãe / filha são um recurso de pré-lançamento e só são compatíveis com tabelas com uma camada de aninhamento.

Exportar métricas de avaliação

1. No console do 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 fazer o download das métricas de avaliação como um arquivo JSON.

Observação: as métricas exportadas são baseadas no valor do controle deslizante Limite de confiança no momento da exportação.