Vector Searchインデックスの作成とクエリー

プレビュー

この機能はパブリックプレビュー段階です。

この記事では、 Databricks Vector Search を使用してベクター検索インデックスを作成してクエリーする方法について説明します。

Vector SearchUI、 Python SDK 、または REST API を使用して、ベクトル検索エンドポイントやベクトル検索インデックスなどの コンポーネントを作成および管理できます。

要件

  • Unity Catalog が有効なワークスペース。

  • サーバレスコンピュートが有効になりました。

  • ソーステーブルでは変更データフィードが有効になっている必要があります。

  • インデックスを作成するには、カタログ スキーマに対する CREATE TABLE 権限が必要です。 別のユーザーが所有するインデックスを照会するには、追加の権限が必要です。 「 Vector Search エンドポイントのクエリ 」を参照してください。

  • personal アクセストークン (本番運用ワークロードには推奨されません) を使用する場合は、 Personal アクセストークンが有効になっていることを確認します。 代わりにサービスプリンシパルトークンを使用するには、SDK または API 呼び出しを使用して明示的に渡します。

SDK を使用するには、ノートブックに SDK をインストールする必要があります。 次のコードを使用します。

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

ベクトル検索エンドポイントの作成

Databricks UI、Python SDK、または API を使用して、ベクター検索エンドポイントを作成できます。

UI を使用してベクトル検索エンドポイントを作成するCreate a vector search endpoint using the UI

これらのステップに従って、UI を使用してベクトル検索エンドポイントを作成します。

  1. 左側のサイドバーで「コンピュート」をクリックします。

  2. Vector Search 」タブをクリックし、「 作成」をクリックします。

    エンドポイント フォームの作成
  3. [ エンドポイントの作成] フォーム が開きます。このエンドポイントの名前を入力します。

  4. 「確認」をクリックします。

Python SDK を使用してベクトル検索エンドポイントを作成する

次の例では、 create_endpoint() SDK 関数を使用して Vector Search エンドポイントを作成します。

# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearch(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD"
)

REST APIを使用してベクトル検索エンドポイントを作成する

POST /api/2.0/vector-search/endpointsを参照してください。

(オプション)埋め込みモデルを提供するエンドポイントを作成して構成する

Databricks で埋め込みをコンピュートすることを選択した場合は、埋め込みモデルを提供するためにモデルビングサー エンドポイントをセットアップする必要があります。 手順については、 エンドポイントを提供する基盤モデルの作成を参照してください。 ノートブックの例については、 「埋め込みモデルを呼び出すためのノートブックの例」を参照してください。

埋め込みエンドポイントを構成する場合、Databricks では、デフォルトの選択であるScale to zeroを削除することをお勧めします。 エンドポイントの提供にはウォームアップに数分かかる場合があり、スケールダウンされたエンドポイントを持つインデックスに対する最初のクエリがタイムアウトする可能性があります。

注:

埋め込みエンドポイントがデータセットに対して適切に構成されていない場合、ベクトル検索インデックスの初期化がタイムアウトになる可能性があります。 CPU エンドポイントは、小規模なデータセットとテストにのみ使用してください。 大規模なデータセットの場合は、最適なパフォーマンスを得るために GPU エンドポイントを使用します。

ベクトル検索インデックスの作成

ベクトル検索インデックスは、UI、Python SDK、または REST API を使用して作成できます。 UI は最も単純なアプローチです。

インデックスには 2 つのタイプがあります。

  • Delta同期インデックスは、ソースDeltaテーブルと自動的に同期し、 Deltaテーブル内の基礎となるデータの変更に応じてインデックスを自動的に増分更新します。

  • ダイレクト・ベクトル・アクセス・インデックス は、ベクターとメタデータの直接読み取りと書き込みをサポートします。 ユーザーは、REST API または Python SDK を使用してこのテーブルを更新する必要があります。 この種類のインデックスは、UI を使用して作成することはできません。 REST API または SDK を使用する必要があります。

UI を使用したインデックスの作成

  1. 左のサイドバーで「カタログ」をクリックして、「 カタログ エクスプローラ」UIを開きます。

  2. 使用するDeltaテーブルに移動します。

  3. 右上のケバブメニューから、 ベクター検索インデックスの作成を選択します。

    [インデックスの作成] ボタン
  4. ダイアログのセレクタを使用して、インデックスを設定します。

    [インデックスの作成] ダイアログ

    名前: Unity Catalogのオンライン テーブルに使用する名前。 この名前には、3 レベルの名前空間 <catalog>.<schema>.<name>が必要です。 使用できるのは、英数字とアンダースコアのみです。

    主キー: 主キーとして使用する列。

    エンドポイント: 使用するモデルサービングエンドポイントを選択します。

    埋め込みソース: Databricks でDeltaテーブル内のテキスト列の埋め込みをコンピュートするか (コンピュート embeddings )、 Deltaテーブルに事前計算された埋め込みが含まれるかどうか ( [既存の埋め込み列を使用] ) を示します。

    • [コンピュート embeddings ]を選択した場合は、エンベディングをコンピュートする列と、エンベディング モデルを提供するエンドポイントを選択します。 テキスト列のみがサポートされています。

      • [ 既存の埋め込み列を使用] を選択した場合は、事前計算された埋め込みと埋め込みディメンションを含む列を選択します。

    同期モード: [連続] では 、インデックスと秒単位の待機時間の同期が維持されます。 ただし、コンピュート クラスターは継続的な同期ストリーミング パイプラインを実行するためのプロビジョニングであるため、それに関連するコストが高くなります。 トリガーの方がコスト効率は高くなりますが、API を使用して手動で開始する必要があります。 [継続的] と [トリガー] のどちらの場合も、更新は増分であり、最後の同期以降に変更されたデータのみが処理されます。

  5. インデックスの構成が完了したら、[ 作成] をクリックします。

Python SDKを使用してインデックスを作成する

次の例では、Databricks による埋め込みコンピュートを使用してDelta同期インデックスを作成します。

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type='TRIGGERED',
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2"
)

次の例では、ダイレクト ベクトル アクセス インデックスを作成します。


client = VectorSearchClient()

index = client.create_direct_access_index(
    endpoint_name="storage_endpoint",
    index_name="{catalog_name}.{schema_name}.{index_name}",
    primary_key="id",
    embedding_dimension=1024,
    embedding_vector_column="text_vector",
    schema={
     "id": "int",
     "field2": "str",
     "field3": "float",
     "text_vector": "array<float>"}
)

REST APIを使用してインデックスを作成する

POST /api/2.0/vector-search/indexesを参照してください。

ベクトル検索インデックスの更新

Delta同期インデックスを更新する

継続同期モードで作成されたインデックスは、ソースDeltaテーブルが変更されると自動的に更新されます。 トリガー同期モードを使用している場合は、Python SDK または REST API を使用して同期を開始できます。

index.sync()

REST API (POST /api/2.0/vector-search/indexes/{index_name}/sync) を参照してください。

ダイレクト・ベクトル・アクセス索引の更新

Python SDK または REST API を使用して、Direct Vector Access Index からデータを挿入、更新、または削除できます。

   index.upsert([{"id": 1,
       "field2": "value2",
       "field3": 3.0,
       "text_vector": [1.0, 2.0, 3.0]
       },
       {"id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1, 2.1, 3.0]
        }
        ])

REST API (POST /api/2.0/vector-search/indexes) を参照してください。

クエリー a Vector Search endpoint

Vector Search エンドポイントのクエリを実行できるのは、Python SDK または REST API を使用した場合のみです。

注:

エンドポイントを照会するユーザーがベクトル検索インデックスの所有者でない場合、そのユーザーには次の UC 権限が必要です。

  • ベクトル検索インデックスを含むカタログに対して USE CATALOG を使用します。

  • ベクトル検索インデックスを含むスキーマで USE SCHEMA を使用します。

  • ベクトル検索インデックスの SELECT。

results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

results

クエリでフィルターを使用する

クエリでは、 Deltaテーブル内の任意の列に基づいてフィルターを定義できます。 similarity_search は、指定されたフィルターに一致する行のみを返します。 次のフィルターがサポートされています。

フィルター演算子

挙動

NOT

フィルターを無効にします。 キーは「NOT」で終わる必要があります。 たとえば、"color NOT" と値 "red" は、色が赤ではないドキュメントと一致します。

{"id NOT": 2} {“color NOT”: “red”}

<

フィールド値がフィルタ値より小さいかどうかをチェックします。 キーは「<」で終わる必要があります。 たとえば、値が 100 の "price <" は、価格が 100 未満のドキュメントと一致します。

{"id <": 200}

<=

フィールド値がフィルタ値以下かどうかをチェックします。 キーは「<=」で終わる必要があります。 たとえば、値が 100 の "price <=" は、価格が 100 以下のドキュメントと一致します。

{"id <=": 200}

>

フィールド値がフィルタ値より大きいかどうかをチェックします。 キーは「>」で終わる必要があります。 たとえば、値が 100 の "price >" は、価格が 100 より大きいドキュメントと一致します。

{"id >": 200}

>=

フィールド値がフィルタ値以上かどうかをチェックします。 キーは「>=」で終わる必要があります。 たとえば、値が 100 の "price >=" は、価格が 100 以上のドキュメントと一致します。

{"id >=": 200}

OR

フィールド値がフィルタ値のいずれかと一致するかどうかをチェックします。 キーには、複数のサブキーを区切るための OR が含まれている必要があります。 たとえば、値 ["red", "blue"]color1 OR color2は、color1red または color2blueのドキュメントと一致します。

{"color1 OR color2": ["red", "blue"]}

LIKE

部分的な文字列と一致します。

{"column LIKE": "hello"}

フィルター演算子が指定されていません

フィルターは、完全一致をチェックします。 複数の値を指定した場合は、どの値にも一致します。

{"id": 200} {"id": [200, 300]}

次のコード例を参照してください。

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]}
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]}
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"}
    num_results=2
    )

ノートブックの例

このセクションの例では、Vector Search Python SDK の使用方法を示します。

LangChainの例

LangChain パッケージとの統合として Databricks Vector Search を使用するには、「 Databricks Vector Search で LangChain を使用する方法 」を参照してください。

次のノートブックは、類似検索結果をLangChainドキュメントに変換する方法を示しています。

Vector SearchPython SDK ノートブック を使用した

ノートブックを新しいタブで開く

埋め込みモデルを呼び出すためのノートブックの例

次のノートブックは、埋め込み生成用に Databricks モデルサービング エンドポイントを構成する方法を示しています。

Databricks を使用して OpenAI 埋め込みモデルを呼び出す モデルサービング ノートブック

ノートブックを新しいタブで開く

Databricks を使用して BGE 埋め込みモデルを呼び出す モデルサービング ノートブック

ノートブックを新しいタブで開く

OSS埋め込みモデルノートブックを登録して提供します

ノートブックを新しいタブで開く