Tujuan Search API adalah untuk menemukan Objek Data yang mirip dengan kueri tertentu dan menampilkan daftar hasil yang diberi peringkat (berdasarkan kemiripan). Search API juga mendukung pemfilteran.
Search API menawarkan berbagai cara untuk menelusuri Objek Data: penelusuran vektor, penelusuran teks lengkap, dan penelusuran semantik. Selain itu, beberapa penelusuran dari jenis apa pun dapat digabungkan untuk mencapai penelusuran campuran.
Penelusuran vektor
Penelusuran vektor memungkinkan Anda menyediakan vektor kueri Anda sendiri. Ini adalah metode yang diperlukan untuk menelusuri kolom embedding yang tidak memiliki embedding-config.
Jika beberapa kolom vector_search disediakan, hasilnya akan digabungkan menggunakan bobot yang sama.
Contoh berikut menunjukkan cara melakukan penelusuran vektor pada Koleksi dengan COLLECTION_ID.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- COLLECTION_ID: ID koleksi.
- LOCATION: Region tempat Anda menggunakan Agent Platform.
- PROJECT_ID: Project ID Anda Google Cloud .
Metode HTTP dan URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Meminta isi JSON:
{
"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": "*"
}
}
}
Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:
Anda akan melihat respons JSON seperti berikut:
{
"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
Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:
-
SEARCH_VECTOR_FILE: Jalur lokal ke file JSON yang berisi vektor padat atau vektor renggang untuk ditelusuri.
Contoh konten file untuk vektor padat:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Contoh konten file untuk vektor renggang:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: ID koleksi.
- LOCATION: Region tempat Anda menggunakan Agent Platform.
- PROJECT_ID: Project ID Anda Google Cloud .
Jalankan perintah berikut:
Linux, macOS, atau 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
Anda akan melihat respons seperti berikut:
---
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)
Penelusuran teks
Tindakan ini akan melakukan penelusuran teks lengkap tanpa vektor jarang. Dialek kueri "kata" default memperlakukan seluruh input sebagai istilah penelusuran individual dengan operator AND implisit. Anda dapat menetapkan enhanced_query ke true untuk memperluas istilah penelusuran, menangani stemming, menghapus kata berhenti, dan mengizinkan operator penelusuran tambahan:
OR: Operator disjungsi yang peka huruf besar/kecil yang cocok dengan dokumen yang berisi setidaknya salah satu istilah yang ditentukan. Operator ini hanya berlaku untuk dua istilah yang berdekatan.": (tanda kutip ganda) untuk penelusuran frasa.-: Operator negasi. Operator ini mengecualikan dokumen yang berisi istilah apa pun yang ditempatkan sebelum operator.
Penelusuran semantik
Penelusuran ini mengonversi kueri teks Anda menjadi embedding untuk menemukan hasil berdasarkan makna semantik. Penelusuran ini menggunakan embedding-config yang ditentukan dalam skema Anda untuk membuat embedding kueri. Jika beberapa kolom vector_search disediakan, hasilnya akan digabungkan menggunakan bobot yang sama.
Menelusuri menggunakan penelusuran campuran
Gunakan batch_search_data_objects untuk menjalankan beberapa penelusuran secara paralel (penelusuran vektor, penelusuran teks, dan penelusuran semantik). Hasilnya dapat digabungkan dan diberi peringkat menggunakan Ranker ReciprocalRankFusion , yang menggabungkan kumpulan hasil menggunakan algoritma Reciprocal Rank Fusion (RFF).