如何建立和查詢向量搜尋索引

發行項
11/14/2024

本文說明如何使用 Mosaic AI 向量搜尋來建立和查詢向量搜尋索引。

使用 UI、Python SDK 或 REST API，您可建立和管理向量搜尋元件，例如向量搜尋端點和向量搜尋索引。

需求

已啟用 Unity Catalog 的工作區。
已啟用無伺服器計算。如需指示，請參閱連線到無伺服器計算。
來源資料表必須啟用變更資料摘要。如需指示，請參閱在 Azure Databricks 上使用 Delta Lake 變更資料摘要。
若要建立索引，您必須擁有目錄結構描述的 CREATE TABLE 權限，才能建立索引。若要查詢其他使用者擁有的索引，您必須擁有額外的權限。請參閱查詢向量搜尋端點。
如果您想要使用個人存取權杖 (不建議用於生產工作負載)，請檢查已啟用個人存取權杖。若要改用服務主體權杖，請使用 SDK 或 API 呼叫明確傳遞它。

若要使用 SDK，您必須在筆記本中安裝它。使用下列程式碼：

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

建立向量搜尋端點

您可以使用 Databricks UI、Python SDK 或 API 來建立向量搜尋端點。

使用 UI 建立向量搜尋端點

請遵循下列步驟，使用 UI 建立向量搜尋端點。

在左側邊欄中，按一下 [計算]。
按一下 [向量搜尋] 索引標籤，然後再按一下 [建立]。
[建立端點表單] 隨即開啟。輸入此端點的名稱。
按一下 [確認]。

使用 Python SDK 建立向量搜尋端點

下列範例會使用 create_endpoint() SDK 函數來建立向量搜尋端點。

# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearch(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD"
)

使用 REST API 建立向量搜尋端點

請參閱 REST API 參考檔： POST /api/2.0/vector-search/endpoints。

(選用) 建立並設定端點來服務於內嵌模型

如果您選擇讓 Databricks 計算內嵌，可以使用預先設定的基礎模型 API 端點，或建立模型服務端點來服務於您選擇的內嵌模型。如需指示，請參閱按權杖付費基礎模型 API 或建立生成式 AI 模型服務端點。如需筆記本範例，請參閱呼叫內嵌模型的筆記本範例。

設定內嵌端點時，Databricks 建議您移除預設選取的 [調整為零]。服務端點可能需要幾分鐘的時間才能預熱，而具有縮小端點的索引上的初始查詢可能會逾時。

注意

如果未適當地為資料集設定內嵌端點，向量搜尋索引初始化可能會逾時。應只能將 CPU 端點用於小型資料集和測試。針對較大的資料集，請使用 GPU 端點以獲得最佳效能。

建立向量搜尋索引

您可以使用 UI、Python SDK 或 REST API 來建立向量搜尋索引。 UI 是最簡單的方法。

有兩種類型的索引：

差異同步索引會自動與來源 Delta 資料表同步，並隨著 Delta 資料表中基礎資料的變更而自動且累加地更新索引。
直接向量存取索引支援向量和中繼資料的直接讀取和寫入。使用者須負責使用 REST API 或 Python SDK 來更新此資料表。無法使用 UI 建立這種類型的索引。必須使用 REST API 或 SDK。

使用 UI 建立索引

在左側邊欄中，按一下 [目錄] 以開啟目錄總管 UI。
瀏覽至您想要使用的 Delta 資料表。
按一下右上角的 [建立] 按鈕，然後從下拉式功能表中選取 [向量搜尋索引]。
使用對話方塊中的選取器來設定索引。

名稱：用於 Unity Catalog 中線上資料表的名稱。名稱需要三層命名空間，<catalog>.<schema>.<name>。只允許英數字元和底線。

主索引鍵：用作主索引鍵的資料行。

端點：選取您想要使用的向量搜尋端點。

要同步的資料行：選取要與向量索引同步的資料行。如果將此欄位保留為空白，來源資料表中的所有資料行都會與索引同步。主索引鍵資料行和內嵌來源資料行或內嵌向量資料行始終同步。

內嵌來源：指出您是否希望 Databricks 計算 Delta 資料表中文字資料行的內嵌 (計算內嵌)，或者您的 Delta 資料表是否包含預先計算的內嵌 (使用現有的內嵌資料行)。
- 如果選取 [計算內嵌]，請選取您要計算內嵌的資料行，以及為內嵌模型提供服務的端點。僅支援文字資料行。
- 如果選取 [ 使用現有的內嵌資料行]，請選取包含預先計算的內嵌和內嵌維度的資料行。預先計算的內嵌資料行格式應該為 array[float]。
同步計算的內嵌：切換此設定，將生成的內嵌儲存至 Unity Catalog 資料表。如需詳細資訊，請參閱儲存生成的內嵌資料表。

同步模式：Continuous 可讓索引與延遲秒數保持同步。不過，由於已佈建計算叢集以執行持續同步串流管線，因此其成本較高。針對 Continuous 和 Triggered，更新為累加式，只會處理自上次同步後變更的資料。

使用 觸發的 同步模式，您可以使用 Python SDK 或 REST API 來啟動同步處理。請參閱更新差異同步索引。
在完成設定索引之後，按一下 [建立]。

使用 Python SDK 建立索引

下列範例會建立差異同步索引，其中內嵌由 Databricks 計算。

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

下列範例會建立具有自我管理內嵌的差異同步索引。此範例也會示範如何使用選擇性參數 columns_to_sync，只選取索引中要使用的資料行子集。

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 中指定它們，如下所示：

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

若要同步其他資料行，請指定它們，如下所示。您不需要包含主索引鍵和內嵌資料行，因為它們始終會同步。

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

下列範例會建立直接向量存取索引。


client = VectorSearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name="{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 資料表變更時，使用連續同步模式建立的索引會自動更新。如果您使用 觸發同步 模式，請使用 Python SDK 或 REST API 來啟動同步處理。

Python SDK

index.sync()

REST API

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

更新直接向量存取索引

可以使用 Python SDK 或 REST API，在直接向量存取索引中插入、更新或刪除資料。

Python SDK

   index.upsert([{"id": 1,
       "field2": "value2",
       "field3": 3.0,
       "text_vector": [1.0, 2.0, 3.0]
       },
       {"id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1, 2.1, 3.0]
        }
        ])

REST API

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

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

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

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/upsert-data --data '{"inputs_json": "..."}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/delete-data --data '{"primary_keys": [...]}'

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

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": "WriteVectorIndex"}'

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

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/upsert-data --data '{"inputs_json": "[...]"}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/delete-data --data '{"primary_keys": [...]}'

查詢向量搜尋端點

您只能使用 Python SDK、REST API 或 SQL vector_search() AI 函數來查詢向量搜尋端點。

注意

如果查詢端點的使用者不是向量搜尋索引的擁有者，則使用者必須具有下列 UC 權限：

包含向量搜尋索引的目錄上的 USE CATALOG 權限。
包含向量搜尋索引的結構描述上的 USE SCHEMA 權限。
向量搜尋索引上的 SELECT 權限。

若要執行混合式關鍵字相似性搜尋，請將參數 query_type 設定為 hybrid。預設值為 ann (近似最近鄰)。

Python SDK

# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

REST API

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

下列程式代碼範例說明如何使用個人存取令牌來查詢索引（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}'

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

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 (TODO: link), 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}'

SQL

重要

vector_search() AI 函數處於公開預覽狀態。

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

在查詢上使用篩選

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

篩選運算子	行為	範例
`NOT`	否定篩選條件。索引鍵必須以 "NOT" 結尾。例如，值為 "red" 的 "color NOT" 會比對不是紅色的文件。	`{"id NOT": 2}` `{“color NOT”: “red”}`
`<`	檢查欄位值是否小於篩選值。索引鍵必須以 "<" 結尾。例如，值為 200 的 "price <" 會比對價格小於 200 的文件。	`{"id <": 200}`
`<=`	檢查欄位值是否小於或等於篩選值。索引鍵必須以 "<=" 結尾。例如，值為 200 的 "price <=" 會比對價格小於或等於 200 的文件。	`{"id <=": 200}`
`>`	檢查欄位值是否大於篩選值。索引鍵必須以 ">" 結尾。例如，值為 200 的 "price >" 會比對價格大於 200 的文件。	`{"id >": 200}`
`>=`	檢查欄位值是否大於或等於篩選值。索引鍵必須以 ">=" 結尾。例如，值為 200 的 "price >=" 會比對價格大於或等於 200 的文件。	`{"id >=": 200}`
`OR`	檢查欄位值是否符合任何篩選值。索引鍵必須包含 `OR` 才能分隔多個子索引鍵。例如，值為 `["red", "blue"]` 的 `color1 OR color2` 會比對 `color1` 為 `red` 或 `color2` 為 `blue` 的文件。	`{"color1 OR color2": ["red", "blue"]}`
`LIKE`	符合部分字串。	`{"column LIKE": "hello"}`
未指定篩選運算子	篩選會檢查是否完全符合。如果指定了多個值，則會比對任何值。	`{"id": 200}` `{"id": [200, 300]}`

請參閱以下程式碼範例：

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
    )

REST API

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

筆記本範例

本節中的範例示範向量搜尋 Python SDK 的使用方式。

LangChain 範例

請參閱如何搭配使用 LangChain 與 Mosaic AI 向量搜尋，以了解如何在與 LangChain 套件整合時使用 Mosaic AI 向量搜尋。

下列筆記本示範如何將相似性搜尋結果轉換成 LangChain 文件。

使用 Python SDK 筆記本進行向量搜尋

取得筆記本

呼叫內嵌模型的筆記本範例

下列筆記本示範如何設定 Mosaic AI 模型服務端點以生成內嵌。

共用方式為

如何建立和查詢向量搜尋索引

需求

建立向量搜尋端點

使用 UI 建立向量搜尋端點

使用 Python SDK 建立向量搜尋端點

使用 REST API 建立向量搜尋端點

(選用) 建立並設定端點來服務於內嵌模型

建立向量搜尋索引

使用 UI 建立索引

使用 Python SDK 建立索引

使用 REST API 建立索引

儲存生成的內嵌資料表

更新向量搜尋索引

更新差異同步索引

Python SDK

REST API

更新直接向量存取索引

Python SDK

REST API

查詢向量搜尋端點

Python SDK

REST API

SQL

在查詢上使用篩選

Python SDK

REST API

筆記本範例

LangChain 範例

使用 Python SDK 筆記本進行向量搜尋

呼叫內嵌模型的筆記本範例

使用 Mosaic AI Model Serving 筆記本呼叫 OpenAI 內嵌模型

使用 Mosaic AI Model Serving 筆記本呼叫 GTE 內嵌模型

註冊並提供 OSS 內嵌模型筆記本

意見反應

其他資源