メインコンテンツまでスキップ
に最終更新

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

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

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

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

要件​

ベクトル検索エンドポイントを作成および管理するためのアクセス許可は、アクセス制御リストを使用して構成されます。 ベクトル検索エンドポイント 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. タイプ フィールドで、 標準 または ストレージ最適化 を選択します。エンドポイントのオプションを参照してください。

  5. (オプション) 詳細設定 で、予算ポリシーを選択します。Mosaic AI Vector Search: 予算ポリシーをご覧ください。

  6. 確認 をクリックします。

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

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

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

エンべディングエンドポイントを構成する場合、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を使用してインデックスを作成する​

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

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

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

    インデックス作成ボタン

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

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

    名前 : 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 インデックスの更新を参照してください。

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

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

    クエリ用のモデルサービングエンドポイントを追加する

  5. インデックスの設定が完了したら、 「作成」 をクリックします。

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 を使用して同期を開始できます。

  1. Catalog Explorer で、「インデックス検索」に移動します。

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

    [今すぐ同期] ボタンを使用して、カタログ エクスプローラーからの検索インデックスを同期します。。

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

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

詳細については、 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
    }
])