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

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

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

要件

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

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

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

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

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

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

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

  2. 「 ベクトル検索 」タブをクリックし、「 作成」をクリックします。

    エンドポイント フォームの作成

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

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

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を使用してベクトル検索エンドポイントを作成する

REST API リファレンスドキュメントを参照してください: POST /api/2.0/vector-search/endpoints。

(オプション)エンべディングモデルを提供するエンドポイントを作成して構成する

Databricksに埋め込みを許可する場合は、事前構成されたインフラストラクチャAPIsエンドポイントを使用するか、モデル サービス エンドポイントを作成して、選択した埋め込みモデルを提供できます。 手順については、「トークン単位の従量課金基盤モデルAPIまたは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を使用したインデックスの作成

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

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

  3. 右上の「 作成 」ボタンをクリックし、ドロップダウンメニューから「 ベクトル検索インデックス 」を選択します。

    [インデックスの作成] ボタン

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

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

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

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

    エンドポイント: 使用するベクトル検索エンドポイントを選択します。

    同期する列: ベクトル インデックスと同期する列を選択します。 このフィールドを空白のままにすると、ソース テーブルのすべての列がインデックスと同期されます。 主キー列と埋め込みソース列または埋め込みベクトル列は常に同期されます。

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

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

    • [ 既存のエンべディング列を使用] を選択した場合は、事前計算されたエンべディングとエンべディングディメンションを含む列を選択します。 事前計算されたエンべディング列の形式は array[float]である必要があります。

    コンピュートエンべディングを同期: 生成されたエンべディングをUnity Catalogテーブルに保存するには、この設定を切り替えます。 詳細については、 「生成されたエンべディングテーブルを保存する」を参照してください。

    同期モード: [連続] では 、インデックスと秒単位の待機時間の同期が維持されます。 ただし、コンピュート クラスターは継続的な同期ストリーミング パイプラインを実行するためのプロビジョニングであるため、それに関連するコストが高くなります。 トリガーの方がコスト効率は高くなりますが、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"
)

次の例では、自己管理型の埋め込みを使用して Delta Sync Index を作成します。 この例では、オプションのパラメーター columns_to_sync を使用して、インデックスで使用する列のサブセットのみを選択する方法も示しています。

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

デフォルトでは、ソーステーブルのすべてのカラムがインデックスと同期されます。 列のサブセットのみを同期するには、 columns_to_syncを使用します。 プライマリ・キーと埋め込みカラムは、常にインデックスに含まれます。

プライマリキーと埋め込みカラム のみを 同期するには、次のように columns_to_sync で指定する必要があります。

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

追加の列を同期するには、次のように指定します。 プライマリ・キーと埋め込みカラムは、常に同期されるため、含める必要はありません。

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

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


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

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

次のコード例は、個人用アクセストークン (PAT) を使用してインデックスを更新する方法を示しています。

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/upsert-data --data '{"inputs_json": "..."}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/delete-data --data '{"primary_keys": [...]}'

次のコード例は、サービスプリンシパルを使用してインデックスを更新する方法を示しています。

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "WriteVectorIndex"}'

# Generate OAuth token
export TOKEN=$(curl -X POST --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/upsert-data --data '{"inputs_json": "[...]"}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/delete-data --data '{"primary_keys": [...]}'

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

ベクトル検索エンドポイントをクエリできるのは、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
    )

REST API リファレンス ドキュメントを参照してください: POST /api/2.0/vector-search/indexes/{index_name}/query。

次のコード例は、個人用アクセストークン (PAT) を使用してインデックスをクエリする方法を示しています。

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Query Vector Search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

次のコード例は、サービスプリンシパルを使用してインデックスをクエリする方法を示しています。

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint (TODO: link), then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'

# Generate OAuth token
export TOKEN=$(curl -X POST  --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

重要

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

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

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

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

フィルター演算子

挙動

例

NOT

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

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

<

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

{"id <": 200}

<=

フィールド値がフィルター値以下であるかどうかを確認します。 キーの末尾は「<=」である必要があります。 たとえば、値が 200 の "price <=" は、価格が 200 以下のドキュメントと一致します。

{"id <=": 200}

>

フィールド値がフィルター値より大きいかどうかを確認します。 キーの末尾は「>」である必要があります。 たとえば、値が 200 の "price >" は、価格が 200 より大きいドキュメントと一致します。

{"id >": 200}

>=

フィールド値がフィルター値以上かどうかを確認します。 キーの末尾は「>=」である必要があります。 たとえば、値が 200 の "price >=" は、価格が 200 以上のドキュメントと一致します。

{"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エンドポイントを構成する方法を示しています。

Mosaic AI Model Serving ノートブックを使用して OpenAI 埋め込みモデルを呼び出す

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

Mosaic AI Model Serving ノートブックを使用して GTE 埋め込みモデルを呼び出す

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

OSSエンべディングモデルの登録とサービングのためのノートブック

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