Condividi tramite

Come creare ed eseguire query su un indice di ricerca vettoriale

  • Articolo

Questo articolo descrive come creare ed eseguire query su un indice di ricerca vettoriale usando Ricerca vettoriale di Databricks.

È possibile creare e gestire componenti di Ricerca vettoriale, ad esempio un endpoint di ricerca vettoriale e indici di ricerca vettoriale, usando l'interfaccia utente, Python SDK o l'API REST.

Requisiti

  • Area di lavoro abilitata per Unity Catalog.
  • Calcolo serverless abilitato.
  • Per la tabella di origine deve essere abilitato il feed di dati delle modifiche.
  • Per creare un indice, è necessario disporre dei privilegi CREATE TABLE per gli schemi di catalogo per creare indici. Per eseguire una query su un indice di proprietà di un altro utente, è necessario disporre di privilegi aggiuntivi. Vedere Eseguire query su un endpoint di ricerca vettoriale.
  • Se si vogliono usare token di accesso personali (non consigliati per i carichi di lavoro di produzione), verificare che i token di accesso personali siano abilitati. Per usare invece un token dell'entità servizio, passarlo in modo esplicito usando l'SDK o le chiamate API.

Per usare l'SDK, è necessario installarlo nel notebook. Usare il codice seguente:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Creare un endpoint di ricerca vettoriale

È possibile creare un endpoint di ricerca vettoriale usando l'interfaccia utente di Databricks, Python SDK o l'API.

Creare un endpoint di ricerca vettoriale usando l'interfaccia utente

Seguire questa procedura per creare un endpoint di ricerca vettoriale usando l'interfaccia utente.

  1. Nella barra laterale sinistra fare clic su Calcolo.

  2. Fare clic sulla scheda Ricerca vettoriale e fare clic su Crea.

    Creare il modulo dell'endpoint

  3. Verrà aperto il modulo Crea endpoint. Immettere un nome per questo endpoint.

  4. Fare clic su Conferma.

Creare un endpoint di ricerca vettoriale con Python SDK

Nell'esempio seguente viene usata la funzione SDK create_endpoint() per creare un endpoint di Ricerca vettoriale.

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

Creare un endpoint di ricerca vettoriale usando l'API REST

Vedere POST /api/2.0/vector-search/endpoints.

(Facoltativo) Creare e configurare un endpoint per gestire il modello di incorporamento

Se si sceglie di usare Databricks per calcolare gli incorporamenti, è possibile usare un endpoint dell'API del modello di base preconfigurato o creare un endpoint di gestione del modello per gestire il modello di incorporamento preferito. Per istruzioni, vedere API modello di base con pagamento in base al token o Creare un modello di base che gestisce gli endpoint. Per esempi di notebook, vedere Esempi di notebook per chiamare un modello di incorporamento.

Quando si configura un endpoint di incorporamento, Databricks consiglia di rimuovere la selezione predefinita di Scale su zero. La gestione degli endpoint può richiedere alcuni minuti e la query iniziale su un indice con un endpoint con riduzione delle prestazioni potrebbe verificarsi un timeout.

Nota

L'inizializzazione dell'indice di ricerca vettoriale potrebbe scadere se l'endpoint di incorporamento non è configurato in modo appropriato per il set di dati. È consigliabile usare solo endpoint CPU per set di dati e test di piccole dimensioni. Per set di dati di dimensioni maggiori, usare un endpoint GPU per ottenere prestazioni ottimali.

Creare un indice di ricerca vettoriale

È possibile creare un indice di ricerca vettoriale usando l'interfaccia utente, Python SDK o l'API REST. L'interfaccia utente è l'approccio più semplice.

Esistono due tipi di indici:

  • L'indice di sincronizzazione differenziale viene sincronizzato automaticamente con una tabella delta di origine, aggiornando automaticamente e in modo incrementale l'indice man mano che cambiano i dati sottostanti nella tabella Delta.
  • Direct Vector Access Index supporta la lettura diretta e la scrittura di vettori e metadati. L'utente è responsabile dell'aggiornamento di questa tabella usando l'API REST o Python SDK. Questo tipo di indice non può essere creato usando l'interfaccia utente. È necessario usare l'API REST o l'SDK.

Creare un indice usando l'interfaccia utente

  1. Nella barra laterale sinistra fare clic su Catalogo per aprire l'interfaccia utente di Esplora cataloghi .

  2. Passare alla tabella Delta da usare.

  3. Fare clic sul pulsante Crea in alto a destra e selezionare Indice di ricerca vettoriale dal menu a discesa.

    Pulsante Crea indice

  4. Usare i selettori nella finestra di dialogo per configurare l'indice.

    Finestra di dialogo crea indice

    Nome: nome da usare per la tabella online nel catalogo unity. Il nome richiede uno spazio dei nomi a tre livelli, <catalog>.<schema>.<name>. Sono consentiti solo caratteri alfanumerici e caratteri di sottolineatura.

    Chiave primaria: colonna da usare come chiave primaria.

    Endpoint: selezionare l'endpoint di ricerca vettoriale da usare.

    Origine incorporamento: indicare se si vuole che Databricks calcoli gli incorporamenti per una colonna di testo nella tabella Delta (incorporamenti di calcolo) o se la tabella Delta contiene incorporamenti precompilate (usare la colonna di incorporamento esistente).

    • Se sono stati selezionati incorporamenti di calcolo, selezionare la colonna per cui si desidera incorporare gli incorporamenti e l'endpoint che gestisce il modello di incorporamento. Sono supportate solo le colonne di testo.
    • Se è stata selezionata l'opzione Usa colonna di incorporamento esistente, selezionare la colonna contenente gli incorporamenti precompilate e la dimensione di incorporamento. Il formato della colonna di incorporamento pre-calcolata deve essere array[float].

    Incorporamenti sincronizzati calcolati: attivare o disattivare questa impostazione per salvare gli incorporamenti generati in una tabella del catalogo Unity. Per altre informazioni, vedere Salvare la tabella di incorporamento generata.

    Modalità di sincronizzazione: mantiene l'indice sincronizzato con i secondi di latenza. Tuttavia, ha un costo più elevato associato perché viene effettuato il provisioning di un cluster di calcolo per eseguire la pipeline di streaming di sincronizzazione continua. Attivato è più conveniente, ma deve essere avviato manualmente usando l'API. Per l'aggiornamento continuo e attivato, l'aggiornamento è incrementale, ma solo i dati modificati dopo l'ultima sincronizzazione vengono elaborati.

  5. Al termine della configurazione dell'indice, fare clic su Crea.

Creare un indice con Python SDK

Nell'esempio seguente viene creato un indice di sincronizzazione Delta con incorporamenti calcolati da 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"
)

Nell'esempio seguente viene creato un indice di accesso a vettori diretti.


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>"}
)

Creare un indice usando l'API REST

Vedere POST /api/2.0/vector-search/indexes.

Salva tabella di incorporamento generata

Se Databricks genera gli incorporamenti, è possibile salvare gli incorporamenti generati in una tabella in Unity Catalog. Questa tabella viene creata nello stesso schema dell'indice vettoriale ed è collegata dalla pagina dell'indice vettoriale.

Il nome della tabella è il nome dell'indice di ricerca vettoriale, aggiunto da _writeback_table. Il nome non è modificabile.

È possibile accedere alla tabella ed eseguire query come qualsiasi altra tabella nel catalogo unity. Tuttavia, non è consigliabile eliminare o modificare la tabella, perché non deve essere aggiornata manualmente. La tabella viene eliminata automaticamente se l'indice viene eliminato.

Aggiornare un indice di ricerca vettoriale

Aggiornare un indice di sincronizzazione delta

Gli indici creati con la modalità di sincronizzazione continua vengono aggiornati automaticamente quando cambia la tabella Delta di origine. Se si usa la modalità di sincronizzazione attivata , è possibile usare Python SDK o l'API REST per avviare la sincronizzazione.

Python SDK

index.sync()

API REST

Vedere API REST (POST /api/2.0/vector-search/indexes/{index_name}/sync).

Aggiornare un indice di accesso a vettori diretti

È possibile usare Python SDK o l'API REST per inserire, aggiornare o eliminare dati da un indice di accesso a vettori diretti.

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]
        }
        ])

API REST

Vedere API REST (POST /api/2.0/vector-search/indexes).

Eseguire una query su un endpoint di ricerca vettoriale

È possibile eseguire query solo sull'endpoint di Ricerca vettoriale usando Python SDK o l'API REST.

Nota

Se l'utente che esegue query sull'endpoint non è il proprietario dell'indice di ricerca vettoriale, l'utente deve disporre dei privilegi uc seguenti:

  • U edizione Standard CATALOG nel catalogo che contiene l'indice di ricerca vettoriale.
  • U edizione Standard SCHEMA nello schema che contiene l'indice di ricerca vettoriale.
  • edizione Standard LECT nell'indice di ricerca vettoriale.

Python SDK

results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

results

API REST

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

Usare filtri per le query

Una query può definire filtri in base a qualsiasi colonna della tabella Delta. similarity_search restituisce solo le righe che corrispondono ai filtri specificati. Sono supportati i filtri seguenti:

Operatore Filter Comportamento Esempi
NOT Nega il filtro. La chiave deve terminare con "NOT". Ad esempio, "color NOT" con valore "rosso" corrisponde ai documenti in cui il colore non è rosso. {"id NOT": 2} {“color NOT”: “red”}
< Controlla se il valore del campo è minore del valore del filtro. La chiave deve terminare con " ". < Ad esempio, "price <" con valore 100 corrisponde ai documenti in cui il prezzo è minore di 100. {"id <": 200}
<= Controlla se il valore del campo è minore o uguale al valore del filtro. La chiave deve terminare con " <=". Ad esempio, "price <=" con valore 100 corrisponde ai documenti in cui il prezzo è minore o uguale a 100. {"id <=": 200}
> Controlla se il valore del campo è maggiore del valore del filtro. La chiave deve terminare con " ". > Ad esempio, "price >" con valore 100 corrisponde ai documenti in cui il prezzo è maggiore di 100. {"id >": 200}
>= Controlla se il valore del campo è maggiore o uguale al valore del filtro. La chiave deve terminare con " >=". Ad esempio, "price >=" con valore 100 corrisponde ai documenti in cui il prezzo è maggiore o uguale a 100. {"id >=": 200}
OR Controlla se il valore del campo corrisponde a uno dei valori del filtro. La chiave deve contenere OR per separare più sottochiavi. Ad esempio, color1 OR color2 con il valore ["red", "blue"] corrisponde ai documenti in cui color1 è red o color2 è blue. {"color1 OR color2": ["red", "blue"]}
LIKE Trova la corrispondenza con stringhe parziali. {"column LIKE": "hello"}
Nessun operatore di filtro specificato Il filtro verifica la corrispondenza esatta. Se vengono specificati più valori, corrisponde a uno qualsiasi dei valori. {"id": 200} {"id": [200, 300]}

Vedere gli esempi di codice seguenti:

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
    )

API REST

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

Notebook di esempio

Gli esempi in questa sezione illustrano l'uso di Vector Search Python SDK.

Esempi di LangChain

Vedere How to use LangChain with Databricks Vector Search for using Databricks Vector Search as in integration with LangChain packages .See How to use LangChain with Databricks Vector Search for using Databricks Vector Search as in integration with LangChain packages.

Il notebook seguente illustra come convertire i risultati della ricerca di somiglianza in documenti LangChain.

Ricerca vettoriale con il notebook python SDK

Ottenere il notebook

Esempi di notebook per chiamare un modello di incorporamento

I notebook seguenti illustrano come configurare un endpoint databricks Model Serving per la generazione di incorporamenti.

Chiamare un modello di incorporamento OpenAI usando il notebook Databricks Model Serving

Ottenere il notebook

Chiamare un modello di incorporamento BGE usando il notebook Databricks Model Serving

Ottenere il notebook

Registrare e gestire un notebook del modello di incorporamento osS

Ottenere il notebook