Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Halaman ini menjelaskan cara mengkueri indeks pencarian vektor, termasuk penomoran halaman, filter, dan reranking.
Misalnya notebook yang mengilustrasikan cara membuat dan mengkueri titik akhir pencarian vektor dan indeks, lihat Buku catatan contoh pencarian vektor. Untuk informasi referensi, lihat referensi SDK Python.
Installation
Untuk menggunakan SDK pencarian vektor, Anda harus menginstalnya di notebook Anda. Gunakan kode berikut untuk menginstal paket.
%pip install databricks-vectorsearch
dbutils.library.restartPython()
Kemudian gunakan perintah berikut untuk mengimpor VectorSearchClient:
from databricks.vector_search.client import VectorSearchClient
Untuk informasi tentang autentikasi, lihat Perlindungan dan autentikasi data.
Cara mengkueri indeks pencarian vektor
Anda hanya dapat mengkueri indeks pencarian vektor menggunakan Python SDK, REST API, atau fungsi SQL vector_search() AI.
Nota
Jika pengguna yang mengkueri indeks bukan pemilik indeks pencarian vektor, pengguna harus memiliki hak istimewa UC berikut:
- USE CATALOG pada katalog yang berisi indeks pencarian vektor.
- USE SCHEMA pada skema yang berisi indeks pencarian vektor.
- SELECT pada indeks pencarian vektor.
Jenis kueri yang default adalah ann (tetangga terdekat perkiraan). Untuk detail tentang algoritma pengambilan yang berbeda, lihat Algoritma pengambilan.
- Untuk melakukan pencarian hibrid berdasarkan kemiripan kata kunci, atur parameter
query_typekehybrid. Dengan pencarian hibrid, semua kolom metadata teks disertakan, dan maksimal 200 hasil dikembalikan. - Untuk menggunakan reranker dalam kueri, lihat Menggunakan reranker dalam kueri.
Penting
Pencarian teks lengkap tersedia sebagai fitur beta. Untuk melakukan pencarian teks lengkap, atur parameter query_type ke FULL_TEXT. Dengan pencarian teks lengkap, Anda dapat mengambil hingga 200 hasil berdasarkan pencocokan kata kunci tanpa menggunakan penyematan vektor. Kueri teks lengkap didukung pada titik akhir standar dan yang dioptimalkan untuk penyimpanan. Pada endpoint yang telah dioptimalkan untuk penyimpanan, Anda juga dapat membuat indeks pencarian teks lengkap khusus tanpa penyematan. Lihat Membuat indeks pencarian teks lengkap (Beta).
Python titik akhir standar SDK
Untuk detailnya, lihat referensi SDK Python.
# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "field2"],
num_results=2
)
# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
query_text="Greek myths",
columns=["id", "field2"],
num_results=2,
query_type="hybrid"
)
# Delta Sync Index using full-text search (Beta)
results4 = index.similarity_search(
query_text="Greek myths",
columns=["id", "field2"],
num_results=2,
query_type="FULL_TEXT"
)
# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
query_vector=[0.9] * 1024,
columns=["id", "text"],
num_results=2
)
Python SDK titik akhir yang dioptimalkan untuk penyimpanan
Untuk detailnya, lihat referensi SDK Python.
Antarmuka filter yang sudah ada telah dirancang ulang untuk mengoptimalkan indeks pencarian vektor dalam penyimpanan, dengan mengadopsi string filter yang lebih mirip SQL daripada menggunakan kamus filter yang dipakai pada titik akhir pencarian vektor standar.
client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")
# similarity search with query vector
results = index.similarity_search(
query_vector=[0.2, 0.33, 0.19, 0.52],
columns=["id", "text"],
num_results=2
)
# similarity search with query vector and filter string
results = index.similarity_search(
query_vector=[0.2, 0.33, 0.19, 0.52],
columns=["id", "text"],
# this is a single filter string similar to SQL WHERE clause syntax
filters="language = 'en' AND country = 'us'",
num_results=2
)
REST API
Lihat dokumentasi referensi REST API: POST /api/2.0/vector-search/indexes/{index_name}/query.
Untuk aplikasi produksi, Databricks merekomendasikan penggunaan perwakilan layanan alih-alih token akses pribadi. Selain peningkatan keamanan dan manajemen akses, penggunaan prinsip layanan dapat meningkatkan kinerja hingga 100 milidetik per kueri.
Contoh kode berikut menggambarkan cara melakukan kueri pada indeks menggunakan service principal.
export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...
# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint, then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'
# Generate OAuth token
export TOKEN=$(curl -X POST --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')
# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')
# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'
# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'
Contoh kode berikut mengilustrasikan cara mengkueri indeks menggunakan token akses pribadi (PAT).
export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
# Query vector search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'
# Query vector search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'
SQL
Penting
Fungsi AI saat ini berada dalam Pratinjau Publik.
Untuk menggunakan fungsi AI ini, lihat vector_search fungsi.
Pengaturan halaman
Saat kueri meminta lebih dari 1.000 hasil, hasilnya secara otomatis dikembalikan di halaman hingga 1.000. Jumlah maksimum hasil yang dapat dikembalikan kueri tunggal di semua halaman adalah 10.000. Titik akhir standar dan penyimpanan yang dioptimalkan mendukung penomoran halaman.
Penomoran halaman berfungsi dengan semua jenis kueri.
Python SDK
Python SDK menangani paginasi secara transparan. Saat Anda mengatur num_results ke nilai yang lebih besar dari 1.000, SDK secara otomatis mengambil semua halaman dan mengembalikan tataan hasil lengkap. Tidak diperlukan kode tambahan.
# The SDK automatically paginates and returns all 5000 results
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
num_results=5000
)
REST API
Saat Anda menggunakan REST API secara langsung, Anda harus menangani paginasi secara manual. Jika lebih banyak hasil tersedia, respons menyertakan next_page_token kolom. Untuk mengambil halaman hasil berikutnya, teruskan token ini ke titik akhir kueri-halaman berikutnya.
Lihat dokumentasi referensi REST API: POST /api/2.0/vector-search/indexes/{index_name}/query-next-page.
export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
# Initial query - if num_results exceeds 1000, the response includes next_page_token
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
--url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query \
--data '{"num_results": 5000, "query_text": "...", "columns": ["id", "text"]}'
# Use next_page_token from the response to get the next page
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
--url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query-next-page \
--data '{"page_token": "<next_page_token from previous response>"}'
Lanjutkan memanggil titik akhir kueri-halaman berikutnya dengan next_page_token dari setiap respons hingga token kosong atau tidak ada, yang menunjukkan bahwa semua hasil telah dikembalikan.
Menggunakan filter pada kueri
Sebuah kueri dapat menetapkan filter berdasarkan kolom mana pun dalam tabel Delta.
similarity_search hanya mengembalikan baris-baris yang sesuai dengan filter yang ditentukan.
Tabel berikut mencantumkan filter yang didukung.
Nota
Untuk titik akhir yang dioptimalkan untuk penyimpanan, hasilnya diambil secara berlebihan. Jika Anda mengatur num_results ke k, lebih dari k hasil diambil, dan filter diterapkan ke hasil yang diambil. Ada kemungkinan bahwa tidak ada hasil yang akan dikembalikan bahkan jika ada hasil dalam himpunan data yang cocok dengan kondisi filter, jika skor dokumen-dokumen ini tidak berada di antara bagian atas.
| Operator penyaring | Perilaku | Examples |
|---|---|---|
NOT |
Standar: Menonaktifkan filter. Kunci harus diakhir dengan "NOT". Sebagai contoh, "warna NOT" dengan nilai "merah" cocok dengan dokumen di mana warnanya bukan merah. Dioptimalkan penyimpanan: Lihat != operator (tanda bangeq). |
Standar: {"id NOT": 2}{“color NOT”: “red”}Dioptimalkan untuk penyimpanan: "id != 2" "color != 'red'" |
< |
Standar: Memeriksa apakah nilai bidang kurang dari nilai filter. Kunci harus diakhiri dengan "<". Misalnya, "harga <" dengan nilai 200 cocok dengan dokumen di mana harga lebih kecil dari 200. Dioptimalkan penyimpanan: Lihat < operator (tanda lt). |
Standar: {"id <": 200}Dioptimalkan untuk penyimpanan: "id < 200" |
<= |
Standar: Memeriksa apakah nilai bidang kurang dari atau sama dengan nilai filter. Kunci harus diakhir dengan " <=". Misalnya, "price <=" dengan nilai 200 cocok dengan dokumen di mana harganya kurang dari atau sama dengan 200. Dioptimalkan untuk penyimpanan: Lihatlah <= (lt eq sign) operator. |
Standar: {"id <=": 200}Dioptimalkan untuk penyimpanan: "id <= 200" |
> |
Standar: Memeriksa apakah nilai bidang lebih besar dari nilai filter. Kunci harus diakhiri dengan ">". Misalnya, "harga >" dengan nilai 200 cocok dengan dokumen di mana harganya lebih besar dari 200. Dioptimalkan penyimpanan: Lihat > operator (tanda gt). |
Standar: {"id >": 200}Dioptimalkan untuk penyimpanan: "id > 200" |
>= |
Standar: Memeriksa apakah nilai bidang lebih besar dari atau sama dengan nilai filter. Kunci harus diakhir dengan " >=". Misalnya, "price >=" dengan nilai 200 cocok dengan dokumen di mana harganya lebih besar dari atau sama dengan 200. Dioptimalkan untuk penyimpanan: Lihat >= operator (gt eq sign). |
Standar: {"id >=": 200}Dioptimalkan untuk penyimpanan: "id >= 200" |
OR |
Standar: Memeriksa apakah nilai bidang cocok dengan salah satu nilai filter. Kunci harus berisi OR untuk memisahkan beberapa subkey. Misalnya, color1 OR color2 dengan nilai ["red", "blue"] cocok dengan dokumen di mana color1 adalah red atau color2 adalah blue.Dioptimalkan untuk penyimpanan: Lihat or operator. |
Standar: {"color1 OR color2": ["red", "blue"]}Dioptimalkan untuk penyimpanan: "color1 = 'red' OR color2 = 'blue'" |
LIKE |
Standar: Cocok dengan token yang dipisahkan spasi putih dalam string. Dioptimalkan untuk penyimpanan: Lihat like operator. |
Lihat Catatan tentang penggunaan LIKE. |
| Operator filter tidak ditentukan |
Standar: Filter memeriksa untuk kecocokan yang tepat. Jika beberapa nilai ditentukan, nilai tersebut cocok dengan salah satu nilai. Dioptimalkan penyimpanan: Lihat = operator dan in predikat (tanda eq). |
Standar: {"id": 200}{"id": [200, 300]}Dioptimalkan untuk penyimpanan: "id = 200""id IN (200, 300)" |
to_timestamp (titik akhir yang dioptimalkan untuk penyimpanan saja) |
Optimalisasi penyimpanan: Filter berdasarkan tanda waktu. Lihat to_timestamp fungsi |
Dioptimalkan untuk penyimpanan: "date > TO_TIMESTAMP('1995-01-01')" |
Catatan tentang penggunaan LIKE
LIKE contoh untuk titik akhir standar
{"column LIKE": "apple"}: cocok dengan string "apel" dan "apel pir" tetapi tidak cocok dengan "nanas". Perhatikan bahwa kata tersebut tidak cocok dengan "nanas" meskipun berisi substring "apel"; ia mencari kecocokan yang tepat atas token yang dipisahkan oleh spasi seperti di "pir apel".
{"column NOT LIKE": "apple"} melakukan yang sebaliknya. Ini cocok dengan "nanas" dan "pir" tetapi tidak cocok dengan "apel" atau "pir apel".
LIKE contoh untuk endpoint yang dioptimalkan untuk penyimpanan
| Rancangan | Pencocokan |
|---|---|
"column LIKE 'apple'" |
Setara dengan = operator. Mengembalikan hanya kecocokan yang tepat. |
"column LIKE 'apple%'" |
Mengembalikan baris di mana awalan applecocok, seperti applepie. |
"column LIKE '%apple'" |
Mengembalikan baris di mana akhiran cocok apple, seperti pineapple. |
"column LIKE '%apple%'" |
Mengembalikan baris yang memiliki substring yang cocok apple, seperti pineapplecake. |
Contoh kode
Python titik akhir standar SDK
# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
filters={"title": ["Ares", "Athena"]},
num_results=2
)
# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
filters={"title OR id": ["Ares", "Athena"]},
num_results=2
)
# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
filters={"title NOT": "Hercules"},
num_results=2
)
Python SDK titik akhir yang dioptimalkan untuk penyimpanan
# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
filters='title IN ("Ares", "Athena")',
num_results=2
)
# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
filters='title = "Ares" OR id = "Athena"',
num_results=2
)
# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
filters='title != "Hercules"',
num_results=2
)
REST API
Lihat POST /api/2.0/vector-search/indexes/{index_name}/query.
Gunakan reranker dalam kueri
Performa agen bergantung pada pengambilan informasi yang paling relevan untuk kueri. Reranking adalah teknik yang meningkatkan kualitas pengambilan dengan mengevaluasi dokumen yang diambil untuk mengidentifikasi dokumen yang paling relevan secara semantik. Databricks telah mengembangkan sistem AI majemuk berbasis penelitian untuk mengidentifikasi dokumen-dokumen ini. Anda juga dapat menentukan kolom yang berisi metadata yang Anda inginkan untuk digunakan reranker untuk konteks tambahan karena menilai relevansi setiap dokumen.
Reranking menimbulkan penundaan latensi kecil tetapi dapat secara signifikan meningkatkan kualitas pengambilan dan performa agen. Databricks merekomendasikan mencoba reranking di setiap kasus penggunaan agen RAG.
Contoh di bagian ini menunjukkan cara menggunakan reranker pencarian vektor. Saat Anda menggunakan reranker, Anda mengatur kolom untuk mengembalikan (columns) dan kolom metadata yang akan digunakan untuk reranking (columns_to_rerank) secara terpisah.
num_results adalah jumlah akhir hasil yang akan dikembalikan. Ini tidak memengaruhi jumlah hasil yang digunakan untuk reranking.
Pesan debug kueri menyertakan informasi tentang berapa lama langkah reranking berlangsung. Contohnya:
'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}
Jika panggilan reranker gagal, informasi tersebut disertakan dalam pesan debug:
'debug_info': {'response_time': 587.0, 'ann_time': 331.0, 'reranker_time': 246.0, 'warnings': [{'status_code': 'RERANKER_TEMPORARILY_UNAVAILABLE', 'message': 'The reranker is temporarily unavailable. Results returned have not been processed by the reranker. Please try again later for reranked results.'}]}
Nota
Urutan kolom yang dicantumkan columns_to_rerank adalah penting. Perhitungan reranking mengambil kolom dalam urutan yang tercantum, dan hanya mempertimbangkan 2000 karakter pertama yang ditemukannya.
Python SDK
# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-vectorsearch --force-reinstall
dbutils.library.restartPython()
from databricks.vector_search.reranker import DatabricksReranker
results = index.similarity_search(
query_text = "How to create a Vector Search index",
columns = ["id", "text", "parent_doc_summary", "date"],
num_results = 10,
query_type = "hybrid",
reranker=DatabricksReranker(columns_to_rerank=["text", "parent_doc_summary", "other_column"])
)
REST API
Untuk memastikan bahwa Anda mendapatkan informasi latensi, atur debug_level ke setidaknya 1.
export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 10, "query_text": "How to create a Vector Search index", "columns": ["id", "text", "parent_doc_summary", "date"], "reranker": {"model": "databricks_reranker",
"parameters": {
"columns_to_rerank":
["text", "parent_doc_summary"]
}
},
"debug_level": 1}'
Pencarian titik
Untuk melakukan pencarian titik, gunakan filter pada kolom kunci utama apa pun.
Algoritma pengambilan
Bagian ini menjelaskan algoritma pengambilan atau jenis kueri yang berbeda dan kapan masing-masing dapat digunakan.
query_type Gunakan parameter untuk menentukan algoritma pengambilan yang akan digunakan. Untuk membandingkan performa algoritma yang berbeda secara otomatis untuk indeks Anda, lihat Mengevaluasi kualitas pengambilan pencarian vektor.
| Strategi | Cara kerjanya | Paling cocok untuk |
|---|---|---|
| ANN (perkiraan tetangga terdekat) | Pencarian menggunakan penyematan vektor untuk menemukan dokumen serupa secara semantik. | Kueri konseptual dan semantik di mana makna lebih penting daripada kata-kata yang tepat. |
| Full-text | Pencarian kata kunci yang cocok dengan istilah yang tepat. | Kueri dengan istilah tertentu, kata benda yang tepat, ID produk, atau jargon teknis. |
| Hibrida | Menggabungkan ANN dan hasil teks lengkap menggunakan Reciprocal Rank Fusion (RRF). | Pengambilan tujuan umum. Titik awal yang direkomendasikan untuk sebagian besar kasus penggunaan. |
| Hibrid + reranker | Menjalankan pencarian hybrid, lalu menilai ulang hasilnya dengan model penyandi silang untuk mereranking. | Presisi yang lebih tinggi ketika latensi memungkinkan (~ 1,5s tambahan per kueri). |
ANN (pencarian vektor)
Pencarian ANN mengonversi kueri menjadi penyematan vektor dan menemukan dokumen yang penyematannya paling mirip. Ini efektif untuk memahami makna. Misalnya, kueri seperti "cara memperbaiki pipa rusak" cocok dengan dokumen tentang pipa pipa meskipun tidak berisi kata-kata yang tepat.
- Ketika ANN berkinerja baik: Kueri bersifat konseptual, percakapan, atau menggunakan kosakata yang berbeda dari dokumen.
- Ketika ANN mungkin berkinerja kurang baik: Kueri mengandalkan kata kunci yang tepat, nama diri, atau terminologi khusus domain yang mungkin tidak dapat ditangkap dengan tepat oleh pemetaan.
Teks lengkap (pencarian kata kunci)
Pencarian teks lengkap cocok dengan dokumen yang berisi istilah kueri. Pencarian teks lengkap memiliki presisi tinggi. Saat pengguna mencari nama, kode, atau istilah teknis tertentu, pencocokan kata kunci menemukan hit yang tepat yang mungkin terlewatkan oleh pencarian vektor.
- Saat teks lengkap berkinerja baik: Kueri berisi pengidentifikasi tertentu, nama produk, kode kesalahan, atau terminologi khusus domain.
- Ketika teks lengkap mungkin tidak berfungsi dengan baik: Kueri diformulasikan secara berbeda dari dokumen atau menggunakan sinonim dan parafrase.
Pencarian hibrid
Pencarian hibrid menjalankan pencarian ANN dan teks lengkap secara paralel, lalu menggabungkan hasilnya menggunakan Reciprocal Rank Fusion (RRF). Ini menggabungkan pemahaman semantik pencarian vektor dengan presisi pencocokan kata kunci.
- Saat pencarian hibrid berkinerja baik: Beban kerja kueri adalah campuran dari kueri konseptual dan berat kata kunci. Hybrid adalah strategi tujuan umum yang paling kuat.
Reranker
Reranker adalah pass kedua opsional yang diterapkan di atas strategi apa pun. Setelah pengambilan awal, model penyandi silang mengevaluasi kembali setiap hasil dalam konteks kueri, menghasilkan pengurutan relevansi yang lebih akurat.
Reranker biasanya meningkatkan kualitas sekitar 10% tetapi menambahkan latensi. Ini cocok untuk aplikasi tempat kualitas paling utama seperti RAG chatbots, tetapi berpotensi kurang cocok untuk aplikasi pencarian dengan throughput tinggi dan latensi rendah.