UTL_TO_SUMMARY

Use the DBMS_VECTOR_CHAIN.UTL_TO_SUMMARY chainable utility function to generate a summary for textual documents.

Purpose

To perform a text-to-summary transformation by accessing:

Oracle Database as the service provider: Uses the in-house implementation with Oracle Database, leveraging a document gist (or summary) generated by Oracle Text (default setting)
Third-party summarization 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)

A summary is a short and concise extract with key features of a document that best represents what the document is about as a whole. A summary can be free-form paragraphs or bullet points based on the format that you specify.

WARNING:

Certain features of the database may allow you to access services offered separately by third-parties, for example, through the use of JSON specifications that facilitate your access to REST APIs.

Your use of these features is solely at your own risk, and you are solely responsible for complying with any terms and conditions related to use of any such third-party services. Notwithstanding any other terms and conditions related to the third-party services, your use of such database features constitutes your acceptance of that risk and express exclusion of Oracle's responsibility or liability for any damages resulting from such access.

Syntax

DBMS_VECTOR_CHAIN.UTL_TO_SUMMARY (
    DATA          IN CLOB,
    PARAMS        IN JSON default NULL
) return CLOB;

DATA

This function accepts the input data type in plain text as CLOB.

It returns a summary of the input document also as CLOB.

PARAMS

Specify summary parameters in JSON format, depending on the service provider that you want to use for document summarization.

If using Oracle Database as the provider:

{
  "provider"     : "database",
  "glevel"       : "<summary format>",
  "numParagraphs": <number in the range 1-16>,
  "maxPercent"   : <number in the range 1-100>,
  "num_themes"   : <number in the range 1-50>,
  "language"     : "<name of the language>"
}

Table 12-30 Database Provider Parameter Details

Parameter	Description
`provider`	Specify `database` (default setting) to access Oracle Database as the provider. Oracle Text is internally used to extract a document `gist` or summary from user data.
`glevel`	Format to display the summary: `SENTENCE` \| `S`: As a list of sentences `PARAGRAPH` \| `P`: In a free-form paragraph
`numParagraphs`	Maximum number of document paragraphs (or sentences) selected for the summary. The default value is `16`. The `numParagraphs` parameter is used only when this parameter yields a smaller summary size than the summary size yielded by the `maxPercent` parameter, because the function always returns the smallest size summary.
`maxPercent`	Maximum number of document paragraphs (or sentences) selected for the summary, as a percentage of the total paragraphs (or sentences) in the document. The default value is `10`. The `maxPercent` parameter is used only when this parameter yields a smaller summary size than the summary size yielded by the `numParagraphs` parameter, because the function always returns the smallest size summary.
`num_themes`	Number of theme summaries to produce. For example, if you specify `10`, then this function returns the top 10 theme summaries. If you specify `0` or `NULL`, then this function returns all themes in a document. The default value is `50`. If the document contains more than 50 themes, only the top 50 themes show conceptual hierarchy.
`language`	Language name of your summary text, as listed in Supported Languages and Data File Locations.

If using a third-party provider:

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

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

Table 12-31 Third-Party Provider Parameter Details

Parameter	Description
`provider`	Third-party service provider that you want to access to get the summary. A REST call is made to the specified provider to access its text summarization model. Specify one of the following values: `cohere` `googleai` `huggingface` `ocigenai` `openai` `vertexai`
`credential_name`	Name of the credential in the form: `schema.credential_name` A credential name holds authentication credentials to enable access to your provider for making REST API calls. You need to first set up your credential by calling the `DBMS_VECTOR_CHAIN.CREATE_CREDENTIAL` helper function to create and store a credential, and then refer to the credential name here. See CREATE_CREDENTIAL.
`url`	URL of the API endpoint for each REST call. Note: For a list of all supported REST endpoints, see Supported Third-Party Provider Operations and Endpoints.
`model`	Name of the third-party text summarization model in the form: `schema.model_name` If the model name is not schema-qualified, then the schema of the procedure invoker is used. Note: For Generative AI, you must specify `schema.model_name`.
`transfer_timeout`	Maximum time to wait for the request to complete. The default value is `60` seconds. You can increase this value for busy web servers.

Additional REST provider parameters:

Optionally, specify additional provider-specific parameters.

Important:

The following examples are for illustration purposes. For accurate and up-to-date information on additional parameters to use, refer to your third-party provider's documentation.

Cohere example:

{
  "provider"        : "cohere",
  "credential_name" : "COHERE_CRED",
  "url"             : "https://api.cohere.example.com/summarize",
  "model"           : "summarize-model",
  "length"          : "medium",
  "format"          : "paragraph",
  "temperature"     : 1.0
}

Google AI example:

{
  "provider"         : "googleai",
  "credential_name"  : "GOOGLEAI_CRED",
  "url"              : "https://googleapis.example.com/models/",
  "model"            : "summarize-model",
  "generation_config": {
    "temperature"    : 0.9,
    "topP"           : 1,
    "candidateCount" : 1,
    "maxOutputTokens": 256
  }
}

Hugging Face example:

{
  "provider"          : "huggingface",
  "credential_name"   : "HF_CRED",
  "url"               : "https://api.huggingface.example.co/models/",
  "model"             : "summarize-model"
}

Generative AI example:

{
 "provider"           : "ocigenai",
 "credential_name"    : "OCI_CRED",
 "url"                : "https://generativeai.oci.example.com/summarizeText",
 "model"              : "summarize-model",
 "length"             : "MEDIUM",
 "format"             : "PARAGRAPH"
}

Ollama example:

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

OpenAI example:

{
  "provider"          : "openai",
  "credential_name"   : "OPENAI_CRED",
  "url"               : "https://api.openai.example.com",
  "model"             : "summarize-model",
  "max_tokens"        : 256,
  "temperature"       : 1.0
}

Vertex AI example:

{
  "provider"          : "vertexai",
  "credential_name"   : "VERTEXAI_CRED",
  "url"               : "https://googleapis.example.com/models/",
  "model"             : "summarize-model",
  "generation_config" : {
    "temperature"     : 0.9,
    "topP"            : 1,
    "candidateCount"  : 1,
    "maxOutputTokens" : 256
  }
}

Table 12-32 Additional REST Provider Parameter Details

Parameter	Description
`length`	Approximate length of the summary text: `SHORT`: Roughly up to 2 sentences `MEDIUM`: Between 3 and 5 sentences `LONG`: 6 or more sentences `AUTO`: The model chooses a length based on the input size Note: For Generative AI, you must enter this value in uppercase.
`format`	Format to display the summary: `PARAGRAPH`: In a free-form paragraph `BULLETS`: In bullet points Note: For Generative AI, you must enter this value in uppercase.
`temperature`	Degree of randomness used when generating output text, in the range of `0.0-5.0`. To generate the same output for a prompt, use `0`. To generate a random new text for that prompt, increase the temperature. Default temperature is `1` and the maximum temperature is `5`. Note: To summarize a text, start with the temperature set to `0`. If you do not require random results, a recommended temperature value is `0.2` for Generative AI and between `0` and `1` for Cohere. Use a higher value if for example you plan to perform a selection of the various summaries afterward. Do not use a high temperature for summarization because a high temperature encourages the model to produce creative text, which might also include hallucinations.
`extractiveness`	How much to reuse the input in the summary: `LOW`: Summaries with low extractiveness tend to paraphrase. `HIGH`: Summaries with high extractiveness lean toward reusing sentences verbatim. Note: For Generative AI, you must enter this value in uppercase.
`max_tokens`	Maximum number of tokens in the output text.
`topP`	Probability of tokens in the output, in the range of `0.0–1.0`. A lower value provides less random responses and a higher value provides more random responses.
`candidateCount`	Number of response variations to return, in the range of `1-4`.
`maxOutputTokens`	Maximum number of tokens to generate for each response.

Note:

When specifying the length, format, and extractiveness parameters for Generative AI, ensure to enter the values in uppercase letters.

Examples

These statements generate a summary from an extract on "Transactions", by accessing the Generative AI summarization model.

-- select example

var params clob;
exec :params := '
{  
 "provider": "ocigenai", 
 "credential_name": "OCI_CRED", 
 "url": "https://generativeai.oci.example.com/summarizeText", 
 "model": "summarize.modelname",
 "temperature": "0.0",
 "extractiveness": "LOW"
}';

select dbms_vector_chain.utl_to_summary(
 'A transaction is a logical, atomic unit of work that contains one or more SQL statements.  An RDBMS must be able to group SQL statements so that they are either all committed, which means they are applied to the database, or all rolled back, which means they are undone.  An illustration of the need for transactions is a funds transfer from a savings account to a checking account. The transfer consists of the following separate operations:
    1. Decrease the savings account.
    2. Increase the checking account.
    3. Record the transaction in the transaction journal.
    Oracle Database guarantees that all three operations succeed or fail as a unit. For example, if a hardware failure prevents a statement in the transaction from executing, then the other statements must be rolled back.
    Transactions set Oracle Database apart from a file system. If you perform an atomic operation that updates several files, and if the system fails halfway through, then the files will not be consistent. In contrast, a transaction moves an Oracle database from one consistent state to another. The basic principle of a transaction is "all or nothing": an atomic operation succeeds or fails as a whole.',
 json(:params)) from dual;

-- PL/SQL example

declare
  input clob;
  params clob;
  output clob;
begin
  input := 'A transaction is a logical, atomic unit of work that contains one or more SQL statements.  An RDBMS must be able to group SQL statements so that they are either all committed, which means they are applied to the database, or all rolled back, which means they are undone.  An illustration of the need for transactions is a funds transfer from a savings account to a checking account. The transfer consists of the following separate operations:
    1. Decrease the savings account.
    2. Increase the checking account.
    3. Record the transaction in the transaction journal.
    Oracle Database guarantees that all three operations succeed or fail as a unit. For example, if a hardware failure prevents a statement in the transaction from executing, then the other statements must be rolled back.
    Transactions set Oracle Database apart from a file system. If you perform an atomic operation that updates several files, and if the system fails halfway through, then the files will not be consistent. In contrast, a transaction moves an Oracle database from one consistent state to another. The basic principle of a transaction is "all or nothing": an atomic operation succeeds or fails as a whole.';

  params := '
  {
   "provider": "ocigenai",
   "credential_name": "OCI_CRED",
   "url": "https://generativeai.oci.example.com/summarizeText",
   "model": "summarize.modelname",
   "length": "MEDIUM",
   "format": "PARAGRAPH",
   "temperature": 1.0
  }';

  output := dbms_vector_chain.utl_to_summary(input, json(params));
  dbms_output.put_line(output);
  if output is not null then
    dbms_lob.freetemporary(output);
  end if;
exception
  when OTHERS THEN
    DBMS_OUTPUT.PUT_LINE (SQLERRM);
    DBMS_OUTPUT.PUT_LINE (SQLCODE);
end;
/

End-to-end examples:

To run end-to-end example scenarios using this function, see Generate Summary.

Parent topic: DBMS_VECTOR_CHAIN