CREATE_PREFERENCE

ハイブリッド・ベクトル索引の作成または更新時に使用されるベクトル化プリファレンスを作成するには、DBMS_VECTOR_CHAIN.CREATE_PREFERENCEヘルパー・プロシージャを使用します。

用途

ベクトル化プリファレンスを作成します。

これにより、ハイブリッド・ベクトル索引付けパイプラインのベクトル検索パラメータをカスタマイズできます。ベクトル化プリファレンスの目的は、様々なチャンク化または埋込みの戦略を深く理解していなくても、ドキュメントのチャンク化または埋込みを行う方法を構成できる簡単な方法を提供することです。

使用上の注意

ベクトル化プリファレンスは、次のチャンク化、埋込みまたはベクトル索引作成パラメータに関連するユーザー指定の値をまとめて保持するJSONオブジェクトです:

  • チャンク化(UTL_TO_CHUNKSおよびVECTOR_CHUNKS)

  • 埋込み(UTL_TO_EMBEDDINGUTL_TO_EMBEDDINGSおよびVECTOR_EMBEDDING)

  • ベクトル索引の作成(distanceaccuracyおよびvector_idxtype)

すべてのベクトル索引プリファレンスは、対応するDBMS_VECTORおよびDBMS_VECTOR_CHAIN APIに定義されているものと同じJSON構文に従います。

ベクトル化プリファレンスを作成した後、VECTORIZERパラメータを使用して、CREATE_HYBRID_VECTOR_INDEXおよびALTER_INDEX SQL文のPARAMETERS句のparamstringにこのプリファレンス名を渡すことができます。

プリファレンスの作成はオプションです。オプションのプリファレンスを指定しない場合、索引はシステムのデフォルトを使用して作成されます。

構文

DBMS_VECTOR_CHAIN.CREATE_PREFERENCE (
    PREF_NAME     IN VARCHAR2,
    PREF_TYPE     IN VARCHAR2,
    PARAMS        IN JSON default NULL
);

PREF_NAME

作成するベクトル化プリファレンスの名前を指定します。

PREF_TYPE

プリファレンスのタイプ。サポートされている唯一のプリファレンス・タイプは次のタイプです:

DBMS_VECTOR_CHAIN.VECTORIZER

PARAMS

ベクトル検索固有のパラメータをJSON形式で指定します:

埋込みパラメータ:

{ "model" : <embedding_model_for_vector_generation> }

次に例を示します。

{ "model" : MY_INDB_MODEL }

modelには、ONNX埋込みモデルがデータベースに格納されるときの名前を指定します。

ONNX形式のデータベース内埋込みモデルがない場合は、『Oracle Database AI Vector Searchユーザーズ・ガイド』に示されている手順を実行します。

チャンク化パラメータ:

{
    "by"           :  mode,
    "max"          :  max,
    "overlap"      :  overlap,
    "split"        :  split_condition,
    "vocabulary"   :  vocabulary_name,
    "language"     :  nls_language,
    "normalize"    :  normalize_mode,
    "extended"     :  boolean
}

次に例を示します。

JSON(
 '{ "by"           :    "vocabulary",
    "max"          :    "100",
    "overlap"      :    "0",
    "split"        :    "none",
    "vocabulary"   :    "myvocab",
    "language"     :    "american",
    "normalize"    :    "all" 
  }')

splitcustom、およびnormalizeoptionsを指定する場合は、custom_listパラメータとnorm_optionsパラメータをそれぞれ指定する必要があります。

JSON(
 '{ "by"           :    "vocabulary",
    "max"          :    "100",
    "overlap"      :    "0",
    "split"        :    "custom",
    "custom_list"  :    [ "<p>" , "<s>" ],
    "vocabulary"   :    "myvocab",
    "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制限で分割します。

  • newlineblanklineおよびspace:

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

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

  • recursively:

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

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

    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など)から始まります。

有効な値: max5%から20%

デフォルト値: 0

language

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

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

有効な値は次のとおりです。:

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

次に例を示します。

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 (Enダッシュ)は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の場合)

ベクトル索引のパラメータ:

{ 
  "distance"        :  <vector_distance>,
  "accuracy"        :  <vector_accuracy>, 
  "vector_idxtype"  :  <vector_idxtype>
}

次に例を示します。

{ 
  "distance"        :  COSINE,
  "accuracy"        :  95, 
  "vector_idxtype"  :  HNSW
}
パラメータ 説明

distance

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

  • COSINE
  • MANHATTAN
  • DOT
  • EUCLIDEAN
  • L2_SQUARED
  • EUCLIDEAN_SQUARED

ノート: 現在、HAMMINGおよびJACCARDベクトル距離メトリックはハイブリッド・ベクトル索引ではサポートされていません。

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

デフォルト値: COSINE

accuracy

ベクトル索引を使用して近似検索問合せを実行するときに近似検索を実行するターゲット精度。

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

  • Hierarchical Navigable Small World (HNSW)の近似検索の場合:

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

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

  • Inverted File Flat (IVF)の近似検索の場合:

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

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

HNSWとIVFの両方のベクトル索引の有効範囲は、次のとおりです:

> 0 and <= 100

デフォルト値: :なし

vector_idxtype

作成するベクトル索引のタイプ:

  • HNSW: HNSWベクトル索引の場合

  • IVF: IVFベクトル索引の場合

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

デフォルト値: IVF

Pathsパラメータ:

このフィールドでは、パス・オブジェクトの配列を指定できます。多数のパス・オブジェクトが存在する可能性があり、各パス・オブジェクトでtypeおよびpath_listを指定する必要があります。

ノート:

ユーザーがpathsフィールドを指定しない場合、ドキュメント全体が考慮されます。
"paths":[
        {"type"      : "<path_type>",
         "path_list" : ["<path_list_array>"]
        }
        ]

JSONドキュメントの例について考えてみましょう:

 {
      "person": 
       {
         "bio": "James is a data scientist who specializes in natural language .. ",
         "profile":
          {
              "text" : "James is a data scientist with expertise in Python programming...",
              "embedding" : [1.60541728E-001,5.76677322E-002,4.0473938E-003,1.2037459E-001,-5.98970801E-004, ..]
          },
         "avatar": "https://example.com/images/James.jpg"
       },
      "product": 
      {
        "description": "A social media analytics tool.", "It helps brands track...",
        "image": "https://example.com/images/data_tool.jpg",
        "embedding" : [1.60541728E-001,5.76677322E-002,4.0473938E-003,1.2037459E-001,-5.98970801E-004, ..]
      }
 }

前述のJSONに対応するpath_listを次に示します:

"paths": [
         {"type"       : "VECTOR",
          "path_list" : ["$.person.profile.embedding", "$.product.embedding"]
         },
         {"type"       : "STRING",
          "path_list" : ["$.person.bio", "$.product.description"]
         }
         ] 

次の表に、pathsパラメータの詳細を示します。

begin
  DBMS_VECTOR_CHAIN.CREATE_PREFERENCE(
    'my_vec_spec',
     DBMS_VECTOR_CHAIN.VECTORIZER,
     json('{ "vector_idxtype" :  "hnsw",
             "model"          :  "my_doc_model",
             "by"             :  "words",
             "max"            :  100,
             "overlap"        :  10,
             "split"          :  "recursively,
             "language"       :  "english",
             "paths":          : [
                                 {
                                  "type"      : "VECTOR",
                                  "path_list" : ["$.person.profile.embedding"]
                                  }
                                 ]  
              }'));
end;
/

CREATE HYBRID VECTOR INDEX my_hybrid_idx on 
    doc_table(text_column) 
    parameters('VECTORIZER my_vec_spec');

関連トピック