Purpose

To automatically generate vector embeddings from a set of textual documents and images.

• Text to Vector:

  You can perform a text-to-embedding transformation by accessing:

  • Oracle Database as the service provider: Calls an ONNX format embedding model that you load into the database (default setting)

  • Third-party embedding model: Makes a REST API call to either a remote service provider (Cohere, Google AI, Hugging Face, Generative AI, OpenAI, or Vertex AI) or a local service provider (Ollama)

• Image to Vector:

  You can also perform an image-to-embedding transformation. For this operation, this API makes a REST call to your chosen image embedding model or multimodal embedding model by Vertex AI (which is the only supported third-party provider).

Syntax

• Text to Vector:

  DBMS_VECTOR.UTL_TO_EMBEDDING (
      DATA           IN CLOB,
      PARAMS         IN JSON default NULL
  ) return VECTOR;

  DBMS_VECTOR.UTL_TO_EMBEDDINGS (
      DATA           IN VECTOR_ARRAY_T,
      PARAMS         IN JSON default NULL
  ) return VECTOR_ARRAY_T;

• Image to Vector:

  DBMS_VECTOR.UTL_TO_EMBEDDING (
      DATA           IN BLOB,
      MODALITY       IN VARCHAR2,
      PARAMS         IN JSON default NULL
  ) return VECTOR;

DATA

UTL_TO_EMBEDDING accepts the input as CLOB containing textual data (text strings or small documents) or as BLOB containing media data (for media files such as images). It then converts the text or image input to a single embedding (VECTOR).

UTL_TO_EMBEDDINGS converts an array of chunks (VECTOR_ARRAY_T) to an array of embeddings (VECTOR_ARRAY_T).

A generated embedding output includes:

{
    "embed_id"    :  NUMBER,
    "embed_data"  : "VARCHAR2(4000)", 
    "embed_vector": "CLOB"
}

MODALITY

For BLOB inputs, specify the type of content to vectorize. The only supported value is image.

PARAMS

Specify input parameters in JSON format, depending on the service provider that you want to use.

{
  "provider" : "database", 
  "model"    : "<in-database ONNX embedding model filename>" 
}

If using a third-party provider:

Set the following parameters along with additional embedding parameters specific to your provider:

• For UTL_TO_EMBEDDING:

  {
    "provider"        : "<AI service provider>", 
    "credential_name" : "<credential name>",
    "url"             : "<REST endpoint URL for embedding service>", 
    "model"           : "<REST provider embedding model name>",
    "transfer_timeout": <maximum wait time for the request to complete>,
    "<additional REST provider parameter>": "<REST provider parameter value>" 
  }

• For UTL_TO_EMBEDDINGS:

  {
    "provider"        : "<AI service provider>", 
    "credential_name" : "<credential name>",
    "url"             : "<REST endpoint URL for embedding service>", 
    "model"           : "<REST provider embedding model name>",
    "transfer_timeout": <maximum wait time for the request to complete>,
    "batch size"      : "<number of vectors to request at a time>",
    "<additional REST provider parameter>": "<REST provider parameter value>" 
  }

Additional REST provider parameters:

Optionally, specify additional provider-specific parameters.

{
  "provider"       : "cohere",
  "credential_name": "COHERE_CRED",
  "url"            : "https://api.cohere.example.com/embed",
  "model"          : "embed-model",
  "input_type"     : "search_query"
}

{
  "provider"       : "googleai",
  "credential_name": "GOOGLEAI_CRED",
  "url"            : "https://googleapis.example.com/models/",
  "model"          : "embed-model"
}

{
  "provider"       : "huggingface",
  "credential_name": "HF_CRED",
  "url"            : "https://api.huggingface.example.com/",
  "model"          : "embed-model"
}

{
  "provider"       : "ocigenai",
  "credential_name": "OCI_CRED",
  "url"            : "https://generativeai.oci.example.com/embedText",
  "model"          : "embed-model",
  "batch_size"     : 10
}

{
  "provider"       : "ollama", 
  "host"           : "local", 
  "url"            : "http://localhost:11434/api/embeddings", 
  "model"          : "llama3"
}

{
  "provider"       : "openai",
  "credential_name": "OPENAI_CRED",
  "url"            : "https://api.openai.example.com/embeddings",
  "model"          : "embed-model"
}

{
  "provider"       : "vertexai",
  "credential_name": "VERTEXAI_CRED",
  "url"            : "https://googleapis.example.com/models/",
  "model"          : "embed-model"
}

Examples

You can use UTL_TO_EMBEDDING in a SELECT clause and UTL_TO_EMBEDDINGS in a FROM clause, as follows:

• The following examples use UTL_TO_EMBEDDING to generate an embedding with Hello world as input, by accessing the Generative AI embedding model:

  -- declare embedding parameters
  
  var params clob;
  
  begin
   :params := '
  { 
    "provider": "ocigenai",
    "credential_name": "OCI_CRED", 
    "url": "https://generativeai.oci.example.com/embedText",
    "model": "embed.modelname",
    "batch_size": 10
  }';
  end;
  /
  
  -- get text embedding: PL/SQL example
  
  declare
    input clob;
    v vector;
  begin
    input := 'Hello world';
  
    v := dbms_vector.utl_to_embedding(input, json(params));
    dbms_output.put_line(vector_serialize(v));
  exception
    when OTHERS THEN
      DBMS_OUTPUT.PUT_LINE (SQLERRM);
      DBMS_OUTPUT.PUT_LINE (SQLCODE);
  end;
  /
  
  -- get text embedding: select example
  
  select dbms_vector.utl_to_embedding('Hello world', json(:params)) from dual;

  The following examples use UTL_TO_EMBEDDING to generate an embedding with parrots.jpg as input and modality as image, by accessing the Vertex AI's multimodal embedding model.

  -- declare embedding parameters
  
  var params clob;
  
  begin
    :params := '
  {
    "provider": "vertexai",
    "credential_name": "VERTEXAI_CRED",
    "url": "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/publishers/google/models/",
    "model": "multimodalembedding:predict"
  }';
  end;
  /
  
  -- get image embedding: PL/SQL example
  
  declare
    v vector;
    output clob;
  begin
    v := dbms_vector.utl_to_embedding(
      to_blob(bfilename('VEC_DUMP', 'parrots.jpg')), 'image', json(:params));
    output := vector_serialize(v);
    dbms_output.put_line('vector data=' || dbms_lob.substr(output, 100) || '...');
  end;
  /
  
  -- get image embedding: select example
  
  select dbms_vector.utl_to_embedding(
    to_blob(bfilename('VEC_DUMP', 'parrots.jpg')), 'image', json(:params));

  End-to-end examples:

  To run end-to-end example scenarios using UTL_TO_EMBEDDING, see Generate Embedding.

• The following example uses UTL_TO_EMBEDDINGS to generate embeddings with a PDF document (stored in the documentation_tab table) as input, by calling an ONNX format model loaded into the database:

  SELECT et.* from documentation_tab dt,dbms_vector.utl_to_embeddings(
    dbms_vector.utl_to_chunks(dbms_vector.utl_to_text(dt.data)),
    json(:embed_params)) et;

  End-to-end examples:

  To run end-to-end example scenarios using UTL_TO_EMBEDDINGS, see Perform Chunking With Embedding.