Évaluer les performances

Document AI génère des métriques d'évaluation, telles que la précision et le rappel, pour vous aider à déterminer les performances prédictives de vos processeurs.

Ces métriques d'évaluation sont générées en comparant les entités renvoyées par le processeur (les prédictions) avec les annotations des documents de test. Si votre processeur ne dispose pas d'ensemble de test, vous devez d'abord créer un ensemble de données et étiqueter les documents de test.

Exécuter une évaluation

Une évaluation est automatiquement exécutée chaque fois que vous entraînez ou surentraînez une version de processeur.

Vous pouvez également exécuter une évaluation manuellement. Cela est nécessaire pour générer des métriques à jour après avoir modifié l'ensemble de test ou si vous évaluez une version de l'outil de traitement préentraîné.

Remarque :Document AI ne peut pas et ne calcule pas les métriques d'évaluation d'une étiquette si la version du processeur ne peut pas l'extraire (par exemple, l'étiquette était désactivée au moment de l'entraînement) ou si l'ensemble de test n'inclut pas d'annotations pour cette étiquette. Ces libellés ne sont pas inclus dans les métriques cumulées.

UI Web

1. Dans la console Google Cloud, accédez à la page Processeurs, puis sélectionnez votre processeur.

   Accéder à la page "Outils de traitement"

2. Dans l'onglet Évaluer et tester, sélectionnez la version de l'outil de traitement à évaluer, puis cliquez sur Exécuter une nouvelle évaluation.

Une fois l'opération terminée, la page contient des métriques d'évaluation pour tous les libellés et pour chaque libellé individuel.

Python

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Python.

Pour vous authentifier auprès de Document AI, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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}")

Obtenir les résultats d'une évaluation

UI Web

1. Dans la console Google Cloud, accédez à la page Processeurs, puis sélectionnez votre processeur.

   Accéder à la page "Outils de traitement"

2. Dans l'onglet Évaluer et tester, sélectionnez la version de l'outil de traitement pour afficher l'évaluation.

Une fois l'opération terminée, la page contient des métriques d'évaluation pour tous les libellés et pour chaque libellé individuel.

Python

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Python.

Pour vous authentifier auprès de Document AI, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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}")

Répertorier toutes les évaluations d'une version de processeur

Python

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Python.

Pour vous authentifier auprès de Document AI, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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étriques d'évaluation pour tous les libellés

Les métriques pour Tous les libellés sont calculées en fonction du nombre de vrais positifs, de faux positifs et de faux négatifs dans l'ensemble de données pour tous les libellés. Elles sont donc pondérées en fonction du nombre de fois où chaque libellé apparaît dans l'ensemble de données. Pour connaître la définition de ces termes, consultez la section Métriques d'évaluation pour les étiquettes individuelles.

• Précision:proportion des prédictions qui correspondent aux annotations de l'ensemble de test. Défini comme True Positives / (True Positives + False Positives)

• Rappel:proportion des annotations de l'ensemble de test qui sont correctement prédites. Défini comme True Positives / (True Positives + False Negatives)

• Score F1:moyenne harmonique de la précision et du rappel, qui combine la précision et le rappel dans une seule métrique, en leur attribuant une pondération égale. Défini comme 2 * (Precision * Recall) / (Precision + Recall)

Remarque :L'Document AI ne fournit pas de métrique pour l'exactitude. La métrique de précision, souvent définie comme la proportion d'instances correctement prédites, est moins pertinente, car : 1) tous les libellés n'apparaissent pas dans l'ensemble de test (par exemple, les champs facultatifs) et 2) il peut y avoir plusieurs valeurs pour un même libellé (par exemple, les lignes d'une facture). En revanche, le score F1 peut être considéré comme à peu près équivalent à la justesse, mais il s'adapte plus précisément à ces scénarios.

Métriques d'évaluation pour les étiquettes individuelles

• Vrais positifs:entités prédites qui correspondent à une annotation dans le document de test. Pour en savoir plus, consultez la section Comportement de mise en correspondance.

• Faux positifs:entités prédites qui ne correspondent à aucune annotation du document de test.

• Faux négatifs:annotations du document de test qui ne correspondent à aucune des entités prédites.

  • Faux négatifs (sous le seuil) : annotations du document de test qui auraient correspondu à une entité prédite, mais la niveau de confiance de l'entité prédite est inférieure au seuil de confiance spécifié.

Remarque :Les faux positifs et les faux négatifs ne s'excluent pas mutuellement. Par exemple, si une entité prédite a une annotation correspondante, mais incorrecte, dans l'ensemble de test, il y a un faux positif pour l'entité prédite et un faux négatif pour l'annotation. Une entité prédite sans annotation n'est qu'un faux positif. Une annotation sans prédiction associée n'est qu'un faux négatif.

Conseil :Si la qualité de l'extraction checkbox n'est pas assez élevée, envisagez d'exécuter les documents via l'analyseur de formulaires. L'analyseur de formulaires extrait des informations qui pourraient potentiellement améliorer la qualité de l'extraction des cases à cocher. Plus précisément, l'analyseur de formulaires peut dessiner automatiquement des cadres de délimitation autour des cases à cocher, tandis que les cadres de délimitation dessinés manuellement peuvent être moins cohérents. Pour ce faire, traitez vos documents à l'aide de l'analyseur de formulaires, puis import les documents traités et annotez-les à nouveau.

Seuil de confiance

La logique d'évaluation ignore toutes les prédictions dont le niveau de confiance est inférieur au seuil de confiance spécifié, même si la prédiction est correcte. L'Document AI fournit une liste de faux négatifs (en dessous du seuil), qui sont les annotations qui correspondraient si le seuil de confiance était défini sur une valeur inférieure.

Document AI calcule automatiquement le seuil optimal, qui maximise le score F1, et définit par défaut le seuil de confiance sur cette valeur optimale.

Remarque :Si plusieurs valeurs de seuil optimales (avec le même score F1 maximal) sont disponibles, la valeur la plus basse est choisie.

Vous pouvez choisir votre propre seuil de confiance en déplaçant la barre de curseur. En règle générale, un seuil de confiance plus élevé entraîne les conséquences suivantes:

• une précision plus élevée, car les prédictions sont plus susceptibles d'être correctes.
• un rappel plus faible, car il y a moins de prédictions.

Entités tabulaires

Les métriques d'une étiquette parente ne sont pas calculées en calculant directement la moyenne des métriques enfants, mais en appliquant le seuil de confiance de l'étiquette parente à toutes ses étiquettes enfants et en agrégant les résultats.

Le seuil optimal pour le parent est la valeur du seuil de confiance qui, appliquée à tous les enfants, génère le score F1 maximal pour le parent.

Comportement de mise en correspondance

Une entité prédite correspond à une annotation si:

• le type de l'entité prédite (entity.type) correspond au nom de l'étiquette de l'annotation ;
• la valeur de l'entité prédite (entity.mention_text ou entity.normalized_value.text) correspond à la valeur textuelle de l'annotation, sous réserve d'une mise en correspondance floue si elle est activée.

Notez que seuls le type et la valeur du texte sont utilisés pour la mise en correspondance. D'autres informations, telles que les ancrages de texte et les rectangles de délimitation (à l'exception des entités tabulaires décrites ci-dessous) ne sont pas utilisées.

Remarque :Certains traitements d'identité extraient une entité Portrait, qui ne contient aucun texte, mais uniquement un cadre de délimitation indiquant l'emplacement du portrait d'une personne dans un document d'identité. Étant donné qu'il n'y a pas de texte, les libellés et les entités du portrait ne sont pas évalués.

Étiquettes à occurrence unique et à occurrences multiples

Les libellés à occurrence unique ont une valeur par document (par exemple, l'ID de facture), même si cette valeur est annotée plusieurs fois dans le même document (par exemple, l'ID de facture apparaît sur chaque page du même document). Même si le texte des différentes annotations est différent, elles sont considérées comme égales. En d'autres termes, si une entité prédite correspond à l'une des annotations, elle est comptabilisée comme une correspondance. Les annotations supplémentaires sont considérées comme des doublons de mentions et ne sont pas comptabilisées dans les nombres de vrais positifs, de faux positifs ou de faux négatifs.

Les libellés à plusieurs occurrences peuvent avoir plusieurs valeurs différentes. Ainsi, chaque entité et annotation prédites sont prises en compte et mises en correspondance séparément. Si un document contient N annotations pour un libellé à plusieurs occurrences, il peut y avoir N correspondances avec les entités prédites. Chaque entité et annotation prédites sont comptabilisées indépendamment en tant que vrai positif, faux positif ou faux négatif.

Correspondance partielle

Le bouton Correspondance floue vous permet de renforcer ou d'assouplir certaines des règles de correspondance pour réduire ou augmenter le nombre de correspondances.

Par exemple, sans mise en correspondance floue, la chaîne ABC ne correspond pas à abc en raison de la casse. Mais avec la correspondance partielle, ils correspondent.

Lorsque la correspondance partielle est activée, les règles sont modifiées comme suit:

• Normalisation des espaces blancs:supprime les espaces blancs de début et de fin, et condense les espaces blancs intermédiaires consécutifs (y compris les retours à la ligne) en espaces uniques.

• Suppression des caractères de ponctuation de début et de fin : supprime les caractères de ponctuation de début et de fin suivants : !,.:;-"?|.

• Correspondance insensible à la casse:convertit tous les caractères en minuscules.

• Normalisation des devises:pour les libellés avec le type de données money, supprimez les symboles de devise au début et à la fin.

Remarque :Vous ne pouvez pas utiliser la correspondance proche pour les valeurs numériques. Par exemple, 1 et 1.00 ne correspondent pas, même lorsque la correspondance partielle est activée.

Entités tabulaires

Les entités et annotations parentes n'ont pas de valeurs textuelles et sont mises en correspondance en fonction des rectangles de délimitation combinés de leurs enfants. S'il n'y a qu'un seul parent prédit et un seul parent annoté, ils sont automatiquement mis en correspondance, quelle que soit la zone de délimitation.

Une fois les parents mis en correspondance, leurs enfants le sont comme s'ils étaient des entités non tabulaires. Si les parents ne sont pas mis en correspondance, Document AI ne tentera pas de mettre en correspondance leurs enfants. Cela signifie que les entités enfants peuvent être considérées comme incorrectes, même avec le même contenu textuel, si leurs entités parents ne sont pas mises en correspondance.

Les entités parent / enfant sont une fonctionnalité en version Preview et ne sont compatibles qu'avec les tables à une seule couche d'imbrication.

Exporter les métriques d'évaluation

1. Dans la console Google Cloud, accédez à la page Processeurs, puis sélectionnez votre processeur.

   Accéder à la page "Outils de traitement"

2. Dans l'onglet Évaluer et tester, cliquez sur Télécharger les métriques pour télécharger les métriques d'évaluation au format JSON.

Remarque :Les métriques exportées sont basées sur la valeur du curseur Seuil de confiance au moment de l'exportation.