Evaluar el rendimiento

Document AI genera métricas de evaluación, como la precisión y el recuerdo, que te ayudan a determinar el rendimiento predictivo de tus procesadores.

Estas métricas de evaluación se generan comparando las entidades que devuelve el procesador (las predicciones) con las anotaciones que hay en los documentos de prueba. Si tu procesador no tiene un conjunto de pruebas, primero debes crear un conjunto de datos y etiquetar los documentos de prueba.

Haz una evaluación

Cada evaluación se ejecuta automáticamente cada vez que entrenas o mejoras una versión de un procesador.

También puedes ejecutar una evaluación manualmente. Es obligatorio para generar métricas actualizadas después de modificar el conjunto de pruebas o si estás evaluando una versión de procesador preentrenada.

Nota: Document AI no puede calcular las métricas de evaluación de una etiqueta si la versión del procesador no puede extraerla (por ejemplo, si la etiqueta se inhabilitó en el momento del entrenamiento) o si el conjunto de pruebas no incluye anotaciones de esa etiqueta. Estas etiquetas no se incluyen en las métricas agregadas.

UI web

1. En la Google Cloud consola, ve a la página Procesadores y elige el procesador.

   Ir a la página Procesadores

2. En la pestaña Evaluar y probar, seleccione la versión del procesador que quiera evaluar y, a continuación, haga clic en Ejecutar nueva evaluación.

Una vez completado el proceso, la página contiene métricas de evaluación de todas las etiquetas y de cada etiqueta individual.

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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}")

Obtener los resultados de una evaluación

UI web

1. En la Google Cloud consola, ve a la página Procesadores y elige el procesador.

   Ir a la página Procesadores

2. En la pestaña Evaluar y probar, seleccione la versión del procesador para ver la evaluación.

Una vez completado el proceso, la página contiene métricas de evaluación de todas las etiquetas y de cada etiqueta individual.

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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}")

Mostrar todas las evaluaciones de una versión de un procesador

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 evaluación de todas las etiquetas

Las métricas de Todas las etiquetas se calculan en función del número de verdaderos positivos, falsos positivos y falsos negativos del conjunto de datos en todas las etiquetas. Por lo tanto, se ponderan según el número de veces que aparece cada etiqueta en el conjunto de datos. Para ver las definiciones de estos términos, consulta Métricas de evaluación de etiquetas individuales.

• Precisión: proporción de predicciones que coinciden con las anotaciones del conjunto de prueba. Definido como True Positives / (True Positives + False Positives)

• Recuerdo: proporción de anotaciones del conjunto de prueba que se han predicho correctamente. Definido como True Positives / (True Positives + False Negatives)

• Puntuación F1: media armónica de la precisión y la recuperación, que combina ambas métricas en una sola y les da la misma importancia. Definido como 2 * (Precision * Recall) / (Precision + Recall)

Nota: Document AI no proporciona una métrica de precisión. La métrica de precisión, que se define a menudo como la proporción de instancias que se predicen correctamente, es menos significativa porque 1) no todas las etiquetas aparecen en el conjunto de prueba (por ejemplo, los campos opcionales) y 2) puede haber varios valores para una sola etiqueta (por ejemplo, las líneas de pedido de una factura). Por otro lado, F1 se puede considerar aproximadamente equivalente a la precisión, pero se adapta mejor a estos casos.

Métricas de evaluación de etiquetas concretas

• Verdaderos positivos: las entidades predichas que coinciden con una anotación del documento de prueba. Para obtener más información, consulta el comportamiento de las coincidencias.

• Falsos positivos: las entidades predichas que no coinciden con ninguna anotación del documento de prueba.

• Falsos negativos: las anotaciones del documento de prueba que no coinciden con ninguna de las entidades predichas.

  • Falsos negativos (por debajo del umbral): las anotaciones del documento de prueba que habrían coincidido con una entidad predicha, pero el valor de confianza de la entidad predicha está por debajo del umbral de confianza especificado.

Nota: Los falsos positivos y los falsos negativos no son mutuamente excluyentes. Por ejemplo, si una entidad predicha tiene una anotación correspondiente, aunque sea incorrecta, en el conjunto de prueba, habrá un falso positivo para la entidad predicha y un falso negativo para la anotación. Una entidad predicha sin una anotación es solo un falso positivo. Una anotación sin una predicción asociada es solo un falso negativo.

Nota: Si la calidad de la extracción de checkbox no es lo suficientemente alta, considera la posibilidad de procesar los documentos con Form Parser. El analizador de formularios extrae información que podría mejorar la calidad de la extracción de casillas. En concreto, Form Parser puede dibujar automáticamente cuadros delimitadores alrededor de las casillas de verificación, mientras que los cuadros delimitadores dibujados manualmente pueden ser menos coherentes. Para ello, procesa tus documentos con el analizador de formularios y, a continuación, importa los documentos procesados y vuelve a añadirles anotaciones.

Umbral de confianza

La lógica de evaluación ignora las predicciones con una confianza inferior al umbral de confianza especificado, aunque la predicción sea correcta. Document AI proporciona una lista de falsos negativos (por debajo del umbral), que son las anotaciones que tendrían una coincidencia si el umbral de confianza fuera más bajo.

Document AI calcula automáticamente el umbral óptimo, que maximiza la puntuación F1, y, de forma predeterminada, define el umbral de confianza en este valor óptimo.

Nota: Si hay varios valores de umbral óptimos (con la misma puntuación F1 máxima), se elige el valor más bajo.

Puedes elegir el umbral de confianza que quieras moviendo la barra deslizante. En general, un umbral de confianza más alto da como resultado lo siguiente:

• una mayor precisión, ya que es más probable que las predicciones sean correctas.
• una recuperación menor, ya que hay menos predicciones.

Entidades tabulares

Las métricas de una etiqueta superior no se calculan haciendo la media directamente de las métricas secundarias, sino aplicando el umbral de confianza de la etiqueta superior a todas sus etiquetas secundarias y agregando los resultados.

El umbral óptimo del elemento superior es el valor del umbral de confianza que, cuando se aplica a todos los elementos secundarios, da como resultado la puntuación F1 máxima del elemento superior.

Comportamiento de la coincidencia

Una entidad predicha coincide con una anotación si:

• El tipo de la entidad predicha (entity.type) coincide con el nombre de la etiqueta de la anotación.
• El valor de la entidad predicha (entity.mention_text o entity.normalized_value.text) coincide con el valor de texto de la anotación, sujeto a la coincidencia aproximada si está habilitada.

Ten en cuenta que solo se usan el tipo y el valor de texto para las coincidencias. No se usa otra información, como anclas de texto y cuadros delimitadores (excepto las entidades tabulares descritas más abajo).

Nota: Algunos procesadores de identidad extraen una entidad Retrato, que no contiene texto y solo incluye un cuadro delimitador que indica dónde se encuentra el retrato de una persona en un documento de identidad. Como no tiene texto, no se evalúan las etiquetas ni las entidades de retrato.

Etiquetas de una o varias ocurrencias

Las etiquetas de una sola aparición tienen un valor por documento (por ejemplo, el ID de factura), aunque ese valor se anote varias veces en el mismo documento (por ejemplo, el ID de factura aparece en todas las páginas del mismo documento). Aunque las anotaciones tengan textos diferentes, se consideran iguales. Es decir, si una entidad predicha coincide con alguna de las anotaciones, se considera una coincidencia. Las anotaciones adicionales se consideran menciones duplicadas y no contribuyen a los recuentos de verdaderos positivos, falsos positivos o falsos negativos.

Las etiquetas de varias ocurrencias pueden tener varios valores diferentes. Por lo tanto, cada entidad y anotación predichas se consideran y se emparejan por separado. Si un documento contiene N anotaciones para una etiqueta de varias ocurrencias, puede haber N coincidencias con las entidades predichas. Cada entidad y anotación predichas se contabilizan de forma independiente como un positivo verdadero, un falso positivo o un falso negativo.

Coincidencia parcial

El interruptor Coincidencia aproximada te permite ajustar o relajar algunas de las reglas de coincidencia para aumentar o reducir el número de coincidencias.

Por ejemplo, sin la coincidencia aproximada, la cadena ABC no coincide con abc debido a las mayúsculas. Sin embargo, con la coincidencia parcial, sí coinciden.

Si la coincidencia aproximada está habilitada, las reglas cambian de la siguiente manera:

• Normalización de espacios en blanco: elimina los espacios en blanco iniciales y finales, y condensa los espacios en blanco intermedios consecutivos (incluidos los saltos de línea) en espacios únicos.

• Eliminación de signos de puntuación iniciales o finales: elimina los siguientes signos de puntuación iniciales o finales: !,.:;-"?|.

• Búsqueda que no distingue entre mayúsculas y minúsculas: convierte todos los caracteres a minúsculas.

• Normalización de dinero: en las etiquetas con el tipo de datos money, elimina los símbolos de moneda iniciales y finales.

Nota: No puedes usar la coincidencia aproximada en valores numéricos. Por ejemplo, 1 y 1.00 no coinciden, aunque la coincidencia aproximada esté habilitada.

Entidades tabulares

Las entidades y las anotaciones principales no tienen valores de texto y se emparejan en función de los cuadros delimitadores combinados de sus elementos secundarios. Si solo hay un elemento superior predicho y un elemento superior anotado, se emparejan automáticamente, independientemente de los cuadros delimitadores.

Una vez que se emparejan los padres, sus hijos se emparejan como si fueran entidades no tabulares. Si no se encuentran coincidencias con los padres, Document AI no intentará encontrar coincidencias con sus hijos. Esto significa que las entidades secundarias se pueden considerar incorrectas, aunque tengan el mismo contenido de texto, si sus entidades principales no coinciden.

Las entidades principales y secundarias son una función de vista previa y solo se admiten en tablas con una capa de anidación.

Exportar métricas de evaluación

1. En la Google Cloud consola, ve a la página Procesadores y elige el procesador.

   Ir a la página Procesadores

2. En la pestaña Evaluar y probar, haz clic en Descargar métricas para descargar las métricas de evaluación como un archivo JSON.

Nota: Las métricas exportadas se basan en el valor del control deslizante Umbral de confianza en el momento de la exportación.