OCI

The UC AI OCI package integrates Oracle Cloud Infrastructure’s Generative AI models into your Oracle database applications.

Features

• Support for Cohere, Meta Llama, xAI Grok models, and Google Gemini models
• Features vary by model

Responses API

As of v26.2, UC AI routes OCI calls through OCI’s Responses API endpoint by default for models that support it. To fall back to the generic chat endpoint, set:

uc_ai_oci.g_use_responses_api := false;

Max output tokens

OCI chat requests are capped by maxTokens, which defaults to 4096. Raise it for long outputs (e.g. document extraction) to avoid silent truncation:

uc_ai_oci.g_max_tokens := 8192;

When the model stops because this cap was reached, UC AI reports finish_reason = 'length' so callers can detect truncation. (You can also set it per call with the provider configuration key g_max_tokens.)

Serving mode

g_serving_type selects the serving mode. It accepts ON_DEMAND and DEDICATED, and the default is ON_DEMAND.

ON_DEMAND reaches a model that OCI hosts for every tenancy. The request carries the model id.

DEDICATED reaches a model on a dedicated AI cluster in your tenancy. That mode carries the OCID of the cluster endpoint in place of the model id. UC AI reads the OCID from g_endpoint_id:

uc_ai_oci.g_serving_type := 'DEDICATED';
uc_ai_oci.g_endpoint_id  := 'ocid1.generativeaiendpoint.oc1.eu-frankfurt-1.aaaaaa...';

g_serving_type := 'DEDICATED' without g_endpoint_id raises ORA-20502 before the request goes out. The provider configuration keys g_serving_type and g_endpoint_id set the same two values per call.

Prerequisites

1. Create OCI API Key and APEX Web Credential (see guide)
2. Oracle database with internet access to OCI’s API endpoints (see Network Setup (ACL & Wallet))
3. UC AI package installed

OCI uses a credential-based authentication system with a private key and three other components, not a simple API key. Oracle does not provide a PL/SQL SDK for these cryptographic operations, so the UC AI package builds on Oracle APEX Web Credentials, which can do the work.

If you have a way to do the cryptographic operations in PL/SQL, contact us or open a pull request, so that this can also work without APEX. The same applies if you know a way to use Auth tokens (simple API keys) with the AI APIs.

Models

The models available to you depend on the region of your OCI tenant.

Currently Oracle provides Cohere, Meta Llama, xAI Grok models, and Google Gemini models.

Refer to this list of available models for more information. Click on a model to see where it is available.

Meta Llama

• uc_ai_oci.c_model_llama_4_scout
• uc_ai_oci.c_model_llama_4_maverick

Cohere

• uc_ai_oci.c_model_cohere_command_a_reasoning
• uc_ai_oci.c_model_cohere_command_a_vision
• uc_ai_oci.c_model_cohere_command_a_03_2025

xAI Grok

• uc_ai_oci.c_model_grok_4_7
• uc_ai_oci.c_model_grok_4_20_multi_agent

OpenAI

• uc_ai_oci.c_model_gpt_oss_120b
• uc_ai_oci.c_model_gpt_oss_20b

Google Gemini

• uc_ai_oci.c_model_google_gemini_2_5_pro
• uc_ai_oci.c_model_google_gemini_2_5_flash
• uc_ai_oci.c_model_google_gemini_2_5_flash_lite

This list shows the newest model of each family. The package keeps the constants of older models for code that still references them.

Retired Models

Oracle marks the Grok 3 and Grok 4 models, grok-code-fast-1, the Llama 3.1 and Llama 3.2 models, and the Command R models as deprecated. The same applies to the Cohere embedding models of version 3. The package keeps their constants, but use a current model for new code.

Tip

If a new model is not yet available as a constant, you can pass the model name directly as a string. See the FAQ for details.

Usage Examples

Basic Text Generation

declare
  l_result json_object_t;
begin
  uc_ai_oci.g_compartment_id := 'your_compartment_id_here';
  uc_ai_oci.g_region := 'eu-frankfurt-1';
  uc_ai_oci.g_apex_web_credential := 'NAME_OF_YOUR_APEX_WEB_CREDENTIAL';

  -- optional
  uc_ai_oci.g_serving_type := 'ON_DEMAND'; -- the default. DEDICATED also needs g_endpoint_id

  l_result := uc_ai.generate_text(
    p_user_prompt => 'What is Oracle APEX?',
    p_provider => uc_ai.c_provider_oci,
    p_model => uc_ai_oci.c_model_cohere_command_a_03_2025
  );

  dbms_output.put_line('AI Response: ' || l_result.get_string('final_message'));
end;
/

With System Prompt

declare
  l_result json_object_t;
begin
  uc_ai_oci.g_compartment_id := 'your_compartment_id_here';
  uc_ai_oci.g_region := 'eu-frankfurt-1';
  uc_ai_oci.g_apex_web_credential := 'NAME_OF_YOUR_APEX_WEB_CREDENTIAL';

  -- optional
  uc_ai_oci.g_serving_type := 'ON_DEMAND'; -- the default. DEDICATED also needs g_endpoint_id

  l_result := uc_ai.generate_text(
    p_user_prompt => 'I have tomatoes, salad, potatoes, olives, and cheese. What can I cook with that?',
    p_system_prompt => 'You are an assistant helping users to get recipes. Please just list 3 possible dish names without instructions.',
    p_provider => uc_ai.c_provider_oci,
    p_model => uc_ai_oci.c_model_cohere_command_a_03_2025
  );

  dbms_output.put_line('Recipe suggestions: ' || l_result.get_string('final_message'));
end;
/

Tools

Tools / function calling is supported. Refer to the model documentation page to see which models support it.

File input (images & PDFs)

OCI supports file input through the file analysis message API, but only via its GENERIC chat format:

• Use a GENERIC-format vision model (Meta Llama vision, Google Gemini, xAI Grok). Cohere models reject file content.
• Images: PNG or JPG only, ≤ 5 MB.
• Documents: PDF only.
• Other types (e.g. WebP, GIF) are rejected with ORA-20303.

Generating Embeddings

OCI provides Cohere embedding models for semantic search, clustering, and other vector-based operations:

• uc_ai_oci.c_model_cohere_embed_4 - Latest Cohere v4 embedding model
• uc_ai_oci.c_model_cohere_embed_english_3 - English-optimized v3 model
• uc_ai_oci.c_model_cohere_embed_english_light_3 - Lightweight English model
• uc_ai_oci.c_model_cohere_embed_multi_3 - Multilingual v3 model
• uc_ai_oci.c_model_cohere_embed_multi_light_3 - Lightweight multilingual model

Image-capable embedding models are also available:

• uc_ai_oci.c_model_cohere_embed_english_image_3
• uc_ai_oci.c_model_cohere_embed_english_light_image_3
• uc_ai_oci.c_model_cohere_embed_multi_image_light_3

Also refer to the OCI documentation for any new models that might not be listed here and region availability.

declare
  l_result json_array_t;
begin
  uc_ai_oci.g_compartment_id := 'your_compartment_id_here';
  uc_ai_oci.g_region := 'eu-frankfurt-1';
  uc_ai_oci.g_apex_web_credential := 'NAME_OF_YOUR_APEX_WEB_CREDENTIAL';

  l_result := uc_ai.generate_embeddings(
    p_input => json_array_t('["Oracle APEX is a low-code development platform.", "UC AI allows you to easily use AI from PL/SQL."]'),
    p_provider => uc_ai.c_provider_oci,
    p_model => uc_ai_oci.c_model_cohere_embed_english_3
  );

  -- l_result.get_size → 2 (one embedding per input string)
  -- l_result.get(0) → JSON array of embedding values for first input
end;
/

For more information about the generate_embeddings function, visit its documentation page.

OCR with Document Understanding

uc_ai.ocr with uc_ai.c_provider_oci reads PDFs and images with OCI Document Understanding. This service is not a chat model. p_model is ignored. The result holds the text lines as Markdown, and optionally the tables, with the box and the confidence of each block.

Document Understanding uses the same web credential as the other OCI requests and the compartment of uc_ai_oci.g_compartment_id. If the compartment is not set, the call raises ORA-20502. The user of the API key needs a policy that allows Document Understanding in the compartment. See the Document Understanding documentation for the policy.

UC AI sends the document inline in one synchronous call. Oracle documents a limit of 5 pages for a synchronous call. UC AI checks only the size of the document (8 MB of raw bytes) and not the number of pages. A larger document raises ORA-20503. The URL comes from uc_ai_oci.g_region. uc_ai.g_base_url does not apply to OCR with OCI.

declare
  l_result json_object_t;
begin
  uc_ai_oci.g_compartment_id      := 'ocid1.compartment.oc1..your-compartment';
  uc_ai_oci.g_region              := 'eu-frankfurt-1';
  uc_ai_oci.g_apex_web_credential := 'OCI_KEY';

  l_result := uc_ai.ocr(
    p_document   => your_pdf_blob,
    p_media_type => 'application/pdf',
    p_provider   => uc_ai.c_provider_oci,
    p_options    => json_object_t('{"tables": true}')
  );
end;
/

The OCR reference describes the options, the result and the errors.