UTL_TO_EMBEDDINGおよびUTL_TO

UTL_TO_EMBEDDINGおよびUTL_TO_EMBEDDINGS

テキスト・ドキュメントおよびイメージから1つ以上のベクトル埋込みを生成するには、DBMS_VECTOR.UTL_TO_EMBEDDINGおよびDBMS_VECTOR.UTL_TO_EMBEDDINGSチェーン可能ユーティリティ関数を使用します。

用途

テキスト・ドキュメントおよびイメージから1つ以上のベクトル埋込みを自動的に生成します。

テキストからベクトルへ:

Oracle Databaseまたはサードパーティのサービス・プロバイダにアクセスすることで、テキストから埋込みへの変換を実行できます:
- サービス・プロバイダとしてのOracle Database (デフォルト設定):
  
  このAPIは、データベースにロードするONNX形式の埋込みモデルをコールします。
- サードパーティの埋込みモデル:
  
  このAPIは、選択したリモート・サービス・プロバイダ(Cohere、生成AI、Google AI、Hugging Face、OpenAIまたはVertex AI)またはローカル・サービス・プロバイダ(Ollama)に対してREST APIコールを実行します。
イメージからベクトルへ:

イメージから埋込みへの変換を実行することもできます。このAPIは、選択したイメージ埋込みモデルまたはVertex AIによるマルチモーダル埋込みモデルに対するRESTコールを実行します。現在、この操作でサポートされているサービス・プロバイダはVertex AIのみであることに注意してください。

警告:

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

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

構文

テキストからベクトルへ:

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;

イメージからベクトルへ:

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

データ

テキストからベクトルへ:

UTL_TO_EMBEDDINGは、テキスト・データ(テキスト文字列または小さいドキュメント)を含むCLOBとして入力を受け入れます。次に、テキストを1つの埋込み(VECTOR)に変換します。

UTL_TO_EMBEDDINGSは、チャンクの配列(VECTOR_ARRAY_T)を埋込みの配列(VECTOR_ARRAY_T)に変換します。

ノート:
データはCLOBまたはCLOBのVECTOR_ARRAY_Tですが、最大入力は4000文字です。大きい入力がある場合は、UTL_TO_CHUNKSを使用して、渡す前にデータを小さいチャンクに分割できます。
イメージからベクトルへ:

UTL_TO_EMBEDDINGは、イメージなどのメディア・ファイルのメディア・データを含むBLOBとして入力を受け入れます。次に、イメージ入力を1つの埋込み(VECTOR)に変換します。

生成された埋込みの出力には、次のものが含まれます:

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

説明は次のとおりです。

embed_idは、各埋込みのID番号を示します。
embed_dataは、埋込みに変換される入力テキストを示します。
embed_vectorは、生成されたベクトル表現を示します。

MODALITY

BLOB入力の場合、ベクトル化するコンテンツのタイプを指定します。サポートされている値はimageのみです。

PARAMS

使用するサービス・プロバイダに応じて、入力パラメータをJSON形式で指定します。

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

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

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

パラメータ説明

パラメータ	説明
`provider`	Oracle Databaseをプロバイダとして使用する場合は、`database` (デフォルト設定)を指定します。この設定を使用する場合は、ONNX形式の埋込みモデルをデータベースにロードする必要があります。
`model`	インポートしたONNX埋込みモデルをOracle Databaseに格納する際のユーザー指定の名前。 ONNX形式の埋込みモデルがない場合は、「事前トレーニング済モデルからONNX形式への変換」に示すステップを実行します。

provider

Oracle Databaseをプロバイダとして使用する場合は、database (デフォルト設定)を指定します。この設定を使用する場合は、ONNX形式の埋込みモデルをデータベースにロードする必要があります。

model

インポートしたONNX埋込みモデルをOracle Databaseに格納する際のユーザー指定の名前。

ONNX形式の埋込みモデルがない場合は、「事前トレーニング済モデルからONNX形式への変換」に示すステップを実行します。

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

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

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

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

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

パラメータ	説明
`provider`	この操作のためにアクセスするサードパーティ・サービス・プロバイダ。埋込みモデルにアクセスするために、指定したプロバイダに対してRESTコールが行われます。イメージ入力の場合は、`vertexai`を指定します。テキスト入力の場合は、次のいずれかの値を指定します: `cohere` `googleai` `huggingface` `ocigenai` `openai` `vertexai`
`credential_name`	次の形式の資格証明の名前: `schema.credential_name` 資格証明名には、REST APIコールを行うためのプロバイダにアクセスできるようにする認証資格証明が保持されます。まず、資格証明を作成および格納するために`DBMS_VECTOR.CREATE_CREDENTIAL`ヘルパー関数をコールして、資格証明をセットアップしてから、ここで資格証明書の名前を参照する必要があります。「CREATE_CREDENTIAL」を参照してください。
`url`	「サポートされているサードパーティ・プロバイダの操作およびエンドポイント」にリストされている、各RESTコールのサードパーティ・プロバイダ・エンドポイントのURL。
`model`	次の形式でのサードパーティ埋込みモデルの名前: `schema.model_name` スキーマを指定しない場合は、プロシージャ実行者のスキーマが使用されます。ノート: 生成AIの場合、サポートされているすべてのサードパーティ・モデルが「サポートされるサードパーティ・プロバイダの操作およびエンドポイント」にリストされています。正確な結果を得るには、選択したテキスト埋込みモデルがチャンク化に使用された語彙ファイルと一致するようにします。語彙ファイルを使用していない場合は、入力長がモデルのトークン制限内で定義されていることを確認してください。イメージの埋込みを取得するには、Vertex AIでサポートされている任意のイメージ埋込みモデルまたはマルチモーダル埋込みモデルを使用できます。マルチモーダル埋込みは、テキストやイメージなどの様々なモダリティからデータをベクトル化する手法です。マルチモーダル埋込みモデルを使用して埋込みを生成する場合は、同じモデルを使用して両方のタイプのコンテンツ(テキストとイメージ)をベクトル化してください。こうすることで、結果の埋込みが互換性を持ち、同じベクトル空間に配置されるため、類似検索で2つのモダリティを効果的に比較できます。
`transfer_timeout`	リクエストを完了するまでの最長待機時間。デフォルト値は`60`秒です。ビジー状態のWebサーバーに対しては、この値を増やすことができます。
`batch_size`	一度にリクエストするベクトルの最大数。たとえば、バッチ・サイズが`50`の場合、`100`個のチャンクが渡されると、このAPIは、それぞれが`50`個の文字列の配列で2つのリクエストを送信します。`30`個チャンクが渡された場合(定義したバッチ・サイズより小さい場合)、APIはそれらを単一のリクエストで送信します。 RESTコールの場合、入力のバッチを一度に送信する方が1コールごとに1つの入力をリクエストするよりも効率的です。バッチ・サイズを大きくするとパフォーマンスが向上しますが、特にプロバイダにレート制限がある場合は、バッチ・サイズを小さくすることでメモリーとデータの使用量を削減できることがあります。デフォルト値や最大許容値は、サードパーティ・プロバイダの設定によって異なります。
`max_count`	特定のサードパーティ・プロバイダに対してAPIをコールできる最大回数。整数nに設定すると、`max_count`によって、指定されたプロバイダのAPIの実行がn回を超えると停止します。これにより、一定の制限を超えてサードパーティのコールが誤って実行されることを防ぎます。たとえば、購入したサービス量を超過しないようにします。

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

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

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

パラメータ	説明
`input_type`	ベクトル化する入力のタイプ。

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

重要:

次の例は説明のための例です。使用するパラメータに関する正確な最新の情報については、サードパーティ・プロバイダのドキュメントを参照してください。
サポートされているすべてのRESTエンドポイントURLのリストは、「サポートされているサードパーティ・プロバイダの操作およびエンドポイント」を参照してください。
生成される埋込み結果は、埋込みモデルや浮動小数点精度に応じて、同じ入力と構成のリクエスト間で異なることがあります。ただし、ベクトル距離は類似するため、問合せには影響しません(また、意味的に正しい結果が得られます)。

Cohereの例:

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

生成AIの例:

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

Google AIの例:

{
  "provider"       : "googleai",
  "credential_name": "GOOGLEAI_CRED",
  "url"            : "https://googleapis.example.com/models/",
  "model"          : "embedding-001",
  "max_count"      : 500
}

Hugging Faceの例:

{
  "provider"       : "huggingface",
  "credential_name": "HF_CRED",
  "url"            : "https://api.huggingface.example.com/",
  "model"          : "sentence-transformers/all-MiniLM-L6-v2"
}

Ollamaの例:

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

OpenAIの例:

{
  "provider"       : "openai",
  "credential_name": "OPENAI_CRED",
  "url"            : "https://api.openai.example.com/embeddings",
  "model"          : "text-embedding-3-small"
}

OpenAI互換プロバイダの例:

ノート:

これは、LlamafileやvLLMなど、多くのOpenAI互換のサード・パーティ・プロバイダに対して構成を設定する方法の一例にすぎません。provider値にはopenaiを指定する必要がありますが、url値は、選択したサード・パーティ・プロバイダのRESTエンドポイントによって異なります。

資格証明を無効にするには、hostをlocalに設定します。サード・パーティ・プロバイダでモデル名(Ollama、vLLMなど)が必要な場合は、modelを目的のモデルに設定します。それ以外の場合は、modelをanyなどの任意の文字列に設定できます(Llamafileを使用する場合など)。

{
  "provider": "openai",
  "url": "http://localhost:8080/v1/chat/completions",
  "host": "local",
  "model": "any"
}

Vertex AIの例:

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

例

次のように、SELECT句でUTL_TO_EMBEDDING、およびFROM句でUTL_TO_EMBEDDINGSを使用できます。

UTL_TO_EMBEDDING:

生成AIを使用してテキストからベクトルへ:

次の例では、UTL_TO_EMBEDDINGを使用して、Hello worldを入力として埋込みを生成します。

ここでは、プロバイダに生成AIを指定してアクセスすることで、cohere.embed-english-v3.0モデルが使用されます。model値は、「サポートされるサードパーティ・プロバイダの操作およびエンドポイント」に示されているように、生成AIで使用する他のサポートされるモデルに置き換えることができます。

-- declare embedding parameters

var params clob;

begin
 :params := '
{ 
  "provider": "ocigenai",
  "credential_name": "OCI_CRED", 
  "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText",
  "model": "cohere.embed-english-v3.0",
  "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;

Vertex AIを使用してイメージからベクトルへ:

次の例では、UTL_TO_EMBEDDINGを使用して、Vertex AIのマルチモーダル埋込みモデルにアクセスして埋込みを生成します。

ここでは、入力はparrots.jpg、VEC_DUMPはparrots.jpgファイルを格納するローカル・ディレクトリで、モダリティはimageとして指定されます。

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

データベース内埋込みモデルを使用してテキストからベクトルへ:

次の例では、UTL_TO_EMBEDDINGを使用して、Oracle DatabaseにロードされたONNX形式の埋込みモデル(doc_model)をコールしてベクトル埋込みを生成します。

ここでは、プロバイダはdatabaseで、入力はhelloです。
```
var params clob; 
exec :params := '{"provider":"database", "model":"doc_model"}';

select dbms_vector.utl_to_embedding('hello', json(:params)) from dual;
```
詳細は、「Oracle Database内でのテキスト文字列から埋込みへの変換」を参照してください。
エンドツーエンドの例:

UTL_TO_EMBEDDINGを使用して様々なエンドツーエンドのシナリオ例を実行するには、「埋込みの生成」を参照してください。

UTL_TO_EMBEDDINGS:

データベース内埋込みモデルを使用してテキストからベクトルへ:

次の例では、UTL_TO_EMBEDDINGSを使用して、Oracle DatabaseにロードされたONNX形式の埋込みモデル(doc_model)をコールして埋込みの配列を生成します。

ここでは、プロバイダはdatabaseで、入力はdocumentation_tab表に格納されているPDFドキュメントです。このように、UTL_TO_EMBEDDINGSに渡す前に、まずUTL_TO_CHUNKSを使用してデータを小さいチャンクに分割します。
```
CREATE TABLE doc_chunks as
(select dt.id doc_id, et.embed_id, et.embed_data, to_vector(et.embed_vector) embed_vector
 from
   documentation_tab dt,
   dbms_vector.utl_to_embeddings(
       dbms_vector.utl_to_chunks(dbms_vector.utl_to_text(dt.data), json('{"normalize":"all"}')),
       json('{"provider":"database", "model":"doc_model"}')) t,
   JSON_TABLE(t.column_value, '$[*]' COLUMNS (embed_id NUMBER PATH '$.embed_id', embed_data VARCHAR2(4000) PATH '$.embed_data', embed_vector CLOB PATH '$.embed_vector')) et
);
```
詳細は、「データベースにアップロードされたベクトル埋込みモデルの使用によるSQLクイック・スタート」を参照してください。
エンドツーエンドの例:

UTL_TO_EMBEDDINGSを使用して様々なエンドツーエンドのシナリオ例を実行するには、「チャンク化と埋込みの実行」を参照してください。

親トピック: DBMS_VECTOR