Valutare il rendimento

Document AI genera metriche di valutazione, come precisione e identificazione, per aiutarti a determinare le prestazioni predittive dei tuoi processori.

Queste metriche di valutazione vengono generate confrontando le entità restituite dal processore (le previsioni) con le annotazioni nei documenti di test. Se il tuo processore non ha un set di test, devi prima creare un set di dati ed etichettare i documenti di test.

Eseguire una valutazione

Una valutazione viene eseguita automaticamente ogni volta che addestri o esegui l'upgrade di una versione del processore.

Puoi anche eseguire manualmente una valutazione. Questo passaggio è necessario per generare metriche aggiornate dopo aver modificato il set di test o se stai valutando una versione del processore preaddestrata.

Nota: Document AI non può e non calcola le metriche di valutazione per un'etichetta se la versione del processore non è in grado di estrarla (ad esempio, l'etichetta è stata disattivata al momento dell'addestramento) o se il set di test non include annotazioni per l'etichetta. Queste etichette non sono incluse nelle metriche aggregate.

UI web

1. Nella console Google Cloud, vai alla pagina Processori e scegli il tuo processore.

   Vai alla pagina Processori

2. Nella scheda Valuta e testa, seleziona la versione del processore da valutare e poi fai clic su Esegui nuova valutazione.

Al termine, la pagina contiene le metriche di valutazione per tutte le etichette e per ogni singola etichetta.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.

Per autenticarti a Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Ottenere i risultati di una valutazione

UI web

1. Nella console Google Cloud, vai alla pagina Processori e scegli il tuo processore.

   Vai alla pagina Processori

2. Nella scheda Valuta e verifica, seleziona la versione del processore per visualizzare la valutazione.

Al termine, la pagina contiene le metriche di valutazione per tutte le etichette e per ogni singola etichetta.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.

Per autenticarti a Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Elenco di tutte le valutazioni per una versione del processore

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.

Per autenticarti a Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Metriche di valutazione per tutte le etichette

Le metriche per Tutte le etichette vengono calcolate in base al numero di veri positivi, falsi positivi e falsi negativi nel set di dati per tutte le etichette e, pertanto, vengono ponderate in base al numero di volte in cui ogni etichetta viene visualizzata nel set di dati. Per le definizioni di questi termini, consulta Metriche di valutazione per le singole etichette.

• Precisione:la proporzione di previsioni che corrispondono alle annotazioni nel set di test. Definito come True Positives / (True Positives + False Positives)

• Richiamo:la proporzione di annotazioni nel set di test che sono previste correttamente. Definito come True Positives / (True Positives + False Negatives)

• Punteggio F1:la media armonica di precisione e richiamo, che combina precisione e richiamo in un'unica metrica, assegnando a entrambe lo stesso peso. Definito come 2 * (Precision * Recall) / (Precision + Recall)

Nota: Document AI non fornisce una metrica per l'accuratezza. La metrica di accuratezza, spesso definita come la proporzione di istanze previste correttamente, è meno significativa perché 1) non tutte le etichette vengono visualizzate nel set di test (ad es. campi facoltativi) e 2) possono essere presenti più valori per una singola etichetta (ad es. elementi pubblicitari in una fattura). Il punteggio F1, invece, può essere considerato approssimativamente equivalente alla precisione, ma tiene conto in modo più significativo di questi scenari.

Metriche di valutazione per le singole etichette

• Veri positivi:le entità previste che corrispondono a un'annotazione nel documento di test. Per ulteriori informazioni, consulta comportamento di corrispondenza.

• Falsi positivi:le entità previste che non corrispondono a nessuna annotazione nel documento di test.

• Falsi negativi:le annotazioni nel documento di test che non corrispondono a nessuna delle entità previste.

  • Falsi negativi (al di sotto della soglia): le annotazioni nel documento di test che avrebbero corrisposto a un'entità prevista, ma il valore di affidabilità dell'entità prevista è inferiore alla soglia di confidenza specificata.

Nota: i falsi positivi e i falsi negativi non sono mutuamente esclusivi. Ad esempio, se un'entità prevista ha un'annotazione corrispondente, anche se errata, nel set di test, esiste un falso positivo per l'entità prevista e un falso negativo per l'annotazione. Un'entità prevista senza un'annotazione è solo un falso positivo. Un'annotazione senza una previsione associata è solo un falso negativo.

Suggerimento: se la qualità dell'estrazione di checkbox non è sufficientemente elevata, valuta la possibilità di eseguire i documenti tramite lo strumento di analisi dei moduli. Il parser di moduli estrae informazioni che potrebbero potenzialmente migliorare la qualità dell'estrazione delle caselle di controllo. Nello specifico, lo strumento di analisi dei moduli può disegnare automaticamente i riquadri delimitanti attorno alle caselle di controllo, mentre quelli disegnati manualmente potrebbero essere meno coerenti. Per farlo, elabora i documenti utilizzando l'analizzatore sintattico di moduli, poi import i documenti elaborati e annotali di nuovo.

Soglia di confidenza

La logica di valutazione ignora le previsioni con un livello di confidenza inferiore alla soglia di confidenza specificata, anche se la previsione è corretta. Document AI fornisce un elenco di falsi negativi (sotto soglia), ovvero le annotazioni che avrebbero una corrispondenza se la soglia di affidabilità fosse impostata su un valore inferiore.

Document AI calcola automaticamente la soglia ottimale, che massimizza il punteggio F1 e, per impostazione predefinita, imposta la soglia di confidenza su questo valore ottimale.

Nota: se sono presenti più valori di soglia ottimali (con lo stesso punteggio F1 massimo), viene scelto il valore più basso.

Puoi scegliere la soglia di confidenza che preferisci spostando la barra del cursore. In generale, una soglia di confidenza più elevata comporta:

• una maggiore precisione, perché le previsioni hanno maggiori probabilità di essere corrette.
• un richiamo inferiore, perché ci sono meno previsioni.

Entità tabulari

Le metriche per un'etichetta principale non vengono calcolate facendo direttamente la media delle metriche figlio, ma applicando la soglia di confidenza dell'etichetta principale a tutte le sue etichette figlio e aggregando i risultati.

La soglia ottimale per l'elemento principale è il valore della soglia di confidenza che, se applicato a tutti gli elementi secondari, genera il punteggio F1 massimo per l'elemento principale.

Comportamento di corrispondenza

Un'entità prevista corrisponde a un'annotazione se:

• il tipo di entità prevista (entity.type) corrisponde al nome dell'etichetta dell'annotazione
• il valore dell'entità prevista (entity.mention_text o entity.normalized_value.text) corrisponde al valore del testo dell'annotazione, in base alla corrispondenza approssimativa se è attivata.

Tieni presente che per la corrispondenza vengono utilizzati solo il tipo e il valore del testo. Altre informazioni, come ancore di testo e caselle delimitanti (ad eccezione delle entità tabulari descritte di seguito), non vengono utilizzate.

Nota: alcuni processori di identità estraggono un'entità Ritratto, che non contiene testo, ma solo un riquadro di delimitazione che indica dove si trova il ritratto di una persona in un documento di identità. Poiché manca il testo, le etichette e le entità dei ritratti non vengono valutate.

Etichette con una singola occorrenza e con più occorrenze

Le etichette con una sola occorrenza hanno un valore per documento (ad es. ID fattura), anche se questo valore viene annotato più volte nello stesso documento (ad es. l'ID fattura viene visualizzato in ogni pagina dello stesso documento). Anche se le più annotazioni hanno un testo diverso, sono considerate uguali. In altre parole, se un'entità prevista corrisponde a una delle annotazioni, viene conteggiata come corrispondenza. Le annotazioni aggiuntive sono considerate menzioni duplicate e non contribuiscono ai conteggi di veri positivi, falsi positivi o falsi negativi.

Le etichette con più occorrenze possono avere più valori diversi. Pertanto, ogni entità e annotazione prevista viene considerata e associata separatamente. Se un documento contiene N annotazioni per un'etichetta con più occorrenze, possono esserci N corrispondenze con le entità previste. Ogni entità e annotazione prevista viene conteggiata in modo indipendente come vero positivo, falso positivo o falso negativo.

Corrispondenza parziale

Il pulsante di attivazione/disattivazione Corrispondenza approssimativa ti consente di applicare o meno alcune regole di corrispondenza per diminuire o aumentare il numero di corrispondenze.

Ad esempio, senza la corrispondenza approssimativa, la stringa ABC non corrisponde a abc a causa della maiuscola. Ma con la corrispondenza approssimativa, corrispondono.

Quando la corrispondenza approssimativa è attiva, le modifiche alle regole sono le seguenti:

• Normalizzazione degli spazi vuoti: rimuove gli spazi vuoti iniziali e finali e comprime gli spazi vuoti intermedi consecutivi (incluse le nuove righe) in singoli spazi.

• Rimozione di punteggiatura iniziale/finale:vengono rimossi i seguenti caratteri di punteggiatura iniziale/finale !,.:;-"?|.

• Corrispondenza senza distinzione tra maiuscole e minuscole:vengono convertiti tutti i caratteri in minuscolo.

• Normalizzazione monetaria:per le etichette con il tipo di dati money, rimuovi i simboli di valuta iniziali e finali.

Nota: non puoi utilizzare la corrispondenza approssimativa sui valori numerici. Ad esempio, 1 e 1.00 non corrispondono, anche se la corrispondenza approssimativa è attivata.

Entità tabulari

Le entità e le annotazioni principali non hanno valori di testo e vengono associate in base ai riquadri delimitatori combinati dei relativi elementi secondari. Se è presente un solo elemento principale previsto e uno annotato, vengono abbinati automaticamente, indipendentemente dalle caselle delimitanti.

Una volta trovati i corrispondenti per i genitori, i figli vengono associati come se fossero entità non tabulari. Se i genitori non corrispondono, Document AI non tenterà di abbinare i figli. Ciò significa che le entità figlie possono essere considerate scorrette, anche con gli stessi contenuti di testo, se le relative entità principali non corrispondono.

Le entità principali / secondarie sono una funzionalità di anteprima e sono supportate solo per le tabelle con un livello di nidificazione.

Esportare le metriche di valutazione

1. Nella console Google Cloud, vai alla pagina Processori e scegli il tuo processore.

   Vai alla pagina Processori

2. Nella scheda Valuta e testa, fai clic su Scarica metriche per scaricare le metriche di valutazione come file JSON.

Nota: le metriche esportate si basano sul valore del cursore Soglia di confidenza al momento dell'esportazione.