Bagikan melalui

Mengkueri indeks pencarian vektor

Artikel ini menjelaskan cara mengkueri indeks pencarian vektor, termasuk cara menggunakan 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 Python SDK.

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 melakukan pencarian hibrid berdasarkan kemiripan kata kunci, atur parameter query_type ke hybrid. 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.

Titik akhir standar Python SDK

Untuk detailnya, lihat referensi Python SDK.

# 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
    )

Titik akhir yang dioptimalkan untuk penyimpanan Python SDK

Untuk detailnya, lihat referensi Python SDK.

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.

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.

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. Lihat contoh kode di bawah ini.
Dioptimalkan untuk penyimpanan: Lihat like operator.		 Standar: {"column LIKE": "hello"}
Dioptimalkan untuk penyimpanan: "column LIKE 'hello'"
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')"

Lihat contoh kode berikut:

Titik akhir standar Python 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
    )

Titik akhir yang dioptimalkan untuk penyimpanan Python SDK

# 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.

Suka

LIKE Contoh

{"column LIKE": "apple"}: mencocokkan string "apel" dan "apel pir" tetapi tidak cocok dengan "nanas" atau "pir". Perhatikan bahwa ini tidak cocok dengan "nanas" meskipun mengandung substring "apel" --- itu mencari kecocokan tepat terhadap token yang dipisahkan oleh spasi seperti dalam "apel pir".

{"column NOT LIKE": "apple"} melakukan yang sebaliknya. Ini cocok dengan "nanas" dan "pir" tetapi tidak cocok dengan "apel" atau "pir apel".

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 untuk mencoba reranking untuk 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 dicantumkan columns_to_rerank 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.

  • Last updated on