集合索引

如要準備應用程式以因應正式環境的規模和效能需求，您需要建立集合索引。如果沒有索引，ANN 搜尋會執行暴力掃描，因此速度緩慢。建立索引後，即可對索引向量欄位執行快速搜尋。

選擇距離指標

為索引選擇合適的距離指標，對於取得準確且相關的相似度搜尋結果至關重要。最佳選擇主要取決於向量嵌入的特徵和資料性質。最重要的規則是使用嵌入模型訓練時所用的距離指標。嵌入模型經過最佳化，可產生向量表示法，並透過特定距離計算方式，盡可能擷取相似性。使用其他指標可能會導致搜尋結果不盡理想或不正確。

查看嵌入模型的說明文件：這是判斷預期距離指標最可靠的方法。
考量用途：如要尋找語意相似的文字或圖片，餘弦相似度通常是最佳選擇。如果向量大小代表的「強度」或「強度」很重要，請考慮使用 L2 距離。
分析向量：判斷向量是否已正規化。如果是，您可以使用餘弦相似度或點積，並預期會得到類似的排名。

仔細考量這些因素，就能為 Index 選取最合適的距離指標，進而獲得更準確且有意義的相似性搜尋結果。

建立 ANN 索引

您可以在特定嵌入欄位上建立 ANN 索引。根據預設，所有資料物件字串、數值和布林值欄位都會推送至索引，以允許內嵌篩選。

如要盡量節省運算成本，您可以確切指定哪些欄位應可篩選 (filter_fields)，哪些欄位應只儲存為酬載 (store_fields)。

以下範例說明如何在 ID 為 COLLECTION_ID 的集合中建立索引 INDEX_ID。

REST

使用任何要求資料之前，請先修改下列項目的值：

INDEX_ID：索引 ID。
COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes?indexId=INDEX_ID

JSON 要求主體：

{
    "index_field": "plot_embedding",
    "filter_fields": [
      "year",
      "genre"
    ],
    "store_fields": [
      "title"
    ]
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes?indexId=INDEX_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes?indexId=INDEX_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770302393524-64a14a54fa197-0dea326c-5a90efda",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1beta.OperationMetadata",
    "createTime": "2026-02-05T14:39:53.558308609Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

gcloud

使用下方的任何指令資料之前，請先替換以下項目：

INDEX_ID：索引 ID。
COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud beta vector-search indexes create INDEX_ID \
  --collection=COLLECTION_ID \
  --index-field=plot_embedding \
  --filter-fields=year,genre \
  --store-fields=title \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes create INDEX_ID `
  --collection=COLLECTION_ID `
  --index-field=plot_embedding `
  --filter-fields=year,genre `
  --store-fields=title `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes create INDEX_ID ^
  --collection=COLLECTION_ID ^
  --index-field=plot_embedding ^
  --filter-fields=year,genre ^
  --store-fields=title ^
  --location=LOCATION ^
  --project=PROJECT_ID

您應該會收到類似以下的回應：

Created index [INDEX_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create a client
client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request argument(s)
index = vectorsearch_v1beta.Index(
    index_field="plot_embedding",
    filter_fields=["year", "genre"],
    store_fields=["title"],
)
request = vectorsearch_v1beta.CreateIndexRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    index_id="INDEX_ID",
    index=index,
)

# Make the request
operation = client.create_index(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

在這個範例中，要求指定 year 和 genre 可篩選 (以篩選欄位形式傳遞至索引)，而酬載欄位 title 不可篩選。

取得索引

以下範例說明如何取得儲存在 ID 為 COLLECTION_ID 的集合中的現有索引 INDEX_ID。

REST

使用任何要求資料之前，請先修改下列項目的值：

INDEX_ID：索引 ID。
COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

GET https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
  "createTime": "2026-02-05T14:39:53.550302019Z",
  "updateTime": "2026-02-05T14:39:53.550302019Z",
  "distanceMetric": "DOT_PRODUCT",
  "indexField": "plot_embedding",
  "filterFields": [
    "year",
    "genre"
  ],
  "storeFields": [
    "title"
  ]
}

gcloud

使用下方的任何指令資料之前，請先替換以下項目：

INDEX_ID：索引 ID。
COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud beta vector-search indexes describe INDEX_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes describe INDEX_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes describe INDEX_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

您應該會收到類似以下的回應：

createTime: '2026-02-05T14:39:53.550302019Z'
distanceMetric: DOT_PRODUCT
filterFields:
- year
- genre
indexField: plot_embedding
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID
storeFields:
- title
updateTime: '2026-02-05T14:39:53.550302019Z'

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.GetIndexRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
)

# Make the request
response = vector_search_service_client.get_index(request=request)

# Handle the response
print(response)

列出索引

以下範例說明如何列出 ID 為 COLLECTION_ID 的集合中所有索引。

REST

使用任何要求資料之前，請先修改下列項目的值：

COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

GET https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "indexes": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
      "createTime": "2026-02-05T14:39:53.550302019Z",
      "updateTime": "2026-02-05T14:39:53.550302019Z",
      "distanceMetric": "DOT_PRODUCT",
      "indexField": "plot_embedding",
      "filterFields": [
        "year",
        "genre"
      ],
      "storeFields": [
        "title"
      ]
    }
  ]
}

gcloud

使用下方的任何指令資料之前，請先替換以下項目：

COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud beta vector-search indexes list \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes list `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes list ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

您應該會收到類似以下的回應：

---
createTime: '2026-02-05T14:39:53.550302019Z'
distanceMetric: DOT_PRODUCT
filterFields:
- year
- genre
indexField: plot_embedding
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID
storeFields:
- title
updateTime: '2026-02-05T14:39:53.550302019Z'

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.ListIndexesRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
)

# Make the request
page_result = vector_search_service_client.list_indexes(request=request)

# Handle the response
for response in page_result:
    print(response)

刪除索引

以下範例說明如何從 ID 為 COLLECTION_ID 的集合中，刪除現有的索引 INDEX_ID。

REST

使用任何要求資料之前，請先修改下列項目的值：

INDEX_ID：索引 ID。
COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

DELETE https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770303323075-64a14dcb7734e-eb6a75d5-6798cef3",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1beta.OperationMetadata",
    "createTime": "2026-02-05T14:55:23.086771813Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

gcloud

使用下方的任何指令資料之前，請先替換以下項目：

INDEX_ID：索引 ID。
COLLECTION_ID：集合的 ID。
LOCATION：您使用 Vertex AI 的區域。
PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud beta vector-search indexes delete INDEX_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes delete INDEX_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes delete INDEX_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

您應該會收到類似以下的回應：

Deleted index [INDEX_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.DeleteIndexRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
)

# Make the request
operation = vector_search_service_client.delete_index(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

後續步驟

瞭解如何查詢資料物件。
瞭解如何使用語意搜尋或混合搜尋搜尋資料物件。

集合索引 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

選擇距離指標

建立 ANN 索引

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

取得索引

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

列出索引

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

刪除索引

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

後續步驟

集合索引