Mit der Search API können Sie Datenobjekte finden, die einer bestimmten Abfrage ähneln, und eine Liste mit sortierten Ergebnissen zurückgeben (sortiert nach Ähnlichkeit). Die Search API unterstützt auch das Filtern.
Die Search API bietet verschiedene Möglichkeiten, nach Datenobjekten zu suchen: Vektorsuche, Volltextsuche und semantische Suche. Außerdem können mehrere Suchvorgänge beliebigen Typs kombiniert werden, um eine Hybridsuche zu erhalten.
Vektorsuche
Bei der Vektorsuche können Sie einen eigenen Abfragevektor angeben. Dies ist die erforderliche Methode zum Suchen in Einbettungsfeldern ohne embedding-config.
Wenn mehrere vector_search-Felder angegeben werden, werden die Ergebnisse mit gleichen Gewichtungen kombiniert.
Im folgenden Beispiel wird gezeigt, wie Sie eine Vektorsuche in einer Sammlung mit der ID COLLECTION_ID durchführen.
REST
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- COLLECTION_ID: Die ID der Sammlung
- LOCATION: Die Region, in der Sie die Agent Platform verwenden
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
HTTP-Methode und URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
JSON-Text anfordern:
{
"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": "*"
}
}
}
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:
{
"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
Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
-
SEARCH_VECTOR_FILE: Der lokale Pfad zu einer JSON-Datei mit dem dichten oder dünnbesetzten Vektor, mit dem gesucht werden soll.
Beispiel für den Inhalt einer Datei mit einem dichten Vektor:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Beispiel für den Inhalt einer Datei mit einem dünnbesetzten Vektor:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: Die ID der Sammlung
- LOCATION: Die Region, in der Sie die Agent Platform verwenden
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
Führen Sie folgenden Befehl aus:
Linux, macOS oder 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
Sie sollten eine Antwort ähnlich der folgenden erhalten:
---
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)
Textsuche
Hier wird eine Volltextsuche ohne dünnbesetzte Vektoren durchgeführt. Beim Standardabfragedialekt „word“ wird die gesamte Eingabe als einzelne Suchbegriffe mit einem impliziten AND-Operator behandelt. Sie können enhanced_query auf true setzen, um Suchbegriffe zu erweitern, Stemming zu verarbeiten, Stoppwörter zu entfernen und zusätzliche Suchoperatoren zuzulassen:
OR: Ein Fallunterscheidungsoperator, der Dokumente abgleicht, die mindestens einen der angegebenen Begriffe enthalten. Er gilt nur für die beiden angrenzenden Begriffe.": (doppelte Anführungszeichen) für die Suche nach Wortgruppen.-: Der Negationsoperator. Er schließt Dokumente aus, die Begriffe enthalten, vor denen er steht.
Semantische Suche
Bei dieser Suche wird Ihre Textabfrage in Einbettungen umgewandelt, um Ergebnisse basierend auf der semantischen Bedeutung zu finden. Dabei wird die in Ihrem Schema definierte embedding-config verwendet, um die Abfrageeinbettung zu generieren. Wenn mehrere vector_search-Felder angegeben werden, werden die Ergebnisse mit gleichen Gewichtungen kombiniert.
Suche mit der Hybridsuche
Verwenden Sie batch_search_data_objects, um mehrere Suchvorgänge parallel auszuführen (Vektorsuche, Textsuche und semantische Suche). Die Ergebnisse können optional mit dem ReciprocalRankFusion -Ranker kombiniert und sortiert werden. Dabei werden die Ergebnismengen mit dem Reciprocal Rank Fusion-Algorithmus (RFF) zusammengeführt.