ベクトル検索インデックスの作成とクエリー

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

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

要件

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

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

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

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

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

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

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

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

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

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

# 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に埋め込みを許可する場合は、事前構成されたインフラストラクチャAPIsエンドポイントを使用するか、モデルサービスエンドポイントを作成して、選択した埋め込みモデルを提供できます。手順については、「トークン単位の従量課金基盤モデルAPIsまたはAIモデル生成サービスエンドポイントの作成」を参照してください。たとえば、埋め込みモデルを呼び出すための「ドイツ語」の例を参照してください。

エンべディングエンドポイントを構成する場合、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"
)

次の例では、自己管理型の埋め込みを使用して Delta Sync Index を作成します。

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_dimension=1024,
  embedding_vector_column="text_vector"
)

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

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 Syncインデックスを更新する

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

index.sync()

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

Direct Vector Access Indexの更新

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

ベクトル検索エンドポイントをクエリーする

ベクトル検索エンドポイントをクエリできるのは、Python SDK、REST API、または SQL vector_search() AI 関数を使用する場合のみです。

注：

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

ベクトル検索インデックスを含むカタログに対して USE CATALOG を使用します。
ベクトル検索インデックスを含むスキーマで USE SCHEMA を使用します。
ベクトル検索インデックスの SELECT。

ハイブリッドキーワード類似性検索を実行するには、引数query_typeをhybridに設定します。デフォルト値はann (近似最近傍) です。

# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

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

重要

vector_search() AI 機能はパブリックプレビュー段階です。

このAI 関数を使用するには、 vector_search 関数を参照してください。

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

クエリでは、 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 を参照してください。

ノートブックの例

このセクションの例では、ベクトル検索Python SDK の使用方法を示します。

LangChainの例

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

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

Python SDK ノートブックを使用したベクトル検索

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

エンべディングモデルを呼び出すためのノートブックの例

次の例は、埋め込み生成用にMosaic AI Model Servingエンドポイントを構成する方法を示しています。