216 DBMS_VECTOR

DBMS_VECTORパッケージは、ユーザー・データからのチャンクや埋込みの抽出、特定のプロンプトに対するテキストの生成、索引の正確性のレポートなど、Oracle AI Vector Searchでの一般的な操作をサポートするAPIを提供します。

これらの関数は、JSON形式で入力パラメータを受け入れます。

関連トピック

DBMS_VECTORサブプログラムの概要

この表は、DBMS_VECTORサブプログラムを示し、簡単に説明しています。

表216-1 DBMS_VECTORパッケージ・サブプログラム

サブプログラム 説明

ONNXモデルに関連するプロシージャ:

これらのプロシージャを使用すると、ONNXモデルをOracle Databaseにロードできます。また、そのONNXモデルを削除できます。

LOAD_ONNX_MODEL

ONNXモデルをデータベースにロードします
LOAD_ONNX_MODEL_CLOUD オブジェクト・ストレージからデータベースにONNXモデルをロードします

DROP_ONNX_MODELプロシージャ

ONNXモデルを削除します

チェーン可能ユーティリティ(UTL)関数:

これらの関数は、ベクトル・ユーティリティのPL/SQLパッケージ内のモジュール化された柔軟な関数のセットです。 これらを連鎖して、エンドツーエンドのデータ変換および類似検索操作を自動化できます。

UTL_TO_CHUNKS

データを小さな部分またはチャンクに分割します。

UTL_TO_EMBEDDINGおよびUTL_TO_EMBEDDINGS

データを1つ以上のベクトル埋込みに変換します

UTL_TO_GENERATE_TEXT

プロンプト(入力文字列)またはイメージに対するテキストを生成します

資格証明ヘルパー・プロシージャ:

これらのプロシージャを使用すると、データベース内で認証の資格証明を安全に管理できます。 RESTコールを行うためにサードパーティ・サービス・プロバイダへのアクセスを有効にするには、これらの資格証明が必要です。

CREATE_CREDENTIAL

資格証明の名前を作成します

DROP_CREDENTIAL

既存の資格証明名を削除します

データ・アクセス関数:

これらの関数を使用すると、データの取得、索引の作成、および単純な類似検索操作を実行できます。

CREATE_INDEX

ベクトル索引を作成します

REBUILD_INDEX

ベクトル索引の再構築します

GET_INDEX_STATUS

ベクトル索引作成のステータスを示します

ENABLE_CHECKPOINT

ベクトル索引ユーザーおよび索引名に対するチェックポイント機能を有効にします

DISABLE_CHECKPOINT

ベクトル索引ユーザーおよび索引名に対するチェックポイント機能を無効にします

INDEX_VECTOR_MEMORY_ADVISOR

ベクトル索引に必要なベクトル・メモリー・サイズを判断します

QUERY

類似性検索問合せを実行します

RERANK

より関連性の高い出力のために検索結果を並べ替えます

精度レポート関数:

これらの関数を使用すると、既存の検索索引の精度を判断し、過去のワークロードで実行された近似検索によって達成された精度値を取得できます。

INDEX_ACCURACY_QUERY

ベクトル索引の精度を検証します

INDEX_ACCURACY_REPORT

 近似検索によって達成された精度値を取得します

ノート:

DBMS_VECTORは、テキスト処理や要約操作をサポートしない軽量パッケージです。 そのため、UTL_TO_TEXTおよびUTL_TO_SUMMARYチェーン可能ユーティリティ関数とすべてのチャンカ・ヘルパー・プロシージャは、拡張DBMS_VECTOR_CHAINパッケージ内でのみ使用できます。

CREATE_CREDENTIAL

ユーザー認証の詳細をOracle Databaseに格納するための資格証明名を作成するには、DBMS_VECTOR.CREATE_CREDENTIAL資格証明ヘルパー・プロシージャを使用します。

用途

データベース内で認証の資格証明を安全に管理することが目的です。 こうした資格証明は、Cohere、Google AI、Hugging Face、Oracle Cloud Infrastructure (OCI) Generative AI、OpenAI、Vertex AIなどから選択したサードパーティ・サービス・プロバイダへのREST APIコール時にアクセスを可能にするために必要になります。

資格証明名は、ユーザー名、パスワード、アクセス・トークン、秘密キー、指紋などの認証パラメータを保持します。

Oracle Databaseをサービス・プロバイダとして使用している場合は、資格証明を作成する必要はありません。

警告:

データベースの特定の機能により、たとえばREST APIへのアクセスを容易にするJSON仕様を使用することで、サードパーティによって個別に提供されるサービスにアクセスできることもあります。

こうした機能の使用は、お客様自身の責任においてのみ行われ、お客様は当該のサードパーティ・サービスの使用に関連するあらゆる利用規約を遵守する責任を負います。 サードパーティ・サービスに関するその他の利用規約にかかわらず、こうしたデータベース機能を使用することは、お客様がそのリスクを受け入れ、そうしたアクセスにより生じた一切の損害についてOracleの責任または法的責任を明示的に排除することで成立します。

構文

DBMS_VECTOR.CREATE_CREDENTIAL (
    CREDENTIAL_NAME     IN VARCHAR2,
    PARAMS              IN JSON DEFAULT NULL
);

CREDENTIAL_NAME

認証パラメータを保持するために作成する資格証明の名前を指定します。

PARAMS

選択したサービス・プロバイダに基づいて、認証パラメータをJSON形式で指定します。

Generative AIには、次の認証パラメータが必要です: 
{ 
"user_ocid"       : "<user ocid>",
"tenancy_ocid"    : "<tenancy ocid>",
"compartment_ocid": "<compartment ocid>",
"private_key"     : "<private key>",
"fingerprint"     : "<fingerprint>" 
}
Cohere、Google AI、Hugging Face、OpenAIおよびVertex AIには、次の認証パラメータが必要です: 
{ "access_token": "<access token>" }

表216-2 パラメータ詳細

パラメータ 説明

user_ocid

OCIコンソールのユーザーの詳細ページにリストされている、ユーザーのOracle Cloud Identifier (OCID)。

tenancy_ocid

OCIコンソールのテナンシの詳細ページにリストされている、テナンシのOCID。

compartment_ocid

OCIコンソールのコンパートメント情報ページにリストされている、コンパートメントのOCID。

private_key

OCI秘密キー。

ノート: 生成された秘密キーは次のように表示されます:
-----BEGIN RSA PRIVATE KEY-----
<private key string>
-----END RSA PRIVATE KEY-----
(BEGINとENDの行を除く) <private key string>値を単一行または複数行として渡します。

fingerprint

OCIコンソールのAPIキーの下のユーザーの詳細ページにリストされている、OCIプロファイル・キーの指紋。

access_token

サードパーティ・サービス・プロバイダから取得したアクセス・トークン。

必要な権限

このAPIをコールするには、CREATE CREDENTIAL権限が必要です。

例

  • Generative AIの場合:
    declare
  jo json_object_t;
begin
  jo := json_object_t();
  jo.put('user_ocid','ocid1.user.oc1..aabbalbbaa1112233aabbaabb1111222aa1111bb');
  jo.put('tenancy_ocid','ocid1.tenancy.oc1..aaaaalbbbb1112233aaaabbaa1111222aaa111a');
  jo.put('compartment_ocid','ocid1.compartment.oc1..ababalabab1112233abababab1111222aba11ab');
  jo.put('private_key','AAAaaaBBB11112222333...AAA111AAABBB222aaa1a/+');
  jo.put('fingerprint','01:1a:a1:aa:12:a1:12:1a:ab:12:01:ab:a1:12:ab:1a');
  dbms_vector.create_credential(
    credential_name   => 'OCI_CRED',
    params            => json(jo.to_string));
end;
/
  • Cohereの場合:
    declare
  jo json_object_t;
begin
  jo := json_object_t();
  jo.put('access_token', 'A1Aa0abA1AB1a1Abc123ab1A123ab123AbcA12a');
  dbms_vector.create_credential(
    credential_name   => 'COHERE_CRED',
    params            => json(jo.to_string));
end;
/

エンドツーエンドの例:

この手順を使用してエンドツーエンドのサンプル・シナリオを実行する場合は、LLMを利用するAPIを使用したサマリーおよびテキストの生成を参照してください。

CREATE_INDEX

ベクトル索引を作成するには、DBMS_VECTOR.CREATE_INDEXプロシージャを使用します。

用途

Hierarchical Navigable Small World (HNSW)ベクトル索引やInverted File Flat (IVF)ベクトル索引などのベクトル索引を作成します。

構文

DBMS_VECTOR.CREATE_INDEX (
    idx_name                    IN VARCHAR2,
    table_name                  IN VARCHAR2,
    idx_vector_col              IN VARCHAR2,
    idx_include_cols            IN VARCHAR2 DEFAULT NULL,
    idx_partitioning_scheme     IN VARCHAR2 default 'LOCAL',
    idx_organization            IN VARCHAR2,
    idx_distance_metric         IN VARCHAR2 DEFAULT COSINE,
    idx_accuracy                IN NUMBER DEFAULT 90,
    idx_parameters              IN CLOB,
    idx_parallel_creation       IN NUMBER DEFAULT 1
);

パラメータ

パラメータ 説明

idx_name

作成する索引の名前。

table_name

索引を作成する表。

idx_vector_col

索引を作成するVector列。
idx_include_cols

索引でカバーされる列名のカンマ区切りリスト。

idx_partitioning_scheme

IVF索引のパーティション化スキーム:

  • GLOBAL

  • LOCAL

IVF索引は、パーティション表のグローバル索引とローカル索引の両方をサポートします。 デフォルトでは、これらの索引は重心によってグローバルにパーティション化されます。 ローカルIVF索引を作成することを選択できます。これにより、実表のパーティションまたはサブパーティションと索引パーティションの間に1対1の関係が提供されます。

これらのパーティション化スキームの詳細は、「Inverted File Flatベクトル索引のパーティション化スキーム」を参照してください。

idx_organization

索引構成:

  • NEIGHBOR PARTITIONS

  • INMEMORY NEIGHBOR GRAPH

これらの組織タイプの詳細は、「ベクトル索引の様々なカテゴリの管理」を参照してください。

idx_distance_metric

ベクトル間の距離を計算するために使用される距離メトリックまたは数学的関数:

  • COSINE (デフォルト)
  • MANHATTAN
  • HAMMING
  • JACCARD
  • DOT
  • EUCLIDEAN
  • L2_SQUARED
  • EUCLIDEAN_SQUARED

これら各メトリックの詳細は、「ベクトル距離関数および演算子」を参照してください。

idx_accuracy

近似検索問合せの実行時に目指す近似検索の実行のターゲット精度。

ベクトル索引を使用した近似類似検索の理解で説明されているように、使用する索引タイプに応じて、パーセント値を指定するか、内部パラメータ値を指定することによって、デフォルト以外のターゲット精度値を指定できます。

  • HNSW近似検索の場合:

    HNSW近似検索の場合、ターゲット精度のパーセント値を指定して、検索の精査で考慮される候補の数に影響を与えることができます。 これは、アルゴリズムによって自動的に計算されます。 値が100の場合は、完全検索と同様の結果となる傾向がありますが、システムでは引き続き索引が使用され、完全検索は実行されません。 オプティマイザでは、問合せの述語がある場合は索引を使用する方が高速になる可能性があるため、引き続き索引を使用することが選択されることがあります。 ターゲット精度のパーセンテージ値を指定するかわりに、EFSEARCHパラメータを指定して、索引の精査中に考慮される特定の最大候補数を指定できます。 その数値が大きいほど、精度が高くなります。

    詳細は、「Hierarchical Navigable Small World索引の理解」を参照してください。

  • IVF近似検索の場合:

    IVF近似検索の場合、ターゲット精度のパーセント値を指定して、検索の精査に使用されるパーティションの数に影響を与えることができます。 これは、アルゴリズムによって自動的に計算されます。 値が100の場合は、完全検索が実行される傾向がありますが、システムでは引き続き索引が使用され、完全検索は実行されません。 オプティマイザでは、問合せの述語がある場合は索引を使用する方が高速になる可能性があるため、引き続き索引を使用することが選択されることがあります。 ターゲット精度のパーセンテージ値を指定するかわりに、NEIGHBOR PARTITION PROBESパラメータを指定して、検索によって精査されるパーティションの最大数を指定できます。 その数値が大きいほど、精度が高くなります。

    詳細は、「Inverted File Flatベクトル索引の理解」を参照してください。

idx_parameters

ベクトル索引のタイプと関連パラメータ。

索引付けパラメータをJSON形式で指定します:

  • HNSW索引の場合:

    • type: 作成するベクトル索引のタイプ(HNSW)

    • neighbors: HNSWグラフでベクトル当たりに許可される最大接続数

    • efConstruction: 挿入時に検索の各ステップで考慮される最も近いベクトル候補の最大数

    例:

    {
    "type"           : "HNSW", 
    "neighbors"      : 3, 
    "efConstruction" : 4
}

    これらのパラメータの詳細は、「Hierarchical Navigable Small World索引の構文およびパラメータ」を参照してください。

  • IVF索引の場合:

    • type: 作成するベクトル索引のタイプ(IVF)

    • partitions: ベクトル空間を分割する近傍パーティションまたはクラスタ

    例:

    {
    "type"       : "IVF",
    "partitions" : 5
}

    これらのパラメータの詳細は、「Inverted File Flat索引の構文およびパラメータ」を参照してください。

idx_parallel_creation

索引作成に使用されるパラレル・スレッドの数。

例

  • HNSW索引のneighborsとefConstructionを指定します:

    dbms_vector.create_index(
    'v_hnsw_01', 
    'vpt01', 
    'EMBEDDING', 
     NULL, 
     NULL, 
    'INMEMORY NEIGHBOR GRAPH', 
    'EUCLIDEAN', 
     95, 
    '{"type" : "HNSW", "neighbors" : 3, "efConstruction" : 4}');

  • IVF索引のパーティション数を指定します:

    dbms_vector.create_index(
    'V_IVF_01', 
    'vpt01', 
    'EMBEDDING', 
     NULL,
     NULL, 
    'NEIGHBOR PARTITIONS', 
    'EUCLIDEAN', 
     95, 
    '{"type" : "IVF", "partitions" : 5}');

DISABLE_CHECKPOINT

DISABLE_CHECKPOINTプロシージャは、特定のHierarchical Navigable Small World (HNSW)索引ユーザーおよびHNSW索引名に対するチェックポイント機能を無効にするために使用します。 この操作は、HNSW索引に対する古いチェックポイントのすべてをパージします。 また、HNSWグラフのリフレッシュの一環として今後のチェックポイントの作成も無効にします。

構文

DBMS_VECTOR.DISABLE_CHECKPOINT('INDEX_USER',['INDEX_NAME']);

INDEX_USER

HNSWベクトル索引所有者のユーザー名を指定します。

INDEX_NAME

チェックポイント機能を無効にするHNSWベクトル索引の名前を指定します。

INDEX_NAME句はオプションです。 索引名を指定していないと、このプロシージャは、指定されたユーザーのすべてのHNSWベクトル索引のチェックポイント機能を無効にします。

例

  • 索引名と索引ユーザーの両方を使用する場合:

    DBMS_VECTOR.DISABLE_CHECKPOINT('VECTOR_USER','VIDX1');

  • 索引ユーザーのみを使用する場合:

    DBMS_VECTOR.DISABLE_CHECKPOINT('VECTOR_USER');

関連トピック

DROP_CREDENTIAL

データ・ディクショナリから既存の資格証明名を削除するには、DBMS_VECTOR.DROP_CREDENTIAL資格証明ヘルパー・プロシージャを使用します。

構文

DBMS_VECTOR.DROP_CREDENTIAL (
    CREDENTIAL_NAME      IN VARCHAR2
);

CREDENTIAL_NAME

削除する資格証明の名前を指定します。

例

  • Generative AIの場合:
    exec dbms_vector.drop_credential('OCI_CRED');
  • Cohereの場合:
    exec dbms_vector.drop_credential('COHERE_CRED');

ENABLE_CHECKPOINT

ENABLE_CHECKPOINTプロシージャは、特定のHierarchical Navigable Small World (HNSW)索引ユーザーおよびHNSW索引名に対するチェックポイント機能を有効にするために使用します。

ノート:

  • このプロシージャでは、索引によるチェックポイントの作成のみを許可します。 チェックポイントは、次回のHNSWグラフのリフレッシュの一環として作成されます。

  • デフォルトでは、HNSWチェックポイントは有効になっています。 必要に応じて、DBMS_VECTOR.DISABLE_CHECKPOINTプロシージャを使用して無効にできます。

構文

DBMS_VECTOR.ENABLE_CHECKPOINT('INDEX_USER',['INDEX_NAME']);

INDEX_USER

HNSWベクトル索引所有者のユーザー名を指定します。

INDEX_NAME

チェックポイント機能を有効にするHNSWベクトル索引の名前を指定します。

INDEX_NAME句はオプションです。 索引名を指定していないと、このプロシージャは、指定されたユーザーのすべてのHNSWベクトル索引のチェックポイント機能を有効にします。

例

  • 索引名と索引ユーザーの両方を使用する場合:

    DBMS_VECTOR.ENABLE_CHECKPOINT('VECTOR_USER','VIDX1');

  • 索引ユーザーのみを使用する場合:

    DBMS_VECTOR.ENABLE_CHECKPOINT('VECTOR_USER');

関連トピック

DROP_ONNX_MODELプロシージャ

このプロシージャは指定したONNXを削除します。

構文

DBMS_VECTOR.DROP_ONNX_MODEL (model_name IN VARCHAR2,
                                  force      IN BOOLEAN DEFAULT FALSE);

パラメータ

表216-3 DROP_ONNX_MODELプロシージャのパラメータ

パラメータ 説明

model_name

[schema_name.]model_name形式の機械学習のONNXモデル名。 スキーマを指定しない場合は、ユーザー独自のスキーマが使用されます。

force

無効な場合でも、機械学習のONNXモデルの削除を強制実行します。 ONNXモデルは、モデルの作成プロセスが重大なシステム・エラーで中断された場合に無効になることがあります。

使用上のノート

ONNXモデルを削除するには、そのモデルの所有者であるか、またはDB_DEVELOPER_ROLEが必要です。

例

次のコマンドを使用すると、スキーマに存在するdoc_modelという名前の有効なONNXモデルを削除できます。 

BEGIN
  DBMS_VECTOR.DROP_ONNX_MODEL(model_name => 'doc_model');
END;
/

GET_INDEX_STATUS

GET_INDEX_STATUSプロシージャは、ベクトル索引作成のステータスを問い合せるために使用します。

構文

DBMS_VECTOR.GET_INDEX_STATUS ('USER_NAME','INDEX_NAME');

USER_NAME

ベクトル索引所有者のユーザー名を指定します。

INDEX_NAME

ベクトル索引の名前を指定します。 Hierarchical Navigable Small World (HNSW)索引とInverted File Flat (IVF)索引の両方について、索引作成ステータスの問合せができます。

使用上のノート

  • GET_INDEX_STATUSプロシージャは、ベクトル索引の作成時にのみ使用できます。

  • Percentage値は、Hierarchical Navigable Small World (HNSW)索引の場合にのみ出力されます(Inverted File Flat (IVF)索引の場合には出力されません)。

  • DB_DEVELOPER_ROLE権限とともに、VECSYS.VECTOR$INDEX$BUILD$表への読取りアクセス権が必要です。

  • 次の問合せを使用すると、すべての補助表を表示できます: 

    select IDX_AUXILIARY_TABLES from vecsys.vector$index;

    • HNSW索引の場合:

      rowid_vid_mapには、行IDとベクトルIDの間のマッピングが格納されます。shared_journal_change_logには、HNSWグラフにまだ組み込まれていないDMLの変更が格納されます。

    • IVF索引の場合:

      centroidsには、各重心の位置が格納されます。centroid_partitionsには、各ベクトルの最適な重心が格納されます。

  • HNSWベクトル索引のStageに示される値は、次のとおりです:

    値 説明

    HNSW Index Initialization

    HNSWベクトル索引作成の初期化フェーズ

    HNSW Index Auxiliary Tables Creation

    HNSW近傍グラフ・ベクトル索引の内部補助表の作成

    HNSW Index Graph Allocation

    HNSWグラフ用のベクトル・メモリー・プールからのメモリーの割当て

    HNSW Index Loading Vectors

    ベクトル・プール・メモリーへの実表ベクトルのロード

    HNSW Index Graph Construction

    以前にロードされたベクトルによる多層HNSWグラフの作成

    HNSW Index Creation Completed

    HNSWベクトル索引の作成完了

  • IVFベクトル索引のStageに示される値は、次のとおりです:

    値 説明

    IVF Index Initialization

    IVFベクトル索引作成の初期化フェーズ

    IVF Index Centroids Creation

    実表ベクトルのサンプルでクラスタ・セントロイドを計算するK平均クラスタリング・フェーズ

    IVF Index Centroid Partitions Creation

    実表ベクトルの重心の割当てフェーズ

    IVF Index Creation Completed

    IVFベクトル索引の作成完了

例

exec DBMS_VECTOR.GET_INDEX_STATUS('VECTOR_USER','VIDX_HNSW');

Index objn: 74745 
Stage: HNSW Index Loading Vectors 
Percentage: 80%

INDEX_ACCURACY_QUERY

特定の問合せベクトル、上位Kおよびターゲット精度についてベクトル索引の精度を検証するには、DBMS_VECTOR.INDEX_ACCURACY_QUERY関数を使用します。

構文

DBMS_VECTOR.INDEX_ACCURACY_QUERY (
    OWNER_NAME         IN VARCHAR2,
    INDEX_NAME         IN VARCHAR2,
    QV                 IN VECTOR,
    TOP_K              IN NUMBER,
    TARGET_ACCURACY    IN NUMBER
) return VARCHAR2;

DBMS_VECTOR.INDEX_ACCURACY_QUERY (
    OWNER_NAME         IN VARCHAR2, 
    INDEX_NAME         IN VARCHAR2,
    QV                 IN VECTOR,
    TOP_K              IN NUMBER,
    QUERY_PARAM        IN JSON
) return VARCHAR2;

パラメータ

表216-4 DBMS_VECTORのINDEX_ACCURACY_QUERY (IN)パラメータ

パラメータ 説明
owner_name

ベクトル索引の所有者の名前。
index_name

ベクトル索引の名前。
qv

問合せベクトルを指定します。
top_k

精度計算のtop_k値。

target_accuracy

ベクトル索引のターゲット精度値。

ベクトル索引の精度を判断する方法の詳細は、「Oracle Database AI Vector Searchユーザーズ・ガイド」の索引精度レポートを参照してください。

INDEX_ACCURACY_REPORT

DBMS_VECTOR.INDEX_ACCURACY_REPORT関数を使用すると、過去のワークロードから、特定のベクトル索引を使用した近似検索で得られた精度値を特定の期間取得できます。

構文

DBMS_VECTOR.INDEX_ACCURACY_REPORT (
    OWNER_NAME         IN VARCHAR2,
    INDEX_NAME         IN VARCHAR2,
    START_TIME         IN TIMESTAMP WITH TIME ZONE,
    END_TIME           IN TIMESTAMP WITH TIME ZONE
) return NUMBER;

パラメータ

表216-5 DBMS_VECTORのINDEX_ACCURACY_REPORT (IN)パラメータ

パラメータ 説明
owner_name

ベクトル索引の所有者の名前。
index_name

ベクトル索引の名前。
start_time

精度計算の対象とする問合せベクターの取得開始時刻を指定します。 NULL start_timeは、過去24時間に取得した問合せベクトルを使用します。

end_time

精度計算の対象とする問合せベクトルの最終時点を指定します。 NULL end_timeは、start_timeから現在の時刻までに取得された問合せベクトルを使用します。

ベクトル索引の精度を判断する方法の詳細は、「Oracle Database AI Vector Searchユーザーズ・ガイド」の索引精度レポートを参照してください。

INDEX_VECTOR_MEMORY_ADVISOR

INDEX_VECTOR_MEMORY_ADVISORプロシージャは、特定のベクトル索引に必要なベクトル・メモリー・サイズを判断するために使用します。 これは、シミュレートされた各ベクトル・メモリー・サイズに適合する索引の数を評価する際に役立ちます。

構文

  • ベクトル索引に格納するベクトル・ディメンションの数とタイプを使用する場合。 

    DBMS_VECTOR.INDEX_VECTOR_MEMORY_ADVISOR(
    INDEX_TYPE        IN    VARCHAR2, 
    NUM_VECTORS       IN    NUMBER, 
    DIM_COUNT         IN    NUMBER, 
    DIM_TYPE          IN    VARCHAR2, 
    PARAMETER_JSON    IN    CLOB, 
    RESPONSE_JSON     OUT   CLOB);

  • ベクトル索引を作成する表とベクトル列を使用する場合: 

    DBMS_VECTOR.INDEX_VECTOR_MEMORY_ADVISOR(
    TABLE_OWNER        IN    VARCHAR2, 
    TABLE_NAME         IN    VARCHAR2, 
    COLUMN_NAME        IN    VARCHAR2, 
    INDEX_TYPE         IN    VARCHAR2, 
    PARAMETER_JSON     IN    CLOB, 
    RESPONSE_JSON      OUT   CLOB);

表216-6 構文の詳細: INDEX_VECTOR_MEMORY_ADVISOR

パラメータ 説明

INDEX_TYPE

ベクトル索引のタイプ:

  • IVF: Inverted File Flat (IVF)ベクトル索引の場合

  • HNSW: Hierarchical Navigable Small World (HNSW)ベクトル索引の場合

NUM_VECTORS

ベクトル索引の作成に使用するベクトルの数。

DIM_COUNT

NUMBERとして、ベクトルのディメンションの数。

DIM_TYPE

ベクトルのディメンションのタイプ。 使用可能な値は次のとおりです。

  • FLOAT16

  • FLOAT32

  • FLOAT64

  • INT8

TABLE_OWNER

ベクトル索引を作成する表の所有者名。

TABLE_NAME

ベクトル索引を作成する表の名前。

COLUMN_NAME

ベクトル索引を作成するベクトル列の名前。

PARAMETER_JSON

JSON形式の入力パラメータ。 次のいずれかの形式のみを指定できます:

  • PARAMTER_JSON=>{"accuracy":value}

  • INDEX_TYPE=>IVF, parameter_json=>{"neighbor_partitions":value}

  • INDEX_TYPE=>HNSW, parameter_json=>{"neighbors":value}

ノート: accuracyの値は、neighbor_partitionsまたはneighborsとともには指定できません。

RESPONSE_JSON

JSON形式のレスポンス文字列。

例

  • パラメータ・リストの近傍を使用する場合: 

    SET SERVEROUTPUT ON;
DECLARE
    response_json CLOB;
BEGIN
    DBMS_VECTOR.INDEX_VECTOR_MEMORY_ADVISOR(
        INDEX_TYPE=>'HNSW', 
        NUM_VECTORS=>10000, 
        DIM_COUNT=>768, 
        DIM_TYPE=>'FLOAT32', 
        PARAMETER_JSON=>'{"neighbors":32}', 
        RESPONSE_JSON=>response_json);
END;
/

    結果:

    Suggested vector memory pool size: 59918628 Bytes

  • パラメータ・リストの精度を使用する場合:

    SET SERVEROUTPUT ON;
DECLARE
    response_json CLOB;
BEGIN
    DBMS_VECTOR.INDEX_VECTOR_MEMORY_ADVISOR(
        INDEX_TYPE=>'HNSW', 
        NUM_VECTORS=>10000, 
        DIM_COUNT=>768, 
        DIM_TYPE=>'FLOAT32', 
        PARAMETER_JSON=>'{"accuracy":90}', 
        RESPONSE_JSON=>response_json); 
END;
/

    結果:

    Suggested vector memory pool size: 53926765 Bytes

  • ベクトル索引を作成する表とベクトル列を使用する場合:

    SET SERVEROUTPUT ON;
DECLARE
    response_json CLOB;
BEGIN
    DBMS_VECTOR.INDEX_VECTOR_MEMORY_ADVISOR(
        'VECTOR_USER', 
        'VECTAB', 
        'DATA_VECTOR', 
        'HNSW', 
        RESPONSE_JSON=>response_json);
END;
/

    結果の例:

    Using default accuracy: 90% 
Suggested vector memory pool size: 76396251 Bytes

関連トピック

LOAD_ONNX_MODEL

この手順では、ONNXモデルをデータベースにロードできます。

構文

DBMS_VECTOR.LOAD_ONNX_MODEL (
     directory  VARCHAR2,
     file_name   VARCHAR2,
     model_name  VARCHAR2,
     metadata   JSON);
DBMS_VECTOR.LOAD_ONNX_MODEL(
model_name  IN  VARCHAR2,
model_data  IN  BLOB,
metadata    IN  JSON);

パラメータ

表216-7 LOAD_ONNX_MODELプロシージャのパラメータ

パラメータ 説明

directory

データ・ダンプのディレクトリ名。 たとえば、DM_DUMPです。

file_name

ONNXモデルの名前を指定するVARCHAR2型のパラメータ。

model_name

[schema_name.]model_nameの形式のモデル名。 スキーマを指定しない場合は、ユーザー独自のスキーマが使用されます。

model_data

これはモデルのONNX表現を保持するBLOBです。 このBLOBには、ONNXファイルに格納されているものと同じバイト・シーケンスが含まれています。

metadata

 モデルを記述するメタデータのJSONによる記述。 このメタデータには、モデルでサポートされている機械学習関数を少なくとも記述する必要があります。 モデルのメタデータ・パラメータの詳細は、「ONNXモデルのJSONメタデータ・パラメータ」を参照してください。

例

次の例は、DBMS_VECTOR.LOAD_ONNX_MODELプロシージャを使用したコード・スニペットを示しています。 完全なステップバイステップの例は、ONNXモデルのインポートおよび埋込みの生成で説明しています。 

EXECUTE DBMS_VECTOR.LOAD_ONNX_MODEL(
	'DM_DUMP', 
	'my_embedding_model.onnx', 
	'doc_model', 
	JSON('{"function" : "embedding", "embeddingOutput" : "embedding", "input": {"input": ["DATA"]}}'));
DBMS_VECTOR.LOAD_ONNX_MODEL('my_embedding_model.onnx',
                                             :blob_bind_variable, 
                                              JSON('{"function" : "embedding", 
                                                     "embeddingOutput" : "embedding" ,
                                                      "input":{"input": ["DATA"]}}'));

BLOB変数を定義し、LOAD_ONNX_MODELプロシージャで使用する方法を示す完全な例として、次のものがあります: 

CREATE OR REPLACE MY_LOAD_EMBEDDING_MODEL(embedding_model_name VARCHAR2, onnx_blob BLOB) IS 
BEGIN
DBMS_VECTOR.LOAD_ONNX_MODEL(embedding_model_name,
                            onnx_blob, 
                            JSON('{"function" : "embedding", 
                                   "embeddingOutput" : "embedding" ,
                                   "input":{"input": ["DATA"]}}'));
END;
/

使用上のノート

モデルの名前は、次のような他の機械学習モデルで使用されるものと同じ制限に従います。

  • スキーマ名を指定する場合は、128文字に制限されます。
  • モデル名は123文字に制限されており、引用符なしの識別子のルールに従う必要があります。名前に使用できるのは、英数字、アンダースコア(_)、ドル記号($)およびシャープ記号(#)のみです。 最初の文字は、英字にする必要があります。
  • モデルのサイズは1GBに制限されます。
  • モデルは外部イニシャライザに依存しないようにします。 イニシャライザおよびその他のONNXの概念の詳細は、https://onnx.ai/onnx/intro/concepts.htmlを参照してください。

  • Pythonユーティリティによって準備されるモデルの入出力属性には、デフォルトの入力名および出力名があります。 これらのモデルは、JSONパラメータなしでロードできます。 例: 

    EXECUTE DBMS_VECTOR.LOAD_ONNX_MODEL('DM_DUMP', 'my_embedding_model.onnx', 'doc_model'));

参照:

機械学習タスクにONNXモデルを使用する例については、『Oracle Machine Learning for SQLユーザーズ・ガイド』を参照してください
ONNXモデル用のJSONメタデータ・パラメータ

IMPORT_ONNX_MODEL (DBMS_DATA_MINING)、 LOAD_ONNX_MODEL (DBMS_VECTOR)またはLOAD_ONNX_MODEL_CLOUD (DBMS_VECTOR)プロシージャを使用してモデルをインポートする場合は、JSONパラメータとしてメタデータを指定します。

パラメータ

フィールド 値タイプ 説明
function 文字列

regression、classification、clusteringまたはembeddingを指定します。 これは必須の設定です。

ノート: モデルのインポート時に必要なJSONパラメータは、機械学習機能のみです。

input なし モデル入力のマッピングを指定します。 詳細は、使用方法の入力に関する項を参照してください。
regressionOutput 文字列 回帰結果を格納する回帰モデル出力の名前。 出力は、サポートされている回帰出力タイプのサポートされるシェイプのテンソルであることが想定されます。 詳細は、使用方法の出力に関する項を参照してください。
classificationProbOutput 文字列 確率を格納する分類モデル出力の名前。 出力は、サポートされているシェイプのfloat型(幅32/64)のテンソル値である必要があります。 使用方法の「出力確率の自動正規化」を参照してください。
clusteringDistanceOutput 文字列 距離を格納するクラスタリング・モデル出力の名前。 出力は、サポートされているシェイプのfloat型(幅16/32/64)です。
clusteringProbOutput 文字列 確率を格納するクラスタリング・モデル出力の名前。 出力は、サポートされているシェイプのfloat型(幅16/32/64)です。
classificationLabelOutput 文字列

ラベル情報を保持するモデル出力の名前。

分類のラベルを指定するための次のメタデータ・パラメータがあります。

  • labels: JSONメタデータで直接ラベルを指定します
  • classificationLabelOutput: ラベルを提供するモデル出力を指定します

このパラメータに値を指定しない場合、またはモデルの機能が分類でない場合は、エラーが発生します。

ユーザーは、ラベル情報を保持するモデル出力にclassificationLabelOutputを設定することで、モデルのラベルを直接使用するように指定できます。 ラベル情報を保持するテンソル出力は、クラスの数と同じサイズで、整数型または文字列型である必要があります。 ラベルを保持するテンソルが文字列型の場合、PREDICTION演算子の戻り型はVARCHAR2です。 ラベルを保持するテンソルが整数型の場合、PREDICTION演算子の戻り型はNUMBERです。

normalizeProb 文字列 出力確率の自動正規化について記述します。 使用方法の「出力確率の自動正規化」を参照してください。
labels なし

分類に使用されるラベル。

カスタム・ラベルを使用する場合は、JSONメタデータのlabelsフィールドを使用してラベルを指定します。 このフィールドは、クラス数と同じ長さの配列に設定できます。 クラスiのラベルは、ラベル配列の索引iに格納する必要があります。 文字列の配列を使用する場合、PREDICTION演算子の戻り型はVARCHAR2です。 ユーザーが指定する文字列ラベルのサイズは、4000バイトを超えないようにしてください。 数値の配列を使用する場合、PREDICTION演算子の戻り型はNUMBERです。

ラベルまたはclassificationLabelOutputを指定しない場合、クラスは1からNの範囲の整数で識別されます。Nはクラスの数です。 この場合、PREDICTION演算子の戻り型はNUMBERです。

embeddingOutput 文字列 生成された埋込みを保持するモデル出力。
suitableDistanceMetrics 文字列 モデルに適した距離メトリックの名前の配列。 名前は、Oracle VECTOR_DISTANCE演算子に使用される距離メトリックの名前である必要があります。 サポートされている距離メトリックを確認するには、「ベクトル距離メトリック」を参照してください。

このパラメータは情報提供のみを目的としています。
normalization ブール ブール値は、正規化が出力ベクトルに適用されるかどうかを示します。 値1は、正規化が適用されることを意味します。 正規化は、標準または長さが1になるように埋込みベクトルを変換するプロセスです。 正規化されたベクトルでは方向が維持されますが、長さは1になります。 結果のベクトルは、多くの場合、単位ベクトルと呼ばれます。
maxSequenceLength 数値 モデルにとって意味のあるトークン(入力)シーケンスの最大長。 このパラメータは、モデルが処理する各入力シーケンス内のトークン、単語または要素の数に制限を設定します。 これにより、モデルの入力サイズが均一になります。 たとえば、パラメータが使用されるタスクに応じて、値は128または512から4096になります。 機械翻訳モデルでは、maxSequenceLengthを512にして、翻訳タスクに最大512個のトークンの文または段落を格納できます。

このパラメータは情報提供のみを目的としています。
pooling 文字列 出力ベクトルに対して実行されるプーリング関数を示します。

このパラメータは情報提供のみを目的としています。
modelDescription オブジェクト 既存のONNXメタデータのモデルの記述を補完するために、ユーザーがモデルに記述を追加できるJSONオブジェクト。

このパラメータは情報提供のみを目的としています。
languages 文字列 言語名または略称のカンマ区切りリスト。『Oracle Databaseグローバリゼーション・サポート・ガイド』の「A.1 言語」を参照してください。 多言語埋込みモデルをインポートする場合は、メタデータとして言語または言語の略称を指定します。

このパラメータは情報提供のみを目的としています。
tokenizer 文字列 トークナイザはテキストを単語に変換するために使用されます。 bert、gpt2、bpe、wordpiece、sentencepiece、clipなどの様々なトークナイザを使用できます。

このパラメータは情報提供のみを目的としています。
embeddingLayer 文字列 埋込みレイヤーの識別子。 ニューラル・ネットワークの隠れ層として機能する埋込みレイヤーは、入力データを高い次元から低い次元に変換し、入力の関係およびデータ処理効率に対するネットワークの理解を高めます。 埋込みレイヤーは、カテゴリ・データまたは個別データの処理と分析に役立ちます。 これを実現するために、カテゴリを連続した埋込みに変換し、重要な意味的な関係とそれらの間の類似度を取得します。 たとえば、一部のトランスフォーマの最後の非表示状態、または残差ネットワーク内のレイヤーです。

このパラメータは情報提供のみを目的としています。
defaultOnNull なし

JSONの欠落値の置換を指定するには、defaultOnNullフィールドを使用します。 defaultOnNullが指定されていない場合、欠落値の置換は実行されません。 defaultOnNullは、欠落値をデフォルトでNULLに設定します。 NULLのかわりに意味のあるデフォルト値を指定することで、デフォルト値のNULLをオーバーライドできます。 このフィールドはJSONオブジェクト・リテラルである必要があります。フィールドは入力属性名であり、その値は入力のデフォルト値です。 デフォルト値は文字列型で、指定されたデータ型の有効なOracle PL/SQL NVL値である必要があります。

ノート:パラメータでは大文字と小文字が区別されます。 出力パラメータ名とデフォルト値の多くのデフォルト規則により、指定する必要のある情報を最小限に抑えることができます。 suitableDistanceMetricsなどのパラメータは情報提供専用のものであり、この情報をモデルのインポート時に指定する必要はありません。 JSON記述子では、入力属性を1つのみ指定できます。 それより多く指定すると、エラーが表示されます。 normalizeProbフィールドがJSONメタデータ・パラメータとして指定されている場合、エラーが発生します。

使用上のノート

モデルの名前は、次のような他の機械学習モデルで使用されるものと同じ制限に従います。

  • 入力

    ONNX表現からモデルをインポートする場合、スコアリングに使用される属性の名前と実際のONNX入力をマップする方法を指定する必要があります。 スコアリング演算子は、これらの属性名を使用して、使用する列を識別します。 (たとえば、PREDICTION)。 次の規則に従って、入力フィールドを使用して属性名を指定します。

    指定なし: inputフィールドが指定されていない場合、属性名は名前によってモデル入力に直接マップされます。 つまり、属性名がJSONメタデータに指定されていない場合、入力テンソルの名前が属性名として使用されます。 各モデル入力には、次元[batch_size, value]が必要です。 JSONメタデータでinputを指定しない場合、値は1である必要があります。 モデルの入力がすでにその形式に準拠している場合は、追加のメタデータを指定する必要はありません。 埋込みモデルの場合は、バッチで使用できる単一の入力が提供されます。 ここで、JSONメタデータでinputパラメータを指定しない場合、有効なモデルは[batch_size, 1]となります。

    モデルによって暗黙的に指定されているか、入力フィールドを使用して明示的に設定したかに関係なく、すべての属性名が列名に対して有効なOracle Database識別子であるようにする必要があります。 モデル内の各属性名は一意である必要があり、重複が存在しないようにします。

    1より大きい次元を持つ入力テンソルを使用するモデルの属性名を明示的に指定できます((batch_size, 2)など)。 この場合、これらの値を独立した属性名として解釈するには、それぞれの名前を指定する必要があります。 これは、スコアリング操作で複数の入力属性を受け取ることができるモデルである回帰、分類、クラスタリングに対して実行できます。

  • 出力

    モデルには複数の出力がある場合があるため、特定の機械学習手法の対象の出力を指定できます。 モデル出力を指定するには、次の方法があります。

    • モデルのインポート時に、対象の出力名をJSONで指定します。 指定された名前が有効なモデル出力でない場合(特定の機械学習機能の有効な出力を示す表を参照)、エラーが表示されます。
    • 指定された機械学習手法(classificationProbOutputなど)で予期される出力名と一致する出力がモデルで生成され、明示的に指定しなかった場合、出力は自動的に想定されます。
    • 出力名を指定せず、モデルに1つの出力がある場合、システムでは、単一の出力が機械学習手法に固有のデフォルトに対応しているとみなされます。 埋込み機械学習機能の場合、デフォルト値はembeddingOutputです。

      モデルの出力を指定しない場合、または指定した機械学習機能でサポートされていない出力を指定した場合は、エラーがレポートされます。 次の表に、特定の機械学習機能でサポートされている出力を示します。

      機械学習機能 出力
      回帰 regressionOutput
      分類 classificationProbOutput
      clustering clusteringDistanceOutput
      埋込み embeddingOutput

      前述のモデル出力のいずれも指定されていない場合、または指定した機械学習機能でサポートされていない出力を指定した場合、エラーが表示されます。

  • 出力確率の自動正規化

    多くのユーザーは、マルチクラス分類モデルの出力を正規化するためにsoftmax関数を広く採用しています。この関数により、これらのモデルの結果を簡単に解釈できるようになります。 softmax関数は、実数のベクトルを確率分布に変換する数学関数です。 これはsoftargmaxまたは正規化された指数関数とも呼ばれます。 この関数は、classificationProbOutputやclusteringProbOutputなどの出力確率を保持するテンソルにsoftmax正規化を適用する必要があるモデル・インポート時に指定できます。 softmax正規化に適用する必要がある正規化を定義するには、normalizeProbを指定します。 デフォルト設定はnoneで、正規化が適用されないことを示します。 確率出力にsoftmax関数を適用するには、softmaxを選択します。 このフィールドに他の値を指定すると、インポート時にエラーが発生します。 また、分類およびクラスタリング以外のモデルにこのフィールドを指定した場合も、エラーが発生します。

例: 埋込みモデル用のJSONメタデータ・パラメータの指定

次の例は、DBMS_VECTOR.IMPORT_ONNX_MODELプロシージャを使用してONNX埋込みモデルをデータベースにインポートする際に、JSONメタデータ・パラメータを指定する方法の簡単な例を示しています。 

DBMS_VECTOR.IMPORT_ONNX_MODEL('my_embedding_model.onnx', 'doc_model', 
                JSON('{"function" : "embedding", 
                      "embeddingOutput" : "embedding" , 
                       "input":{"input": ["DATA"]}}'));

例: 埋込みモデル用のすべてのJSONメタデータ・パラメータの指定

次の例は、埋込みモデルをインポートするためにすべてのJSONメタデータ・パラメータ(embeddingLayerを除く)を指定する方法を示しています。 

DECLARE
  metadata JSON;
  mdtxt varchar2(4000);
BEGIN
  metadata := JSON(q'#
           {
             "function"                : "embedding",
             "embeddingOutput"         : "embedding",
             "input"                   : { "input" : ["txt"]},
             "maxSequenceLength"       : 512,
             "tokenizer"               : "bert",
             "suitableDistanceMetrics" : [ "DOT", "COSINE", "EUCLIDEAN"],
             "pooling"                 : "Mean Pooling",
             "normalization"           : true,
             "languages"               : ["US"],
             "modelDescription"        : {
                 "description" : "This model was tuned for semantic search: Given a query/question, if can find relevant passages. It was trained on a large and diverse set of (question, a
nswer) pairs.", 
                 "url" : "https://example.co/sentence-transformers/my_embedding_model"}
           }
           #');
  -- load the onnx model
    DBMS_VECTOR.IMPORT_ONNX_MODEL('my_embedding_model.onnx', 'doc_model', metadata);
END;
/

参照:

機械学習タスクにONNXモデルを使用する例については、『Oracle Machine Learning for SQLユーザーズ・ガイド』を参照してください

LOAD_ONNX_MODEL_CLOUD

このプロシージャを使用すると、オブジェクト・ストレージからデータベースにONNXモデルをロードできます。

構文

DBMS_VECTOR.LOAD_ONNX_MODEL_CLOUD (
     model_name  IN  VARCHAR2,
     credential  IN  VARCHAR2,
     uri         IN  VARCHAR2,
     metadata    IN  JSON DEFAULT JSON('{"function" : "embedding", '|| 
                          '"embeddingOutput" : "embedding", "input": {"input":["DATA"]}}')
);

パラメータ

表216-8 LOAD_ONNX_MODEL_CLOUDプロシージャのパラメータ

パラメータ 説明

model_name

モデル名の形式は、[schema_name.]model_nameです。 スキーマを指定しない場合は、ユーザー独自のスキーマが使用されます。

credential

オブジェクト・ストアへのアクセスに使用する資格証明の名前。

uri

ONNXモデルのURI。

metadata

モデルを記述するメタデータのJSONによる記述。 このメタデータには、モデルでサポートされている機械学習関数を少なくとも記述する必要があります。 モデルのメタデータ・パラメータの詳細は、「ONNXモデルのJSONメタデータ・パラメータ」を参照してください。

例

次の例には、DBMS_VECTOR.LOAD_ONNX_MODEL_CLOUDプロシージャを使用したコード・スニペットが含まれています。 

EXECUTE DBMS_VECTOR.LOAD_ONNX_MODEL_CLOUD(
    model_name => 'database',
    credential => 'MYCRED', 
    uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/all-MiniLM-L6-v2.onnx',
    metadata => JSON('{"function" : "embedding", "embeddingOutput" : "embedding" , "input": {"input": ["DATA"]}}')
);

使用上のノート

モデルの名前は、次のような他の機械学習モデルで使用されるものと同じ制限に従います。

  • スキーマ名を指定する場合は、128文字に制限されます。
  • モデル名は123文字に制限されており、引用符なしの識別子のルールに従う必要があります。名前に使用できるのは、英数字、アンダースコア(_)、ドル記号($)およびシャープ記号(#)のみです。 最初の文字は、英字にする必要があります。
  • モデルのサイズは1GBに制限されます。
  • モデルは外部イニシャライザに依存しないようにします。 イニシャライザおよびその他のONNXの概念の詳細は、https://onnx.ai/onnx/intro/concepts.htmlを参照してください。

  • Pythonユーティリティによって準備されるモデルの入出力属性には、デフォルトの入力名および出力名があります。 これらのモデルは、JSONパラメータなしでロードできます。 例: 

    EXECUTE DBMS_VECTOR.LOAD_ONNX_MODEL_CLOUD(
    'database', 
    'MYCRED',
    'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/all-MiniLM-L6-v2.onnx'
);

参照:

機械学習タスクにONNXモデルを使用する例については、『Oracle Machine Learning for SQLユーザーズ・ガイド』を参照してください

QUERY

上位k件の結果をJSON配列として返す類似検索操作を実行するには、DBMS_VECTOR.QUERY関数を使用します。

構文

問合せがオーバーロードされ、CLOBに加えてVECTOR型としてquery_vectorが渡されるバージョンがサポートされます。 

DBMS_VECTOR.QUERY (
    TAB_NAME             IN VARCHAR2,
    VEC_COL_NAME         IN VARCHAR2,
    QUERY_VECTOR         IN CLOB,
    TOP_K                IN NUMBER,
    VEC_PROJ_COLS        IN JSON_ARRAY_T DEFAULT NULL,
    IDX_NAME             IN VARCHAR2 DEFAULT NULL, 
    DISTANCE_METRIC      IN VARCHAR2 DEFAULT 'COSINE', 
    USE_INDEX            IN BOOLEAN DEFAULT TRUE, 
    ACCURACY             IN NUMBER DEFAULT '90', 
    IDX_PARAMETERS       IN CLOB DEFAULT NULL
) return JSON_ARRAY_T;

DBMS_VECTOR.QUERY (
    TAB_NAME             IN VARCHAR2,
    VEC_COL_NAME         IN VARCHAR2,
    QUERY_VECTOR         IN VECTOR,
    TOP_K                IN NUMBER, 
    VEC_PROJ_COLS        IN JSON_ARRAY_T DEFAULT NULL,
    IDX_NAME             IN VARCHAR2 DEFAULT NULL,
    DISTANCE_METRIC      IN VARCHAR2 DEFAULT 'COSINE',
    USE_INDEX            IN BOOLEAN DEFAULT TRUE,
    ACCURACY             IN NUMBER DEFAULT '90',
    IDX_PARAMETERS       IN CLOB DEFAULT NULL
) return JSON_ARRAY_T;

パラメータ

JSON形式で入力パラメータを指定します。

表216-9 DBMS_VECTOR.QUERYパラメータ

パラメータ 説明

tab_name

問い合せる表名

vec_col_name

Vector列名

query_vector

問合せベクトルは、CLOBまたはVECTORとして渡されます。

top_k

返される結果の数。

vec_proj_cols

結果の一部として推定される列。

idx_name

問い合せた索引の名前。

distance_metric

距離計算メトリック。 デフォルトはCOSINEです。 MANHATTAN、HAMMING、DOT、EUCLIDEAN、L2_SQUARED、EUCLIDEAN_SQUAREDを指定することもできます。

.

use_index

検索が近似検索と完全検索のいずれであるかを指定します。 デフォルトはTRUE (近似)です。

accuracy

最低限必要な問合せの精度を指定します。

idx_parameters

渡されるefsearchおよびneighbor partition probesの値をJSON形式で指定します

DATA

この関数は、入力データ型をVARCHAR2、NUMBER、JSON、BOOLEANまたはCLOBとして受け入れます。

REBUILD_INDEX

ベクトル索引を再作成するには、DBMS_VECTOR.REBUILD_INDEX関数を使用します。

用途

Hierarchical Navigable Small World (HNSW)ベクトル索引やInverted File Flat (IVF)ベクトル索引などのベクトル索引を再構築します。 idx_nameのみが指定されている場合は、get_ddlを使用して索引を再作成します。 すべてのパラメータを指定すると、索引を削除してからdbms_vector.create_index()へのコールが実行されます。

構文

DBMS_VECTOR.REBUILD_INDEX (
    idx_name                   IN VARCHAR2,
    table_name                 IN VARCHAR2 DEFAULT NULL,
    idx_vector_col             IN VARCHAR2 DEFAULT NULL, 
    idx_include_cols           IN VARCHAR2 DEFAULT NULL,
    idx_partitioning_scheme    IN VARCHAR2 DEFAULT NULL,
    idx_organization           IN VARCHAR2 DEFAULT NULL,
    idx_distance_metric        IN VARCHAR2 DEFAULT 'COSINE',
    idx_accuracy               IN NUMBER DEFAULT 90,
    idx_parameters             IN CLOB DEFAULT NULL,
    idx_parallel_creation      IN NUMBER DEFAULT 1,
);

パラメータ

パラメータ 説明

idx_name

再作成する索引の名前。

table_name

索引を作成する表。

idx_vector_col

索引を作成するVector列。
idx_include_cols

索引でカバーされる列名のカンマ区切りリスト。

idx_partitioning_scheme

IVF索引のパーティション化スキーム:

  • GLOBAL

  • LOCAL

IVF索引は、パーティション表のグローバル索引とローカル索引の両方をサポートします。 デフォルトでは、これらの索引は重心によってグローバルにパーティション化されます。 ローカルIVF索引を作成することを選択できます。これにより、実表のパーティションまたはサブパーティションと索引パーティションの間に1対1の関係が提供されます。

これらのパーティション化スキームの詳細は、「Inverted File Flatベクトル索引のパーティション化スキーム」を参照してください。

idx_organization

索引構成:

  • NEIGHBOR PARTITIONS

  • INMEMORY NEIGHBOR GRAPH

これらの組織タイプの詳細は、「ベクトル索引の様々なカテゴリの管理」を参照してください。

idx_distance_metric

ベクトル間の距離を計算するために使用される距離メトリックまたは数学的関数:

  • COSINE (デフォルト)
  • MANHATTAN
  • HAMMING
  • JACCARD
  • DOT
  • EUCLIDEAN
  • L2_SQUARED
  • EUCLIDEAN_SQUARED

これら各メトリックの詳細は、「ベクトル距離関数および演算子」を参照してください。

idx_accuracy

近似検索問合せの実行時に目指す近似検索の実行のターゲット精度。

ベクトル索引を使用した近似類似検索の理解で説明されているように、使用する索引タイプに応じて、パーセント値を指定するか、内部パラメータ値を指定することによって、デフォルト以外のターゲット精度値を指定できます。

  • HNSW近似検索の場合:

    HNSW近似検索の場合、ターゲット精度のパーセント値を指定して、検索の精査で考慮される候補の数に影響を与えることができます。 これは、アルゴリズムによって自動的に計算されます。 値が100の場合は、完全検索と同様の結果となる傾向がありますが、システムでは引き続き索引が使用され、完全検索は実行されません。 オプティマイザでは、問合せの述語がある場合は索引を使用する方が高速になる可能性があるため、引き続き索引を使用することが選択されることがあります。 ターゲット精度のパーセンテージ値を指定するかわりに、EFSEARCHパラメータを指定して、索引の精査中に考慮される特定の最大候補数を指定できます。 その数値が大きいほど、精度が高くなります。

    詳細は、「Hierarchical Navigable Small World索引の理解」を参照してください。

  • IVF近似検索の場合:

    IVF近似検索の場合、ターゲット精度のパーセント値を指定して、検索の精査に使用されるパーティションの数に影響を与えることができます。 これは、アルゴリズムによって自動的に計算されます。 値が100の場合は、完全検索が実行される傾向がありますが、システムでは引き続き索引が使用され、完全検索は実行されません。 オプティマイザでは、問合せの述語がある場合は索引を使用する方が高速になる可能性があるため、引き続き索引を使用することが選択されることがあります。 ターゲット精度のパーセンテージ値を指定するかわりに、NEIGHBOR PARTITION PROBESパラメータを指定して、検索によって精査されるパーティションの最大数を指定できます。 その数値が大きいほど、精度が高くなります。

    詳細は、「Inverted File Flatベクトル索引の理解」を参照してください。

idx_parameters

ベクトル索引のタイプと関連パラメータ。

索引付けパラメータをJSON形式で指定します:

  • HNSW索引の場合:

    • type: 作成するベクトル索引のタイプ(HNSW)

    • neighbors: HNSWグラフでベクトル当たりに許可される最大接続数

    • efConstruction: 挿入時に検索の各ステップで考慮される最も近いベクトル候補の最大数

    例:

    {
    "type"           : "HNSW", 
    "neighbors"      : 3, 
    "efConstruction" : 4
}

    これらのパラメータの詳細は、「Hierarchical Navigable Small World索引の構文およびパラメータ」を参照してください。

  • IVF索引の場合:

    • type: 作成するベクトル索引のタイプ(IVF)

    • partitions: ベクトル空間を分割する近傍パーティションまたはクラスタ

    例:

    {
    "type"       : "IVF",
    "partitions" : 5
}

    これらのパラメータの詳細は、「Inverted File Flat索引の構文およびパラメータ」を参照してください。

idx_parallel_creation

索引作成に使用されるパラレル・スレッドの数。

例

  • HNSW索引のneighborsとefConstructionを指定します:

    dbms_vector.rebuild_index(
    'v_hnsw_01', 
    'vpt01', 
    'EMBEDDING', 
     NULL, 
     NULL, 
    'INMEMORY NEIGHBOR GRAPH', 
    'EUCLIDEAN', 
     95, 
    '{"type" : "HNSW", "neighbors" : 3, "efConstruction" : 4}');

  • IVF索引のパーティション数を指定します:

    dbms_vector.rebuild_index(
    'V_IVF_01', 
    'vpt01', 
    'EMBEDDING', 
     NULL,
     NULL, 
    'NEIGHBOR PARTITIONS', 
    'EUCLIDEAN', 
     95, 
    '{"type" : "IVF", "partitions" : 5}');

RERANK

DBMS_VECTOR.RERANK関数は、より関連性の高い検索出力を取得するために、結果の初期セットを再評価および順序変更するために使用します。

用途

類似性検索と検索拡張生成(RAG)の両方のシナリオで検索結果の関連性と品質を向上させるため。

再ランク付けは、最も関連性の高いドキュメントまたはチャンクが優先されるようにすることで、LLMに取り込まれる情報の品質を向上させます。 これは、ハルシネーションの減少と、生成された出力の精度向上につながります。

この操作について、Oracle AI Vector Searchでは、CohereおよびVertex AIが提供する再ランク付けモデルをサポートしています。

警告:

データベースの特定の機能により、たとえばREST APIへのアクセスを容易にするJSON仕様を使用することで、サードパーティによって個別に提供されるサービスにアクセスできることもあります。

こうした機能の使用は、お客様自身の責任においてのみ行われ、お客様は当該のサードパーティ・サービスの使用に関連するあらゆる利用規約を遵守する責任を負います。 サードパーティ・サービスに関するその他の利用規約にかかわらず、こうしたデータベース機能を使用することは、お客様がそのリスクを受け入れ、そうしたアクセスにより生じた一切の損害についてOracleの責任または法的責任を明示的に排除することで成立します。

構文

DBMS_VECTOR.RERANK(
                QUERY      IN CLOB,
                DOCUMENTS  IN JSON,
                PARAMS     IN JSON default NULL
) return JSON;

この関数は、CLOBとしての問合せと、JSON形式でのドキュメントのリストを受け入れます。 その後、この情報を処理して、再ランク付けされスコアでソートされたドキュメントのリストが含まれているJSONオブジェクトを生成します。

たとえば、再ランク付けされた出力には次のものが含まれます:
{
    "index"   : "1",
    "score"   : "0.99",
    "content" : "Jupiter boasts an impressive system of 95 known moons."
}
内容は次のとおりです。

  • indexは、入力テキストのリスト内のドキュメントの位置を指定します。

  • scoreは、関連性スコアを指定します。

  • contentは、索引に対応する入力テキストを指定します。

QUERY

CLOBとして検索問合せ(通常は初期検索から)を指定します。

DOCUMENTS

次の形式で、文字列のJSON配列(再ランク付けする潜在的な関連ドキュメントのリスト)を指定します:

{
  "documents": [
  "string1",
  "string2",
    ...
  ]
}

PARAMS

次のパラメータのリストをJSON形式で指定します。 これらのパラメータはすべて必須です。 

{
  "provider"         : "<service provider>",
  "credential_name"  : "<credential name>",  
  "url"              : "<REST endpoint URL for reranking>",
  "model"            : "<reranking model name>",
  ...
}

表216-10 RERANKパラメータ詳細

パラメータ 説明

provider

再ランク付けのためのアクセスがサポートされているRESTプロバイダ:

  • cohere

  • vertexai

credential_name

次の形式の資格証明の名前:

schema.credential_name

資格証明名には、REST APIコールを行うためのプロバイダにアクセスできるようにする認証資格証明が保持されます。

まず、資格証明を作成および格納するためにDBMS_VECTOR.CREATE_CREDENTIALヘルパー関数をコールして、資格証明をセットアップしてから、ここで資格証明書の名前を参照する必要があります。

CREATE_CREDENTIALを参照してください。

url

サポートされているサードパーティ・プロバイダの操作およびエンドポイントにリストされている、各RESTコールのサードパーティ・プロバイダ・エンドポイントのURL。

model

次の形式での再ランク付けモデルの名前:

schema.model_name

モデル名がスキーマ修飾されていない場合は、プロシージャ実行者のスキーマが使用されます。

追加のRESTプロバイダのパラメータ:

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

重要:

Cohereの例:
{
  "provider"        : "cohere", 
  "credential_name" : "COHERE_CRED",
  "url"             : "https://api.cohere.example.com/rerank",
  "model"           : "rerank-english-v3.0",
  "return_documents": false,
  "top_n"           : 3
}
Vertex AIの例:
{
  "provider"         : "vertexai",
  "credential_name"  : "VERTEXAI_CRED",
  "url"              : "https://googleapis.example.com/default_ranking_config:rank",
  "model"            : "semantic-ranker-512@latest",
  "ignoreRecordDetailsInResponse" : true,
  "topN"             : 3
  }

表216-11 追加のRESTプロバイダ・パラメータ詳細

パラメータ 説明

return_documents

元のドキュメントまたは入力テキストとともに検索結果を返すかどうか(content):

  • false (デフォルト、推奨): 入力テキストを返しません(索引とスコアのみを返します)

  • true: 索引およびスコアとともに入力テキストを返します

ノート: Cohereをプロバイダとして使用する場合は、パフォーマンスを向上させるために、このオプションを無効にしておくことをお薦めします。 デバッグの目的で元のテキストを表示する必要がある場合には、有効にすることもできます。

ignoreRecordDetailsInResponse

元のレコード詳細または入力テキストとともに検索結果を返すかどうか(content):

  • false (デフォルト): 索引およびスコアとともに入力テキストを返します

  • true (推奨): 入力テキストを返しません(索引とスコアのみを返します)

ノート: Vertex AIをプロバイダとして使用する場合は、パフォーマンスを向上させるために、このオプションを有効にしておくことをお薦めします。 デバッグの目的で元のテキストを表示する必要がある場合には、無効にすることもできます。

top_nまたはtopN

最も関連性の高いドキュメントを返す数。

例

  • Cohereの使用:

    declare
  params clob;
  reranked_output json;
begin
  params := '
{
  "provider": "cohere",
  "credential_name": "COHERE_CRED",
  "url": "https://api.cohere.com/v1/rerank",
  "model": "rerank-english-v3.0",
  "return_documents": true,
  "top_n": 3
}';

  reranked_output := dbms_vector.rerank(:query, json(:initial_retrieval_docs), json(params));
  dbms_output.put_line(json_serialize(reranked_output));
end;
/

  • Vertex AIの使用:

    declare
  params clob;
  reranked_output json;
begin
  params := '
{
  "provider": "vertexai",
  "credential_name": "VERTEXAI_CRED",
  "url": "https://discoveryengine.googleapis.com/v1/projects/1085581009881/locations/global/rankingConfigs/default_ranking_config:rank",
  "model": "semantic-ranker-512@latest",
  "ignoreRecordDetailsInResponse": false,
  "topN": 3
}';

  reranked_output := dbms_vector.rerank(:query, json(:initial_retrieval_docs), json(params));
  dbms_output.put_line(json_serialize(reranked_output));
end;
/

エンドツーエンドの例:

この関数を使用してエンドツーエンドのシナリオ例を実行する場合は、RAGの結果を改善するための再ランク付けの使用を参照してください。

UTL_TO_CHUNKS

大きいプレーン・テキスト・ドキュメントをテキストの小さなチャンクに分割するには、DBMS_VECTOR.UTL_TO_CHUNKSチェーン可能ユーティリティ関数を使用します。

用途

テキストからチャンクへの変換を実行します。 このチェーン可能ユーティリティ関数は、操作の際に内部的にVECTOR_CHUNKS SQLファンクションをコールします。

大きなドキュメントを埋め込むには、まず、チャンク化と呼ばれる分割プロセス(「データ変換のステージの理解」を参照)によって、そのドキュメントを複数の適切なサイズのセグメントまたはチャンクに分割する必要があります。 チャンクは、単語(特定の単語や単語の断片を取得)、文(特定の意味を取得)、段落(より広いテーマを取得)のいずれかになります。 単一のドキュメントを複数のチャンクに分割し、それぞれをベクトルに変換できます。

構文

DBMS_VECTOR.UTL_TO_CHUNKS (
    DATA         IN  CLOB | VARCHAR2,
    PARAMS       IN  JSON  default  NULL
) return VECTOR_ARRAY_T;

DATA

この関数は、入力データ型をCLOBまたはVARCHAR2として受け入れます。

CLOBの配列を返します。各CLOBには、次のように、JSON形式のメタデータとともにチャンクが含まれています。 

{
    "chunk_id"     : NUMBER,
    "chunk_offset" : NUMBER,
    "chunk_length" : NUMBER, 
    "chunk_data"   : "VARCHAR2(4000)"
}
例:
{"chunk_id":1,"chunk_offset":1,"chunk_length":6,"chunk_data":"sample"}
内容は次のとおりです。

  • chunk_idは、各チャンクのチャンクIDを示します。

  • chunk_offsetは、ソース・ドキュメント内の各チャンクの元の位置を示します(ドキュメントの始まりの位置である1を基準とする)。

  • chunk_lengthは、各チャンクの文字長を示します。

  • chunk_dataは、各チャンクのテキストの部分を示します。

PARAMS

JSON形式で入力パラメータを指定します:

{
    "by"           :     mode,
    "max"          :     max,
    "overlap"      :     overlap,
    "split"        :     split_condition,
    "custom_list"  :     [ split_chars1, ... ],
    "vocabulary"   :     vocabulary_name,
    "language"     :     nls_language,
    "normalize"    :     normalize_mode,
    "norm_options" :     [ normalize_option1, ... ],
    "extended"     :     boolean
}

例:

JSON('
  { "by"           :    "vocabulary",
    "vocabulary"   :    "myvocab",
    "max"          :    "100",
    "overlap"      :    "0",
    "split"        :    "custom",
    "custom_list"  :    [ "<p>" , "<s>" ],
    "language"     :    "american",
    "normalize"    :    "options",
    "norm_options" :    [ "WHITESPACE" ] 
  }')

これらのパラメータの詳細は、次のとおりです:

パラメータ 説明および許容される値

by

データを分割するモードを指定します。つまり、文字、単語または語彙トークンの数をカウントして分割します。

有効値:

  • characters (またはchars):

    文字数をカウントして分割します。

  • words:

    単語数をカウントして分割します。

    単語は、英字のシーケンス、数字のシーケンス、個々の句読点、または記号として定義されます。 空白の単語境界のないセグメント化された言語(中国語、日本語、タイ語など)では、各ネイティブ文字が単語とみなされます(つまり、ユニグラム)。

  • vocabulary:

    語彙トークンの数をカウントして分割します。

    語彙トークンは、埋込みモデルで使用されるトークナイザの語彙によって認識される単語または単語の断片です。 語彙ファイルは、チャンカ・ヘルパーAPIのDBMS_VECTOR_CHAIN.CREATE_VOCABULARYを使用してロードできます。

    ノート: 正確な結果を得るには、選択したモデルがチャンク化に使用される語彙ファイルと一致するようにしてください。 語彙ファイルを使用していない場合は、入力長がモデルのトークン制限内で定義されていることを確認してください。

デフォルト値: words

max

各チャンクの最大サイズの制限を指定します。 この設定では、大きいテキストで最大制限に達したときに、固定された位置で入力テキストが分割されます。 maxの単位は、byモードに対応しています。つまり、特定の数の文字、単語、数字、句読点または語彙トークンが最大サイズ制限に達したときにデータが分割されます。

有効値:

  • by characters: 50文字から4000文字

  • by words: 10単語から1000単語

  • by vocabulary: 10トークンから1000トークン

デフォルト値: 100

split [by]

最大サイズ制限に達したときに入力テキストを分割する位置を指定します。 これにより、チャンクに対して適切な境界を定義することで、関連するデータが一緒になるように維持できます。

有効値:

  • none:

    文字、単語または語彙トークンのmax制限で分割します。

  • newline、blanklineおよびspace:

    これらは、max値の前の最後の分割文字で分割される単一分割文字条件です。

    テキストの行の最後で分割するには、newlineを使用します。 空白行(2つの改行などの文字のシーケンス)の最後で分割するには、blanklineを使用します。 空白の最後で分割するには、spaceを使用します。

  • recursively:

    これは、文字(またはシーケンス)の順序付きリストを使用して入力テキストを分割する複数分割文字条件です。

    recursivelyは、次の順序でBLANKLINE、newline、space、noneとして事前定義されています:

    1. 入力テキストがmax値より大きい場合は、最初の分割文字で分割されます。

    2. 失敗した場合は、2番目の分割文字で分割します。

    3. 同様に続けます。

    4. 分割文字が存在しない場合は、テキスト内のmaxの位置で分割します。

  • sentence:

    これは、文の境界で入力テキストを分割する文末分割条件です。

    この条件では、入力言語の文の句読点およびコンテキスト・ルールの知識を使用して、文の境界が自動的に判断されます。 この言語固有の条件は、主に文末(EOS)の句読点および一般的な略記法に依存しています。

    コンテキスト・ルールは単語情報に基づいているため、この条件はテキストを(文字ではなく)単語または語彙で分割する場合にのみ有効です。

    ノート: この条件は、by wordおよびmaxの設定に従っているため、場合によっては正確な文の境界を判断できないことがあります。 たとえば、文がmax値より大きい場合、文はmaxで分割されます。 同様に、maxの制限内に収まる場合にのみ、テキストに複数の文が含まれます。

  • custom:

    カスタム分割文字リストに基づいて分割します。 カスタム・シーケンスは、制限である16個の分割文字列まで指定でき、最大長はそれぞれ10文字です。

    custom_listパラメータを使用して、有効なテキスト・リテラルの配列を指定します。 

    {
    "split"        :  "custom",
    "custom_list"  :  [ "split_chars1", ... ]
}

    例:

    {
    "split"        :    "custom",
    "custom_list"  :    [ "<p>" , "<s>" ]
}

    ノート: シーケンスは、タブ(\t)、改行(\n)および改行(\r)の場合にのみ省略できます。

デフォルト値: recursively

overlap

チャンクに含める必要がある先行するテキストの量(正の整数リテラルまたはゼロ)を指定します(存在する場合)。 これは、先行するチャンク・テキストの一部を含めて、関連するテキスト(文など)を論理的に分割するのに役立ちます。

重なりの量は、チャンクの最大サイズの測定方法(文字、単語または語彙トークン)によって異なります。 重なりは、指定されたsplit条件(newlineなど)から始まります。

有効な値: maxの5%から20%

デフォルト値: 0

language

入力データの言語を指定します。

この句は、別の言語では異なる解釈になる可能性がある特定の文字(句読点や略語など)がテキストに含まれている場合に特に重要です。

有効値:

ノート: エスケープ文字は、SQL予約語でもある言語の略語(たとえば、IN、AS、OR、ISなどの言語の略語)とともに使用する必要があります。

例:

SELECT dbms_vector_chain.utl_to_chunks('this is an example', 
   JSON('{ "language" : "\"in\"" }')) 
from dual;
SELECT dbms_vector_chain.utl_to_chunks('this is an example', 
   JSON_OBJECT('language' value '"in"' RETURNING JSON)) 
from dual;

デフォルト値: セッションのNLS_LANGUAGE

normalize

ドキュメントがテキストに変換されるときに発生する可能性のある問題(連続する複数の空白やスマート・クォートなど)を自動的に前処理または後処理します。 高品質のチャンクを抽出するために、正規化モードを使用することをお薦めします。

有効値:

  • none:

    正規化を適用しません。

  • all:

    一般的なマルチバイト(Unicode)の句読点を標準のシングルバイトに正規化します。

  • options:

    norm_optionsパラメータを使用して、正規化オプションの配列を指定します。 

    {
    "normalize"    :  "options",
    "norm_options" :  [ "normalize_option1", ... ]
}

    • punctuation:

      そのテキストの文字セットでサポートされている引用符、ダッシュおよびその他の句読点文字を、共通のASCII形式に変換します。 例:

      • U+2013 (エンダッシュ)はU+002D (ハイフンマイナス)にマップされます

      • U+2018 (左一重引用符)はU+0027 (アポストロフィ)にマップされます

      • U+2019 (右一重引用符)はU+0027 (アポストロフィ)にマップされます

      • U+201B (単一の高逆9引用符)はU+0027 (アポストロフィ)にマップされます

    • whitespace:

      不要な文字を排除することで、空白を最小化します。

      たとえば、空白行は維持しますが、余分な改行、空白またはタブは削除します: " \n \n " => "\n\n"

    • widechar:

      ワイド文字とマルチバイト文字の数字および(a-z)をシングルバイトに正規化します。

      これらは、0-9およびa-z A-Zに相当するマルチバイト文字であり、中国語、日本語または韓国語のテキストで出現することがあります。

    例:

    {
    "normalize"    :  "options",
    "norm_options" :  [ "whitespace" ]
}

デフォルト値: none

extended

max_string_sizeパラメータをextendedに設定することなく、VARCHAR2文字列の出力制限を32767バイトに増やします。

デフォルト値: 4000または32767 (max_string_size=extendedの場合)

例

SELECT D.id doc,
    JSON_VALUE(C.column_value, '$.chunk_id' RETURNING NUMBER) AS id,
    JSON_VALUE(C.column_value, '$.chunk_offset' RETURNING NUMBER) AS pos,
    JSON_VALUE(C.column_value, '$.chunk_length' RETURNING NUMBER) AS siz,
    JSON_VALUE(C.column_value, '$.chunk_data') AS txt
FROM docs D,
   dbms_vector.utl_to_chunks(D.text,
   JSON('{ "by"       : "words",
           "max"      : "100",
           "overlap"  : "0",
           "split"    : "recursively",
           "language" : "american",
           "normalize": "all" }')) C;

エンドツーエンドの例:

この関数を使用してエンドツーエンドのサンプル・シナリオを実行する場合は、埋込みを使用したチャンク化の実行およびチャンク化パラメータの構成を参照してください。

関連トピック

UTL_TO_EMBEDDINGおよびUTL_TO_EMBEDDINGS

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

用途

テキスト・ドキュメントおよびイメージから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;

DATA

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

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

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

パラメータ 説明

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

表216-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

スキーマを指定しない場合は、プロシージャ実行者のスキーマが使用されます。

ノート:

  • Generative 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回を超えると停止します。 これにより、一定の制限を超えてサードパーティのコールが誤って実行されることを防ぎます。たとえば、購入したサービス量を超過しないようにします。

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

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

表216-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"
}
Generative 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"
}
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値は、サポートされているサードパーティ・プロバイダの操作およびエンドポイントに示されているように、Generative 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を使用して様々なエンドツーエンドのシナリオ例を実行するには、「チャンク化と埋込みの実行」を参照してください。

UTL_TO_GENERATE_TEXT

DBMS_VECTOR.UTL_TO_GENERATE_TEXTチェーン可能ユーティリティ関数を使用して、サードパーティのテキスト生成モデルにアクセスすることで、所定のプロンプトまたはイメージに対するテキスト・レスポンスを生成します。

用途

自然言語による会話を通じて大規模言語モデル(LLM)と通信すること。 LLM搭載のチャット・インタフェースへの入力として与えられたプロンプトおよびイメージに対して、テキスト形式の回答、説明またはサマリーを生成できます。

  • プロンプトからテキストへ:

    プロンプトには、LLMに尋ねる質問などの入力テキスト文字列を指定できます。 たとえば、"What is Oracle Text?"などです。 プロンプトは、"Summarize the following ..."、"Draft an email asking for ..."または"Rewrite the following ..."などのコマンドでもあり、検索の結果を含めることができます。 LLMは、プロンプトに指定されたタスクに基づいて、テキスト形式の回答または説明で応答します。

    この操作では、このAPIによって、選択したリモート・サードパーティ・プロバイダ(Cohere、生成AI、Google AI、Hugging Face、OpenAIまたはVertex AI)またはローカル・サードパーティ・プロバイダ(Ollama)へのRESTコールが行われます。

  • イメージからテキストへ:

    イメージなどのメディア・ファイルでプロンプトして、画像や写真からテキストを抽出することもできます。 テキストの質問("What is this image about?"や"How many birds are there in this painting?"など)をプロンプトとして、イメージとともに指定します。 LLMは、イメージの内容についてのテキストによる分析または説明で応答します。

    この操作では、このAPIによって、選択したリモート・サードパーティ・プロバイダ(Google AI、Hugging Face、OpenAIまたはVertex AI)またはローカル・サードパーティ・プロバイダ(Ollama)へのRESTコールが実行されます。

警告:

データベースの特定の機能により、たとえばREST APIへのアクセスを容易にするJSON仕様を使用することで、サードパーティによって個別に提供されるサービスにアクセスできることもあります。

こうした機能の使用は、お客様自身の責任においてのみ行われ、お客様は当該のサードパーティ・サービスの使用に関連するあらゆる利用規約を遵守する責任を負います。 サードパーティ・サービスに関するその他の利用規約にかかわらず、こうしたデータベース機能を使用することは、お客様がそのリスクを受け入れ、そうしたアクセスにより生じた一切の損害についてOracleの責任または法的責任を明示的に排除することで成立します。

構文

このファンクションは、テキスト・データが含まれたCLOB (テキスト・プロンプトの場合)またはメディア・データが含まれたBLOB (イメージなどのメディア・ファイルの場合)として入力を受け入れます。 その後、この情報を処理して、生成されたテキストが含まれている新しいCLOBを生成します。

  • プロンプトからテキストへ:

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

  • イメージからテキストへ:

    DBMS_VECTOR.UTL_TO_GENERATE_TEXT(
          TEXT_DATA      IN CLOB,
          MEDIA_DATA     IN BLOB,
          MEDIA_TYPE     IN VARCHAR2 default 'image/jpeg',
          PARAMS         IN JSON default NULL
) return CLOB;

DATAおよびTEXT_DATA

DATAまたはTEXT_DATA句のCLOBとして、テキスト形式のプロンプトを指定します。

ノート:

Hugging Faceは、入力としてイメージを与えるときに、プロンプトを必要としないイメージ・キャプション・モデルを使用します。 イメージとともにプロンプトを入力すると、プロンプトは無視されます。

MEDIA_DATA

イメージやビジュアルPDFファイルなどのBLOBファイルを指定します。

MEDIA_TYPE

サポートされているイメージ・データMIMEタイプのいずれかで、指定のイメージまたはビジュアルPDFファイル(BLOBファイル)のイメージ形式を指定します。 例:

  • PNGの場合: image/png

  • JPEGの場合: image/jpeg

  • PDFの場合: application/pdf

ノート:

サポートされているイメージ形式の完全なリストは、サードパーティ・プロバイダのドキュメントを参照してください。

PARAMS

テキスト生成のためにアクセスするサービス・プロバイダに応じて、次の入力パラメータをJSON形式で指定します:

{
  "provider"         : "<AI service provider>",
  "credential_name"  : "<credential name>",  
  "url"              : "<REST endpoint URL for text generation service>",
  "model"            : "<text generation 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>"
}

表216-15 UTL_TO_GENERATE_TEXTパラメータの詳細

パラメータ 説明

provider

テキストを生成するためにアクセスするサポート対象のRESTプロバイダ。

次のいずれかの値を指定します。

CLOB入力の場合:

  • cohere

  • googleai

  • huggingface

  • ocigenai

  • openai

  • vertexai

BLOB入力の場合:

  • googleai

  • huggingface

  • openai

  • vertexai

credential_name

次の形式の資格証明の名前:

schema.credential_name

資格証明名には、REST APIコールを行うためのプロバイダにアクセスできるようにする認証資格証明が保持されます。

まず、資格証明を作成および格納するためにDBMS_VECTOR.CREATE_CREDENTIALヘルパー関数をコールして、資格証明をセットアップしてから、ここで資格証明書の名前を参照する必要があります。 CREATE_CREDENTIALを参照してください。

url

サポートされているサードパーティ・プロバイダの操作およびエンドポイントにリストされている、各RESTコールのサードパーティ・プロバイダ・エンドポイントのURL。

model

次の形式でのサードパーティ・テキスト生成モデルの名前:

schema.model_name

モデル名がスキーマ修飾されていない場合は、プロシージャ実行者のスキーマが使用されます。

ノート: Generative AIの場合、サポートされているすべてのサードパーティ・モデルがサポートされているサードパーティ・プロバイダの操作およびエンドポイントにリストされています。

transfer_timeout

リクエストを完了するまでの最長待機時間。

デフォルト値は60秒です。 ビジー状態のWebサーバーに対しては、この値を増やすことができます。

max_count

特定のサードパーティ・プロバイダに対してAPIをコールできる最大回数。

整数nに設定すると、max_countによって、指定されたプロバイダのAPIの実行がn回を超えると停止します。 これにより、一定の制限を超えてサードパーティのコールが誤って実行されることを防ぎます。たとえば、購入したサービス量を超過しないようにします。

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

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

表216-16 追加のRESTプロバイダ・パラメータ詳細

パラメータ 説明

max_tokens

出力テキスト内の最大トークン数。

temperature

出力テキストの生成時に使用されるランダム性の度合い(0.0-5.0の範囲)。

プロンプトに対して同じ出力を生成するには、0を使用します。 そのプロンプトに対してランダムな新しいテキストを生成するには、temperatureを大きくします。

ノート: 最初は温度を0に設定します。 ランダムな結果が必要ない場合、推奨される温度値は0から1の間です。 高温では創造的なテキストが生成される可能性があり、ハルシネーションも含まれることがあるため、高い値は推奨されません。

topP

出力内のトークンの確率(0.0-1.0の範囲)。

小さな値ほどランダム応答が少なくなり、大きな値ほどランダム応答が多くなります。

candidateCount

応答のバリエーション数(1-4の範囲)。

maxOutputTokens

応答ごとに生成するトークンの最大数。

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

重要:

Cohereの例:
{
  "provider"       : "cohere", 
  "credential_name": "COHERE_CRED",
  "url"            : "https://api.cohere.example.com/chat",
  "model"          : "command"
}

Generative AIの例:

ノート:

Generative AIの場合で追加のRESTプロバイダ固有のパラメータを渡す場合は、chatRequestにこれらを含める必要があります。 
{
  "provider"       : "ocigenai",
  "credential_name": "OCI_CRED",
  "url"            : "https://inference.generativeai.us-example.com/chat",
  "model"          : "cohere.command-r-16k",
  "chatRequest"    : {
                      "maxTokens"    : 256
                     }
}
Google AIの例:
{
  "provider"        : "googleai",
  "credential_name" : "GOOGLEAI_CRED",
  "url"             : "https://googleapis.example.com/models/",
  "model"           : "gemini-pro:generateContent"
}
Hugging Faceの例:
{
  "provider"        : "huggingface",
  "credential_name" : "HF_CRED",
  "url"             : "https://api.huggingface.example.com/models/",
  "model"           : "gpt2"
}
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"      : 60,
  "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
                       }
}

例

  • プロンプトからテキストへ:

    次の文は、Generative AIへのRESTコールによってテキスト・レスポンスを生成します。 ここに示されるプロンプトは"What is Oracle Text?"です。

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

    cohere.command-r-16kモデルの使用: 

    -- select example

var params clob;
exec :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",
  "chatRequest"    : {
                      "maxTokens": 256
                     }
}';

select dbms_vector.utl_to_generate_text(
 'What is Oracle Text?',
 json(:params)) from dual;

-- PL/SQL example

declare
  input clob;
  params clob;
  output clob;
begin
  input := 'What is Oracle Text?';

  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",
  "chatRequest"    : {
                      "maxTokens": 256
                     }
}';

  output := dbms_vector.utl_to_generate_text(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;
/

    meta.llama-3.1-70b-instructモデルの使用: 

    -- select example

var params clob;
exec :params := '
{
   "provider"       : "ocigenai",
   "credential_name": "OCI_CRED",
   "url"            : "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat",
   "model"          : "meta.llama-3.1-70b-instruct",
   "chatRequest"    : {
                       "topK" : 1
                      }
}';

select dbms_vector.utl_to_generate_text(
 'What is Oracle Text?',
 json(:params)) from dual;

-- PL/SQL example

declare
  input clob;
  params clob;
  output clob;
begin
  input := 'What is Oracle Text?';

  params := '
{
   "provider"       : "ocigenai",
   "credential_name": "OCI_CRED",
   "url"            : "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat",
   "model"          : "meta.llama-3.1-70b-instruct",
   "chatRequest"    : {
                       "topK" : 1
                      }
}';

  output := dbms_vector.utl_to_generate_text(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;
/

    エンドツーエンドの例:

    エンドツーエンドのサンプル・シナリオを実行する場合は、テキスト・レスポンスの生成を参照してください。

  • イメージからテキストへ:

    次の文は、OpenAIへのRESTコールによってテキスト・レスポンスを生成します。 ここでの入力は、イメージ(sample_image.jpeg)とプロンプト"Describe this image?"です。 

    -- select example

var input clob;
var media_data blob;
var media_type clob;
var params clob;

begin
  :input := 'Describe this image';
  :media_data := load_blob_from_file('DEMO_DIR', 'sample_image.jpeg');
  :media_type := 'image/jpeg';
  :params := '
{
  "provider"       : "openai",
  "credential_name": "OPENAI_CRED",
  "url"            : "https://api.openai.com/v1/chat/completions",
  "model"          : "gpt-4o-mini",
  "max_tokens"     : 60
}';
end;
/

select dbms_vector.utl_to_generate_text(:input, :media_data, :media_type, json(:params));

-- PL/SQL example

declare
  input clob;
  media_data blob;
  media_type varchar2(32);
  params clob;
  output clob;

begin
  input := 'Describe this image';
  media_data := load_blob_from_file('DEMO_DIR', 'image_file');
  media_type := 'image/jpeg';
  params := '
{
  "provider"       : "openai",
  "credential_name": "OPENAI_CRED",
  "url"            : "https://api.openai.com/v1/chat/completions",
  "model"          : "gpt-4o-mini",
  "max_tokens"     : 60
}';

  output := dbms_vector.utl_to_generate_text(
    input, media_data, media_type, json(params));
  dbms_output.put_line(output);

  if output is not null then
    dbms_lob.freetemporary(output);
  end if;
  if media_data is not null then
    dbms_lob.freetemporary(media_data);
  end if;
exception
  when OTHERS THEN
    DBMS_OUTPUT.PUT_LINE (SQLERRM);
    DBMS_OUTPUT.PUT_LINE (SQLCODE);
end;
/

    エンドツーエンドの例:

    エンドツーエンドのサンプル・シナリオを実行する場合は、イメージ・コンテンツの説明を参照してください。