Bagikan melalui

Cara membuat dan mengkueri indeks pencarian vektor

  • Artikel

Artikel ini menjelaskan cara membuat dan mengkueri indeks pencarian vektor menggunakan Mosaic AI Vector Search.

Anda dapat membuat dan mengelola komponen pencarian vektor, seperti titik akhir pencarian vektor dan indeks pencarian vektor, menggunakan UI, Python SDK, atau REST API.

Persyaratan

  • Ruang kerja yang diaktifkan Katalog Unity.
  • Komputasi tanpa server diaktifkan. Untuk petunjuknya, lihat Menyambungkan ke komputasi tanpa server.
  • Tabel sumber harus mengaktifkan Ubah Umpan Data. Untuk petunjuknya, lihat Menggunakan umpan data perubahan Delta Lake di Azure Databricks.
  • Untuk membuat indeks, Anda harus memiliki hak istimewa CREATE TABLE pada skema katalog untuk membuat indeks. Untuk mengkueri indeks yang dimiliki oleh pengguna lain, Anda harus memiliki hak istimewa tambahan. Lihat Mengkueri titik akhir pencarian vektor.
  • Jika Anda ingin menggunakan token akses pribadi (tidak disarankan untuk beban kerja produksi), periksa apakah token akses pribadi diaktifkan. Untuk menggunakan token perwakilan layanan sebagai gantinya, teruskan secara eksplisit menggunakan panggilan SDK atau API.

Untuk menggunakan SDK, Anda harus menginstalnya di buku catatan Anda. Gunakan kode berikut:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Membuat titik akhir pencarian vektor

Anda dapat membuat titik akhir pencarian vektor menggunakan UI Databricks, Python SDK, atau API.

Membuat titik akhir pencarian vektor menggunakan UI

Ikuti langkah-langkah ini untuk membuat titik akhir pencarian vektor menggunakan UI.

  1. Di bilah sisi kiri, klik Komputasi.

  2. Klik tab Pencarian Vektor dan klik Buat.

    Membuat formulir titik akhir

  3. Formulir Buat titik akhir terbuka. Masukkan nama untuk titik akhir ini.

  4. Klik Konfirmasi.

Membuat titik akhir pencarian vektor menggunakan Python SDK

Contoh berikut menggunakan fungsi SDK create_endpoint() untuk membuat titik akhir pencarian vektor.

# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearch(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD"
)

Membuat titik akhir pencarian vektor menggunakan REST API

Lihat dokumentasi referensi REST API: POST /api/2.0/vector-search/endpoints.

(Opsional) Membuat dan mengonfigurasi titik akhir untuk melayani model penyematan

Jika Anda memilih untuk membuat Databricks menghitung penyematan, Anda dapat menggunakan titik akhir API Model Foundation yang telah dikonfigurasi sebelumnya atau membuat model yang melayani titik akhir untuk melayani model penyematan pilihan Anda. Lihat API Model Foundation bayar per token atau Buat model AI generatif yang melayani titik akhir untuk mendapatkan petunjuk. Misalnya buku catatan, lihat Contoh buku catatan untuk memanggil model penyematan.

Saat Anda mengonfigurasi titik akhir penyematan, Databricks menyarankan agar Anda menghapus pilihan default Skala ke nol. Melayani titik akhir dapat memakan waktu beberapa menit untuk dihangatkan, dan kueri awal pada indeks dengan titik akhir yang diturunkan skalanya mungkin habis.

Catatan

Inisialisasi indeks pencarian vektor mungkin kehabisan waktu jika titik akhir penyematan tidak dikonfigurasi dengan tepat untuk himpunan data. Anda hanya boleh menggunakan titik akhir CPU untuk himpunan data dan pengujian kecil. Untuk himpunan data yang lebih besar, gunakan titik akhir GPU untuk performa optimal.

Membuat indeks pencarian vektor

Anda dapat membuat indeks pencarian vektor menggunakan UI, Python SDK, atau REST API. UI adalah pendekatan paling sederhana.

Ada dua jenis indeks:

  • Indeks Sinkronisasi Delta secara otomatis disinkronkan dengan Tabel Delta sumber, secara otomatis dan bertahap memperbarui indeks saat data yang mendasar dalam Tabel Delta berubah.
  • Indeks Akses Vektor Langsung mendukung baca dan tulis langsung vektor dan metadata. Pengguna bertanggung jawab untuk memperbarui tabel ini menggunakan REST API atau Python SDK. Tipe indeks ini tidak dapat dibuat menggunakan UI. Anda harus menggunakan REST API atau SDK.

Membuat indeks menggunakan UI

  1. Di bilah sisi kiri, klik Katalog untuk membuka UI Penjelajah Katalog.

  2. Navigasi ke tabel Delta yang ingin Anda gunakan.

  3. Klik tombol Buat di kanan atas, dan pilih Indeks pencarian vektor dari menu drop-down.

    Tombol Buat indeks

  4. Gunakan pemilih dalam dialog untuk mengonfigurasi indeks.

    dialog buat indeks

    Nama: Nama yang akan digunakan untuk tabel online di Katalog Unity. Nama memerlukan namespace tiga tingkat, <catalog>.<schema>.<name>. Hanya karakter alfanumerik dan garis bawah yang diizinkan.

    Kunci primer: Kolom untuk digunakan sebagai kunci utama.

    Titik akhir: Pilih titik akhir pencarian vektor yang ingin Anda gunakan.

    Kolom yang akan disinkronkan: Pilih kolom yang akan disinkronkan dengan indeks vektor. Jika Anda membiarkan bidang ini kosong, semua kolom dari tabel sumber disinkronkan dengan indeks. Kolom kunci utama dan kolom sumber penyematan atau kolom vektor penyematan selalu disinkronkan.

    Sumber penyematan: Menunjukkan apakah Anda ingin Databricks menghitung penyematan untuk kolom teks dalam tabel Delta (Penyematan komputasi), atau jika tabel Delta Anda berisi penyematan yang telah dikomputasi sebelumnya (Gunakan kolom penyematan yang ada).

    • Jika Anda memilih Penyematan komputasi, pilih kolom yang ingin Anda sematkan komputasinya dan titik akhir yang melayani model penyematan. Hanya kolom teks yang didukung.
    • Jika Anda memilih Gunakan kolom penyematan yang ada, pilih kolom yang berisi penyematan yang telah dikomputasi dan dimensi penyematan. Format kolom penyematan yang telah dikomputasi harus array[float].

    Menyinkronkan penyematan komputasi: Alihkan pengaturan ini untuk menyimpan penyematan yang dihasilkan ke tabel Katalog Unity. Untuk informasi selengkapnya, lihat Menyimpan tabel penyematan yang dihasilkan.

    Mode sinkronisasi: Berkelanjutan menjaga indeks tetap sinkron dengan detik latensi. Namun, ini memiliki biaya yang lebih tinggi yang terkait dengannya karena kluster komputasi disediakan untuk menjalankan alur streaming sinkronisasi berkelanjutan. Dipicu lebih hemat biaya, tetapi harus dimulai secara manual menggunakan API. Untuk Berkelanjutan dan Dipicu, pembaruan bertambah bertahas - hanya data yang telah berubah sejak sinkronisasi terakhir diproses.

  5. Setelah Anda selesai mengonfigurasi indeks, klik Buat.

Membuat indeks menggunakan Python SDK

Contoh berikut membuat Indeks Sinkronisasi Delta dengan penyematan yang dihitung oleh Databricks.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2"
)

Contoh berikut membuat Indeks Sinkronisasi Delta dengan penyematan yang dikelola sendiri. Contoh ini juga menunjukkan penggunaan parameter columns_to_sync opsional untuk memilih hanya subset kolom yang akan digunakan dalam indeks.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector"
)

Secara default, semua kolom dari tabel sumber disinkronkan dengan indeks. Untuk menyinkronkan hanya subset kolom, gunakan columns_to_sync. Kunci utama dan kolom penyematan selalu disertakan dalam indeks.

Untuk menyinkronkan hanya kunci primer dan kolom penyematan, Anda harus menentukannya seperti yang ditunjukkan columns_to_sync :

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

Untuk menyinkronkan kolom tambahan, tentukan seperti yang diperlihatkan. Anda tidak perlu menyertakan kunci utama dan kolom penyematan, karena selalu disinkronkan.

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

Contoh berikut membuat Indeks Akses Vektor Langsung.


client = VectorSearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name="{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    "id": "int",
    "field2": "str",
    "field3": "float",
    "text_vector": "array<float>"}
)

Membuat indeks menggunakan REST API

Lihat dokumentasi referensi REST API: POST /api/2.0/vector-search/indexes.

Menyimpan tabel penyematan yang dihasilkan

Jika Databricks menghasilkan penyematan, Anda dapat menyimpan penyematan yang dihasilkan ke tabel di Unity Catalog. Tabel ini dibuat dalam skema yang sama dengan indeks vektor dan ditautkan dari halaman indeks vektor.

Nama tabel adalah nama indeks pencarian vektor, ditambahkan oleh _writeback_table. Nama tidak dapat diedit.

Anda bisa mengakses dan mengkueri tabel seperti tabel lainnya di Katalog Unity. Namun, Anda tidak boleh menghilangkan atau memodifikasi tabel, karena tidak dimaksudkan untuk diperbarui secara manual. Tabel dihapus secara otomatis jika indeks dihapus.

Memperbarui indeks pencarian vektor

Memperbarui Indeks Sinkronisasi Delta

Indeks yang dibuat dengan mode Sinkronisasi berkelanjutan secara otomatis diperbarui saat tabel Delta sumber berubah. Jika Anda menggunakan mode Sinkronisasi yang dipicu , Anda dapat menggunakan Python SDK atau REST API untuk memulai sinkronisasi.

Python SDK

index.sync()

REST API

Lihat dokumentasi referensi REST API: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Memperbarui Indeks Akses Vektor Langsung

Anda dapat menggunakan Python SDK atau REST API untuk menyisipkan, memperbarui, atau menghapus data dari Indeks Akses Vektor Langsung.

Python SDK

   index.upsert([{"id": 1,
       "field2": "value2",
       "field3": 3.0,
       "text_vector": [1.0, 2.0, 3.0]
       },
       {"id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1, 2.1, 3.0]
        }
        ])

REST API

Lihat dokumentasi referensi REST API: POST /api/2.0/vector-search/indexes.

Contoh kode berikut menggambarkan cara memperbarui indeks menggunakan token akses pribadi (PAT).

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/upsert-data --data '{"inputs_json": "..."}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/delete-data --data '{"primary_keys": [...]}'

Contoh kode berikut menggambarkan cara memperbarui indeks menggunakan perwakilan layanan.

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": "WriteVectorIndex"}'

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

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/upsert-data --data '{"inputs_json": "[...]"}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/delete-data --data '{"primary_keys": [...]}'

Mengkueri titik akhir pencarian vektor

Anda hanya dapat mengkueri titik akhir pencarian vektor menggunakan Python SDK, REST API, atau fungsi SQL vector_search() AI.

Catatan

Jika pengguna yang mengkueri titik akhir bukan pemilik indeks pencarian vektor, pengguna harus memiliki hak istimewa UC berikut:

  • GUNAKAN KATALOG pada katalog yang berisi indeks pencarian vektor.
  • GUNAKAN SKEMA pada skema yang berisi indeks pencarian vektor.
  • SELECT pada indeks pencarian vektor.

Untuk melakukan pencarian kesamaan kata kunci hibrid, atur parameter query_type ke hybrid. Nilai defaultnya adalah ann (perkiraan tetangga terdekat).

Python SDK

# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

REST API

Lihat dokumentasi referensi REST API: POST /api/2.0/vector-search/indexes/{index_name}/query.

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}'

Contoh kode berikut mengilustrasikan cara mengkueri indeks menggunakan perwakilan layanan.

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 (TODO: link), 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}'

SQL

Penting

Fungsi vector_search() AI ada di Pratinjau Umum.

Untuk menggunakan fungsi AI ini, lihat fungsi vector_search.

Menggunakan filter pada kueri

Kueri dapat menentukan filter berdasarkan kolom apa pun dalam tabel Delta. similarity_search hanya mengembalikan baris yang cocok dengan filter yang ditentukan. Filter berikut ini didukung:

Operator filter Perilaku Contoh
NOT Meniadakan filter. Kunci harus diakhir dengan "NOT". Misalnya, "color NOT" dengan nilai "merah" cocok dengan dokumen di mana warnanya tidak merah. {"id NOT": 2} {“color NOT”: “red”}
< Memeriksa apakah nilai bidang kurang dari nilai filter. Kunci harus diakhir dengan " <". Misalnya, "harga <" dengan nilai 200 cocok dengan dokumen di mana harganya kurang dari 200. {"id <": 200}
<= 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. {"id <=": 200}
> Memeriksa apakah nilai bidang lebih besar dari nilai filter. Kunci harus diakhir dengan " >". Misalnya, "harga >" dengan nilai 200 cocok dengan dokumen di mana harganya lebih besar dari 200. {"id >": 200}
>= 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. {"id >=": 200}
OR 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. {"color1 OR color2": ["red", "blue"]}
LIKE Cocok dengan string parsial. {"column LIKE": "hello"}
Tidak ada operator filter yang ditentukan Filter memeriksa kecocokan yang tepat. Jika beberapa nilai ditentukan, nilai tersebut cocok dengan salah satu nilai. {"id": 200} {"id": [200, 300]}

Lihat contoh kode berikut:

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
    )

REST API

Lihat POST /api/2.0/vector-search/indexes/{index_name}/query.

Contoh buku catatan

Contoh di bagian ini menunjukkan penggunaan pencarian vektor Python SDK.

Contoh LangChain

Lihat Cara menggunakan LangChain dengan Mosaic AI Vector Search untuk menggunakan Mosaic AI Vector Search seperti dalam integrasi dengan paket LangChain.

Buku catatan berikut ini memperlihatkan cara mengonversi hasil pencarian kesamaan Anda ke dokumen LangChain.

Pencarian vektor dengan buku catatan Python SDK

Dapatkan buku catatan

Contoh buku catatan untuk memanggil model penyematan

Notebook berikut menunjukkan cara mengonfigurasi titik akhir Mosaic AI Model Serving untuk pembuatan penyematan.

Memanggil model penyematan OpenAI menggunakan buku catatan Mosaic AI Model Serving

Dapatkan buku catatan

Memanggil model penyematan GTE menggunakan mosaic AI Model Melayani notebook

Dapatkan buku catatan

Mendaftar dan melayani buku catatan model penyematan OSS

Dapatkan buku catatan