ベクター検索インデックスを作成してクエリを実行する方法

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

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

要求事項

• Unity Catalog 対応ワークスペース。
• サーバーレス コンピューティングが有効になっている。 手順については、「サーバーレス コンピューティングに接続する」を参照してください。
• 標準エンドポイントの場合、ソース テーブルで Change Data Feed が有効になっている必要があります。 「Azure Databricks で Delta Lake 変更データ フィードを使用する」を参照してください。
• ベクター検索インデックスを作成するには、インデックスが作成されるカタログ スキーマに対する CREATE TABLE 権限が必要です。
• 別のユーザーが所有するインデックスに対してクエリを実行するには、追加の権限が必要です。 ベクター検索エンドポイントのクエリを参照してください。

ベクター検索エンドポイントを作成および管理するためのアクセス許可は、アクセス制御リストを使用して構成されます。 Vector 検索エンドポイント ACL を参照してください。

取り付け

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

%pip install databricks-vectorsearch
dbutils.library.restartPython()

次に、次のコマンドを使用して VectorSearchClientをインポートします。

from databricks.vector_search.client import VectorSearchClient

認証

データ保護と認証に関する説明を参照してください。

ベクター検索エンドポイントを作成する

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

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

UI を使用してベクター検索エンドポイントを作成するには、次の手順に従います。

1. 左側のサイドバーで、[ コンピューティング] をクリックします。

2. [ ベクター検索 ] タブをクリックし、[ 作成] をクリックします。

   

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

   

4. [ タイプ ] フィールドで、[ Standard ] または [ Storage Optimized] を選択します。 「エンドポイント オプション」を参照してください。

5. (省略可能)[ 詳細設定] で、予算ポリシーを選択します。 モザイク AI ベクター検索: 予算ポリシーを参照してください。

6. [Confirm](確認) をクリックします。

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 = VectorSearchClient(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

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

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

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

(省略可能)埋め込みモデルを提供するエンドポイントを作成して構成する

Databricks で埋め込みを計算するように選択した場合は、事前構成済みの Foundation Model API エンドポイントを使用するか、モデル サービス エンドポイントを作成して、任意の埋め込みモデルを提供できます。 手順については、「トークンごとの支払い基盤モデル API」または「エンドポイントにサービスを提供するエンドポイントを作成する」 を参照してください。 ノートブックの例については、 埋め込みモデルを呼び出すためのノートブックの例を参照してください。

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

ベクター検索インデックスを作成する

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

インデックスには次の 2 種類があります。

• 差分同期インデックス は、ソース差分テーブルと自動的に同期され、差分テーブルの基になるデータが変更されるとインデックスが自動的に増分更新されます。
• Direct Vector Access Index では、ベクトルとメタデータの直接読み取りと書き込みがサポートされます。 ユーザーは、REST API または Python SDK を使用してこのテーブルを更新する必要があります。 この種類のインデックスは、UI を使用して作成することはできません。 REST API または SDK を使用する必要があります。

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

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

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

3. 右上にある [ 作成 ] ボタンをクリックし、ドロップダウン メニューから ベクター検索インデックス を選択します。

   

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

   

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

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

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

   同期する列: (標準エンドポイントでのみサポートされます)。ベクター インデックスと同期する列を選択します。 このフィールドを空白のままにすると、ソース テーブルのすべての列がインデックスと同期されます。 主キー列と埋め込みソース列または埋め込みベクター列は常に同期されます。 ストレージ最適化エンドポイントの場合、ソース テーブルのすべての列は常に同期されます。

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

   • [ コンピューティング埋め込み] を選択した場合は、埋め込みを計算する列と、埋め込みモデルを提供するエンドポイントを選択します。 テキスト列のみがサポートされています。 大規模な埋め込み生成の場合、Databricks では、より高いスループットを得るためのトークンごとの支払い基盤モデル databricks-gte-large-en を使用することをお勧めします。
   • [ 既存の埋め込み列を使用] を選択した場合は、事前計算済みの埋め込みと埋め込みディメンションを含む列を選択します。 事前計算済み埋め込み列の形式は array[float]する必要があります。 ストレージ最適化エンドポイントの場合、埋め込みディメンションは 16 で均等に割り切れる必要があります。

   計算された埋め込みの同期: 生成された埋め込みを Unity カタログ テーブルに保存するには、この設定を切り替えます。 詳細については、「 生成された埋め込みテーブルを保存する」を参照してください。

   同期モード: 継続的に インデックスを秒単位の待機時間で同期します。 ただし、継続的同期ストリーミング パイプラインを実行するためにコンピューティング クラスターがプロビジョニングされるため、それに関連するコストは高くなります。 標準エンドポイントの場合、 継続的 更新と トリガー実行の 両方で増分更新が実行されるため、最後の同期以降に変更されたデータのみが処理されます。 ストレージ最適化エンドポイントの場合、すべての同期でベクター検索インデックスが完全に再構築されます。 ストレージ最適化エンドポイントの制限事項を参照してください。

   トリガーされた同期モードでは、Python SDK または REST API を使用して同期を開始します。差分同期インデックスの更新を参照してください。

   ストレージ最適化エンドポイントの場合、 トリガーされた 同期モードのみがサポートされます。

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

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

次の例では、Databricks によって計算された埋め込みを使用して差分同期インデックスを作成します。 詳細については、 Python SDK リファレンスを参照してください。

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

次の例では、自己管理型埋め込みを使用して差分同期インデックスを作成します。 この例では、オプションのパラメーター 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.
)

次の例では、Direct Vector Access インデックスを作成します。

client = VectorSearchClient()

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

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

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

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

Databricks で埋め込みを生成する場合は、生成された埋め込みを Unity カタログのテーブルに保存できます。 このテーブルは、ベクター インデックスと同じスキーマで作成され、ベクター インデックス ページからリンクされます。

テーブルの名前は、ベクター検索インデックスの名前で、 _writeback_tableが追加されます。 名前は編集できません。

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

ベクター検索インデックスを更新する

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

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

Databricks ユーザーインターフェース

1. カタログ エクスプローラーで、ベクター検索インデックスに移動します。

2. [ 概要 ] タブの [ データ取り込み ] セクションで、[ 今すぐ同期] をクリックします。

   。

Python SDK

詳細については、 Python SDK リファレンスを参照してください。

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

index.sync()

REST API

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

直接ベクター アクセス インデックスを更新する

Python SDK または REST API を使用して、直接ベクター アクセス インデックスのデータを挿入、更新、または削除できます。

Python SDK

詳細については、 Python SDK リファレンスを参照してください。

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

REST API

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

運用アプリケーションの場合、Databricks では、個人用アクセス トークンではなくサービス プリンシパルを使用することをお勧めします。 クエリあたり最大 100 ミリ秒でパフォーマンスを向上させることができます。

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

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": [...]}'

次のコード例は、個人用アクセス トークン (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": [...]}'

ベクター検索エンドポイントのクエリを実行する

ベクター検索エンドポイントのクエリは、Python SDK、REST API、または SQL vector_search() AI 関数を使用してのみ実行できます。

既定のクエリの種類は ann (近似最近隣) です。 ハイブリッド キーワード類似性検索を実行するには、パラメーター query_type を hybrid に設定します。 ハイブリッド検索では、すべてのテキスト メタデータ列が含まれており、最大 200 件の結果が返されます。

Python SDK 標準エンドポイント

詳細については、 Python SDK リファレンスを参照してください。

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

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

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.9] * 1024,
    columns=["id", "text"],
    num_results=2
    )

Python SDK ストレージ最適化エンドポイント

詳細については、 Python SDK リファレンスを参照してください。

既存のフィルター インターフェイスは、標準のベクター検索エンドポイントで使用されるフィルター ディクショナリではなく、より SQL に似たフィルター文字列を採用するように、ストレージ最適化ベクター検索インデックス用に再設計されています。

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

# similarity search with query vector
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
)

# similarity search with query vector and filter string
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    # this is a single filter string similar to SQL WHERE clause syntax
    filters="language = 'en' AND country = 'us'",
    num_results=2
)

REST API

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

運用アプリケーションの場合、Databricks では、個人用アクセス トークンではなくサービス プリンシパルを使用することをお勧めします。 セキュリティとアクセス管理の向上に加えて、サービス プリンシパルを使用すると、クエリあたり最大 100 ミリ秒のパフォーマンスを向上させることができます。

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

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, 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}'

次のコード例は、個人用アクセス トークン (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}'

SQL

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

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

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

次の表に、サポートされているフィルターの一覧を示します。

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

Python SDK 標準エンドポイント

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

Python SDK ストレージ最適化エンドポイント

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title IN ("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 = "Ares" OR id = "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 != "Hercules"',
    num_results=2
    )

REST API

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

いいね

LIKE 例

{"column LIKE": "apple"}: 文字列 "apple" と "apple pear" と一致しますが、"pineapple" または "pear" とは一致しません。 "pineapple" には部分文字列 "apple" が含まれていますが、それとは一致しないことに注意してください。"apple pear" のように空白で区切られたトークンとの正確な一致が探索されます。

{"column NOT LIKE": "apple"} は逆を行います。 "pineapple" や "pear" とは一致しますが、"apple" または "apple pear" とは一致しません。

ノートブックの例

このセクションの例では、ベクター検索 Python SDK の使用方法を示します。 リファレンス情報については、 Python SDK リファレンスを参照してください。

LangChain の例

LangChain パッケージとの統合と同様に、モザイク AI ベクター検索で LangChain を使用する方法を参照してください。

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

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

ノートブックを入手

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

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

モザイク AI モデル サービス ノートブックを使用して OpenAI 埋め込みモデルを呼び出す

ノートブックを入手

Mosaic AI Model Serving Notebook を使用して GTE 埋め込みモデルを呼び出す

ノートブックを入手

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

ノートブックを入手