Índices de colección

Para preparar tu aplicación para el rendimiento y la escala de producción, debes crear índices de colección. Sin un índice, las búsquedas de ANN son lentas porque realizan un análisis de fuerza bruta. Crear un índice hace que las búsquedas en los campos de vectores indexados sean muy rápidas.

Cómo elegir una métrica de distancia

Elegir la métrica de distancia adecuada para tu índice es fundamental para obtener resultados de búsqueda por similitud precisos y pertinentes. La elección óptima depende principalmente de las características de tus incorporaciones de vectores y la naturaleza de tus datos. La regla más importante es usar la métrica de distancia con la que se entrenó tu modelo de embedding. Los modelos de embedding se optimizan para producir representaciones vectoriales en las que la similitud se capta mejor con un cálculo de distancia específico. Usar una métrica diferente puede generar resultados de la búsqueda incorrectos o no óptimos.

  • Consulta la documentación de tu modelo de incorporación: Esta es la forma más confiable de determinar la métrica de distancia prevista.

  • Ten en cuenta tu caso de uso: Para encontrar texto o imágenes semánticamente similares, la similitud de coseno suele ser la mejor opción. Si la "fuerza" o la "intensidad" representadas por la magnitud del vector son importantes, considera la distancia L2.

  • Analiza tus vectores: Determina si tus vectores están normalizados. Si es así, puedes usar la similitud del coseno o el producto escalar, y esperar una clasificación similar.

Si consideras cuidadosamente estos factores, podrás seleccionar la métrica de distancia más adecuada para tu índice, lo que generará resultados de búsqueda de similitud más precisos y significativos.

Cómo crear un índice de ANN

Puedes crear un índice de ANN en un campo de incorporación específico. De forma predeterminada, todos los campos de cadena, numéricos y booleanos del objeto de datos se envían al índice para permitir el filtrado intercalado.

Para optimizar los costos de procesamiento, puedes especificar exactamente qué campos deben ser filtrables (filter_fields) y cuáles solo deben almacenarse como carga útil (store_fields).

En el siguiente ejemplo, se muestra cómo crear un índice, INDEX_ID, en una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • INDEX_ID: Es el ID del índice.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • INDEX_ID: Es el ID del índice.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Ejecuta el siguiente 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

Deberías recibir una respuesta similar a la que figura a continuación:

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

En el ejemplo, la solicitud especifica que year y genre se pueden filtrar (se pasan como campos de filtro al índice) y que el campo de carga útil title no se puede filtrar.

Cómo obtener un índice

En el siguiente ejemplo, se muestra cómo obtener un índice existente, INDEX_ID, almacenado en una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • INDEX_ID: Es el ID del índice.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • INDEX_ID: Es el ID del índice.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Ejecuta el siguiente 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

Deberías recibir una respuesta similar a la que figura a continuación:

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)

Cómo enumerar índices

En el siguiente ejemplo, se muestra cómo enumerar todos los índices de una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Ejecuta el siguiente 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

Deberías recibir una respuesta similar a la que figura a continuación:

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

Cómo borrar un índice

En el siguiente ejemplo, se muestra cómo borrar un índice existente, INDEX_ID, de una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • INDEX_ID: Es el ID del índice.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • INDEX_ID: Es el ID del índice.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: Es el Google Cloud ID del proyecto.

Ejecuta el siguiente 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

Deberías recibir una respuesta similar a la que figura a continuación:

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

Próximos pasos