メインコンテンツまでスキップ

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

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

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

必要条件​

ベクトル検索エンドポイントを作成および管理するためのアクセス許可は、アクセス制御リストを使用して構成されます。 ベクトル検索エンドポイント 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に計算させることを選択した場合は、事前に構成された基盤モデル API エンドポイントを使用するか、モデルサービング エンドポイントを作成して、選択したエンベディングモデルを提供できます。 手順については、トークン単位の従量課金 基盤モデル API または エンドポイント基盤モデルをサービングするエンドポイントの作成を参照してください。ノートブックの例については、 エンベディングモデルを呼び出すためのノートブックの例を参照してください。

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

注記

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

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

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

インデックスには、次の 2 つのタイプがあります。

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

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

UI を使用したインデックスの作成​

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

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

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

    インデックス作成ボタン

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

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

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

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

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

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

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

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

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

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

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

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

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

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

次の例では、埋め込みコンピュートDelta by a の を使用して Sync IndexDatabricks を作成します。詳細については、 Python SDK リファレンスを参照してください。

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

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

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

次の例では、Direct Vector Access Index を作成します。

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 Sync インデックスの更新​

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

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

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

    「Sync now」ボタンをクリックすると、カタログエクスプローラーからベクトル検索インデックスを同期できます。.

Direct Vector Access インデックスの更新​

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
    }
])

ベクトル検索エンドポイントのクエリ​

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

注記

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

  • ベクトル検索インデックスを含むカタログ上のUSE CATALOG。
  • ベクトル検索インデックスを含むスキーマに対して USE SCHEMA。
  • ベクトル検索インデックスに対するSELECT権限。

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

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

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

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

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

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

フィルター演算子

挙動

例

NOT

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

ストレージ最適化 : != (bangeq sign) 演算子を参照してください。

スタンダード : {"id NOT": 2} {“color NOT”: “red”}

ストレージ最適化 : "id != 2" "color != 'red'"

<

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

ストレージ最適化 : < (lt 記号) 演算子を参照してください。

スタンダード : {"id <": 200}

ストレージ最適化 : "id < 200"

<=

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

ストレージ最適化 : <= (lt eq sign) 演算子を参照してください。

スタンダード : {"id <=": 200}

ストレージ最適化 : "id <= 200"

>

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

ストレージ最適化 : > (gt 記号) 演算子を参照してください。

スタンダード : {"id >": 200}

ストレージ最適化 : "id > 200"

>=

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

ストレージ最適化 : >= (gt eq sign) 演算子を参照してください。

スタンダード : {"id >=": 200}

ストレージ最適化 : "id >= 200"

OR

標準 : フィールド値がフィルター値のいずれかと一致するかどうかを確認します。キーには、複数のサブキーを区切る OR が含まれている必要があります。たとえば、値が ["red", "blue"] の color1 OR color2 は、color1 が red であるか、color2 が blueのドキュメントと一致します。

ストレージ最適化 : or演算子を参照してください。

スタンダード : {"color1 OR color2": ["red", "blue"]}

ストレージ最適化 : "color1 = 'red' OR color2 = 'blue'"

LIKE

標準 : 文字列内の空白で区切られたトークンを照合します。以下のコード例を参照してください。

ストレージ最適化 : like演算子を参照してください。

スタンダード : {"column LIKE": "hello"}

ストレージ最適化 : "column LIKE 'hello'"

フィルタ演算子が指定されていません

標準 : フィルターは完全一致をチェックします。複数の値を指定すると、いずれかの値に一致します。

ストレージ最適化 : = (eq 符号) 演算子とin述語を参照してください。

スタンダード : {"id": 200} {"id": [200, 300]}

ストレージ最適化 : "id = 200" "id IN (200, 300)"

to_timestamp (ストレージ最適化エンドポイントのみ)

ストレージ最適化 : タイムスタンプでフィルタリングします。to_timestamp機能を見る

ストレージ最適化 : "date > TO_TIMESTAMP('1995-01-01')"

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

Python
# 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 の使用法を示します。リファレンス情報については、 Python SDK リファレンスを参照してください。

LangChain の例​

LangChainパッケージとの統合と同様にMosaic AI Vector Searchを使用するには、LangChainでMosaic AI Vector Searchを使用する方法 を参照してください。

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

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

Open notebook in new tab

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

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

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

Open notebook in new tab

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

Open notebook in new tab

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

Open notebook in new tab
に最終更新