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

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

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

要件

Unity Catalog が有効なワークスペース。
サーバレスコンピュートが有効になりました。
ソーステーブルでは変更データフィードが有効になっている必要があります。
インデックスを作成するには、カタログスキーマに対する CREATE TABLE 権限が必要です。別のユーザーが所有するインデックスを照会するには、追加の権限が必要です。「 Vector Search エンドポイントのクエリ」を参照してください。
個人用アクセストークンを使用する場合 (本番運用ワークロードには推奨されません)、個人用アクセストークンが有効になっていることを確認します。代わりにサービスプリンシパルトークンを使用するには、 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 を使用してベクトル検索エンドポイントを作成します。

左側のサイドバーで「コンピュート」をクリックします。
「 Vector Search 」タブをクリックし、「作成」をクリックします。
[ エンドポイントの作成] フォーム が開きます。このエンドポイントの名前を入力します。
「確認」をクリックします。

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 を使用したインデックスの作成

左のサイドバーで「カタログ」をクリックして、「 カタログ エクスプローラ」UIを開きます。
使用するDeltaテーブルに移動します。
右上の「作成」ボタンをクリックし、ドロップダウンメニューから「 ベクトル検索インデックス 」を選択します。
ダイアログのセレクタを使用して、インデックスを設定します。

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

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

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

埋め込みソース: Databricks でDeltaテーブル内のテキスト列の埋め込みをコンピュートするか (コンピュート embeddings )、 Deltaテーブルに事前計算された埋め込みが含まれるかどうか ( [既存の埋め込み列を使用] ) を示します。
- [コンピュート embeddings ]を選択した場合は、エンベディングをコンピュートする列と、エンベディングモデルを提供するエンドポイントを選択します。テキスト列のみがサポートされています。
- [ 既存の埋め込み列を使用] を選択した場合は、事前計算された埋め込みと埋め込みディメンションを含む列を選択します。事前計算された埋め込み列の形式は array[float]である必要があります。
コンピュート埋め込みを同期: 生成された埋め込みをUnity Catalogテーブルに保存するには、この設定を切り替えます。詳細については、「生成された埋め込みテーブルを保存する」を参照してください。

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

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を参照してください。

生成された埋め込みテーブルを保存する

Databricks が埋め込みを生成する場合、生成された埋め込みを Unity Catalog のテーブルに保存できます。このテーブルは、ベクトル索引と同じスキーマで作成され、ベクトル索引ページからリンクされます。

テーブルの名前は、ベクトル検索インデックスの名前に _writeback_tableを付けたものです。名前は編集できません。

Unity Catalog 内の他のテーブルと同様に、テーブルにアクセスしてクエリを実行できます。ただし、テーブルは手動で更新することを意図していないため、削除または変更しないでください。インデックスが削除されると、テーブルも自動的に削除されます。

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

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) を参照してください。

Vector Searchエンドポイントをクエリーする

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

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

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

クエリでは、 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`は、`color1` が `red` または `color2` が `blue`のドキュメントと一致します。	`{"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
    )

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

ノートブックの例

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

LangChainの例

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

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

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

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

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

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