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

通用検索インデックスを作成してクエリする方法

この記事では、 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 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テーブルに事前計算されたエンべディングが含まれるかどうか ( 既存のエンべディング列を使用 ) を示します。

    • [コンピュート embeddings ] を 選択した場合は、エンベディングをコンピュートする列と、計算に使用するエンベディング モデルを選択します。 テキスト列のみがサポートされます。本番運用アプリケーションの場合、 Databricksプロビジョニング スループット サービング エンドポイントを備えた基盤モデルdatabricks-gte-large-enを使用することをお勧めします。
    • 既存の埋め込み列を使用 を選択した場合は、事前計算された埋め込みと埋め込みディメンションを含む列を選択します。事前計算された埋め込み列の形式は 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
    }
])

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

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

注記

エンドポイントにクエリを実行するユーザーが一斉検索インデックスの所有者ではない場合、ユーザーは次の UC 権限を持っている必要があります。

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

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

クエリでリランカーを使用するには、 「クエリでリランカーを使用する」を参照してください。

備考

ベータ版

全文検索はベータ機能として利用できます。全文検索を実行するには、パラメーターquery_typeをFULL_TEXTに設定します。 全文検索では、ベクトルエンべディングを使用せずに、キーワードの一致に基づいて最大 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 using full-text search (Beta)
results4 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="FULL_TEXT"
    )

# 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 符号) 演算子を参照してください。

標準 ： {"id NOT": 2} {“color NOT”: “red”}

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

<

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

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

標準 ： {"id <": 200}

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

<=

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

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

標準 ： {"id <=": 200}

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

>

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

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

標準 ： {"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
    )

クエリでリランカーを使用する​

備考

プレビュー

この機能は パブリック プレビュー段階です。

エージェントのパフォーマンスは、クエリに最も関連性の高い情報を取得するかどうかに依存します。再ランク付けは、取得したドキュメントを評価して、意味的に最も関連性の高いドキュメントを特定することで、検索品質を向上させる手法です。Databricks は、これらの文書を識別するための研究ベースの複合AI システムを開発しました。また、各ドキュメントの関連性を評価するときに、リランカーが追加のコンテキストに使用するメタデータを含む列を指定することもできます。

再ランク付けにより、若干の遅延が発生しますが、検索品質とエージェントのパフォーマンスが大幅に向上します。Databricks では、あらゆる RAG エージェントの使用例で再ランク付けを試すことを推奨しています。

このセクションの例では、ベクトル検索リランカーの使用方法を示します。再ランク付け機能を使用する場合、返される列 ( columns ) と再ランク付けに使用するメタデータ列 ( columns_to_rerank ) を個別に設定します。num_results返される結果の最終的な数です。これは、再ランク付けに使用される結果の数には影響しません。

クエリ デバッグ メッセージには、ステップの再ランキングにかかった時間に関する情報が含まれています。 例えば：

Bash
'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}

再ランク付け呼び出しが失敗した場合、その情報はデバッグ メッセージに含まれます。

Bash
'debug_info': {'response_time': 587.0, 'ann_time': 331.0, 'reranker_time': 246.0, 'warnings': [{'status_code': 'RERANKER_TEMPORARILY_UNAVAILABLE', 'message': 'The reranker is temporarily unavailable. Results returned have not been processed by the reranker. Please try again later for reranked results.'}]}
注記

columns_to_rerankにリストされる列の順序は重要です。再ランク付けの計算では、列がリストされている順序で取得され、見つかった最初の 2000 文字のみが考慮されます。

Python
# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-vectorsearch --force-reinstall
dbutils.library.restartPython()
Python
from databricks.vector_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create a Vector Search index",
    columns = ["id", "text", "parent_doc_summary", "date"],
    num_results = 10,
    query_type = "hybrid",
    reranker=DatabricksReranker(columns_to_rerank=["text", "parent_doc_summary", "other_column"])
    )

ノートブックの例​

このセクションの例では、ベクトル検索 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

OAuthトークンでVector Searchを使う​

次のノートブックでは、Vector Search SDKまたは新しいOAuthトークンを使用して HTTP を使用して、Vector Searchエンドポイントを呼び出す方法を示します。

OAuthトークンでVector Searchを使うノートブック

Open notebook in new tab
に最終更新