Gestione delle versioni del processore

Le nuove versioni vengono rilasciate per vari motivi, ad esempio per migliorare l'accuratezza, aumentare la disponibilità e supportare nuovi elementi del documento, come i segni di selezione.

Poiché Document AI è basato sull'AI generativa, le versioni future utilizzano nuovi foundation model, in modo che tu possa usufruire dei miglioramenti dell'AI generativa.

Man mano che miglioriamo i foundation model, i foundation model precedenti vengono ritirati. Allo stesso modo, le versioni del processore vengono ritirate sei mesi dopo il rilascio di nuove versioni.

Un processore può avere una delle seguenti versioni:

• Versione stabile
• Release candidate (RC)
• Versione personalizzata e la relativa versione di base

Questa pagina descrive come viene eseguito il controllo delle versioni dei processori e come visualizzare e selezionare una determinata versione.

Panoramica delle versioni del processore

Esistono due categorie di versioni del processore:

• Le versioni Google sono stabili (per i casi d'uso di produzione) o candidate al rilascio (sperimentali con le funzionalità più recenti).
• Le versioni utente vengono create da te per personalizzare le previsioni per i tuoi documenti e hanno ID versione alfanumerici.

Versioni di Google

Ogni versione di Google è identificata da un ID versione, ad esempio pretrained-TYPE-vX.X-YYYY-MM-DD. Ogni versione del processore offerta da Google è denominata Google Stable o Google Release Candidate (RC).

Versioni stabili di Google

Le versioni stabili sono di qualità elevata e pronte all'uso.

• Google dà la priorità alla stabilità del comportamento del processore, ma include comunque correzioni critiche.
• Le versioni stabili precedenti di Google vengono ritirate sei mesi dopo il rilascio della versione stabile più recente, come illustrato nella figura seguente.

Versioni candidate alla release (RC) di Google

I candidati per le release sono sperimentali e vengono aggiornati regolarmente con le ultime funzionalità. Non sono versioni di qualità elevata e la loro stabilità può variare.

Versioni personalizzate

Le versioni personalizzate sono le versioni del processore che puoi creare in base ai tuoi documenti per personalizzare le previsioni. Le versioni personalizzate hanno un'icona Type, che mostra il tipo di modello utilizzato per le previsioni. Se crei una versione utilizzando un foundation model (creando una versione o eseguendo il fine tuning), il tipo è AI generativa. Se crei una versione del processore addestrando un modello personalizzato più piccolo (basato su modello o su modello), il tipo è Personalizzato. Se crei versioni del processore, decidi il nome e l'ID.

Versioni di base

Se crei una versione del processore, la "versione di base" mostra la versione di Google che alimenta la tua versione utente personalizzata. La versione di base determina il ciclo di vita della versione utente. Devi prendere decisioni su come gestire il ciclo di vita della tua versione utente personalizzata.

Versioni stabili del processore disponibili

Puoi esaminare le versioni stabili del processore disponibili per i diversi tipi di processore nelle tabelle seguenti.

Ciclo di vita della versione del processore

Non appena è disponibile una nuova versione di Google, devi creare e valutare nuove versioni utente con la nuova versione di base. Quindi, esegui il deployment della nuova versione e annulla il deployment (o elimina) le versioni utente precedenti che utilizzano la versione stabile precedente come base. Le versioni stabili vengono ritirate dopo il rilascio di una nuova. Google ti invia un preavviso di almeno sei mesi quando si verifica questa situazione.

Cosa succede quando una versione di base viene ritirata?

Le versioni utente che dipendono da versioni di base precedenti smettono di restituire previsioni quando la versione di base viene ritirata.

Come vengono selezionate le versioni del processore per le tue richieste?

Quando chiami un endpoint del processore senza specificare la versione del processore, viene utilizzata la versione predefinita del processore. Quando la versione del processore predefinita cambia, potresti dover aggiornare il codice.

Esempio di ritiro di una versione personalizzata

Considera lo scenario seguente che descrive la sequenza di eventi in un ritiro della versione personalizzata:

1. In qualità di sviluppatore, utilizzi un estrattore personalizzato per ottenere dati dai documenti. Data la complessità e il volume dei documenti che elabori, ottimizzi il foundation model per creare una versione denominata fine-tune-A. Imposta la versione fine-tune-A come versione predefinita del processore e utilizzala per elaborare i documenti. La versione di base che alimenta il modello fine-tune-A è la versione stabile pretrained-foundation-model-v1.0-2023-08-22 (v1.0).

2. Google ha pubblicato una nuova versione stabile denominata pretrained-foundation-model-v1.2-2024-05-10 (v1.2) e ha annunciato che la versione stabile v1.0 verrà ritirata il 9 aprile 2025.

3. Poiché hai mantenuto i documenti di addestramento e test nel set di dati del processore, ottimizza un'altra versione in base alla versione stabile più recente di Google, v1.2, e chiamala fine-tune-B. Dopo averne valutato il rendimento, imposta la versione fine-tune-B come nuova versione predefinita per il processore e dismette la versione fine-tune-A. La nuova versione ora utilizza l'ultima versione stabile di Google supportata.

Se invece non avessi creato e valutato la versione personalizzata di fine-tune-B, Google avrebbe aggiornato la versione predefinita del processore a v1.2 il 9 aprile 2025. Poiché stai chiamando l'endpoint del processore e non specificando una versione del processore, la nuova versione v1.2 viene utilizzata come nuova versione predefinita per elaborare le tue richieste.

Risorse per il ritiro e la migrazione

Per i parser e i processori ritirati, puoi consultare Ritiri di Document AI.

Consulta le seguenti risorse per le migrazioni:

• Per la creazione e l'addestramento di un nuovo analizzatore di spese, puoi fare riferimento a Addestramento di un processore preaddestrato.

• Per la creazione e l'ottimizzazione di un nuovo processore Custom Extractor, puoi fare riferimento a Custom Extractor con l'IA generativa.

Seleziona una versione del processore

Esistono tre modi per specificare la versione del processore da utilizzare per l'elaborazione batch e online:

• Se non specifichi una versione, viene utilizzata quella predefinita del processore.

  • Esempio: projects/my-proj/locations/us/processors/my-processor:process

• Se specifichi una versione, viene utilizzata quella specifica. Se la versione specifica non esiste, la richiesta non va a buon fine e viene visualizzato un errore.

  • Esempio: projects/my-proj/locations/us/processors/my-processor/processorVersions/pretrained-invoice-v1.2-2022-02-18:process

• Se specifichi un canale, viene utilizzata l'ultima versione disponibile in quel canale. (Opzioni: stable, rc)

  • Esempio: projects/my-proj/locations/us/processors/my-processor/processorVersions/stable:process

Visualizza la versione disponibile

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions" | Select-Object -Expand Content

{
  "processorVersions": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/pretrained-ocr-v1.1-2022-09-12",
      "displayName": "Google Release Candidate",
      "state": "DEPLOYED",
      "createTime": "2022-09-13T23:39:12.156648Z",
      "googleManaged": true
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/pretrained-ocr-v1.0-2020-09-23",
      "displayName": "Google Stable",
      "state": "DEPLOYED",
      "createTime": "2022-09-12T23:35:09.829557Z",
      "googleManaged": true,
      "deprecationInfo": {
        "deprecationTime": "1970-01-01T00:00:00Z"
      }
    }
  ]
}

using Google.Api.Gax;
using Google.Cloud.DocumentAI.V1;
using System;

public sealed partial class GeneratedDocumentProcessorServiceClientSnippets
{
    /// <summary>Snippet for ListProcessorVersions</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void ListProcessorVersionsRequestObject()
    {
        // Create client
        DocumentProcessorServiceClient documentProcessorServiceClient = DocumentProcessorServiceClient.Create();
        // Initialize request argument(s)
        ListProcessorVersionsRequest request = new ListProcessorVersionsRequest
        {
            ParentAsProcessorName = ProcessorName.FromProjectLocationProcessor("[PROJECT]", "[LOCATION]", "[PROCESSOR]"),
        };
        // Make the request
        PagedEnumerable<ListProcessorVersionsResponse, ProcessorVersion> response = documentProcessorServiceClient.ListProcessorVersions(request);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (ProcessorVersion item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (ListProcessorVersionsResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (ProcessorVersion item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<ProcessorVersion> singlePage = response.ReadPage(pageSize);
        // Do something with the page of items
        Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
        foreach (ProcessorVersion item in singlePage)
        {
            // Do something with each item
            Console.WriteLine(item);
        }
        // Store the pageToken, for when the next page is required.
        string nextPageToken = singlePage.NextPageToken;
    }
}

//go:build examples

package main

import (
	"context"

	documentai "cloud.google.com/go/documentai/apiv1"
	documentaipb "cloud.google.com/go/documentai/apiv1/documentaipb"
	"google.golang.org/api/iterator"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := documentai.NewDocumentProcessorClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &documentaipb.ListProcessorVersionsRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/documentai/apiv1/documentaipb#ListProcessorVersionsRequest.
	}
	it := c.ListProcessorVersions(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			// TODO: Handle error.
		}
		// TODO: Use resp.
		_ = resp

		// If you need to access the underlying RPC response,
		// you can do so by casting the `Response` as below.
		// Otherwise, remove this line. Only populated after
		// first call to Next(). Not safe for concurrent access.
		_ = it.Response.(*documentaipb.ListProcessorVersionsResponse)
	}
}

import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.ListProcessorVersionsRequest;
import com.google.cloud.documentai.v1.ProcessorName;
import com.google.cloud.documentai.v1.ProcessorVersion;

public class SyncListProcessorVersions {

  public static void main(String[] args) throws Exception {
    syncListProcessorVersions();
  }

  public static void syncListProcessorVersions() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentProcessorServiceClient documentProcessorServiceClient =
        DocumentProcessorServiceClient.create()) {
      ListProcessorVersionsRequest request =
          ListProcessorVersionsRequest.newBuilder()
              .setParent(ProcessorName.of("[PROJECT]", "[LOCATION]", "[PROCESSOR]").toString())
              .setPageSize(883849137)
              .setPageToken("pageToken873572522")
              .build();
      for (ProcessorVersion element :
          documentProcessorServiceClient.listProcessorVersions(request).iterateAll()) {
        // doThingsWith(element);
      }
    }
  }
}

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


def list_processor_versions_sample(
    project_id: str, location: str, processor_id: str
) -> None:
    # You must set the `api_endpoint` if you use a location other than "us".
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor
    # e.g.: projects/project_id/locations/location/processors/processor_id
    parent = client.processor_path(project_id, location, processor_id)

    # Make ListProcessorVersions request
    processor_versions = client.list_processor_versions(parent=parent)

    # Print the processor version information
    for processor_version in processor_versions:
        processor_version_id = client.parse_processor_version_path(
            processor_version.name
        )["processor_version"]

        print(f"Processor Version: {processor_version_id}")
        print(f"Display Name: {processor_version.display_name}")
        print(f"DEPLOYED: {processor_version.state}")
        print("")