databricks-vector-search

Databricks Vector Search

最初に：CLI の基本、認証、プロファイルの選択には、親の databricks-core スキルを使用してください。

RAG およびセマンティック検索アプリケーション向けのベクトル検索インデックスの作成、管理、クエリのパターンです。

使用するタイミング

次の場合にこのスキルを使用してください：

• RAG（検索拡張生成）アプリケーションを構築する
• セマンティック検索や類似度マッチングを実装する
• Delta テーブルからベクトルインデックスを作成する
• ストレージ最適化エンドポイントと標準エンドポイントのどちらを使うか選択する
• フィルターを使ってベクトルインデックスにクエリを実行する

概要

Databricks Vector Search は、埋め込みの自動生成と Delta Lake との統合を備えた、マネージドのベクトル類似度検索を提供します。

コンポーネント	説明
エンドポイント	インデックスをホストするコンピューティングリソース（Standard または Storage-Optimized）
インデックス	類似度検索用のベクトルデータ構造
Delta Sync	ソースの Delta テーブルと自動同期します
Direct Access	ベクトルに対する手動の CRUD 操作

エンドポイントの種類

種類	レイテンシ	容量	コスト	最適な用途
Standard	20-50ms	3億2,000万ベクトル（768 dim）	高め	リアルタイム、低レイテンシ
Storage-Optimized	300-500ms	10億以上のベクトル（768 dim）	7分の1	大規模、コスト重視

インデックスの種類

種類	埋め込み	同期	ユースケース
Delta Sync (managed)	Databricks が計算	Delta から自動	最も簡単なセットアップ
Delta Sync (self-managed)	ユーザーが用意	Delta から自動	カスタム埋め込み
Direct Access	ユーザーが用意	手動 CRUD	リアルタイム更新

クイックスタート

エンドポイントを作成する

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Create a standard endpoint
endpoint = w.vector_search_endpoints.create_endpoint(
    name="my-vs-endpoint",
    endpoint_type="STANDARD"  # or "STORAGE_OPTIMIZED"
)
# Note: Endpoint creation is asynchronous; check status with get_endpoint()

Delta Sync インデックスを作成する（マネージド埋め込み）

# Source table must have: primary key column + text column
index = w.vector_search_indexes.create_index(
    name="catalog.schema.my_index",
    endpoint_name="my-vs-endpoint",
    primary_key="id",
    index_type="DELTA_SYNC",
    delta_sync_index_spec={
        "source_table": "catalog.schema.documents",
        "embedding_source_columns": [
            {
                "name": "content",  # Text column to embed
                "embedding_model_endpoint_name": "databricks-gte-large-en"
            }
        ],
        "pipeline_type": "TRIGGERED"  # or "CONTINUOUS"
    }
)

インデックスにクエリを実行する

results = w.vector_search_indexes.query_index(
    index_name="catalog.schema.my_index",
    columns=["id", "content", "metadata"],
    query_text="What is machine learning?",
    num_results=5
)

for doc in results.result.data_array:
    score = doc[-1]  # Similarity score is last column
    print(f"Score: {score}, Content: {doc[1][:100]}...")

よく使われるパターン

ストレージ最適化エンドポイントを作成する

# For large-scale, cost-effective deployments
endpoint = w.vector_search_endpoints.create_endpoint(
    name="my-storage-endpoint",
    endpoint_type="STORAGE_OPTIMIZED"
)

セルフマネージド埋め込みで Delta Sync を使用する

# Source table must have: primary key + embedding vector column
index = w.vector_search_indexes.create_index(
    name="catalog.schema.my_index",
    endpoint_name="my-vs-endpoint",
    primary_key="id",
    index_type="DELTA_SYNC",
    delta_sync_index_spec={
        "source_table": "catalog.schema.documents",
        "embedding_vector_columns": [
            {
                "name": "embedding",  # Pre-computed embedding column
                "embedding_dimension": 768
            }
        ],
        "pipeline_type": "TRIGGERED"
    }
)

Direct Access インデックス

import json

# Create index for manual CRUD
index = w.vector_search_indexes.create_index(
    name="catalog.schema.direct_index",
    endpoint_name="my-vs-endpoint",
    primary_key="id",
    index_type="DIRECT_ACCESS",
    direct_access_index_spec={
        "embedding_vector_columns": [
            {"name": "embedding", "embedding_dimension": 768}
        ],
        "schema_json": json.dumps({
            "id": "string",
            "text": "string",
            "embedding": "array<float>",
            "metadata": "string"
        })
    }
)

# Upsert data
w.vector_search_indexes.upsert_data_vector_index(
    index_name="catalog.schema.direct_index",
    inputs_json=json.dumps([
        {"id": "1", "text": "Hello", "embedding": [0.1, 0.2, ...], "metadata": "doc1"},
        {"id": "2", "text": "World", "embedding": [0.3, 0.4, ...], "metadata": "doc2"},
    ])
)

# Delete data
w.vector_search_indexes.delete_data_vector_index(
    index_name="catalog.schema.direct_index",
    primary_keys=["1", "2"]
)

埋め込みベクトルを使ってクエリを実行する

# When you have pre-computed query embedding
results = w.vector_search_indexes.query_index(
    index_name="catalog.schema.my_index",
    columns=["id", "text"],
    query_vector=[0.1, 0.2, 0.3, ...],  # Your 768-dim vector
    num_results=10
)

ハイブリッド検索（セマンティック検索＋キーワード検索）

ハイブリッド検索は、ベクトル類似度（ANN）と BM25 キーワードスコアリングを組み合わせます。SKU、エラーコード、固有名詞、専門用語など、完全一致が必要な語句をクエリに含む場合に使用してください。純粋なセマンティック検索では、キーワードに固有の結果を見逃す可能性があります。ANN 検索とハイブリッド検索の選択に関する詳しいガイダンスは、references/search-modes.md を参照してください。

# Combines vector similarity with keyword matching
results = w.vector_search_indexes.query_index(
    index_name="catalog.schema.my_index",
    columns=["id", "content"],
    query_text="SPARK-12345 executor memory error",
    query_type="HYBRID",
    num_results=10
)

フィルタリング

Standard エンドポイントのフィルター（ディクショナリ）

# filters_json uses dictionary format
results = w.vector_search_indexes.query_index(
    index_name="catalog.schema.my_index",
    columns=["id", "content"],
    query_text="machine learning",
    num_results=10,
    filters_json='{"category": "ai", "status": ["active", "pending"]}'
)

Storage-Optimized フィルター（SQL 形式）

Storage-Optimized エンドポイントでは、databricks-vectorsearch パッケージの filters パラメーター（文字列を受け付けます）を使って、SQL 形式のフィルター構文を使用します。

from databricks.vector_search.client import VectorSearchClient

vsc = VectorSearchClient()
index = vsc.get_index(endpoint_name="my-storage-endpoint", index_name="catalog.schema.my_index")

# SQL-like filter syntax for storage-optimized endpoints
results = index.similarity_search(
    query_text="machine learning",
    columns=["id", "content"],
    num_results=10,
    filters="category = 'ai' AND status IN ('active', 'pending')"
)

# More filter examples
# filters="price > 100 AND price < 500"
# filters="department LIKE 'eng%'"
# filters="created_at >= '2024-01-01'"

インデックス同期を開始する

# For TRIGGERED pipeline type, manually sync
w.vector_search_indexes.sync_index(
    index_name="catalog.schema.my_index"
)

インデックスの全エントリーをスキャンする

# Retrieve all vectors (for debugging/export)
scan_result = w.vector_search_indexes.scan_index(
    index_name="catalog.schema.my_index",
    num_results=100
)

リファレンスファイル

トピック	ファイル	説明
インデックスの種類	references/index-types.md	Delta Sync（managed/self-managed）と Direct Access の詳細な比較
エンドツーエンドの RAG	references/end-to-end-rag.md	ソーステーブル → エンドポイント → インデックス → クエリ → エージェント統合の完全な手順
検索モード	references/search-modes.md	セマンティック検索（ANN）とハイブリッド検索の使い分け、および選択ガイド
運用	references/troubleshooting-and-operations.md	監視、コスト最適化、容量計画、移行

CLI クイックリファレンス

# List endpoints
databricks vector-search-endpoints list-endpoints

# Create endpoint (positional args: NAME ENDPOINT_TYPE)
databricks vector-search-endpoints create-endpoint my-endpoint STANDARD

# List indexes on endpoint (positional arg: ENDPOINT_NAME)
databricks vector-search-indexes list-indexes my-endpoint

# Get index status (positional arg: INDEX_NAME)
databricks vector-search-indexes get-index catalog.schema.my_index

# Sync index (positional arg: INDEX_NAME)
databricks vector-search-indexes sync-index catalog.schema.my_index

# Delete index (positional arg: INDEX_NAME)
databricks vector-search-indexes delete-index catalog.schema.my_index

よくある問題

問題	解決策
インデックスの同期が遅い	Storage-Optimized エンドポイントを使用します（インデックス作成が20倍高速です）
クエリのレイテンシーが高い	レイテンシーを100ms未満にするには、Standard エンドポイントを使用します
filters_json が機能しない	Storage-Optimized では、databricks-vectorsearch パッケージの filters パラメーターを使って、SQL のような文字列形式のフィルターを指定します
埋め込みの次元数が一致しない	クエリとインデックスの次元数が一致していることを確認します
インデックスが更新されない	pipeline_type を確認します。TRIGGERED には sync_index() を使用します
容量不足	Storage-Optimized にアップグレードします（10億件以上のベクトルに対応）
query_vector が途中で切り詰められる	大きなベクトル（例：1024次元）は、JSON としてシリアル化すると途中で切り詰められることがあります。代わりに query_text を使用するか（マネージド埋め込みインデックスの場合）、Databricks SDK を使用して生のベクトルを渡します

埋め込みモデル

Databricks には、組み込みの埋め込みモデルが用意されています。

モデル	次元数	コンテキストウィンドウ	用途
databricks-gte-large-en	1024	8192トークン	英語テキスト、高品質
databricks-bge-large-en	1024	512トークン	英語テキスト、汎用

# Use with managed embeddings
embedding_source_columns=[
    {
        "name": "content",
        "embedding_model_endpoint_name": "databricks-gte-large-en"
    }
]

注意事項

• Storage-Optimized は新しい方式です — レイテンシーを100ms未満にする必要がない限り、ほとんどの用途に適しています
• Delta Sync を推奨します — ほとんどのシナリオで、Direct Access より簡単です
• ハイブリッド検索 — Delta Sync と Direct Access の両方のインデックスで利用できます
• columns_to_sync は重要です — クエリ結果で利用できるのは同期された列のみです。必要な列をすべて含めてください
• フィルター構文はエンドポイントによって異なります — Standard では辞書形式のフィルターを使用し、Storage-Optimized では SQL のような文字列形式のフィルターを使用します。両方の形式を受け付ける databricks-vectorsearch パッケージの filters パラメーターを使用してください
• 管理と実行時の処理 — CLI と SDK はライフサイクル管理を担います。実行時にエージェントからツールを呼び出すには、VectorSearchRetrieverTool を使用します

関連スキル

• databricks-model-serving - VectorSearchRetrieverTool を使用するエージェントをデプロイします
• databricks-agent-bricks - Knowledge Assistants は、インデックス化されたドキュメントに対して RAG を使用します
• databricks-unstructured-pdf-generation - Vector Search にインデックス化するドキュメントを生成します
• databricks-unity-catalog - Delta Sync インデックスを支えるカタログとテーブルを管理します
• databricks-pipelines - Vector Search のソースとして使用する Delta テーブルを構築します