Aggiungere una risorsa di indice di ricerca di intelligenza artificiale a un'app Databricks

Aggiungere indici di ricerca di intelligenza artificiale come risorse di Databricks Apps per abilitare la ricerca semantica e il recupero basato sulla somiglianza nelle applicazioni. Gli indici di ricerca basati sull’IA archiviano e interrogano embedding vettoriali ad alta dimensionalità, abilitando casi d’uso come la retrieval-augmented generation (RAG), la ricerca semantica e i sistemi di raccomandazione.

Ricerca di intelligenza artificiale di Databricks era precedentemente nota come Ricerca vettoriale di Databricks.

Requisiti dei privilegi

Per accedere a un indice AI Search, il service principal dell'applicazione deve disporre del privilegio USE CATALOG sul catalogo padre, del privilegio USE SCHEMA sullo schema padre e del privilegio SELECT sull'indice. Quando si aggiunge la risorsa di indice, Azure Databricks concede automaticamente questi privilegi al principale del servizio dell'app.

Affinché questa concessione automatica abbia esito positivo, è necessario che uno dei seguenti sia true per ogni privilegio:

• Per USE CATALOG: Tutti gli utenti dell'account hanno il USE CATALOG privilegio sul catalogo, oppure tu hai il MANAGE privilegio sul catalogo.
• Per USE SCHEMA: tutti gli utenti dell'account hanno il USE SCHEMA privilegio per lo schema oppure si dispone del MANAGE privilegio per lo schema.
• Per SELECT: o tutti gli utenti dell'account hanno il SELECT privilegio per l'indice, o si dispone del MANAGE privilegio per l'indice.

Se l'indice utilizza un modello di embedding gestito da Databricks su un endpoint di throughput provisionato o di servizio personalizzato, aggiungi anche quell'endpoint come risorsa dell'app con permesso Can query, più qualsiasi endpoint separato di embedding di query (model_endpoint_name_for_query). get_index() legge questi endpoint e fallisce senza accesso. Gli endpoint delle API del modello di base a pagamento per token, come databricks-gte-large-en, non hanno bisogno di una risorsa dell'app a meno che il tuo account non limiti i modelli di base con permessi del Catalogo Unity, nel qual caso il service principal ha bisogno EXECUTE sul modello. Vedi Impostare un'entità servizio.

Per altre informazioni sull'esecuzione di query sugli indici di ricerca di intelligenza artificiale con queste autorizzazioni, vedere Come eseguire query su un indice di ricerca di intelligenza artificiale.

Vedere Informazioni di riferimento sui privilegi del catalogo Unity.

Aggiungi una risorsa dell'indice di AI Search

Prima di aggiungere un indice di ricerca di intelligenza artificiale come risorsa, esaminare i prerequisiti delle risorse dell'app.

1. Nella sezione Risorse dell'app quando si crea o si modifica un'app fare clic su + Aggiungiindice di ricerca vettore>.
2. Scegliere un indice di ricerca di intelligenza artificiale dagli indici disponibili nell'area di lavoro. L'indice deve esistere già in Unity Catalog.
3. Selezionare il livello di autorizzazione per l'app:
   • Può selezionare: Concede all'app l'autorizzazione per eseguire query sull'indice di ricerca di intelligenza artificiale per cercare ricerche di somiglianza. Corrisponde al SELECT privilegio.
4. (Facoltativo) Specificare una chiave di risorsa personalizzata, ovvero come si fa riferimento all'indice nella configurazione dell'app. La chiave predefinita è vector-search-index.

Variabili di ambiente

Quando si distribuisce un'app con una risorsa di indice di ricerca di intelligenza artificiale, Azure Databricks espone il nome completo a tre livelli tramite variabili di ambiente a cui è possibile fare riferimento usando il valueFrom campo .

Configurazione di esempio:

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

Uso dell'indice nell'applicazione:

Consulta l'indice con l'databricks-ai-searchSDK Python e le credenziali dell'entità servizio dell'app. Quando lo spazio di lavoro soddisfa i requisiti dell'URL dell'indice, l'SDK invia le query all'URL dell'indice, che può utilizzare la capacità aggiuntiva di un endpoint con un numero target di query al secondo (QPS). Le query inviate con WorkspaceClient().vector_search_indexes.query_index utilizzano l'URL della query dello spazio di lavoro, che è limitato a poche decine di QPS.

Aggiungi databricks-ai-search la versione 0.81 o superiore alle dipendenze della tua app. Vedere Gestire le dipendenze per un'app 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)))

Sostituisci columns con le colonne del tuo indice. Per raggiungere un throughput più elevato, imposta un QPS target su un endpoint standard.

Per altre informazioni, vedere Usare le variabili di ambiente per accedere alle risorse.

Rimuovere una risorsa dell'indice di ricerca di intelligenza artificiale

Quando si rimuove una risorsa dell'indice di ricerca di intelligenza artificiale da un'app, l'entità servizio dell'app perde l'accesso all'indice. L'indice stesso rimane invariato e continua a essere disponibile per altri utenti e applicazioni con autorizzazioni appropriate.

Procedure consigliate

Quando si lavora con le risorse dell'indice di ricerca di intelligenza artificiale, tenere presente quanto segue:

• Assicurarsi che il principale di servizio dell'app abbia accesso alle origini dati sottostanti se l'indice fa riferimento ad altre tabelle.
• Monitorare le prestazioni delle query e regolare la configurazione dell'indice o i modelli di incorporamento in caso di riduzione dei tempi di risposta.
• Prendere in considerazione le pianificazioni di aggiornamento dell'indice per mantenere sincronizzate le incorporazioni con i dati di origine.
• Usare le metriche di somiglianza appropriate (coseno, euclideo, prodotto punto) in base al modello di incorporamento.
• Un endpoint può essere online prima che i suoi indici siano pronti per le interrogazioni. Per controllare un indice senza bloccare, leggi ready e detailed_state nel status campo che index.describe() restituisce. Per aspettare un indice, chiama index.wait_until_ready(), che esegue il polling ogni 30 secondi e genera un errore se l'indice va offline o il timeout passa.