Indici di raccolta

Per preparare l'applicazione per la scalabilità e il rendimento della produzione, devi creare indici di raccolta. Senza un indice, le ricerche ANN sono lente perché eseguono una scansione esaustiva. La creazione di un indice rende molto veloci le ricerche nei campi vettoriali indicizzati.

Scegliere una metrica di distanza

La scelta della metrica di distanza corretta per l'indice è fondamentale per ottenere risultati di ricerca di somiglianze accurati e pertinenti. La scelta ottimale dipende principalmente dalle caratteristiche degli incorporamenti vettoriali e dalla natura dei dati. La regola più importante è utilizzare la metrica di distanza su cui è stato addestrato il modello di incorporamento. I modelli di incorporamento sono ottimizzati per produrre rappresentazioni vettoriali in cui la somiglianza viene acquisita al meglio da un calcolo della distanza specifico. L'utilizzo di una metrica diversa può portare a risultati di ricerca non ottimali o errati.

  • Consulta la documentazione del modello di incorporamento: questo è il modo più affidabile per determinare la metrica di distanza prevista.

  • Considera il tuo caso d'uso: per trovare testo o immagini semanticamente simili, la somiglianza del coseno è spesso la scelta migliore. Se la "forza" o "intensità" rappresentata dalla magnitudo del vettore è importante, prendi in considerazione la distanza L2.

  • Analizza i vettori:determina se i vettori sono normalizzati. In questo caso, puoi utilizzare la similarità del coseno o il prodotto scalare e prevedere un ranking simile.

Considerando attentamente questi fattori, puoi selezionare la metrica di distanza più appropriata per il tuo indice, ottenendo risultati di ricerca per similarità più precisi e significativi.

Creazione di un indice ANN

Puoi creare un indice ANN su un campo di incorporamento specifico. Per impostazione predefinita, tutti i campi stringa, numerici e booleani dell'oggetto dati vengono trasferiti all'indice per consentire il filtraggio in linea.

Per ottimizzare i costi di calcolo, puoi specificare esattamente quali campi devono essere filtrabili (filter_fields) e quali devono essere archiviati solo come payload (store_fields).

L'esempio seguente mostra come creare un indice, INDEX_ID, in una raccolta con l'ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • INDEX_ID: l'ID dell'indice.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • INDEX_ID: l'ID dell'indice.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

Linux, macOS o 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

Dovresti ricevere una risposta simile alla seguente:

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

Nell'esempio, la richiesta specifica che year e genre sono filtrabili (passati come campi di filtro all'indice) e il campo payload title non è filtrabile.

Ottenere un indice

Di seguito viene illustrato come ottenere un indice esistente, INDEX_ID, archiviato in una raccolta con ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • INDEX_ID: l'ID dell'indice.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • INDEX_ID: l'ID dell'indice.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

Linux, macOS o 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

Dovresti ricevere una risposta simile alla seguente:

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)

Indici di elenchi

L'esempio seguente mostra come elencare tutti gli indici in una raccolta con l'ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

Linux, macOS o 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

Dovresti ricevere una risposta simile alla seguente:

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

Eliminare un indice

L'esempio seguente mostra come eliminare un indice esistente, INDEX_ID, da una raccolta con l'ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • INDEX_ID: l'ID dell'indice.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • INDEX_ID: l'ID dell'indice.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Vertex AI.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

Linux, macOS o 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

Dovresti ricevere una risposta simile alla seguente:

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

Passaggi successivi