Oracle Cloud Infrastructure Documentation

Creating a Custom Generative Model V2.0 (New)

The OCI Document Service features Key-Value Extraction powered by Large Multimodal Models (LMMs), offering enhanced accuracy and adaptability over conventional model-driven methods.

About

OCI Document service's key-value extraction uses multimodal reasoning to analyze both textual content and visual layouts, making it highly effective for handling documents with varied formats, templates, and structures. You can provide a schema outlining the required keys (fields) for extraction, enabling the service to adapt across different document types without the need for model retraining.

This large multimodal model (LMM)-powered approach shines in situations involving layout inconsistencies, irregular labeling, or scarce training data, circumstances where traditional template or model-based solutions often demand ongoing updates and upkeep.

Available Regions

You can create custom models for Generative large multimodal model (LMM)-based Key-Value extraction in the following OCI regions:

Region Name Location Region Identifier Region Key
Brazil East (Sao Paulo) Sao Paulo sa-saopaulo-1 GRU
Japan Central (Osaka) Osaka ap-osaka-1 KIX
UK South (London) London uk-london-1 LHR
US Midwest (Chicago) Chicago us-chicago-1 ORD

Learn About Regions and Availability Domains.

Creating a JSON File for Keys and Values

With generative extraction, you specify the information to be extracted by defining a schema. The schema acts as a set of instructions that describes the keys (fields) of interest and their expected values. Based on these instructions, the model identifies and extracts the values across documents with your specifics.

  1. Define the JSON Schema: Create a JSON file that contains an array of objects, where each object represents a key to be extracted.
  2. Specify Key Properties: Create each object in the array with the following properties:
    • key: The name of the key to extract (required).
    • dataType: The expected data type (optional).
    • description: A natural language description of the key (required).
  3. Enter the Keys: For key names, see Using System Keys and Custom Keys.
  4. (Optional) Add an Optional Data Type: If you need a specific data type for any of the keys, then for the dataType property, assign one of the following values:
    • string
    • date
    • number
    • currency
    • phone
  5. Use Natural Language for Descriptions: In the description property, provide clear, contextual details in plain English to guide the Generative AI model in identifying and extracting the correct values.

    Documents analyzed with this custom model can be in various languages, as listed in the version 2 column for custom key-value extraction in the Supported Languages table.

    An effective description explicitly clarifies:

    • What the field represents.

    • Where it typically appears in the document (visual or contextual location), such as the top right corner.

    • How it's formatted (patterns, separators, constraints), such as date formats.

    • What to exclude, including visually or semantically similar text that you don't want to extract.

  6. Populate the JSON File: Add your required keys and their descriptions. You can leave the description field as an empty string if you prefer the model to infer the value.
  7. In a supported region, save this JSON file in an Object Storage bucket in your tenancy.
Example JSON File

Here's an example JSON file for key-value extraction:

[
                    {
                    "key": "InvoiceId",
                    "dataType": "String",
                    "description": "A unique alphanumeric identifier assigned to the invoice. Usually labelled Invoice No., Inv #, 
Bill Number and appears near the top of the invoice, often right after the text label."
                    },
                    {
                    "key": "InvoiceDate",
                    "description": "Date the invoice was issued. Common formats include DD-MM-YYYY or MM/DD/YYYY."
                    },
                    {
                    "key": "DueDate",
                    "description": ""
                    },
                    {
                    "key": "PurchaseOrder",
                    "description": ""
                    },
                    {
                    "key": "InvoiceTotal",
                    "description": "Total amount due. Exclude subtotals, taxes, and discounts. 
Look for labels such as Grand Total, Amount Payable, or Balance Due near the bottom of the document."
                    },
                    {
                    "key": "TotalTax",
                    "description": ""
                    },
                    {
                    "key": "SubTotal",
                    "description": ""
                    },
                    {
                    "key": "AmountDue",
                    "description": ""
                    },
                    {
                    "key": "PreviousUnpaidBalance",
                    "description": ""
                    }
                    ]
Tip

For more examples for writing descriptions, see Best Practices for Custom Descriptions.

Using System Keys and Custom Keys

Document Understanding provides a set of predefined system keys. These keys are tuned to work with various document types and layouts. You can reuse these keys as-is, or alter their description.

Start with system-provided keys

Begin by using the predefined system key definitions and evaluate their performance on a representative sample of your documents. For a list of system-provided keys, see Key-Value Extraction.

  • If the results meet the requirements, reuse the system-provided keys.
  • You don't need to add descriptions for these keys.

Customize key descriptions when necessary

If a system-provided key doesn't fit the requirements, define a custom description based on the documents.

Best Practices for Custom Descriptions

Here are some best practices with examples for writing key descriptions:

Be explicit and unambiguous

Clearly distinguish between fields that might appear similar, such as different numeric identifiers.

Example

"key": "Invoice number"   
"description": "A unique alphanumeric identifier assigned to the invoice. 
Usually labeled Invoice No., Inv #, Bill Number and appears near the top of the invoice, 
often right after the text label."

Describe context and label variations

Generative models rely heavily on surrounding text and labels. Include common label variants.

Example

"key": "Company GST Number" "description": "Company GST number, 
often labeled as GSTIN, GST No., or Tax ID. Usually appears 
in the header with other business identifiers."

Specify expected value formats

If the field follows a known format, explicitly state it.

Example

"key": "Invoice Date" "description": "Date the invoice was issued. 
Common formats include DD-MM-YYYY or MM/DD/YYYY."

Clarify what to exclude

Explicitly identify similar fields that you don't want extracted.

Example

"key": "Total Amount" "description": "Total amount due. 
Exclude subtotals, taxes, and discounts. 
Look for labels such as Grand Total, Amount Payable, or Balance Due near the bottom of the document."

Include synonyms and label variations

Provide different labels to improve robustness across document variants.

Example

"key": "Customer Phone Number" "description": "Customer phone number. 
A 10-digit numeric value labeled as Phone, Tel, Contact, or Mobile, typically adjacent to the 
customer name or address."

Add reference location hints

If documents follow consistent layouts, include relative position cues.

Example

"key": "Supplier Address" "description": "Supplier address 
located under the business name in the top-left area of the first page."

Include examples when helpful

Concrete examples improve extraction accuracy.

Example

"key": "Invoice Date" "description": "Invoice date, 
for example 24-12-2025 or Dec 24, 2025. 
Usually follows labels such as Date or Invoice Date."

Be concise and precise

Prefer one clear descriptive sentence supplemented with essential constraints or examples.

Define fallback behavior

When applicable, specify how to infer values if the primary label is missing.

Example:

If Invoice Total is missing, use Total Amount Due instead.

Encode section awareness explicitly

For multi-section documents (such as forms), specify section context and field ordering.

Example

"key": "First Name" "description": "Person’s given name. 
Appears under the Personal Information or Applicant   Details section header. 
Usually the first field in the section and appears before Last Name. 
Might contain multiple words (for example, MaryAnn)."

Handle multi-word and multi-line values

Explicitly allow multi-token or multi-line extraction when applicable.

Example

"key": "Address" "description": "Full residential address. 
May span multiple consecutive lines within the same section. 
Extract all adjacent address lines as a single value."

Use negative guidance to avoid false positives

Explicitly state where values should not be extracted from.

Example

"key": "Applicant Name" "description": "Applicant name. 
Do not extract names appearing in signature blocks, declaration sections, 
or references to officials or witnesses."

Handling fields without explicit labels

For implicit fields, rely on semantic role and layout cues:

  • Position relative to section headers

  • Ordering among nearby fields

  • Proximity to related labels

Example Phrases

  • Appears immediately after…
  • Located next to…
  • Follows the section header…

Creating a Custom Generative Model

To create a custom model for key-value extraction using Generative AI, follow these steps:

Select Data

Create a Key-Value (KV) custom generative model using Document Understanding.

  1. Navigate to the Projects list page. If you need help finding the list page, see Listing Projects.
  2. Perform one of the following options:
    • If you don't have an existing project, create a project and then select that project.
    • If you have an existing project, select the project from the list.
  3. From the project details page, select Create Model. If you need help finding the project details page, see Viewing a Project.
  4. Select Create Model.
  5. For model details, select the following:
    • Choose model type to train: Key value extraction
    • Model version: V2.0 (Generative extraction)
  6. For Training Data, select Choose existing dataset.
  7. For Data Source, select Object Storage.
  8. Select the bucket that contains the JSON file that you prepared in Creating a JSON File for Keys and Values. If the bucket is in a different compartment than this project, select the compartment with the bucket.
  9. For Data Labeling File, select the JSON file and then select Next.

Train Model

  1. Enter a name for the custom model.
  2. (Optional) Give the model a description to help you find it.
  3. Inference Unit Count is a Compute resource dedicated to your endpoint and is set to 1. You can't change it.
  4. For Training Document Language, select EN for English.
  5. For Training Duration, select one of the following options:
    • Recommended training: Document Understanding automatically selects the training duration to create the best model. The training might take up to 24 hours.
    • Custom: With this option you can set the maximum training duration (in hours).
  6. Select Next.

Review

  1. Review the information you provided in the previous steps. You can make any changes, by selecting Previous or Edit.
  2. When you're happy with the selections, select Create and train.

Test the Model

  1. After the custom model creates, in the model detail page, navigate to the Analyze section.
  2. Upload a document from a local file or Object Storage to test the custom model.
  3. Select Analyze.
  4. Review the keys and their extracted values.
  5. If you're not happy with the results, for example, to add a key or to update a description, update your JSON file and repeat the previous steps.