AI 検索インデックス リソースを Databricks アプリに追加する
アプリケーションでセマンティック検索と類似性に基づく検索を有効にするために、Databricks Apps のリソースとしてAI Search インデックスを追加します。AI Searchインデックスは、高次元ベクトル埋め込みを保存およびクエリし、検索拡張生成(RAG)、セマンティック検索、および推奨システムなどのユースケースを強化します。
Databricks AI Search(旧 Databricks ベクトル検索)でした。
特権要件
AI Searchインデックスにアクセスするには、アプリのサービスプリンシパルは、親カタログに対するUSE CATALOG権限、親スキーマに対するUSE SCHEMA権限、およびインデックスに対するSELECT権限を持っている必要があります。インデックスリソースを追加すると、Databricksは自動的にこれらの権限をアプリのサービスプリンシパルに付与します。
この自動付与が成功するには、権限ごとに次のいずれかが当てはまる必要があります。
USE CATALOGの場合: すべてのアカウント ユーザーがカタログに対してUSE CATALOG権限を持っているか、カタログに対してMANAGE権限を持っています。USE SCHEMAの場合: すべてのアカウント ユーザーがスキーマに対するUSE SCHEMA権限を持っているか、またはスキーマに対するMANAGE権限を持っています。SELECTの場合: すべてのアカウント ユーザーがインデックスに対してSELECT権限を持っているか、またはユーザーがインデックスに対してMANAGE権限を持っています。
インデックスが Databricks 管理埋め込みモデル をプロビジョニング済み throughputまたはカスタムサービングEndpointで使用している場合、そのEndpointを クエリー可能 の権限を持つ アプリリソースとして追加 し、さらに個別のクエリー埋め込みEndpoint(model_endpoint_name_for_query )も追加してください。get_index()がこれらのEndpointを読み取り、アクセス権がないために失敗します。トークン単位の従量課金基盤モデルAPIs Endpoint(databricks-gte-large-enなど)では、アカウントがUnity Catalog権限で基盤モデルを制限している場合を除き、アプリリソースは必要ありません。その場合、Service Principalはモデルに対してEXECUTEが必要です。「Service Principalを設定する」を参照してください。
これらのアクセス許可を使用して AI Searchインデックスのクエリに関する詳細については、「AI Searchインデックスをクエリする方法」を参照してください。
Unity Catalog権限に関するリファレンスを参照してください。
AI Searchインデックス リソースを追加
AI Search インデックスをリソースとして追加する前に、アプリのリソースの前提条件を確認してください。
-
アプリを作成する際の アプリリソース セクション、またはアプリを編集する際の 設定 > リソース で、 + リソースを追加 > ベクトル検索インデックス をクリックします。
-
ワークスペースにある利用可能なAI Searchインデックスから選択してください。インデックスはUnity Catalogにすでに存在している必要があります。
-
アプリの権限レベルを選択します:
- 選択可能:アプリが類似性検索のためにAI Searchインデックスをクエリーすることを許可します。SELECT 権限に相当します。
-
(オプション) アプリ構成でインデックスを参照する方法であるカスタム リソース キーを指定します。デフォルトのキーは
vector-search-indexです。
AI Searchインデックスは、タイプTABLE_ONLINE_VECTOR_INDEX_REPLICAまたはTABLE_ONLINE_VECTOR_INDEX_DIRECTのUnity Catalogテーブルです。AI Searchインデックスを選択すると、セマンティック検索操作をサポートする特別に構成されたテーブルが選択されます。
環境変数
AI Search インデックスリソースを使用してアプリをデプロイすると、Databricks は、valueFrom フィールドを使用して参照できる環境変数を介して、完全な 3 レベル名を公開します。
構成例:
env:
- name: VECTOR_SEARCH_INDEX
valueFrom: vector-search-index # Use your custom resource key if different
アプリケーションでインデックスを使用する:
databricks-ai-search Python SDKとアプリのService Principal資格情報を使用してインデックスをクエリーします。ワークスペースが インデックスURL要件 を満たしている場合、SDKはインデックスURLにクエリーを送信します。このURLは、ターゲットの1秒あたりのクエリー数 (QPS) を持つEndpointの追加容量を使用できます。WorkspaceClient().vector_search_indexes.query_indexで送信されたクエリーはワークスペースクエリーURLを使用しますが、これは数十QPSに制限されています。ユーザー承認 からユーザーのトークンで送信されたクエリーもワークスペースクエリーURLを使用するため、アプリのService Principalで検索トラフィックを送信してください。
databricks-ai-search バージョン0.83以上をアプリの依存関係に追加します。Databricks アプリの依存関係を管理するを参照してください。
import os
from databricks.ai_search.client import AISearchClient
# DATABRICKS_HOST can be set without a scheme, and the SDK requires one.
host = os.environ["DATABRICKS_HOST"]
if not host.startswith(("https://", "http://")):
host = f"https://{host}"
# Pass the app's service principal credentials so queries use the index URL.
client = AISearchClient(
workspace_url=host,
service_principal_client_id=os.environ["DATABRICKS_CLIENT_ID"],
service_principal_client_secret=os.environ["DATABRICKS_CLIENT_SECRET"],
)
# Create the index object when the app starts and reuse it for every query.
index = client.get_index(index_name=os.environ["VECTOR_SEARCH_INDEX"])
results = index.similarity_search(
query_text="What is machine learning?", # Or pass query_vector for self-managed embeddings.
columns=["id", "text"],
num_results=10,
)
# Each row lists values in the same order as the manifest columns.
column_names = [column["name"] for column in results["manifest"]["columns"]]
for row in results["result"]["data_array"]:
print(dict(zip(column_names, row)))
columnsをインデックスのカラムで置き換えます。より高いthroughputを実現するには、標準endpointでターゲットQPSを設定します。追加容量は、endpointのscaling_info.stateがSCALING_CHANGE_APPLIEDになった後にのみ適用されます。その状態に達するまで数分から数時間かかる可能性があるため、ロードテストを行う前に待機してください。変更とその推定完了時間を追跡するには、スケーリングの進行状況を追跡を参照してください。
詳細については、 「環境変数を使用してリソースにアクセスする」を参照してください。
AI Searchインデックスのリソースを削除
アプリから AI Searchインデックスリソースを削除すると、アプリのサービスプリンシパルはインデックスにアクセスできなくなります。インデックス自体は変更されず、適切な権限を持つ他のユーザーおよびアプリケーションが引き続き使用できます。
ベストプラクティス
AI Searchインデックス リソースを使用する場合は、次の点を考慮してください。
- インデックスが他のテーブルを参照している場合、アプリのサービスプリンシパルが基になるデータソースにアクセスできることを確認してください。
- クエリのパフォーマンスを監視し、応答時間が低下する場合はインデックス構成または埋め込みモデルを調整します。
- 埋め込みをソース データと同期させるには、インデックス更新スケジュールを検討してください。
- 埋め込みモデルに基づいて、適切な類似度メトリクス (コサイン、ユークリッド、ドット製品) を使用します。
- インデックスをクエリーする準備ができていなくても、Endpointをオンラインにできます。インデックスをブロックせずに確認するには、
index.describe()が返すstatusフィールドのreadyとdetailed_stateを読み取ります。インデックスを待機するにはindex.wait_until_ready()を呼び出します。これは30秒ごとにポーリングを実行し、インデックスがオフラインになるか、タイムアウトが経過するとエラーを発生させます。