Leistung auswerten

Document AI generiert Bewertungsmesswerte wie Precision und Recall, damit Sie die Vorhersageleistung Ihrer Prozessoren ermitteln können.

Diese Bewertungsmesswerte werden durch einen Vergleich der vom Prozessor zurückgegebenen Entitäten (Vorhersagen) mit den Annotationen in den Testdokumenten generiert. Wenn Ihr Prozessor kein Testset hat, müssen Sie zuerst ein Dataset erstellen und die Testdokumente labeln.

Bewertung ausführen

Eine Bewertung wird automatisch ausgeführt, wenn Sie eine Prozessorversion trainieren oder aktualisieren.

Sie können eine Bewertung auch manuell ausführen. Dies ist erforderlich, um aktualisierte Messwerte zu generieren, nachdem Sie das Testset geändert haben, oder wenn Sie eine vortrainierte Prozessorversion bewerten.

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

Ergebnisse einer Bewertung abrufen

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

Alle Bewertungen für eine Prozessorversion auflisten

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

Bewertungsmesswerte für alle Labels

Messwerte für Alle Labels werden anhand der Anzahl der echt positiven, falsch positiven und falsch negativen Ergebnisse im Dataset für alle Labels berechnet. Sie werden also nach der Häufigkeit gewichtet, mit der die einzelnen Labels im Dataset vorkommen. Definitionen dieser Begriffe finden Sie unter Bewertungsmesswerte für einzelne Labels.

• Präzision:Der Anteil der Vorhersagen, die mit den Anmerkungen im Testset übereinstimmen. Definiert als True Positives / (True Positives + False Positives)

• Trefferquote:Der Anteil der Anmerkungen im Testsatz, die korrekt vorhergesagt wurden. Definiert als True Positives / (True Positives + False Negatives)

• F1-Wert:Der harmonische Mittelwert von Precision und Recall. Er kombiniert Precision und Recall in einem einzelnen Messwert, wobei beide gleich gewichtet werden. Definiert als 2 * (Precision * Recall) / (Precision + Recall)

Bewertungsmesswerte für einzelne Labels

• Richtig positive Ergebnisse:Die vorhergesagten Entitäten, die mit einer Annotation im Testdokument übereinstimmen. Weitere Informationen finden Sie unter Abgleichsverhalten.

• Falsch positive Ergebnisse:Die vorhergesagten Entitäten, die mit keiner Annotation im Testdokument übereinstimmen.

• Falsch negative Ergebnisse:Die Annotationen im Testdokument, die mit keiner der vorhergesagten Entitäten übereinstimmen.

  • Falsch negative Ergebnisse (unterhalb Grenzwert): Die Anmerkungen im Testdokument, die mit einer vorhergesagten Einheit übereingestimmt hätten, aber der Konfidenzwert der vorhergesagten Einheit liegt unter dem angegebenen Konfidenzschwellenwert.

Konfidenzwert

Bei der Auswertungslogik werden alle Vorhersagen mit einem Konfidenzwert unter dem angegebenen Konfidenzschwellenwert ignoriert, auch wenn die Vorhersage richtig ist. Document AI bietet eine Liste mit Falsch negativen Ergebnissen (unter dem Grenzwert). Das sind die Anmerkungen, die eine Übereinstimmung hätten, wenn der Konfidenzgrenzwert niedriger wäre.

Document AI berechnet automatisch den optimalen Grenzwert, der den F1-Wert maximiert, und legt den Konfidenzgrenzwert standardmäßig auf diesen optimalen Wert fest.

Sie können den Konfidenzwert selbst festlegen, indem Sie den Schieberegler bewegen. Im Allgemeinen führt ein höherer Konfidenzschwellenwert zu Folgendem:

• höhere Precision, da die Vorhersagen mit höherer Wahrscheinlichkeit richtig sind.
• niedrigerer Recall, da es weniger Vorhersagen gibt.

Tabellarische Entitäten

Die Messwerte für ein übergeordnetes Label werden nicht durch direktes Mitteln der untergeordneten Messwerte berechnet, sondern durch Anwenden des Vertrauensschwellenwerts des übergeordneten Labels auf alle untergeordneten Labels und Aggregieren der Ergebnisse.

Der optimale Grenzwert für das übergeordnete Label ist der Konfidenzgrenzwert, der bei Anwendung auf alle untergeordneten Labels den maximalen F1-Wert für das übergeordnete Label ergibt.

Abgleichsverhalten

Eine vorhergesagte Entität stimmt mit einer Annotation überein, wenn:

• Der Typ der vorhergesagten Entität (entity.type) stimmt mit dem Labelnamen der Annotation überein.
• Der Wert der vorhergesagten Entität (entity.mention_text oder entity.normalized_value.text) stimmt mit dem Textwert der Anmerkung überein, wobei Fuzzy Matching angewendet wird, falls es aktiviert ist.

Für den Abgleich werden nur Typ und Textwert verwendet. Andere Informationen wie Textanker und Begrenzungsrahmen (mit Ausnahme der unten beschriebenen tabellarischen Einheiten) werden nicht verwendet.

Labels mit einem oder mehreren Vorkommen

Labels mit einmaligem Vorkommen haben einen Wert pro Dokument (z. B. Rechnungs-ID), auch wenn dieser Wert mehrmals im selben Dokument annotiert wird (z. B. wenn die Rechnungs-ID auf jeder Seite desselben Dokuments erscheint). Auch wenn die mehreren Anmerkungen unterschiedlichen Text haben, werden sie als gleich betrachtet. Mit anderen Worten: Wenn eine vorhergesagte Entität mit einer der Anmerkungen übereinstimmt, wird sie als Übereinstimmung gezählt. Die zusätzlichen Anmerkungen gelten als doppelte Erwähnungen und werden nicht auf die Anzahl der richtig positiven, falsch positiven oder falsch negativen Ergebnisse angerechnet.

Labels mit mehreren Vorkommen können mehrere unterschiedliche Werte haben. Daher werden jede vorhergesagte Entität und Annotation separat berücksichtigt und abgeglichen. Wenn ein Dokument N Anmerkungen für ein Label mit mehreren Vorkommen enthält, kann es N Übereinstimmungen mit den vorhergesagten Elementen geben. Jede vorhergesagte Entität und Anmerkung wird unabhängig als richtig positiv, falsch positiv oder falsch negativ gezählt.

Ungenaue Übereinstimmung

Mit dem Schalter Ungefähre Übereinstimmung können Sie einige der Abgleichsregeln verschärfen oder lockern, um die Anzahl der Übereinstimmungen zu verringern oder zu erhöhen.

Ohne unscharfen Abgleich stimmt der String ABC beispielsweise aufgrund der Groß- und Kleinschreibung nicht mit abc überein. Mit ungenauer Übereinstimmung stimmen sie jedoch überein.

Wenn die ungenaue Übereinstimmung aktiviert ist, gelten die folgenden Regeländerungen:

• Normalisierung von Leerräumen:Voran- und nachgestellte Leerräume werden entfernt und aufeinanderfolgende Leerräume (einschließlich Zeilenumbrüche) werden in einzelne Leerzeichen umgewandelt.

• Entfernen von Satzzeichen am Anfang und Ende: Die folgenden Satzzeichen am Anfang und Ende werden entfernt: !,.:;-"?|.

• Abgleich ohne Berücksichtigung der Groß-/Kleinschreibung:Alle Zeichen werden in Kleinbuchstaben umgewandelt.

• Geldnormalisierung:Entfernen Sie für Labels mit dem Datentyp money die führenden und nachgestellten Währungssymbole.

Tabellarische Entitäten

Übergeordnete Einheiten und Anmerkungen haben keine Textwerte und werden anhand der kombinierten Begrenzungsrahmen ihrer untergeordneten Elemente abgeglichen. Wenn es nur ein vorhergesagtes und ein annotiertes übergeordnetes Element gibt, werden sie automatisch zugeordnet, unabhängig von den Begrenzungsrahmen.

Sobald Eltern zugeordnet sind, werden ihre Kinder so zugeordnet, als wären sie nicht tabellarische Einheiten. Wenn Eltern nicht zugeordnet werden, versucht Document AI nicht, ihre Kinder zuzuordnen. Das bedeutet, dass untergeordnete Entitäten auch bei gleichem Textinhalt als falsch angesehen werden können, wenn ihre übergeordneten Entitäten nicht übereinstimmen.

Über- und untergeordnete Einheiten sind eine Vorschaufunktion und werden nur für Tabellen mit einer Verschachtelungsebene unterstützt.

Bewertungsmesswerte exportieren

1. Rufen Sie in der Google Cloud Console die Seite Prozessoren auf und wählen Sie Ihren Prozessor aus.

   Zur Seite „Prozessoren“

2. Klicken Sie auf dem Tab Bewerten und testen auf Messwerte herunterladen, um die Bewertungsstatistiken als JSON-Datei herunterzuladen.