Lo scopo dell'API Search è trovare oggetti di dati simili a una determinata query e restituire un elenco di risultati classificati (in base alla somiglianza). L'API Search supporta anche il filtraggio.
L'API Search offre diversi modi per cercare oggetti di dati: ricerca vettoriale, ricerca a testo intero e ricerca semantica. Inoltre, è possibile combinare più ricerche di qualsiasi tipo per ottenere una ricerca ibrida.
Ricerca vettoriale
La ricerca vettoriale ti consente di fornire il tuo vettore di query. Questo è il metodo
obbligatorio per la ricerca di campi di incorporamento che non hanno un embedding-config.
Se vengono forniti più campi vector_search, i risultati vengono combinati utilizzando
pesi uguali.
L'esempio seguente mostra come eseguire una ricerca vettoriale su 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 Agent Platform.
- 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/dataObjects:search
Corpo JSON della richiesta:
{
"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": "*"
}
}
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"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
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
-
SEARCH_VECTOR_FILE: il percorso locale di un file JSON contenente il vettore denso o sparso con cui eseguire la ricerca.
Esempio di contenuti del file per un vettore denso:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Esempio di contenuti del file per un vettore sparso:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: l'ID della raccolta.
- LOCATION: la regione in cui utilizzi Agent Platform.
- PROJECT_ID: il tuo Google Cloud ID progetto.
Esegui questo 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
Dovresti ricevere una risposta simile alla seguente:
---
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)
Ricerca testo
Esegue la ricerca full-text senza vettori sparsi. Il dialetto di query "word" predefinito
tratta l'intero input come singoli termini di ricerca con un operatore
AND implicito. Puoi impostare enhanced_query su true per espandere i termini di ricerca,
gestire la derivazione, la rimozione delle stop word e consentire operatori di ricerca aggiuntivi:
OR: un operatore di disgiunzione sensibile alle maiuscole che corrisponde ai documenti contenenti almeno uno dei termini specificati. Si applica solo ai due termini adiacenti.": (virgolette doppie) per la ricerca di frasi.-: l'operatore di negazione. Esclude i documenti che contengono i termini che lo precedono.
Ricerca semantica
Questa ricerca converte la query di testo in incorporamenti per trovare risultati in base al significato semantico. Utilizza embedding-config definito nello schema per generare l'incorporamento della query. Se vengono forniti più campi vector_search, i risultati vengono combinati utilizzando pesi uguali.
Ricerca con la ricerca ibrida
Utilizza batch_search_data_objects per eseguire più ricerche in parallelo
(ricerca vettoriale, ricerca di testo e ricerca semantica). I risultati possono essere combinati e classificati utilizzando il Ranker ReciprocalRankFusion, che unisce i set di risultati utilizzando l'algoritmo Reciprocal Rank Fusion (RFF).