查詢向量搜尋索引

本頁說明如何查詢向量搜尋索引，包括分頁、篩選與重新排序。

例如說明如何建立及查詢向量搜尋端點與索引的筆記本，請參見向量搜尋範例筆記本。參考資訊請參閱 Python SDK 參考。

安裝

若要使用向量搜尋 SDK，您必須在筆記本中安裝它。使用下列程式代碼來安裝套件：

%pip install databricks-vectorsearch
dbutils.library.restartPython()

然後使用下列命令匯入 VectorSearchClient：

from databricks.vector_search.client import VectorSearchClient

有關認證的資訊，請參見資料保護與認證。

如何查詢向量搜尋索引

你只能用 Python SDK、REST API 或 SQL vector_search() AI 函式查詢向量搜尋索引。

備註

若查詢索引的使用者並非向量搜尋索引的擁有者，該使用者必須具備以下通用搜尋權限：

USE CATALOG 位於包含向量搜尋索引的目錄中。
USE SCHEMA 在包含向量搜尋索引的架構中。
向量搜尋索引上的 SELECT。

默認查詢類型為 ann （近似近鄰）。關於不同檢索演算法的詳細資訊，請參見檢索演算法。

若要執行混合式關鍵字相似性搜尋，請將參數 query_type 設定為 hybrid。使用混合式搜尋時，會包含所有文字元數據行，且最多會傳回 200 個結果。
若要在查詢中使用重新排名器，請參閱在查詢中使用重新排名器。

這很重要

全文檢索搜尋可作為測試版功能使用。若要執行全文檢索搜尋，請將參數 query_type 設為 FULL_TEXT。透過全文搜尋，您可以根據關鍵字比對擷取多達 200 個結果，而無需使用向量嵌入。全文查詢支援標準端點與儲存空間優化端點。在儲存優化端點上，你也可以建立一個專用的全文搜尋索引，無需嵌入。參見建立全文搜尋索引（測試版）。

Python SDK 標準端點

詳情請參閱 Python SDK 參考文獻。

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

Python SDK 儲存優化端點

詳情請參閱 Python SDK 參考文獻。

現有的篩選介面已針對記憶體優化向量搜尋索引重新設計，採用更類似 SQL 的篩選字串，而不是標準向量搜尋端點中使用的篩選字典。

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

# similarity search with query vector
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
)

# similarity search with query vector and filter string
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    # this is a single filter string similar to SQL WHERE clause syntax
    filters="language = 'en' AND country = 'us'",
    num_results=2
)

REST API

請參閱 REST API 參考檔：POST /api/2.0/vector-search/indexes/{index_name}/query。

針對生產應用程式，Databricks 建議使用服務主體，而不是個人存取令牌。除了改善安全性和存取管理之外，使用服務主體可使每個查詢的效能提升最多 100 毫秒。

下列程式代碼範例說明如何使用服務主體查詢索引。

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint, then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'

# Generate OAuth token
export TOKEN=$(curl -X POST  --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

下列程式代碼範例說明如何使用個人存取令牌來查詢索引（PAT）。

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Query vector search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query vector search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

SQL

這很重要

vector_search() AI 功能目前在公開預覽中。

若要使用此 AI 函式，請參閱 vector_search 函式。

分頁

當查詢要求超過 1,000 個結果時，結果會自動以最多 1,000 個頁面的形式回傳。單一查詢在所有頁面上最多可返回的結果數為 10,000 個。標準端點與儲存空間優化端點皆支援分頁。

分頁適用於所有查詢類型。

Python SDK

Python SDK 可以透明地處理分頁。當你設定 num_results 值大於 1,000 時，SDK 會自動擷取所有頁面並回傳完整的結果集。不需要額外的程式碼。

# The SDK automatically paginates and returns all 5000 results
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=5000
)

REST API

直接使用 REST API 時，必須手動處理分頁。若有更多結果，回應中會包含一個 next_page_token 欄位。要取得下一頁結果，將此標記傳遞給查詢下一頁端點。

請參閱 REST API 參考文件： POST /api/2.0/vector-search/indexes/{index_name}/query-next-page。

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Initial query - if num_results exceeds 1000, the response includes next_page_token
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query \
  --data '{"num_results": 5000, "query_text": "...", "columns": ["id", "text"]}'

# Use next_page_token from the response to get the next page
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query-next-page \
  --data '{"page_token": "<next_page_token from previous response>"}'

繼續使用每個回應中的next_page_token token 呼叫 query-next-page 端點，直到 token 為空或不存在，表示所有結果已回傳。

在查詢上使用篩選

查詢可以根據 Delta 資料表中的任何數據行來定義篩選。 similarity_search 只會傳回符合指定篩選的數據列。

下表列出支持的篩選條件。

備註

對於儲存優化端點，結果會被超取。如果你設定 num_results 為 k，會擷取超過 k 的結果，並對擷取結果套用過濾器。即使資料集中有符合篩選條件的結果，若這些文件的分數不在頂尖，也可能不會回傳結果。

篩選運算子	行為	範例
`NOT`	標準：否定篩選條件。密鑰必須以「NOT」結尾。例如，值為 “red” 的 “color NOT” 用於比對顏色不是紅色的文件。儲存優化：請參閱 `!=` （bangeq 符號）運算符。	標準： `{"id NOT": 2}{“color NOT”: “red”}` 記憶體優化： `"id != 2" "color != 'red'"`
`<`	標準：檢查域值是否小於篩選值。索引鍵必須以「<」結尾。例如，值為 200 的「價格 <」會比對價格小於 200 的檔。記憶體優化：請參閱 `<` （lt sign）運算符。	標準： `{"id <": 200}` 記憶體優化： `"id < 200"`
`<=`	標準：檢查域值是否小於或等於篩選值。密鑰的結尾必須是「<=」。例如，值為 200 的「price <=」會比對價格小於或等於 200 的檔。記憶體優化：請參閱 `<=` （lt eq sign）運算符。	標準： `{"id <=": 200}` 記憶體優化： `"id <= 200"`
`>`	標準：檢查域值是否大於篩選值。索引鍵必須以「>」結尾。例如，值為 200 的「價格 >」會比對價格大於 200 的檔。記憶體優化：請參閱 `>` （gt sign）運算符。	標準： `{"id >": 200}` 記憶體優化： `"id > 200"`
`>=`	標準：檢查域值是否大於或等於篩選值。密鑰的結尾必須是「>=」。例如，值為 200 的「price >=」會比對價格大於或等於 200 的檔。記憶體優化：請參閱 `>=` （gt eq sign）運算符。	標準： `{"id >=": 200}` 記憶體優化： `"id >= 200"`
`OR`	標準：檢查域值是否符合任何篩選值。鍵值必須包含 `OR`，以分隔多個子鍵。例如，值為 `color1 OR color2` 的 `["red", "blue"]` 的文檔符合 `color1` 為 `red` 或 `color2` 為 `blue`的條件。記憶體優化：請參閱 `or` 運算元。	標準： `{"color1 OR color2": ["red", "blue"]}` 記憶體優化： `"color1 = 'red' OR color2 = 'blue'"`
`LIKE`	標準：比對字串中的空格符分隔標記。記憶體優化：請參閱 `like` 運算元。	請參閱`LIKE`的使用注意事項。
未指定篩選運算子	標準：篩選檢查是否完全相符。如果指定了多個值，則會比對任何值。記憶體優化：請參閱 `=` （eq sign）運算符和 `in` 述詞。	標準： `{"id": 200}{"id": [200, 300]}` 記憶體優化： `"id = 200""id IN (200, 300)"`
`to_timestamp` （僅限記憶體優化端點）	記憶體優化：篩選時間戳。請參閱 `to_timestamp` 函式	記憶體優化： `"date > TO_TIMESTAMP('1995-01-01')"`

關於`LIKE`的使用說明

LIKE 標準端點範例

{"column LIKE": "apple"}：與「apple」和「apple pear」這兩個字串相符，僅不匹配「pineapple」。請注意，它不匹配「pineapple」，儘管它包含一個子字串「apple」——它會透過空白分隔的標記（如「apple pear」）尋找完全匹配。

{"column NOT LIKE": "apple"} 做相反的事情。它匹配「鳳梨」和「梨子」，但不匹配「蘋果」或「蘋果梨」。

LIKE 儲存優化端點範例

格式	比對
`"column LIKE 'apple'"`	相當於運算子 `=`。只回傳完全相符的結果。
`"column LIKE 'apple%'"`	回傳前綴與相符 `apple`的列，例如 `applepie`。
`"column LIKE '%apple'"`	回傳與後綴 `apple` 相符的列，例如`pineapple`。
`"column LIKE '%apple%'"`	回傳具有與相符 `apple`子串的列，例如 `pineapplecake`。

程式碼範例

Python SDK 標準端點

# 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 儲存優化端點

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title IN ("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 = "Ares" OR id = "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 != "Hercules"',
    num_results=2
    )

REST API

請參閱 POST /api/2.0/vector-search/indexes/{index_name}/query。

在查詢中使用重新排名器

代理程式效能取決於擷取查詢最相關的資訊。重新排名是一種技術，透過評估擷取的文件來識別語義上最相關的文件，從而提高檢索品質。 Databricks 開發了一種基於研究的複合人工智慧系統來識別這些文件。您也可以指定包含中繼資料的資料行，您希望重新排名器在評估每個文件的相關性時用於其他內容。

重新排名會產生較小的延遲延遲，但可以顯著提高檢索品質和客服專員效能。 Databricks 建議嘗試任何 RAG 代理程式使用案例的重新排名。

本節中的範例顯示如何使用向量搜尋重新排名器。當您使用重排序器時，您需要分別設定要回傳的資料行（columns）和用於重新排序的中繼資料欄位（columns_to_rerank）。 num_results 是要傳回的最終結果數。這不會影響用於重新排名的結果數量。

查詢除錯訊息包含重新排序步驟所花費時間的相關資訊。例如：

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

如果重新排序器呼叫失敗，則該資訊會包含在偵錯訊息中：

'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 SDK

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

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

REST API

若要確保您取得延遲資訊，請設定 debug_level 至少為 1。

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 10, "query_text": "How to create a Vector Search index", "columns": ["id", "text", "parent_doc_summary", "date"], "reranker": {"model": "databricks_reranker",
             "parameters": {
               "columns_to_rerank":
                 ["text", "parent_doc_summary"]
              }
             },
"debug_level": 1}'

點查詢

要做點查詢，請對任一主鍵欄位使用過濾器。

檢索演算法

本節說明不同的檢索演算法或查詢類型，以及每種方式的使用時機。使用 query_type 參數指定要使用的檢索演算法。若要自動比較不同演算法對你指數的效能，請參見「評估向量搜尋檢索品質」。

策略	運作方式	最適合用於
ANN（近似最近鄰）	利用向量嵌入搜尋語意相似的文件。	概念性與語意性查詢，意義比精確措辭更重要。
Full-text	關鍵字搜尋，精確匹配詞彙。	包含特定術語、專有名詞、產品識別碼或專業術語的查詢。
混合	結合人工神經網路與全文結果，使用倒數秩融合（RRF）。	一般用途檢索。大多數使用情境的建議起點。
混合 + 重排序器	執行混合搜尋，然後用跨編碼器重新排序模型重新評分結果。	當延遲允許時，精度會更高（每次查詢多約 1.5 秒）。

ANN（向量搜尋）

人工神經網路搜尋將查詢轉換為向量嵌入，並尋找嵌入最相似的文件。這對於理解意義非常有效。例如，像「如何修理破裂的水管」這樣的查詢，即使文件中沒有完全相同的詞彙，也能與有關水管的文件相符。

當 ANN 表現良好時：查詢具有概念性、對話性，或使用與文件不同的詞彙。
當人工神經網路可能表現不佳時：查詢依賴精確關鍵字、專有名詞或領域專屬術語，嵌入可能無法精確捕捉這些。

全文（關鍵字搜尋）

全文搜尋會匹配包含查詢詞的文件。全文搜尋具有高精度。當使用者搜尋特定名稱、代碼或技術術語時，關鍵字匹配會精確找到向量搜尋可能錯過的精確結果。

當全文表現良好時：查詢包含特定識別碼、產品名稱、錯誤代碼或領域專屬術語。
當全文可能表現不佳時：查詢表述與文件不同，或使用同義詞與意譯。

混合式搜尋

混合搜尋同時執行人工神經網路與全文搜尋，然後利用倒數排序融合（RRF）合併結果。這結合了向量搜尋的語意理解與關鍵字匹配的精確度。

當混合搜尋表現良好時：查詢工作量是概念性查詢與關鍵字為主的混合。混合策略是最穩健的通用策略。

重排序器

重排序器是附加在任何策略之上可選的第二次運行。初步檢索後，交叉編碼器模型會在查詢情境中重新評估每個結果，產生更精確的相關性排序。

重排序器通常能提升質量約百分之十，但會增加延遲。它適合品質最重視的應用，如 RAG 聊天機器人，但對於高吞吐量、低延遲的搜尋應用可能較不適合。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-19

查詢向量搜尋索引

安裝

如何查詢向量搜尋索引

Python SDK 標準端點

Python SDK 儲存優化端點

REST API

SQL

分頁

Python SDK

REST API

在查詢上使用篩選

關於LIKE的使用說明

程式碼範例

Python SDK 標準端點

Python SDK 儲存優化端點

REST API

在查詢中使用重新排名器

Python SDK

REST API

點查詢

檢索演算法

ANN（向量搜尋）

全文（關鍵字搜尋）

混合式搜尋

重排序器

意見反應

其他資源

關於`LIKE`的使用說明