Avalie o desempenho

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

Estas métricas de avaliação são geradas comparando as entidades devolvidas pelo processador (as previsões) com as anotações nos documentos de teste. Se o seu processador não tiver um conjunto de testes, tem primeiro de criar um conjunto de dados e etiquetar os documentos de teste.

Execute uma avaliação

É executada automaticamente uma avaliação sempre que forma ou atualiza uma versão do processador.

Também pode executar manualmente uma avaliação. Isto é necessário para gerar métricas atualizadas depois de modificar o conjunto de testes ou se estiver a avaliar uma versão do processador pré-treinado.

Nota: a IA Documentos não calcula nem calcula métricas de avaliação para uma etiqueta se a versão do processador não conseguir extrair essa etiqueta (por exemplo, a etiqueta foi desativada no momento da preparação) ou se o conjunto de testes não incluir anotações para essa etiqueta. Essas etiquetas não estão incluídas nas métricas agregadas.

IU da Web

1. Na Google Cloud consola, aceda à página Processadores e escolha o seu processador.

   Aceda à página Processadores

2. No separador Avaliar e testar, selecione a versão do processador a avaliar e, de seguida, clique em Executar nova avaliação.

Quando estiver concluída, a página contém métricas de avaliação para todas as etiquetas e para cada etiqueta individual.

Python

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

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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}")

Obtenha os resultados de uma avaliação

IU da Web

1. Na Google Cloud consola, aceda à página Processadores e escolha o seu processador.

   Aceda à página Processadores

2. No separador Avaliar e testar, selecione a versão do processador para ver a avaliação.

Quando estiver concluída, a página contém métricas de avaliação para todas as etiquetas e para cada etiqueta individual.

Python

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

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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}")

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

Python

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

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 para todas as etiquetas

As métricas para Todas as etiquetas são calculadas com base no número de verdadeiros positivos, falsos positivos e falsos negativos no conjunto de dados em todas as etiquetas e, por isso, são ponderadas pelo número de vezes que cada etiqueta aparece no conjunto de dados. Para ver as definições destes termos, consulte o artigo Métricas de avaliação para etiquetas individuais.

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

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

• Pontuação F1: o meio harmónico de precisão e revocação, que combina a precisão e a revocação numa única métrica, atribuindo igual importância a ambas. Definido como 2 * (Precision * Recall) / (Precision + Recall)

Nota: o Document AI não fornece uma métrica para a precisão. A métrica de precisão, frequentemente definida como a proporção de instâncias previstas corretamente, é menos significativa porque 1) nem todas as etiquetas aparecem no conjunto de testes (por exemplo, campos opcionais) e 2) pode haver vários valores para uma única etiqueta (por exemplo, elementos publicitários numa fatura). Por outro lado, o F1 pode ser considerado aproximadamente equivalente à precisão, mas acomoda de forma mais significativa estes cenários.

Métricas de avaliação para etiquetas individuais

• Verdadeiros positivos: as entidades previstas que correspondem a uma anotação no documento de teste. Para mais informações, consulte o artigo sobre o 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 de confiança especificado.

Nota: os falsos positivos e os falsos negativos não são mutuamente exclusivos. Por exemplo, se uma entidade prevista tiver uma anotação correspondente, embora incorreta, no conjunto de testes, existe 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.

Sugestão: se a qualidade da extração de checkbox não for suficientemente elevada, considere executar os documentos através do Form Parser. O analisador de formulários extrai informações que podem aumentar potencialmente a qualidade da extração de caixas de verificação. Em concreto, o analisador de formulários pode desenhar automaticamente caixas de limite em torno das caixas de verificação, enquanto as caixas de limite desenhadas manualmente podem ser menos consistentes. Para o fazer, processe os documentos através da análise de formulários e, em seguida, importe os documentos processados e anote-os novamente.

Limite de confiança

A lógica de avaliação ignora todas as previsões com uma confiança inferior ao limite de confiança especificado, mesmo que a previsão esteja correta. A IA Documentos 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 inferior.

A IA Documentos calcula automaticamente o limite ideal, que maximiza a pontuação F1 e, por predefinição, define o limite de confiança para este valor ideal.

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

Pode escolher o seu próprio limiar de confiança movendo a barra de controlo de deslize. Em geral, um limite de confiança mais elevado resulta no seguinte:

• Maior precisão, porque é mais provável que as previsões estejam corretas.
• Uma menor capacidade de memorização, porque existem menos previsões.

Entidades tabulares

As métricas de uma etiqueta principal não são calculadas através da média direta das métricas secundárias, mas sim aplicando o limite de confiança da principal a todas as etiquetas secundárias e agregando os resultados.

O limite ideal para o elemento principal é o valor do limite de confiança que, quando aplicado a todos os elementos secundários, produz a pontuação F1 máxima para o elemento principal.

Comportamento de correspondência

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

• O tipo da entidade prevista (entity.type) corresponde ao nome da etiqueta 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 à correspondência aproximada, se estiver ativada.

Tenha em atenção que o tipo e o valor de texto são tudo o que é usado para a correspondência. Não são usadas outras informações, como as âncoras de texto e as caixas delimitadoras (com exceção das entidades tabulares descritas abaixo).

Nota: alguns processadores de identidade extraem uma entidade Retrato, que não contém texto e apenas uma caixa delimitadora que indica onde está o retrato de uma pessoa num documento de identidade. Uma vez que não tem texto, as etiquetas e as entidades de retratos não são avaliadas.

Etiquetas de ocorrência única versus múltipla

As etiquetas 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 texto diferente, são consideradas iguais. Por outras palavras, se uma entidade prevista corresponder a alguma das anotações, é considerada uma correspondência. As anotações adicionais são consideradas menções duplicadas e não contribuem para nenhuma das contagens de verdadeiros positivos, falsos positivos ou falsos negativos.

As etiquetas de ocorrência múltipla podem ter vários valores diferentes. Assim, cada entidade e anotação prevista é considerada e correspondida separadamente. Se um documento contiver N anotações para uma etiqueta de ocorrências múltiplas, podem existir N correspondências com as entidades previstas. Cada entidade e anotação previstas são contabilizadas independentemente como um verdadeiro positivo, um falso positivo ou um falso negativo.

Correspondência semelhante

O botão Correspondência aproximada permite-lhe restringir ou relaxar 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 maiúsculas. No entanto, com a correspondência semelhante, correspondem.

Quando a correspondência aproximada está ativada, as regras são alteradas da seguinte forma:

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

• Remoção de pontuação à esquerda/direita: remove os seguintes carateres de pontuação à esquerda/direita !,.:;-"?|.

• Correspondência não sensível a maiúsculas/minúsculas: converte todos os carateres em minúsculas.

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

Nota: não pode usar a correspondência aproximada em valores numéricos. Por exemplo, 1 e 1.00 não correspondem, mesmo quando a correspondência aproximada está ativada.

Entidades tabulares

As entidades principais e as anotações não têm valores de texto e são correspondidas com base nas caixas delimitadoras combinadas dos respetivos elementos secundários. Se existir apenas um elemento principal previsto e um elemento principal anotado, estes são automaticamente associados, independentemente das caixas delimitadoras.

Depois de os pais serem associados, os filhos são associados como se fossem entidades não tabulares. Se não for encontrada uma correspondência para os pais, o Document AI não tenta encontrar uma correspondência para os filhos. Isto significa que as entidades secundárias podem ser consideradas incorretas, mesmo com o mesmo conteúdo de texto, se as respetivas entidades principais não forem correspondentes.

As entidades principais / secundárias são uma funcionalidade de pré-visualização e só são suportadas para tabelas com uma camada de aninhamento.

Exporte métricas de avaliação

1. Na Google Cloud consola, aceda à página Processadores e escolha o seu processador.

   Aceda à página Processadores

2. No separador Avaliar e testar, clique em Transferir métricas para transferir as métricas de avaliação como um ficheiro JSON.

Nota: as métricas exportadas baseiam-se no valor do controlo deslizante do Limite de confiança no momento da exportação.