El propósito de la API de Search es encontrar objetos de datos que sean similares a una consulta determinada y devolver una lista de resultados clasificados (según la similitud). La API de búsqueda también admite el filtrado.
La API de Search ofrece varias formas de buscar objetos de datos: búsqueda de vectores, búsqueda en el texto completo y búsqueda semántica. Además, se pueden combinar varias búsquedas de cualquier tipo para lograr una búsqueda híbrida.
Búsqueda de vectores
La búsqueda vectorial te permite proporcionar tu propio vector de búsqueda. Este es el método requerido para buscar campos de incorporación que no tienen un embedding-config. Si se proporcionan varios campos vector_search, los resultados se combinan con pesos iguales.
En el siguiente ejemplo, se muestra cómo realizar una búsqueda de vectores 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:
- COLLECTION_ID: ID de la colección.
- LOCATION: Es la región en la que usas Agent Platform.
- PROJECT_ID: Tu Google Cloud ID del proyecto.
Método HTTP y URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Cuerpo JSON de la solicitud:
{
"vector_search": {
"search_field": "plot_embedding",
"vector": {
"values": [
0.42426406871192845,
0.565685424949238,
0.7071067811865475
]
},
"filter": {
"genre": {
"$eq": "Thriller"
}
},
"top_k": 5,
"output_fields": {
"data_fields": "*",
"vector_fields": "*",
"metadata_fields": "*"
}
}
}
Para enviar tu solicitud, expande una de estas opciones:
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{
"results": [
{
"dataObject": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
"createTime": "2026-01-31T20:05:06Z",
"updateTime": "2026-02-02T13:59:24Z",
"data": {
"year": 1991,
"title": "The Silence of the Lambs",
"director": "Jonathan Demme",
"genre": "Thriller"
},
"vectors": {
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
"distance": 1.697
},
{
"dataObject": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
"createTime": "2026-02-04T14:35:29Z",
"updateTime": "2026-02-04T14:37:29Z",
"data": {
"year": 1995,
"title": "Se7en",
"director": "David Fincher",
"genre": "Thriller"
},
"vectors": {
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
"distance": 1.75
}
]
}
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
- SEARCH_VECTOR_FILE: Es la ruta de acceso local a un archivo JSON que contiene el vector denso o disperso con el que se realizará la búsqueda.
Ejemplo de contenido de archivo para un vector denso:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Ejemplo de contenido de archivo para un vector disperso:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: ID de la colección.
- LOCATION: Es la región en la que usas Agent Platform.
- PROJECT_ID: Tu Google Cloud ID del proyecto.
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud beta vector-search collections data-objects search \ --vector-search-field="plot_embedding" \ --vector-from-file=SEARCH_VECTOR_FILE \ --json-filter='{"genre": {"$eq": "Thriller"}}' \ --top-k=5 \ --output-data-fields='*' \ --output-vector-fields='*' \ --output-metadata-fields='*' \ --collection=COLLECTION_ID \ --location=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud beta vector-search collections data-objects search ` --vector-search-field="plot_embedding" ` --vector-from-file=SEARCH_VECTOR_FILE ` --json-filter='{"genre": {"$eq": "Thriller"}}' ` --top-k=5 ` --output-data-fields='*' ` --output-vector-fields='*' ` --output-metadata-fields='*' ` --collection=COLLECTION_ID ` --location=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud beta vector-search collections data-objects search ^ --vector-search-field="plot_embedding" ^ --vector-from-file=SEARCH_VECTOR_FILE ^ --json-filter='{"genre": {"$eq": "Thriller"}}' ^ --top-k=5 ^ --output-data-fields='*' ^ --output-vector-fields='*' ^ --output-metadata-fields='*' ^ --collection=COLLECTION_ID ^ --location=LOCATION ^ --project=PROJECT_ID
Deberías recibir una respuesta similar a la que figura a continuación:
---
dataObject:
createTime: '2026-01-31T20:05:06Z'
data:
director: Jonathan Demme
genre: Thriller
title: The Silence of the Lambs
year: 1991
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
updateTime: '2026-02-02T13:59:24Z'
vectors:
genre_embedding:
dense:
values:
- 0.38638
- 0.739343
- 0.161891
- 0.527137
plot_embedding:
dense:
values:
- 1.0
- 1.0
- 1.0
soundtrack_embedding:
dense:
values:
- 0.592045
- 0.0830164
- 0.126473
- 0.619643
- 0.492583
sparse_embedding:
sparse:
indices:
- 4065
- 13326
- 17377
- 25918
- 28105
- 32683
- 42998
values:
- 1.0
- 6.0
- 3.0
- 2.0
- 8.0
- 5.0
- 2.0
distance: 1.697
---
dataObject:
createTime: '2026-02-04T14:35:29Z'
data:
director: David Fincher
genre: Thriller
title: Se7en
year: 1995
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
updateTime: '2026-02-04T14:37:29Z'
vectors:
genre_embedding:
dense:
values:
- 0.38638
- 0.739343
- 0.161891
- 0.527137
plot_embedding:
dense:
values:
- 1.0
- 1.0
- 1.0
soundtrack_embedding:
dense:
values:
- 0.592045
- 0.0830164
- 0.126473
- 0.619643
- 0.492583
sparse_embedding:
sparse:
indices:
- 4065
- 13326
- 17377
- 25918
- 28105
- 32683
- 42998
values:
- 1.0
- 6.0
- 3.0
- 2.0
- 8.0
- 5.0
- 2.0
distance: 1.75
Python
from google.cloud import vectorsearch_v1beta
# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()
# Initialize request
vector_search = vectorsearch_v1beta.VectorSearch(
search_field="plot_embedding",
vector={"values": [0.1, 0.2, 0.3]},
filter={"genre": {"$eq": "Thriller"}},
top_k=5,
)
request = vectorsearch_v1beta.SearchDataObjectsRequest(
parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
vector_search=vector_search,
)
# Make the request
response = data_object_search_service_client.search_data_objects(request=request)
# Handle the response
print(response)
Búsqueda de texto
Esto realiza una búsqueda en el texto completo sin vectores dispersos. El dialecto de consulta predeterminado "palabra" trata toda la entrada como términos de búsqueda individuales con un operador AND implícito. Puedes establecer enhanced_query en true para expandir los términos de búsqueda, controlar la lematización, quitar las palabras vacías y permitir operadores de búsqueda adicionales:
OR: Es un operador de disyunción que distingue mayúsculas de minúsculas y que coincide con los documentos que contienen al menos uno de los términos especificados. Solo se aplica a los dos términos adyacentes.": (comillas dobles) para la búsqueda de frases-: Es el operador de negación. Excluye los documentos que contienen los términos que preceden al operador.
Búsqueda semántica
Esta búsqueda convierte tu consulta de texto en embeddings para encontrar resultados basados en el significado semántico. Utiliza el embedding-config definido en tu esquema para generar la incorporación de la búsqueda. Si se proporcionan varios campos vector_search, los resultados se combinan con pesos iguales.
Cómo realizar búsquedas con la búsqueda híbrida
Usa batch_search_data_objects para ejecutar varias búsquedas en paralelo (búsqueda de vectores, búsqueda de texto y búsqueda semántica). Los resultados se pueden combinar y clasificar de forma opcional con el clasificador ReciprocalRankFusion, que combina conjuntos de resultados con el algoritmo de fusión de clasificación recíproca (RRF).