UTL_TO_SUMMARY

テキスト・ドキュメントのサマリーを生成するには、DBMS_VECTOR_CHAIN.UTL_TO_SUMMARYチェーン可能ユーティリティ関数を使用します。

サマリーは、ドキュメント全体の内容を最もよく表す、ドキュメントの主な特徴を含む短くて簡潔な抽出です。サマリーは、指定した形式に基づいて自由形式の段落または箇条書きにすることができます。

用途

Oracle Databaseまたはサードパーティのサービス・プロバイダにアクセスして、テキストからサマリーへの変換を実行するには:

サービス・プロバイダとしてのOracle Database (デフォルト設定):

社内実装とOracle Databaseを使用します。Oracle Text PL/SQLプロシージャCTX_DOC.GISTを使用してドキュメントからサマリー(要旨)を抽出するために、Oracle Textが内部的に使用されます。
サードパーティの要約モデル:

選択したリモート・サービス・プロバイダ(Cohere、生成AI、Google AI、Hugging Face、OpenAIまたはVertex AI)またはローカル・サービス・プロバイダ(Ollama)に対してREST APIコールを実行します。

ノート:

現在、生成AIでサポートされているモデルおよびサマリー・エンドポイントが廃止されたため、UTL_TO_SUMMARYは生成AIでは機能しません。以降のリリースで使用可能になる予定です。

警告:

データベースの特定の機能により、たとえば、REST APIへのアクセスを容易にするJSON仕様を使用して、第三者によって個別に提供されるサービスにアクセスできる場合があります。

お客様によるこれらの機能の使用は、お客様自身の責任においてのみ行われ、お客様は、当該第三者サービスの使用に関連するあらゆる条件を遵守する責任を負います。第三者のサービスに関するその他の条件にかかわらず、お客様は、かかるデータベース機能の使用によって、そのリスクを受諾し、当該アクセスにより生じた一切の損害について、Oracleの責任または法的責任を明示的に除外することになります。

構文

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

データ

この関数は、プレーン・テキストの入力データ型をCLOBとして受け入れます。

入力ドキュメントのサマリーもCLOBとして返されます。

PARAMS

ドキュメントの要約に使用するサービス・プロバイダに応じて、要約パラメータをJSON形式で指定します。

プロバイダとしてOracle Databaseを使用する場合:

{
  "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>"
}

表12-28 データベース・プロバイダのパラメータの詳細

パラメータ	説明
`provider`	プロバイダとしてのOracle Databaseにアクセスする場合は、`database`を指定します(デフォルト設定)。Oracle Textで生成されたドキュメントの`gist`またはサマリーを利用します。
`glevel`	要約を表示するフォーマット: `SENTENCE` \| `S`: 文のリストとして `PARAGRAPH` \| `P`: 自由形式の段落
`numParagraphs`	要約のために選択されたドキュメントの段落(または文)の最大数。デフォルト値は`16`です。 `numParagraphs`パラメータは、このパラメータによって生成される要約のサイズが、`maxPercent`パラメータによって生成される要約のサイズよりも小さくなる場合にのみ使用されます。これは、この関数が常に最小サイズの要約を返すためです。
`maxPercent`	要約のために選択されたドキュメントの段落(または文)の最大数であり、ドキュメントの段落(または文)の合計に対する割合です。デフォルト値は`10`です。 `maxPercent`パラメータは、このパラメータによって生成される要約のサイズが、`numParagraphs`パラメータによって生成される要約のサイズよりも小さくなる場合にのみ使用されます。これは、この関数が常に最小サイズの要約を返すためです。
`num_themes`	生成するテーマ要約の数。たとえば、`10`を指定すると、この関数は上位10のテーマ要約を戻します。`0`または`NULL`を指定すると、この関数はドキュメント内のすべてのテーマを戻します。デフォルト値は`50`です。51以上のテーマがドキュメントに格納されている場合、概念階層が表示されるのは、トップ50のテーマのみです。
`language`	「サポートされる言語とデータ・ファイルの場所」にリストされている要約テキストの言語名。

次に例を示します。

{
  "provider"          : "database",
  "glevel"            : "sentence",
  "numParagraphs"     : 1
}

サードパーティ・プロバイダを使用している場合:

プロバイダに固有の追加の要約パラメータとともに、次のパラメータも設定します:

{
  "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>,
  "max_count": "<maximum calls to the AI service provider>",
  "<additional REST provider parameter>": "<REST provider parameter value>"
}

表12-29 サードパーティ・プロバイダのパラメータの詳細

パラメータ	説明
`provider`	要約を取得するためにアクセスするサードパーティ・サービス・プロバイダ。テキスト要約モデルにアクセスするために、指定したプロバイダに対してRESTコールが実行されます。次のいずれかの値を指定します。 `cohere` `googleai` `huggingface` `ocigenai` `openai` `vertexai`
`credential_name`	次の形式の資格証明の名前: `schema.credential_name` 資格証明名には、REST APIコールを行うためのプロバイダにアクセスできるようにする認証資格証明が保持されます。まず、資格証明を作成および格納するために`DBMS_VECTOR_CHAIN.CREATE_CREDENTIAL`ヘルパー関数をコールすることで資格証明をセットアップしてから、ここで資格証明書の名前を参照する必要があります。「CREATE_CREDENTIAL」を参照してください。
`url`	「サポートされているサードパーティ・プロバイダの操作およびエンドポイント」にリストされている、各RESTコールのサードパーティ・プロバイダ・エンドポイントのURL。
`model`	次の形式でのサードパーティ・テキスト要約モデルの名前: `schema.model_name` モデル名がスキーマ修飾されていない場合は、プロシージャ実行者のスキーマが使用されます。ノート: Generative AIの場合は、`schema.model_name`を指定する必要があります。生成AIでサポートされるすべてのサードパーティ・モデルは、「サポートされるサードパーティ・プロバイダの操作およびエンドポイント」にリストされています。
`transfer_timeout`	リクエストを完了するまでの最長待機時間。デフォルト値は`60`秒です。ビジー状態のWebサーバーに対しては、この値を増やすことができます。
`max_count`	特定のサードパーティ・プロバイダに対してAPIをコールできる最大回数。整数nに設定すると、`max_count`によって、指定されたプロバイダのAPIの実行がn回を超えると停止します。これにより、一定の制限を超えてサードパーティのコールが誤って実行されることを防ぎます。たとえば、購入したサービス量を超過しないようにします。

追加のサードパーティ・プロバイダのパラメータ:

オプションで、プロバイダ固有の追加パラメータを指定します。

表12-30 追加のRESTプロバイダのパラメータの詳細

パラメータ	説明
`length`	要約テキストの概算の長さ: `SHORT`: およそ2文まで `MEDIUM`: 3文から5文の間 `LONG`: 6文以上の文 `AUTO`: モデルによって入力サイズに基づいた長さが選択されますノート: Generative AIの場合は、この値を大文字で入力する必要があります。
`format`	要約を表示するフォーマット: `PARAGRAPH`: 自由形式の段落 `BULLETS`: 箇条書きノート: Generative AIの場合は、この値を大文字で入力する必要があります。
`temperature`	出力テキストの生成時に使用されるランダム性の度合い(`0.0-5.0`の範囲)。プロンプトに対して同じ出力を生成するには、`0`を使用します。そのプロンプトに対してランダムな新しいテキストを生成するには、temperatureを大きくします。デフォルトのtemperatureは`1`で、最大のtemperatureは`5`です。ノート: テキストを要約するには、まず温度を`0`に設定します。ランダムな結果が必要ない場合に推奨される温度値は、Generative AIの場合は`0.2`、Cohereの場合は`0`と`1`の間です。たとえば、この後に様々な要約を選択する予定がある場合は、より高い値を使用します。要約に高い温度を使用しないでください。高い温度を使用すると、モデルでハルシネーションが含まれている可能性もある創造的なテキストの生成が促進されるためです。
`extractiveness`	要約内の入力をどの程度再利用するか: `LOW`: 抽出性の低い要約は言い換えする傾向があります。 `HIGH`: 抽出性の高い要約は、文をそのまま再利用する傾向があります。ノート: Generative AIの場合は、この値を大文字で入力する必要があります。
`max_tokens`	出力テキスト内の最大トークン数。
`topP`	出力内のトークンの確率(`0.0–1.0`の範囲)。小さな値ほどランダム応答が少なくなり、大きな値ほどランダム応答が多くなります。
`candidateCount`	応答のバリエーション数(`1-4`の範囲)。
`maxOutputTokens`	応答ごとに生成するトークンの最大数。

ノート:

生成AIにlength、formatおよびextractivenessパラメータを指定する場合は、必ず大文字で値を入力してください。

すべてのサードパーティ・プロバイダの構成例を見てみましょう:

重要:

次の例は説明のための例です。使用する追加パラメータに関する正確で最新の情報については、サードパーティ・プロバイダのドキュメントを参照してください。
サポートされているすべてのRESTエンドポイントURLのリストは、「サポートされているサードパーティ・プロバイダの操作およびエンドポイント」を参照してください。

Cohereの例:

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

生成AIの例:

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

Google AIの例:

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

Hugging Faceの例:

{
  "provider"          : "huggingface",
  "credential_name"   : "HF_CRED",
  "url"               : "https://api.huggingface.example.co/models/",
  "model"             : "facebook/bart-large-cnn"
}

Ollamaの例:

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

OpenAIの例:

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

Vertex AIの例:

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

例

Oracle Databaseを使用したサマリーの生成:

この文では、プロバイダとしてdatabaseを指定します。ここでは、Oracle Text PL/SQLプロシージャCTX_DOC.GISTが内部的にコールされ、「トランザクション」に関する抽出のサマリーが生成されます。

-- select example

set serveroutput on

var params clob;
begin
  :params := '
{
  "provider": "database",
  "glevel": "sentence",
  "numParagraphs": 1
}';
end;
/

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": "database",
   "glevel": "sentence",
   "numParagraphs": 1
  }';

  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;
/

生成AIを使用したサマリーの生成:

これらの文は、プロバイダに生成AIを指定してアクセスすることで、「トランザクション」に関する抽出のサマリーを生成します。

ここでは、cohere.command-r-16kモデルが集計操作に使用されます。model値は、「サポートされるサードパーティ・プロバイダの操作およびエンドポイント」に示されているように、生成AIで使用する他のサポートされるモデルに置き換えることができます。

-- select example

var params clob;
begin
  :params := '
{  
 "provider": "ocigenai", 
 "credential_name": "OCI_CRED", 
 "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat", 
 "model": "cohere.command-r-16k",
 "temperature": "0.0",
 "extractiveness": "LOW"
}';
end;
/

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://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat",
   "model": "cohere.command-r-16k",
   "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;
/

エンドツーエンドの例:

この関数を使用してエンドツーエンドのシナリオ例を実行するには、「サマリーの生成」を参照してください。

親トピック: DBMS_VECTOR_CHAIN