下列各節將說明如何設定、建立、列出及刪除索引。
索引總覽
索引是包含嵌入向量的檔案。這些向量是由您想透過 Vector Search 部署及查詢的大量資料所建立。您可以使用向量搜尋建立兩種索引,具體取決於您打算如何使用資料更新索引。您可以建立專為批次更新設計的索引,或是專為串流更新設計的索引。
當您想要以批次方式更新索引,並使用在指定時間內儲存的資料時 (例如每週或每月處理的系統),就會用到批次索引。當您希望在資料儲存庫中新增新資料時更新索引資料時,就需要使用串流索引,例如,如果您是書店,希望盡快在線上顯示新商品目錄,您選擇的類型非常重要,因為設定和需求各不相同。
設定索引參數
建立索引前,請先設定索引的參數。
例如,建立名為 index_metadata.json
的檔案:
{ "contentsDeltaUri": "gs://BUCKET_NAME/path", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "shardSize": "SHARD_SIZE_MEDIUM", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 5000, "fractionLeafNodesToSearch": 0.03 } } } }
如要查看這些欄位的定義,請參閱索引設定參數。
建立索引
索引大小
為了進行處理,索引資料會分成等量的部分,稱為資料分割。建立索引時,您必須指定要使用的分割區大小。支援的尺寸如下:
SHARD_SIZE_SMALL
:每個分割區 2 GiB。SHARD_SIZE_MEDIUM
:每個區塊 20 GiB。SHARD_SIZE_LARGE
:每個區塊 50 GiB。
您可以使用公開端點或虛擬私有雲端點,部署索引的機器類型取決於索引的分片大小。下表列出每個機器類型支援的分片大小:
機型 | SHARD_SIZE_SMALL |
SHARD_SIZE_MEDIUM |
SHARD_SIZE_LARGE |
---|---|---|---|
n1-standard-16 |
|||
n1-standard-32 |
|||
e2-standard-2 |
(預設) | ||
e2-standard-16 |
(預設) | ||
e2-highmem-16 |
(預設) | ||
n2d-standard-32 |
如要瞭解分片大小和機器類型對定價的影響,請參閱 Vertex AI 定價頁面。如要瞭解分割區大小對效能造成的影響,請參閱「影響效能的設定參數」。
建立批次更新索引
請按照下列操作說明建立及部署索引。如果您尚未準備好嵌入資料,可以跳到「建立空白批次索引」一節。使用這個選項時,建立索引時不需要嵌入資料。
如要建立索引:
gcloud
使用下列任何指令資料之前,請先替換以下項目:
- LOCAL_PATH_TO_METADATA_FILE:中繼資料檔案的本機路徑。
- INDEX_NAME:索引的顯示名稱。
- LOCATION:您使用 Vertex AI 的區域。
- PROJECT_ID:您的 Google Cloud 專案 ID。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud ai indexes create \ --metadata-file=LOCAL_PATH_TO_METADATA_FILE \ --display-name=INDEX_NAME \ --region=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud ai indexes create ` --metadata-file=LOCAL_PATH_TO_METADATA_FILE ` --display-name=INDEX_NAME ` --region=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud ai indexes create ^ --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^ --display-name=INDEX_NAME ^ --region=LOCATION ^ --project=PROJECT_ID
您應該會收到類似以下的回應:
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
如要進一步瞭解 describe
指令,請參閱 gcloud ai operations。
REST
使用任何要求資料之前,請先替換以下項目:
- INPUT_DIR:索引內容的 Cloud Storage 目錄路徑。
- INDEX_NAME:索引的顯示名稱。
- LOCATION:您使用 Vertex AI 的區域。
- PROJECT_ID:您的 Google Cloud 專案 ID。
- PROJECT_NUMBER:系統自動產生的專案編號。
HTTP 方法和網址:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
JSON 要求主體:
{ "display_name": "INDEX_NAME", "metadata": { "contentsDeltaUri": "INPUT_DIR", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T01:21:10.147035Z", "updateTime": "2022-01-08T01:21:10.147035Z" } } }
Terraform
以下範例使用 google_vertex_ai_index
Terraform 資源,建立用於批次更新的索引。
如要瞭解如何套用或移除 Terraform 設定,請參閱「基本 Terraform 指令」。
Python 適用的 Vertex AI SDK
如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。
Java
在試用這個範例之前,請先按照 Vertex AI 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Vertex AI Java API 參考說明文件。
如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
控制台
請按照下列操作說明建立索引,以便進行批次更新。
- 在 Google Cloud 控制台的 Vertex AI 專區中,前往「部署及使用」專區。選取「向量搜尋」
- 按一下「 建立新索引」,開啟「索引」窗格。畫面上會顯示「Create a new index」窗格。
- 在「Display name」欄位中,提供用於識別索引的不重複名稱。
- 在「Description」欄位中,提供索引的用途說明。
- 在「Region」欄位中,從下拉式選單中選取所需地區。
- 在 Cloud Storage 欄位中,搜尋並選取儲存向量資料的 Cloud Storage 資料夾。
- 在「演算法類型」下拉式選單中,選取 Vector Search 用於高效率搜尋的演算法類型。如果您選取 treeAh 演算法,請輸入近似鄰點數量。
- 在「Dimensions」欄位中,輸入輸入向量的維度數量。
- 在「更新方法」欄位中,選取「批次」。
- 在「分片大小」欄位中,從下拉式選單中選取所需的分片大小。
- 按一下「建立」,新的索引準備就緒後,就會顯示在索引清單中。注意:建構作業最多可能需要一小時才能完成。
建立空白批次索引
如要立即建立及部署索引,您可以建立空白批次索引。使用這個選項時,建立索引時不需要嵌入資料。
如要建立空白索引,要求幾乎與建立批次更新索引相同。差別在於您會移除 contentsDeltaUri
欄位,因為您並未連結資料位置。以下是空白批次索引範例:
空白索引要求範例
{ "display_name": INDEX_NAME, "indexUpdateMethod": "BATCH_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "fractionLeafNodesToSearch": 0.07 } } } } }
建立用於串流更新的索引
請按照這些操作說明建立及部署串流索引。如果您尚未準備好內嵌項目,請跳到「建立空白索引以進行串流更新」一節。使用這個選項時,建立索引時不需要嵌入資料。
REST
使用任何要求資料之前,請先替換以下項目:
- INDEX_NAME:索引的顯示名稱。
- DESCRIPTION:索引的說明。
- INPUT_DIR:索引內容的 Cloud Storage 目錄路徑。
- DIMENSIONS:嵌入向量的維度數量。
- PROJECT_ID:您的 Google Cloud 專案 ID。
- PROJECT_NUMBER:系統自動產生的專案編號。
- LOCATION:您使用 Vertex AI 的區域。
HTTP 方法和網址:
POST https://ENDPOINT-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
JSON 要求主體:
{ displayName: "INDEX_NAME", description: "DESCRIPTION", metadata: { contentsDeltaUri: "INPUT_DIR", config: { dimensions: "DIMENSIONS", approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", algorithmConfig: {treeAhConfig: {leafNodeEmbeddingCount: 10000, leafNodesToSearchPercent: 2}} }, }, indexUpdateMethod: "STREAM_UPDATE" }
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.ui.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2023-12-05T23:17:45.416117Z", "updateTime": "2023-12-05T23:17:45.416117Z", "state": "RUNNING", "worksOn": [ "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID" ] } } }
Terraform
以下範例使用 google_vertex_ai_index
Terraform 資源,建立用於串流更新的索引。
如要瞭解如何套用或移除 Terraform 設定,請參閱「基本 Terraform 指令」。
Python 適用的 Vertex AI SDK
如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。
Java
在試用這個範例之前,請先按照 Vertex AI 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Vertex AI Java API 參考說明文件。
如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
控制台
請按照這些操作說明,在 Google Cloud 控制台中建立串流更新索引。
如要建立可用於串流更新的索引 ,您必須採取與設定批次更新索引類似的步驟,但需要將 indexUpdateMethod
設為 STREAM_UPDATE
。
- 在 Google Cloud 控制台的 Vertex AI 專區中,前往「部署及使用」專區。選取「Vector Search」
- 按一下「 建立新索引」,開啟「索引」窗格。畫面上會顯示「Create a new index」(建立新索引) 窗格。
- 在「Display name」欄位中,輸入用於識別索引的名稱。
- 在「Description」欄位中,提供索引的用途說明。
- 在「Region」欄位中,從下拉式選單中選取所需地區。
- 在 Cloud Storage 欄位中,搜尋並選取儲存向量資料的 Cloud Storage 資料夾。
- 在「演算法類型」下拉式選單中,選取 Vector Search 用於執行搜尋的演算法類型。如果您選取 treeAh 演算法,請輸入近似鄰點數量。
- 在「維度」欄位中輸入輸入向量的維度數量。
- 在「Update method」欄位中,選取「Stream」。
- 在「分片大小」欄位中,從下拉式選單中選取所需的分片大小。
- 按一下「建立」,新的索引準備就緒後,就會顯示在索引清單中。 注意:建構作業最多可能需要一小時才能完成。
建立用於串流更新的空白索引
如要立即建立及部署索引,您可以建立用於串流的空白索引。使用這個選項時,建立索引時不需要嵌入資料。
如要建立空白索引,要求幾乎與建立串流索引相同。差別在於您會移除 contentsDeltaUri
欄位,因為您並未連結資料位置。以下是空串流索引範例:
空白索引要求範例
{ "display_name": INDEX_NAME, "indexUpdateMethod": "STREAM_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
列出索引
gcloud
使用下列任何指令資料之前,請先替換以下項目:
- INDEX_NAME:索引的顯示名稱。
- LOCATION:您使用 Vertex AI 的區域。
- PROJECT_ID:您的 Google Cloud 專案 ID。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud ai indexes list \ --region=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud ai indexes list ` --region=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud ai indexes list ^ --region=LOCATION ^ --project=PROJECT_ID
您應該會收到類似以下的回應:
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
如要進一步瞭解 describe
指令,請參閱 gcloud ai operations。
REST
使用任何要求資料之前,請先替換以下項目:
- INDEX_NAME:索引的顯示名稱。
- LOCATION:您使用 Vertex AI 的區域。
- PROJECT_ID:您的 Google Cloud 專案 ID。
- PROJECT_NUMBER:系統自動產生的專案編號。
HTTP 方法和網址:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "indexes": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID", "displayName": "INDEX_NAME", "metadataSchemaUri": "gs://google-cloud-aiplatform/schema/matchingengine/metadata/nearest_neighbor_search_1.0.0.yaml", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "featureNormType": "NONE", "algorithmConfig": { "treeAhConfig": { "maxLeavesToSearch": 50, "leafNodeCount": 10000 } } } }, "etag": "AMEw9yNU8YX5IvwuINeBkVv3yNa7VGKk11GBQ8GkfRoVvO7LgRUeOo0qobYWuU9DiEc=", "createTime": "2020-11-08T21:56:30.558449Z", "updateTime": "2020-11-08T22:39:25.048623Z" } ] }
Python 適用的 Vertex AI SDK
如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。
Java
在試用這個範例之前,請先按照 Vertex AI 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Vertex AI Java API 參考說明文件。
如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
控制台
請按照下列操作說明查看索引清單。
- 在 Google Cloud 控制台的 Vertex AI 專區中,前往「部署及使用」專區。選取「向量搜尋」
- 系統會顯示有效索引清單。
調整索引
調整索引時,您必須設定會影響已部署索引效能的設定參數,尤其是喚回率和延遲時間。這些參數會在首次建立索引時設定。您可以使用暴力索引來評估回憶率。
影響效能的設定參數
下列設定參數可在建立索引時設定,並可影響使用向量搜尋時的喚回率、延遲時間、可用性和費用。這項指引適用於大多數情況。不過,請務必嘗試設定,確保設定適用於您的用途。
如要瞭解參數定義,請參閱「索引設定參數」。
參數 | 關於 | 效能影響 |
---|---|---|
shardSize
|
控制每部機器上的資料量。 選擇分割區大小時,請預估資料集未來的大小。如果資料集的大小有上限,請選擇適當的分片大小來配合。如果沒有上限,或是您的用途對延遲變化極為敏感,建議選擇較大的區塊大小。 |
如果您設定較多個較小的資料分割,系統在搜尋期間會處理較多候選結果。較多切片可能會對效能造成以下影響:
如果您設定較少數量的較大資料分割,系統在搜尋期間處理的候選結果就會減少。較少的分片可能會對效能造成以下影響:
|
distanceMeasureType
|
決定用於計算資料點與查詢向量之間距離的演算法。 |
下列
|
leafNodeEmbeddingCount
|
每個分葉節點的嵌入項目數量。預設值為 1000。
一般來說,變更 |
增加每個分葉節點的嵌入項目數量,雖然可以縮短延遲時間,但會降低回憶品質。這可能會影響效能,具體影響如下:
減少每個分葉節點的嵌入項目數量,可能會對效能造成以下影響:
|
使用暴力搜尋索引評估回憶率
如要取得最鄰近的項目,請使用索引搭配暴力搜尋演算法。暴力演算法可提供 100% 的喚回率,但延遲時間較長。在實際運作時,使用暴力索引來評估回憶率通常不是個好選擇,但您或許會發現,在離線評估各種索引選項的回憶率時,這項方法很實用。
如要使用暴力搜尋演算法建立索引,請在索引中繼資料中指定 brute_force_config
:
curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer `gcloud auth print-access-token`" \ https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \ -d '{ displayName: "'${DISPLAY_NAME}'", description: "'${DESCRIPTION}'", metadata: { contentsDeltaUri: "'${INPUT_DIR}'", config: { dimensions: 100, approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", featureNormType: "UNIT_L2_NORM", algorithmConfig: { bruteForceConfig: {} } }, }, }'
刪除索引
gcloud
使用下列任何指令資料之前,請先替換以下項目:
- INDEX_ID:索引的 ID。
- LOCATION:您使用 Vertex AI 的區域。
- PROJECT_ID:您的 Google Cloud 專案 ID。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud ai indexes delete INDEX_ID \ --region=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud ai indexes delete INDEX_ID ` --region=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud ai indexes delete INDEX_ID ^ --region=LOCATION ^ --project=PROJECT_ID
REST
使用任何要求資料之前,請先替換以下項目:
- INDEX_ID:索引的 ID。
- LOCATION:您使用 Vertex AI 的區域。
- PROJECT_ID:您的 Google Cloud 專案 ID。
- PROJECT_NUMBER:系統自動產生的專案編號。
HTTP 方法和網址:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID
如要傳送要求,請展開以下其中一個選項:
您應該會收到如下的 JSON 回應:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeleteOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T02:35:56.364956Z", "updateTime": "2022-01-08T02:35:56.364956Z" } }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty" } }
Python 適用的 Vertex AI SDK
如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。
Java
在試用這個範例之前,請先按照 Vertex AI 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Vertex AI Java API 參考說明文件。
如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
控制台
請按照下列操作說明刪除一或多個索引。
- 在 Google Cloud 控制台的 Vertex AI 專區中,前往「部署及使用」專區。選取「向量搜尋」
- 系統會顯示有效索引清單。
- 如要刪除索引,請前往與索引位於同一列的 選項選單,然後選取「Delete」。
後續步驟
- 瞭解索引設定參數
- 瞭解如何部署及管理公開索引端點
- 瞭解如何在虛擬私有雲網路中部署及管理索引端點
- 瞭解如何更新及重建索引
- 瞭解如何監控索引