ベクトル検索エンドポイントとインデックスを作成する

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

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

たとえば、ベクトル検索エンドポイントを作成してクエリする方法を説明するノートブックについては、ベクトル検索の例を参照してください。リファレンス情報については、 Python SDK リファレンスを参照してください。

要件

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

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

インストール

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

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

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

from databricks.vector_search.client import VectorSearchClient

認証に関する情報については、「データ保護と認証」を参照してください。

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

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

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

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

左側のサイドバーで 「コンピュート」 をクリックします。
[検索] タブをクリックし、 [エンドポイントの作成] をクリックします。
エンドポイントの作成フォーム が開きます。このエンドポイントの名前を入力します。
タイプ フィールドで、標準または ストレージ最適化 を選択します。エンドポイントのオプションを参照してください。
(オプション) 詳細設定 で、予算ポリシーを選択します。Mosaic AI Vector Search: 予算ポリシーをご覧ください。
確認をクリックします。

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

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

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

高スループットのワークロード向けに最小 QPS ターゲットを持つエンドポイントを作成する

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。「Databricks プレビューの管理」を参照してください。

高スループットのワークロードの場合、最小 QPS ターゲットを設定したエンドポイントを作成できます。この機能は標準エンドポイントでのみ使用できます。

最小 QPS 目標を設定するには、 min_qpsを使用します。「高 QPS によるエンドポイントスループットのスケーリング (ベータ版)」を参照してください。

重要

min_qpsを設定すると追加の容量がプロビジョニングされ、エンドポイントのコストが増加します。実際のクエリトラフィックに関係なく、この追加容量に対して料金が発生します。これらの料金の発生を停止するには、 min_qps=-1を使用してエンドポイントをリセットします。スループットのスケーリングはベストエフォートであり、ベータ期間中は保証されません。

Python
client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD",
    min_qps=500,  # Beta: minimum QPS target for high-throughput workloads
)

既存のエンドポイントの最小 QPS を変更するには、 update_endpoint()を使用します。

Python
from databricks.vector_search.client import VectorSearchClient, MIN_QPS_RESET_TO_DEFAULT

client = VectorSearchClient()

# Set or update minimum QPS
response = client.update_endpoint(name="vector_search_endpoint_name", min_qps=500)

# Check scaling status
scaling_info = response.get("endpoint", {}).get("scaling_info", {})
print(f"State: {scaling_info.get('state')}")  # SCALING_CHANGE_IN_PROGRESS or SCALING_CHANGE_APPLIED

# Remove high QPS configuration and return to default
client.update_endpoint(name="vector_search_endpoint_name", min_qps=MIN_QPS_RESET_TO_DEFAULT)

最小 QPS を更新した後、インデックスを同期して新しい構成を適用します。

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

Databricksで埋め込みをコンピュートすることを選択した場合は、事前構成された基盤モデルAPIエンドポイントを使用するか、選択した埋め込みモデルを提供するモデルサービングエンドポイントを作成できます。手順については、トークン単位の従量課金基盤モデルAPIまたは基盤モデルサービングエンドポイントの作成を参照してください。たとえば、ノートブックについては、ベクトル検索サンプルノートブックを参照してください。

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

注記

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

ベクトル検索インデックスを作成する

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

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

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

注記

列名_idは予約されています。ソーステーブルに_idという名前の列がある場合は、ベクトル検索インデックスを作成する前に名前を変更してください。

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

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

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

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

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

エンべディングソース : Databricks でDeltaテーブル内のテキスト列のエンべディングをコンピュートするか ( エンベディングの計算 )、 Deltaテーブルに事前計算されたエンべディングが含まれるかどうか ( 既存のエンべディング列を使用 ) を示します。
- [埋め込みをコンピュート] を選択した場合は、埋め込みをコンピュートする列と、計算に使用する埋め込みモデルを選択します。テキスト列のみがサポートされます。
  - 標準エンドポイントを使用する本番運用アプリケーションの場合、 Databricksプロビジョニングスループットサービングエンドポイントを備えた基盤モデルdatabricks-gte-large-enを使用することを推奨します。
  - Databricksでホストされるモデルでストレージ最適化エンドポイントを使用する本番運用アプリケーションの場合は、埋め込みモデルエンドポイントとしてモデル名を直接使用します (たとえば、 databricks-gte-large-en )。ストレージ最適化エンドポイントは、取り込み時にバッチ推論でai_queryを使用し、埋め込みジョブに高いスループットを提供します。クエリにプロビジョニングされたスループットエンドポイントを使用する場合は、インデックスを作成するときにmodel_endpoint_name_for_queryフィールドに指定します。
- 既存の埋め込み列を使用 を選択した場合は、事前計算された埋め込みと埋め込みディメンションを含む列を選択します。事前計算された埋め込み列の形式は array[float]である必要があります。ストレージ最適化エンドポイントの場合、埋め込みディメンションは 16 で均等に割り切れる必要があります。
計算されたエンベディングの同期 : この設定を切り替えて、生成されたエンベディングを Unity Catalog テーブルに保存します。詳細については、「生成されたエンベディングテーブルの保存」を参照してください。

ベクトル検索エンドポイント : インデックスを保存するためのベクトル検索エンドポイントを選択します。

同期モード : 連続は、インデックスを数秒の待機時間と同期させます。ただし、継続的な同期ストリーミングパイプラインを実行するためにコンピュートクラスターをプロビジョニングするため、コストが高くなります。
- 標準エンドポイントの場合、連続と トリガー の両方が増分更新を実行するため、最後の同期以降に変更されたデータのみが処理されます。
- ストレージ最適化エンドポイントの場合、同期ごとにインデックスが部分的に再構築されます。後続の同期の管理インデックスの場合、ソース行が変更されていない生成された埋め込みは再利用されるため、再計算する必要はありません。ストレージ最適化エンドポイントの制限事項を参照してください。
トリガー モードでは、Python SDK または REST API を使用して同期を開始します。Delta Sync インデックスの更新を参照してください。

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

詳細設定 : (オプション)
- インデックスに予算ポリシーを適用できます。Mosaic AI Vector Search: 予算ポリシーを参照してください。
- [コンピュート embeddings ] を選択した場合は、別の埋め込みモデルを指定して、一斉検索インデックスをクエリできます。これは、取り込みには高スループットのエンドポイントが必要だが、インデックスのクエリには低レイテンシのエンドポイントが必要な場合に役立ちます。 埋め込みモデル フィールドで指定されたモデルは、ここで別のモデルを指定しない限り、常に取り込みに使用され、クエリにも使用されます。別のモデルを指定するには、 「インデックスのクエリに別の埋め込みモデルを選択」 をクリックし、ドロップダウンメニューからモデルを選択します。
インデックスの設定が完了したら、 「作成」 をクリックします。

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

次の例では、Databricksによって計算されるエンべディングを用いたDelta Sync Indexを作成します。詳細については、 Python SDK リファレンスを参照してください。

この例では、オプションのパラメーターmodel_endpoint_name_for_queryも示しています。これは、インデックスのクエリに使用される別の埋め込みモデルサービングエンドポイントを指定します。

Python
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", # This model is used for ingestion, and is also used for querying unless model_endpoint_name_for_query is specified.
  model_endpoint_name_for_query="e5-mini-v2"   # Optional. If specified, used only for querying the index.
)

次の例では、自己管理型のエンベディングを使用して Delta Sync Index を作成します。

Python
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 で指定する必要があります。

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

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

Python
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.
)

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

Python

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 Catalog のテーブルに保存できます。このテーブルは、ベクトル索引と同じスキーマで作成され、ベクトル索引ページからリンクされます。

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

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

ベクトル検索インデックスを更新する

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

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

Databricks UI
Python SDK
REST API

Catalog Explorer で、「ベクトル検索インデックス」に移動します。
概要タブの データ取り込み セクションで、 今すぐ同期 をクリックします。

。

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

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

index.sync()

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

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

Python SDK
REST API

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

Python
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 リファレンスドキュメントを参照してください: POST /api/2.0/vector-search/indexes 。

本番運用アプリケーションの場合、 Databricks はパーソナルアクセストークンの代わりにサービスプリンシパルを使用することをお勧めします。パフォーマンスは、クエリごとに最大 100 ミリ秒向上できます。

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

sh
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) を使用してインデックスを更新する方法を示しています。

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

ダウンタイムなしでスキーマを変更する方法

ソーステーブル内の既存の列のスキーマが変更された場合は、インデックスを再構築する必要があります。書き戻しテーブルが有効になっている場合は、ソーステーブルに新しい列が追加されたときにインデックスを再構築する必要もあります。書き戻しテーブルが有効になっていない場合、新しい列のインデックスを再構築する必要はありません。

次のステップに従って、ダウンタイムなしでインデックスを再構築してデプロイします。

ソーステーブルでスキーマの変更を実行します。
新しいインデックスを作成します。
新しいインデックスの準備ができたら、トラフィックを新しいインデックスに切り替えます。
元のインデックスを削除します。

要件​

インストール​

ベクトル検索エンドポイントを作成する​

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

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

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

高スループットのワークロード向けに最小 QPS ターゲットを持つエンドポイントを作成する​

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

ベクトル検索インデックスを作成する​

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

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

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

生成されたエンベディングテーブルを保存​

ベクトル検索インデックスを更新する​

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

直接ベクトルアクセスインデックスを更新する​

ダウンタイムなしでスキーマを変更する方法​

要件