建立向量搜尋端點與索引

本文說明如何使用 Mosaic AI 向量搜尋建立向量搜尋端點與索引。

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

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

需求

已啟用 Unity Catalog 的工作區。
已啟用無伺服器計算。如需指示，請參閱連線到無伺服器計算。
針對標準端點，源表必須啟用變更資料饋入。請參閱在 Azure Databricks 上使用 Delta Lake 變更數據饋送。
若要建立向量搜尋索引，您必須在建立索引的目錄架構上擁有 CREATE TABLE 許可權。
若要查詢其他使用者擁有的索引，您必須擁有額外的許可權。請參閱如何查詢向量搜尋索引。

使用訪問控制清單來設定建立和管理向量搜尋端點的許可權。請參閱向量搜尋端點 ACL。

安裝

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

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

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

from databricks.vector_search.client import VectorSearchClient

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

建立向量搜尋端點

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

使用UI建立向量搜尋端點

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

在左側邊欄中，點擊 [計算]。
點選 向量搜尋 標籤，然後點擊建立。
[建立端點] 表單 隨即開啟。輸入此端點的名稱。
在 [ 類型] 欄位中，選取 [ 標準 ] 或 [ 記憶體優化]。請參閱端點選項。
（選擇性）在 [ 進階設定] 底下，選取預算原則。請參閱馬賽克 AI 向量搜尋：預算原則。
按一下 [確認]。

使用 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 = 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 建議您取消預設選項，使 的縮放比例設為零，。服務端點需要幾分鐘才能完成熱身，而縮減的端點上的索引初始查詢可能會逾時。

備註

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

建立向量搜尋索引

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

有兩種類型的索引：

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

備註

欄位名稱 _id 是保留的。如果您的來源表有一個名為_id的欄位，在建立向量搜尋索引前請先重新命名。

使用 UI 建立索引

在左側邊欄中，按一下 [目錄] 以開啟 [目錄瀏覽器介面]。
導覽到您想使用的 Delta 表格。
單擊右上角的 [[建立] 按鈕，然後從下拉菜單中選取 向量搜尋索引。
使用對話框中的選取器來設定索引。

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

主鍵：用作主鍵的欄位。

要同步處理的資料列:(僅支援標準端點。）選取要與向量索引同步的數據行。如果您將此欄位保留空白，源數據表中的所有資料行都會與索引同步。主鍵數據行和內嵌源數據行或內嵌向量數據行一律會同步處理。針對儲存優化端點，來源表中的所有欄位都會同步。

內嵌來源：指出您是否希望 Databricks 計算 Delta 數據表中文字數據行的內嵌（計算內嵌），或如果您的 Delta 數據表包含預先計算的內嵌（使用現有的內嵌數據行）。
- 如果您選取 [計算內嵌]，請選取您要計算內嵌的直欄，以及要用於計算的內嵌模型。僅支援文字欄位。
  - 對於使用標準端點的生產應用，Databricks 建議使用基礎模型 databricks-gte-large-en ，並使用具有預配置吞吐量的服務端點。
  - 對於使用儲存優化端點並搭配 Databricks 主機模型的生產應用，直接使用模型名稱（例如 databricks-gte-large-en）作為嵌入模型端點。儲存優化端點在資料擷取時使用 ai_query 批次推論，為嵌入處理作業提供高吞吐量。如果你偏好使用已配置的吞吐量端點來查詢，請在 model_endpoint_name_for_query 建立索引時的欄位中指定。
- 如果您選擇了使用現有的嵌入列，請選擇包含預先計算的嵌入和嵌入維度的列。預先計算的內嵌資料列格式應該 array[float]。針對記憶體優化的端點，內嵌維度必須平均地由16來分割。
同步計算內嵌：切換此設定，將產生的內嵌儲存至 Unity 目錄數據表。如需詳細資訊，請參閱儲存產生的內嵌資料表。

向量搜尋端點：選取要儲存索引的向量搜尋端點。

同步模式：連續保持索引同步，延遲時間以秒計。不過，由於已布建計算叢集以執行持續同步串流管線，因此其成本較高。
- 對於標準端點， 「連續 」和 「觸發」 都會執行累加式更新，因此只會處理自上次同步處理后已變更的數據。
- 對於儲存最佳化端點，每次同步都會部分重建索引。對於後續同步處理時的受管理索引，來源資料列未變更的任何產生的內嵌都會重複使用，且不需要重新計算。請參閱記憶體優化的端點限制。
使用觸發同步模式時，您可以使用 Python SDK 或 REST API 來啟動同步。請參閱更新 Delta 同步索引。

針對儲存空間優化的端點，僅支援 觸發的 同步模式。

進階設定：（選擇性）如果您選取了 計算內嵌，您可以指定個別的內嵌模型來查詢向量搜尋索引。如果您需要高輸送量端點來擷取，但需要較低延遲端點來查詢索引，這會很有用。內 嵌模型 欄位中指定的模型一律用於擷取，也用於查詢，除非您在此處指定不同的模型。若要指定不同的模型，請按一下 選擇個別內嵌模型以查詢索引 ，然後從下拉式功能表中選取模型。
當您完成索引設定後，請點擊 [建立]。

使用 Python SDK 建立索引

以下範例會建立一個 Delta Sync 索引，其中的嵌入向量由 Databricks 計算。如需詳細資訊，請參閱 Python SDK 參考。

此範例也顯示選擇性參數，該參數 model_endpoint_name_for_query指定要用於查詢索引的個別內嵌模型服務端點。

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 同步索引。

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=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 目錄中的數據表。此數據表會建立於與向量索引相同的架構中，並從向量索引頁面連結。

資料表的名稱是向量搜尋索引的名稱，附加 _writeback_table。無法編輯名稱。

您可以像 Unity 目錄中的任何其他資料表一樣存取和查詢資料表。不過，您不應該卸除或修改數據表，因為它不適合手動更新。如果刪除索引，數據表會自動刪除。

更新向量搜尋索引

更新差異同步索引

當來源 Delta 數據表變更時，使用連續同步模式建立的索引會自動更新。如果您使用 觸發同步 模式，您可以使用UI、Python SDK 或 REST API 來啟動同步處理。

Databricks 使用者介面

在目錄總管中，流覽至向量搜尋索引。
在 [ 概觀] 索引標籤的 [ 數據內嵌] 區段中，按兩下 [立即同步處理]。

Python SDK

如需詳細資訊，請參閱 Python SDK 參考。

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

index.sync()

REST API

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

更新直接向量存取索引

您可以使用 Python SDK 或 REST API，從直接向量存取索引插入、更新或刪除數據。

Python SDK

如需詳細資訊，請參閱 Python SDK 參考。

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

REST API

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

針對生產應用程式，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": "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": [...]}'

下列程式代碼範例說明如何使用個人存取令牌來更新索引（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": [...]}'

如何在不停機的情況下進行架構變更

如果來源資料表中現有欄位的結構改變，你必須重建索引。如果有啟用寫回資料表，當新增欄位到來源資料表時，你也必須重新建立索引。若未啟用寫回表，新增欄位則不需要重新建立索引。

請依照以下步驟重建並部署指數，避免停機：

在你的來源資料表上執行結構變更。
建立新的索引。
新索引準備好後，切換流量到新索引。
刪除原始索引。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-05

共用方式為

建立向量搜尋端點與索引

需求

安裝

建立向量搜尋端點

使用UI建立向量搜尋端點

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

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

（選擇性）建立並設定端點來提供內嵌模型

建立向量搜尋索引

使用 UI 建立索引

使用 Python SDK 建立索引

使用 REST API 建立索引

儲存產生的內嵌數據表

更新向量搜尋索引

更新差異同步索引

Databricks 使用者介面

Python SDK

REST API

更新直接向量存取索引

Python SDK

REST API

如何在不停機的情況下進行架構變更

意見反應

其他資源