L'API Search permet de trouver des objets de données semblables à une requête donnée et de renvoyer une liste de résultats classés (par similarité). L'API Search accepte également le filtrage.
L'API Search propose différentes méthodes pour rechercher des objets de données : recherche vectorielle, recherche en texte intégral et recherche sémantique. De plus, plusieurs recherches de n'importe quel type peuvent être combinées pour effectuer une recherche hybride.
Recherche vectorielle
La recherche vectorielle vous permet de fournir votre propre vecteur de requête. Il s'agit de la méthode requise pour rechercher des champs d'embedding qui ne comportent pas de embedding-config.
Si plusieurs champs vector_search sont fournis, les résultats sont combinés à l'aide de pondérations égales.
L'exemple suivant montre comment effectuer une recherche vectorielle sur une collection avec l'ID COLLECTION_ID.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- COLLECTION_ID : ID de la collection.
- LOCATION : région dans laquelle vous utilisez Agent Platform.
- PROJECT_ID : ID de votre projet Google Cloud .
Méthode HTTP et URL :
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Corps JSON de la requête :
{
"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": "*"
}
}
}
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{
"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
Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :
-
SEARCH_VECTOR_FILE : chemin d'accès local à un fichier JSON contenant le vecteur dense ou creux à utiliser pour la recherche.
Exemple de contenu d'un fichier pour un vecteur dense :
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Exemple de contenu d'un fichier pour un vecteur creux :
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID : ID de la collection.
- LOCATION : région dans laquelle vous utilisez Agent Platform.
- PROJECT_ID : ID de votre projet Google Cloud .
Exécutez la commande suivante :
Linux, macOS ou 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
Vous devriez obtenir un résultat semblable à celui-ci :
---
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)
Recherche textuelle
Cela effectue une recherche en texte intégral sans vecteurs creux. Le dialecte de requête "word" par défaut traite l'intégralité de l'entrée comme des termes de recherche individuels avec un opérateur AND implicite. Vous pouvez définir enhanced_query sur true pour étendre les termes de recherche, gérer la racinisation et la suppression des mots vides, et autoriser des opérateurs de recherche supplémentaires :
OR: opérateur de disjonction sensible à la casse qui correspond aux documents contenant au moins l'un des termes spécifiés. Elle ne s'applique qu'aux deux termes adjacents.": (guillemets doubles) pour la recherche d'expressions.-: opérateur de négation. Il exclut les documents contenant les termes qui le précèdent.
Recherche sémantique
Cette recherche convertit votre requête textuelle en embeddings pour trouver des résultats basés sur la signification sémantique. Il utilise le embedding-config défini dans votre schéma pour générer l'embedding de requête. Si plusieurs champs vector_search sont fournis, les résultats sont combinés à l'aide de pondérations égales.
Rechercher à l'aide de la recherche hybride
Utilisez batch_search_data_objects pour exécuter plusieurs recherches en parallèle (recherche vectorielle, recherche textuelle et recherche sémantique). Les résultats peuvent éventuellement être combinés et classés à l'aide du module de classement ReciprocalRankFusion, qui fusionne les ensembles de résultats à l'aide de l'algorithme de fusion de classement réciproque (RRF).