Evalúa el rendimiento

Document AI genera métricas de evaluación, como precisión y recuperación, para ayudarte a determinar el rendimiento predictivo de tus procesadores.

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

Ejecuta una evaluación

Una evaluación se ejecuta automáticamente cada vez que entrenas o actualizas una versión del procesador.

También puedes ejecutar una evaluación de forma manual. Esto es necesario para generar métricas actualizadas después de modificar el conjunto de prueba o si estás evaluando una versión del procesador previamente entrenada.

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

IU web

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

   Ir a la página Procesadores

2. En la pestaña Evaluar y probar, selecciona la Versión del procesador que quieres evaluar y, luego, haz clic en Ejecutar nueva evaluación.

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

Python

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

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para 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}")

Cómo obtener los resultados de una evaluación

IU web

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

   Ir a la página Procesadores

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

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

Python

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

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para 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}")

Enumera todas las evaluaciones de una versión de procesador

Python

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

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para 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 para todas las etiquetas

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

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

• Recuperación: Es la proporción de anotaciones en el conjunto de prueba que se predicen de forma correcta. Se define como True Positives / (True Positives + False Negatives).

• Puntuación F1: Es la media armónica de precisión y recuperación, que combina la precisión y la recuperación en una sola métrica, lo que les otorga el mismo peso a ambas. Se define como 2 * (Precision * Recall) / (Precision + Recall).

Nota: Document AI no proporciona una métrica para la precisión. La métrica de precisión, que a menudo se define 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, campos opcionales) y 2) puede haber varios valores para una sola etiqueta (por ejemplo, líneas de pedido en una factura). Por otro lado, F1 se puede considerar aproximadamente equivalente a la precisión, pero se adapta de manera más significativa a estas situaciones.

Métricas de evaluación para etiquetas individuales

• Verdaderos positivos: Son las entidades predichas que coinciden con una anotación en el documento de prueba. Para obtener más información, consulta Comportamiento de coincidencia.

• Falsos positivos: Son las entidades previstas que no coinciden con ninguna anotación en el documento de prueba.

• Falsos negativos: Son las anotaciones en el documento de prueba que no coinciden con ninguna de las entidades previstas.

  • Falsos negativos (por debajo del umbral): Son las anotaciones en el documento de prueba que coincidirían con una entidad prevista, pero el valor de confianza de la entidad prevista 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 incorrecta, en el conjunto de prueba, entonces hay un falso positivo para la entidad predicha y un falso negativo para la anotación. Una entidad prevista sin una anotación es solo un falso positivo. Una anotación sin una predicción asociada es solo un falso negativo.

Sugerencia: Si la calidad de la extracción de checkbox no es lo suficientemente alta, considera ejecutar los documentos a través del analizador de formularios. El analizador de formularios extrae información que podría mejorar la calidad de la extracción de cuadros de verificación. Específicamente, Form Parser puede dibujar automáticamente cuadros de límite alrededor de las casillas de verificación, mientras que los cuadros de límite dibujados de forma manual pueden ser menos coherentes. Para ello, procesa tus documentos con el analizador de formularios, luego, import los documentos procesados y vuelve a anotarlos.

Límite de confianza

La lógica de evaluación ignora las predicciones con una confianza inferior al umbral de confianza especificado, incluso si la predicción es correcta. Document AI proporciona una lista de falsos negativos (por debajo del umbral), que son las anotaciones que coincidirían si el umbral de confianza se estableciera en un valor más bajo.

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

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

Puedes elegir tu propio umbral de confianza moviendo la barra deslizante. En general, un umbral de confianza más alto genera lo siguiente:

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

Entidades tabulares

Las métricas de una etiqueta superior no se calculan promediando directamente 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 para el elemento superior es el valor del umbral de confianza que, cuando se aplica a todos los elementos secundarios, genera la puntuación F1 máxima para el elemento superior.

Comportamiento de coincidencia

Una entidad predicha coincide con una anotación en los siguientes casos:

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

Ten en cuenta que solo se usan el tipo y el valor de texto para la coincidencia. No se usa otra información, como anclas de texto y cuadros delimitados (con la excepción de las entidades tabulares que se describen a continuación).

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

Etiquetas de una sola ocurrencia en comparación con etiquetas de varias ocurrencias

Las etiquetas de ocurrencia única tienen un valor por documento (por ejemplo, el ID de factura) incluso si ese valor se anota varias veces en el mismo documento (por ejemplo, el ID de factura aparece en cada página del mismo documento). Incluso si las múltiples anotaciones tienen texto diferente, se consideran iguales. En otras palabras, si una entidad predicha coincide con alguna de las anotaciones, se cuenta como una coincidencia. Las anotaciones adicionales se consideran menciones duplicadas y no contribuyen a ninguno de los recuentos de verdaderos positivos, falsos positivos ni falsos negativos.

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

Concordancias parciales

El botón de activación Coincidencia aproximada te permite endurecer o relajar algunas de las reglas de coincidencia para disminuir o aumentar la cantidad de coincidencias.

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

Cuando se habilita la coincidencia parcial, se producen los siguientes cambios en las reglas:

• Normalización de espacios en blanco: Quita los espacios en blanco iniciales y finales, y condensa los espacios en blanco intermedios consecutivos (incluidas las líneas nuevas) en espacios simples.

• Eliminación de puntuación inicial o final: Quita los siguientes caracteres de puntuación inicial o final !,.:;-"?|.

• Coincidencia sin distinción entre mayúsculas y minúsculas: Convierte todos los caracteres en minúsculas.

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

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

Entidades tabulares

Las entidades superiores y las anotaciones no tienen valores de texto y se hacen coincidir en función de los cuadros delimitados combinados de sus elementos secundarios. Si solo hay un elemento superior previsto y uno anotado, se hacen coincidir automáticamente, independientemente de los cuadros delimitadores.

Una vez que se encuentran las coincidencias de los elementos superiores, sus elementos secundarios se encuentran como si fueran entidades no tabulares. Si no hay coincidencias entre los elementos superiores, Document AI no intentará hacer coincidir sus elementos secundarios. Esto significa que las entidades secundarias se pueden considerar incorrectas, incluso con el mismo contenido de texto, si sus entidades superiores no coinciden.

Las entidades superiores o secundarias son una función de versión preliminar y solo se admiten para tablas con una capa de anidación.

Exporta métricas de evaluación

1. En la consola de Google Cloud, ve a la página Procesadores y elige tu 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.