Menambahkan sumber daya indeks Pencarian AI ke aplikasi Databricks

Tambahkan indeks Pencarian AI sebagai sumber daya Aplikasi Databricks untuk mengaktifkan pencarian semantik dan pengambilan berbasis kesamaan di aplikasi Anda. Indeks AI Search menyimpan dan menjalankan kueri pada embedding vektor berdimensi tinggi, yang mendukung kasus penggunaan seperti retrieval-augmented generation (RAG), pencarian semantik, dan sistem rekomendasi.

Databricks AI Search sebelumnya dikenal sebagai Databricks Vector Search.

Persyaratan hak istimewa

Untuk mengakses indeks Pencarian AI, perwakilan layanan aplikasi harus memiliki USE CATALOG hak istimewa pada katalog induk, USE SCHEMA hak istimewa pada skema induk, dan SELECT hak istimewa pada indeks. Saat Anda menambahkan sumber daya indeks, Azure Databricks secara otomatis memberikan hak istimewa ini ke perwakilan layanan aplikasi.

Agar pemberian otomatis ini berhasil, salah satu hal berikut harus benar untuk setiap hak istimewa:

  • Untuk USE CATALOG: Semua pengguna akun memiliki USE CATALOG hak istimewa pada katalog, atau Anda memiliki MANAGE hak istimewa pada katalog.
  • Untuk USE SCHEMA: Semua pengguna akun memiliki USE SCHEMA hak istimewa pada skema, atau Anda memiliki MANAGE hak istimewa pada skema.
  • Untuk SELECT: Semua pengguna akun memiliki SELECT hak istimewa pada indeks, atau Anda memiliki MANAGE hak istimewa pada indeks.

Jika indeks menggunakan model embedding yang dikelola Databricks pada endpoint throughput terprovisi atau endpoint serving kustom, tambahkan endpoint tersebut juga sebagai sumber daya aplikasi dengan izin Can query, serta juga endpoint embedding kueri terpisah (model_endpoint_name_for_query). get_index() membaca endpoint-endpoint ini dan gagal tanpa akses. Endpoint API Foundation Model pay-per-token, seperti databricks-gte-large-en, tidak memerlukan sumber daya aplikasi kecuali akun Anda membatasi model foundation dengan izin Unity Catalog, dalam hal ini prinsipal layanan membutuhkan EXECUTE pada model tersebut. Lihat Atur service principal.

Untuk informasi selengkapnya tentang mengkueri indeks Pencarian AI dengan izin ini, lihat Cara mengkueri indeks Pencarian AI.

Lihat Referensi hak istimewa Katalog Unity.

Menambahkan sumber daya indeks Pencarian AI

Sebelum Anda menambahkan indeks Pencarian AI sebagai sumber daya, tinjau prasyarat sumber daya aplikasi.

  1. Di bagian Sumber daya aplikasi saat Anda membuat atau mengedit aplikasi, klik + Tambahkanindeks pencarian Vektor>.
  2. Pilih indeks Pencarian AI dari indeks yang tersedia di ruang kerja Anda. Indeks harus sudah ada di Katalog Unity.
  3. Pilih tingkat izin untuk aplikasi Anda:
    • Dapat memilih: Memberikan izin aplikasi untuk mengkueri indeks Pencarian AI untuk pencarian kesamaan. SELECT Sesuai dengan hak istimewa.
  4. (Opsional) Tentukan kunci sumber daya kustom, yang merupakan cara Anda mereferensikan indeks dalam konfigurasi aplikasi Anda. Kunci defaultnya adalah vector-search-index.

Nota

Indeks Pencarian AI adalah tabel Katalog Unity dengan jenis TABLE_ONLINE_VECTOR_INDEX_REPLICA atau TABLE_ONLINE_VECTOR_INDEX_DIRECT. Saat Anda memilih indeks Pencarian AI, Anda memilih tabel yang dikonfigurasi khusus yang mendukung operasi pencarian semantik.

Variabel lingkungan

Saat Anda menerapkan aplikasi dengan sumber daya indeks AI Search, Azure Databricks menyediakan nama lengkap tiga tingkat melalui variabel lingkungan yang dapat Anda referensikan menggunakan bidang valueFrom.

Konfigurasi contoh:

env:
  - name: VECTOR_SEARCH_INDEX
    valueFrom: vector-search-index # Use your custom resource key if different

Menggunakan indeks di aplikasi Anda:

Query indeks dengan databricks-ai-search SDK Python dan kredensial service principal aplikasi. Ketika workspace memenuhi persyaratan URL indeks, SDK mengirimkan query ke URL indeks, yang dapat menggunakan kapasitas tambahan endpoint dengan target kueri per detik (QPS). Kueri yang dikirim dengan WorkspaceClient().vector_search_indexes.query_index menggunakan URL kueri workspace, yang dibatasi hanya beberapa puluh QPS.

Tambahkan databricks-ai-search versi 0.81 atau lebih tinggi ke dependensi aplikasi Anda. Lihat Mengelola dependensi untuk aplikasi Databricks.

import os
from databricks.ai_search.client import AISearchClient

# DATABRICKS_HOST can be set without a scheme, and the SDK requires one.
host = os.environ["DATABRICKS_HOST"]
if not host.startswith(("https://", "http://")):
    host = f"https://{host}"

# Pass the app's service principal credentials so queries use the index URL.
client = AISearchClient(
    workspace_url=host,
    service_principal_client_id=os.environ["DATABRICKS_CLIENT_ID"],
    service_principal_client_secret=os.environ["DATABRICKS_CLIENT_SECRET"],
)

# Create the index object when the app starts and reuse it for every query.
index = client.get_index(index_name=os.environ["VECTOR_SEARCH_INDEX"])

results = index.similarity_search(
    query_text="What is machine learning?",  # Or pass query_vector for self-managed embeddings.
    columns=["id", "text"],
    num_results=10,
)

# Each row lists values in the same order as the manifest columns.
column_names = [column["name"] for column in results["manifest"]["columns"]]
for row in results["result"]["data_array"]:
    print(dict(zip(column_names, row)))

Ganti columns dengan kolom-kolom indeks. Untuk mencapai throughput yang lebih tinggi, tetapkan target QPS pada endpoint standar.

Untuk informasi selengkapnya, lihat Menggunakan variabel lingkungan untuk mengakses sumber daya.

Menghapus sumber daya indeks Pencarian AI

Saat Anda menghapus sumber daya indeks Pencarian AI dari aplikasi, perwakilan layanan aplikasi kehilangan akses ke indeks. Indeks itu sendiri tetap tidak berubah dan terus tersedia untuk pengguna dan aplikasi lain yang memiliki izin yang sesuai.

Praktik terbaik

Pertimbangkan hal berikut saat Anda bekerja dengan sumber daya indeks Pencarian AI:

  • Pastikan perwakilan layanan aplikasi memiliki akses ke sumber data yang mendasar jika indeks mereferensikan tabel lain.
  • Pantau performa kueri dan sesuaikan konfigurasi indeks atau sematkan model jika waktu respons menurun.
  • Pertimbangkan jadwal refresh indeks untuk menjaga penyematan tetap sinkron dengan data sumber.
  • Gunakan metrik kesamaan yang sesuai (produk kosinus, euclidean, titik) berdasarkan model penyematan Anda.
  • Endpoint dapat online sebelum indeksnya siap untuk melakukan query. Untuk memeriksa indeks tanpa memblokir, baca ready dan detailed_state di kolom status yang dikembalikan oleh index.describe(). Untuk menunggu indeks, panggil index.wait_until_ready(), yang melakukan polling setiap 30 detik dan memunculkan error jika indeks offline atau timeout lewat.