Gerenciar versões do processador

Novas versões são lançadas por vários motivos, por exemplo, para melhorar a precisão, aumentar a disponibilidade e oferecer suporte a novos elementos de documentos, como marcas de seleção.

Como a Document AI é alimentada por IA generativa, as versões futuras vão usar novos modelos de fundação para que você possa aproveitar as melhorias da IA generativa.

À medida que melhoramos os modelos de fundação, os modelos anteriores são descontinuados. Da mesma forma, as versões do processador são descontinuadas seis meses após o lançamento de novas versões.

Um processador pode ter uma das seguintes versões:

• Versão estável
• Versão candidata a lançamento (RC)
• Versão personalizada e a versão base associada

Nesta página, descrevemos como os processadores são controlados por versão e como visualizar e selecionar uma versão específica.

Visão geral das versões do processador

Há duas categorias de versões de processador:

• As versões do Google são estáveis (para casos de uso de produção) ou candidatas a lançamento (experimentais com a funcionalidade mais recente).
• As versões do usuário são criadas por você para personalizar as previsões dos seus documentos e têm IDs de versão alfanuméricos.

Versões do Google

Cada versão do Google é identificada por um ID da versão, por exemplo, pretrained-TYPE-vX.X-YYYY-MM-DD. Cada versão de processador oferecida pelo Google é chamada de Google Stable ou Google Release Candidate (RC).

Versões estáveis do Google

As versões estáveis têm qualidade de produção e estão prontas para uso.

• O Google prioriza a estabilidade do comportamento do processador, mas sem deixar de incluir correções críticas.
• As versões estáveis anteriores do Google são descontinuadas seis meses após o lançamento da versão estável mais recente, conforme mostrado na figura a seguir.

Versões candidatas a lançamento (RC) do Google

As versões candidatas a lançamento são experimentais e atualizadas regularmente com os recursos mais recentes. Elas não são versões de qualidade de produção, e a estabilidade delas pode variar.

Versões personalizadas

As versões personalizadas são as versões do processador que você pode criar com base nos seus documentos para personalizar as previsões. As versões personalizadas têm um Type, que mostra o tipo de modelo usado para as previsões. Se você criar uma versão usando um modelo de fundação (criando uma versão ou ajustando), o tipo será IA generativa. Se você criar uma versão do processador treinando um modelo personalizado menor (com base em modelo ou modelo), o tipo será Personalizado. Se você criar versões do processador, vai decidir o nome e o ID.

Versões de base

Se você criar uma versão do processador, a "versão de base" vai mostrar qual versão do Google alimenta sua versão personalizada do usuário. A versão de base determina o ciclo de vida da versão do usuário. Você precisa tomar decisões sobre como gerenciar o ciclo de vida da sua versão personalizada do usuário.

Versões de processador estáveis disponíveis

Confira as versões estáveis de processador disponíveis para os diferentes tipos de processador nas tabelas a seguir.

Ciclo de vida da versão do processador

Assim que uma nova versão do Google estiver disponível, crie e avalie novas versões de usuário com a nova versão de base. Em seguida, implante a nova versão e cancele a implantação (ou exclua) das versões anteriores do usuário que usam a versão estável anterior como base. As versões estáveis são descontinuadas após o lançamento de uma nova. O Google avisa com pelo menos seis meses de antecedência quando isso acontece.

O que acontece quando uma versão de base é descontinuada?

As versões de usuário que dependem de versões de base anteriores param de retornar previsões quando a versão de base é descontinuada.

Como as versões do processador são selecionadas para suas solicitações?

Quando você chama um endpoint de processador sem especificar a versão, a versão padrão é usada. Quando a versão padrão do processador muda, talvez seja necessário atualizar o código.

Exemplo de descontinuação de uma versão personalizada

Considere o seguinte cenário que descreve a sequência de eventos em uma descontinuação de versão personalizada:

1. Como desenvolvedor, você está usando um extrator personalizado para receber dados de documentos. Devido à complexidade e ao volume de documentos processados, você ajusta o modelo de fundação para criar uma versão chamada fine-tune-A. Você define a versão fine-tune-A como a padrão do processador e a usa para processar documentos. A versão de base que alimenta o modelo fine-tune-A é a versão estável pretrained-foundation-model-v1.0-2023-08-22 (v1.0).

2. O Google publicou uma nova versão estável chamada pretrained-foundation-model-v1.2-2024-05-10 (v1.2) e anunciou que a versão estável v1.0 será descontinuada em 9 de abril de 2025.

3. Como você manteve os documentos de treinamento e teste no conjunto de dados do seu processador, ajuste outra versão com base na versão estável mais recente do Google, v1.2, e nomeie-a como fine-tune-B. Depois de avaliar a performance, defina a versão fine-tune-B como a nova versão padrão do seu processador e desative a versão fine-tune-A. A nova versão agora usa a versão estável mais recente do Google.

Por outro lado, se você não tivesse criado e avaliado a versão personalizada do fine-tune-B, o Google teria atualizado a versão padrão do seu processador para v1.2 em 9 de abril de 2025. Como você está chamando o endpoint do processador e não especificando uma versão, a nova versão v1.2 é usada como padrão para processar suas solicitações.

Recursos de descontinuação e migração

Para analisadores e processadores descontinuados, consulte Descontinuações da Document AI.

Confira os seguintes recursos para migrações:

• Para criar e treinar um novo analisador de despesas, consulte aprimorar o treinamento de um processador pré-treinado.

• Para criar e ajustar um novo processador de extrator personalizado, consulte Extrator personalizado com IA generativa.

Selecione uma versão do processador

Há três maneiras de especificar qual versão do processador usar para o processamento on-line e em lote:

• Se você não especificar uma versão, o padrão do processador será usado.

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

• Se você especificar uma versão, ela será usada. Se a versão específica não existir, a solicitação vai falhar com um erro.

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

• Se você especificar um canal, a versão mais recente dele será usada. (Opções: stable, rc)

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

Ver versão disponível

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 (