Custom splitter

Custom splitter is designed to be used to split composite documents (documents made up of multiple classes) into a number of single class documents by identifying each logical document. For example, a mortgage package contains multiple classes within it such as application, income verification, and photo ID. Custom splitter processors can be used out of the box, or trained from the ground up using your own documents and custom classes.

Splitter description and usage

You can create custom splitters that are specifically suited to your documents and trained and evaluated with your data, or deploy pretrained models with generative AI. These processors identify classes of documents from a user-defined set of classes. You can then use these processors on your documents. You typically would use a custom splitter on files that are composed of different types of logical documents, then use the class identification of each to pass the documents to an appropriate extraction processor to extract the entities.

Because ML models are not perfect and have a certain error rate, and because errors in splitting are typically very problematic (a bad split makes two documents wrong and causes extraction errors), a best practice is to always have a human review step after the splitting prediction but before the actual file split. Based on business requirements, there are alternatives to always doing human review:

  • Use confidence scores in the prediction to decide whether to bypass human review (if high enough). That confidence score threshold should be determined based on historical data about error rates at given confidence scores. This should be a business decision based on the business process tolerance for errors and requirement to bypass human review.
  • In some use cases, the split documents can be routed directly to the appropriate extractor according to the predicted class. Then, if the extraction is incomplete or has low confidence scores, isolate the split documents and trigger the original composite document and split decision to then be reviewed. This has rather complex workflow requirements.

Custom splitter model versions

The following models are available for custom splitter. To change model versions, see Manage processor versions.

Version 1.5 supports confidence scores.

Model version Description Release channel Release date
pretrained-splitter-v1.5-2025-07-14 GA model powered by the Gemini 2.5 Flash LLM. This pre-trained model can be used without prior training. It supports zero-shot splitting and classification. Stable July 14, 2025
pretrained-splitter-v1.6-2026-03-09 Release candidate powered by the Gemini 3.1 Flash LLM. Release Candidate March 9, 2026
pretrained-splitter-v1.6-pro-2026-03-09 Release candidate powered by the Gemini 3.1 Pro LLM. Release Candidate March 9, 2026

To make a Quota Increase Request (QIR) for the default processor quota, follow the steps to request a quota adjustment.

Decide on a custom splitter version

When using custom splitter, train on your own data or use a pre-trained version with generative AI, such as pretrained-splitter-v1.5-2025-07-14.

The training process can take several hours, but lets you adjust the model to the specifics of your data. Pre-trained versions are based on Gemini models. They can be brought to production in less time or used to quickly iterate and test labeling schema. They don't require a training dataset.

The following guide applies to both versions, and will call out the different steps for each when they vary.

Create a custom splitter in Google Cloud console

This quickstart guide describes how to use Document AI to create and train a custom splitter that splits and classifies procurement documents. Most of the document prep is done, so that you can focus on creating a custom splitter.

A typical workflow to create and use a custom splitter trained base version is as follows:

  1. Create a custom splitter in Document AI.
  2. Create a dataset using an empty Cloud Storage bucket.
  3. Define and create the processor schema (classes).
  4. Import documents.
  5. Assign documents to the training and test sets.
  6. Annotate documents manually in Document AI or with labeling tasks.
  7. Train the processor.
  8. Evaluate the processor.
  9. Deploy the processor.
  10. Test the processor.
  11. Use the processor on your documents.

A typical workflow to create and use a custom splitter pre-trained version is as follows:

  1. Create a custom splitter in Document AI.
  2. Create a dataset using an empty Cloud Storage bucket.
  3. Select a pre-trained model version
  4. Define and create the processor schema (classes).
  5. (Optionally) Import documents.
  6. (Optionally if you want to evaluate its performance) Assign documents to the test sets
  7. (Optionally) Evaluate the processor.
  8. Test the processor.
  9. Deploy the processor.
  10. Use the processor on your documents.

To follow step-by-step guidance for this task directly in the Google Cloud console, click Guide me:

Guide me

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Document AI, Cloud Storage APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Document AI, Cloud Storage APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    10.

Required roles

To get the permissions that you need to create a custom splitter, ask your administrator to grant you the following IAM roles on your project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create a processor

  1. In the Google Cloud console, in the Document AI section, go to the Workbench page.

    Workbench

  2. For Custom Document Splitter, select Create processor. custom-splitter-1

  3. In the Create processor menu, enter a name for your processor, such as my-custom-document-splitter.

    custom-splitter-2

  4. Select the region closest to you.

  5. Select Create. The Processor Details tab appears.

Configure dataset

In order to train this new processor, you must create a dataset with training and testing data to help the processor identify the documents that you want to split and classify.

This dataset requires a new location for it. This can be an empty Cloud Storage bucket or folder, or you can allow a Google-Managed (internal) location.

  • If you want Google-managed storage, select that option.
  • If you want to use your own storage in order to use Customer-Managed Encryption Keys (CMEK), select I'll specify my own storage location and follow the later procedure.

custom-splitter-3

Create a Cloud Storage bucket for the dataset

  1. Go to your processor's Train tab.

  2. Select Set dataset location. You are prompted to select or create an empty Cloud Storage bucket or folder.

    custom-splitter-4

  3. Select Browse to open Select folder.

  4. Select the Create a new bucket icon and follow the prompts to create a new bucket. After you create the bucket, the Select folder page appears for it. For more information on creating a Cloud Storage bucket, refer to Cloud Storage buckets.

  5. On the Select folder page for your bucket, choose the Select button at the bottom of the dialog.

    custom-splitter-5

Make sure the destination path is populated with the bucket name you selected. Select Create dataset. The dataset might take up to several minutes to create.

(Optional) Select a pre-trained model version

If you have decided to use a pre-trained model, you must first select it in the Deploy and use section. You can ignore the sections after the next one, "Define processor schema."

  1. Navigate to Deploy and use

    custom-splitter-15

  2. Click the Manage versions drop-down.

  3. Select the chosen processor version.

Define processor schema

You can create the processor schema either before or after you import documents into your dataset. The schema provides labels that you use to annotate documents.

  1. On the Build tab, select Manage dataset. The manage dataset page opens.

  2. Select Edit Schema.

  3. Select Create label and enter the name for the label. Select Create. Refer to Define processor schema for detailed instructions on creating and editing a schema.

  4. Create each of the following labels for the processor schema.

    • bank_statement
    • form_1040
    • form_w2
    • form_w9
    • paystub

  5. Select Save when the labels are complete.

    custom-splitter-6

Import an unlabeled document into a dataset

The next step is to begin importing unlabeled documents into your dataset and label them. A recommended alternative is to import documents organized in folders by class, if available.

If working on your own project, you determine how to label your data. Refer to Labeling options.

Document AI custom processors require a minimum of 10 documents in the training and test sets, along with 10 instances of each label in each set. We recommend at least 50 documents in each set, with 50 instances of each label for best performance. In general, more training data produces higher accuracy.

  1. On the Train tab, select Import documents.

    custom-splitter-7

  2. For this example, enter this path in Source path. This contains one document PDF.

    cloud-samples-data/documentai/Custom/Lending-Splitter/PDF-Unlabeled

  3. Set the Document label as None.

  4. Set the Dataset split dropdown to Unassigned.

    The document in this folder is not given a label or assigned to the testing or training set by default.

  5. Select Import. Document AI reads the documents from the bucket into the dataset. It does not modify the import bucket or read from the bucket after the import is complete.

When you import documents, you can optionally assign the documents to the Training or Test set when imported, or wait to assign them later.

If you want to delete a document or documents that you have imported, select them on the Train tab, and select Delete.

For more information about preparing your data for import, refer to the Data preparation guide.

Optional: Batch label documents at import

You can label all documents that are in a particular directory at import to save time with labeling. If you have your training documents organized by class in folders, then you can use the Document label field to specify the class for those documents and avoid manual labeling of each document.

custom-splitter-8

In the image Bank_statements and Invoice are available defined labels (document classes) you can select. Or you can use CREATE LABEL and define a new class.

  1. Click Import documents.

  2. Enter the following path in Source path. This bucket contains unlabeled documents in PDF format.

    cloud-samples-data/documentai/Custom/Patents/PDF-CDC-BatchLabel

  3. From the Data split list, select Auto-split. This automatically splits the documents to have 80% in the training set, and 20% in the test set.

  4. In the Apply labels section, select Choose label.

  5. For these sample documents, select other.

  6. Click Import and wait for the documents to import. You can leave this page and return later.

Label a document

The process of applying labels to a document is known as annotation.