Managing processor versions

New versions are released for a variety of reasons, for example, to improve accuracy, increase availability, and support new document elements, such as selection marks.

Given that Document AI is powered by generative AI, future versions are using new foundation models so you can benefit from generative AI enhancements.

As we improve foundation models, earlier foundation models are deprecated. Similarly, processor versions are deprecated six months after new versions are released.

A processor can have one of the following versions:

• Stable version
• Release candidate (RC)
• Customized version and its associated base version

This page describes how processors are versioned, and how to view and select a particular version.

Processor versions overview

There are two categories of processor versions:

• Google versions are either stable (for production use cases) or release candidates (experimental with latest functionality).
• User versions are created by you to customize predictions for your documents and have alphanumeric version IDs.

Google versions

Each Google version is identified by a Version ID, for example pretrained-TYPE-vX.X-YYYY-MM-DD. Each processor version Google offers is named either Google Stable or Google Release Candidate (RC).

Google stable versions

Stable versions are production-quality and ready for use.

• Google prioritizes stability of the processor behaviour, but still includes critical fixes.
• Earlier Google stable versions are deprecated six months after the newest stable version is released as depicted in the following figure.

Google release candidates (RC)

Release candidates are experimental and are upgraded regularly with the latest features. These are not production-quality versions, and their stability may vary.

Customized versions

Customized versions are the processor versions that you can create based on your documents to customize predictions. Customized versions have a Type, which shows the kind of model used for predictions. If you create a version using a foundation model (either by creating a version or fine tuning), then the type is Generative AI. If you create a processor version by training a smaller, custom model (either model or template based), then the type is Custom. If you create processor versions, you decide the name and ID.

Base versions

If you create a processor version, the "base version" shows which Google version powers your customized user version. The base version dictates the lifecycle of your user version. You need to make decisions about how to manage the lifecycle of your customized user version.

Available stable processor versions

You can review the available stable processor versions for the different processor types in the following tables.

Processor version lifecycle

As soon as a new Google version is available, you should create and evaluate new user versions with the new base version. Then, deploy your new version and undeploy (or delete) earlier user versions that use the prior stable version as their base. Stable versions are discontinued after a new one is released. Google gives you at least six months' notice when this occurs.

What happens when a base version is deprecated?

User versions depending on earlier base versions stop returning predictions when the base version is deprecated.

How are processor versions selected for your requests?

When you call a processor endpoint without specifying the processor version, the default processor version is used. When the default processor version changes, you might need to update the code.

Deprecation example of a customized version

Consider the following scenario that describes the sequence of events in a customized version deprecation:

1. As a developer, you're using a Custom Extractor to get data from documents. Given the complexity and volume of documents you process, you fine tune the foundation model to create a version named fine-tune-A. You set the fine-tune-A version as the default version for your processor and use it to process documents. The base version that powers the fine-tune-A model is the pretrained-foundation-model-v1.0-2023-08-22 (v1.0) stable version.

2. Google published a new stable version named pretrained-foundation-model-v1.2-2024-05-10 (v1.2) and announced that the v1.0 stable version is to be deprecated on April 9, 2025.

3. Since you kept your training and test documents in your processor's dataset, you fine-tune another version based on the newest Google stable version, v1.2, and name it fine-tune-B. After you evaluate its performance, you set the fine-tune-B version as the new default version for your processor and decommission the fine-tune-A version. Your new version now uses the latest supported Google stable version.

On the other hand, had you not created and evaluated the customized fine-tune-B version, then Google would have updated the default version of your processor to v1.2 on April 9, 2025. Because you are calling the processor's endpoint and not specifying a processor version, the new v1.2 version is used as the new default to process your requests.

Deprecation and migration resources

For deprecated parsers and processors, you can consult Document AI deprecations.

See the following resources for migrations:

• For creation and training of a new Expense Parser, you can refer to uptrain pretrained processor.

• For creation and tuning of a new Custom Extractor processor, you can refer to Custom Extractor with GenAI.

Select a processor version

There are three ways to specify which processor version to use for online and batch processing:

• If you do not specify a version, the processor's default is used.

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

• If you specify a version, then that specific version is used. If the specific version does not exist, the request fails with an error.

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

• If you specify a channel then the latest version in that channel is used. (Options: stable, rc)

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

View available version

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)