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 Mosaic AI Vector Search.

È 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 SDKo l'API REST .

Requisiti

L'autorizzazione per creare e gestire gli endpoint di ricerca vettoriali viene configurata usando gli elenchi di controllo di accesso. Consulta gli ACL per l'endpoint di ricerca vettoriale .

Installazione

Per usare l'SDK di ricerca vettoriale, è necessario installarlo nel notebook. Usare il codice seguente per installare il pacchetto:

%pip install databricks-vectorsearch
dbutils.library.restartPython()

Usare quindi il comando seguente per importare VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Autenticazione

Vedere Protezione dei dati e autenticazione.

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 modulo endpoint

  3. Si apre il modulo Crea un 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 create_endpoint() SDK 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 = VectorSearchClient(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

Consultare la documentazione di riferimento dell'API REST: 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 delle API del modello di base preconfigurato o creare un endpoint di gestione di un 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, consultare gli esempi per chiamare un modello di embedding.

Quando configuri un endpoint di embedding, Databricks consiglia di rimuovere la selezione predefinita di Riduci a zero. Gli endpoint di servizio possono richiedere un paio di minuti per scaldarsi, e la query iniziale su un indice con un endpoint ridimensionato può andare in timeout.

Nota

L'inizializzazione dell'indice di ricerca vettoriale potrebbe andare in timeout se l'endpoint di embedding non è configurato correttamente 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:

  • indice di sincronizzazione delta sincronizza 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 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.

    Crea pulsante 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 un namespace 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.

    Colonne da sincronizzare: selezionare le colonne da sincronizzare con l'indice vettoriale. Se si lascia vuoto questo campo, tutte le colonne della tabella di origine vengono sincronizzate con l'indice. La colonna chiave primaria e la colonna di origine di incorporamento o la colonna vettoriale di incorporamento vengono sempre sincronizzate.

    Fonte di embedding: Indicare se si vuole che Databricks calcoli gli embedding per una colonna di testo nella tabella Delta (Calcolare embedding) o se la tabella Delta contiene embedding precompilati (Utilizzare la colonna di embedding esistente).

    • Se hai selezionato calcolare incorporamenti, seleziona la colonna per cui desideri calcolare gli incorporamenti e l'endpoint che serve il modello di incorporamento. Sono supportate solo le colonne di testo.
    • Se è stata selezionata Usa colonna di embedding esistente, selezionare la colonna contenente gli embedding precomputati e la dimensione di embedding. Il formato della colonna di incorporamento pre-calcolata deve essere array[float].

    Sincronizza gli embeddings calcolati: Attiva o disattiva questa impostazione per salvare gli embeddings generati in una tabella del catalogo Unity. Per ulteriori informazioni, vedere Tabella di embedding generata.

    modalità di sincronizzazione: continua mantiene la sincronizzazione dell'indice 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. Sia per continuo che per attivato, l'aggiornamento è incrementale: vengono elaborati solo i dati modificati dalla sincronizzazione precedente.

    Con la modalità di sincronizzazione attivata con , utilizzare il Python SDK o l'API REST per avviare la sincronizzazione. Consultare Aggiornare un indice di sincronizzazione delta.

  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 embedding 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 Delta Sync con incorporamenti autogestiti. Questo esempio mostra anche l'uso del parametro facoltativo columns_to_sync per selezionare solo un subset di colonne da utilizzare nell'indice.

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

Per impostazione predefinita, tutte le colonne della tabella di origine vengono sincronizzate con l'indice. Per sincronizzare solo un subset di colonne, usare columns_to_sync. La chiave primaria e le colonne di incorporazione sono sempre incluse nell'indice.

Per sincronizzare solo la chiave primaria e la colonna di incorporamento, è necessario specificarli in columns_to_sync come illustrato:

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

Per sincronizzare colonne aggiuntive, specificarle come illustrato. Non è necessario includere la chiave primaria e la colonna embedding, perché vengono sempre sincronizzate.

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

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": "string",
    "field3": "float",
    "text_vector": "array<float>"}
)

Creare un indice usando l'API REST

Consulta la documentazione di riferimento dell'API REST: 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 ed eseguire query sulla tabella come su 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 si aggiornano automaticamente quando cambia la tabella Delta di origine. Se si utilizza la modalità di sincronizzazione attivata, utilizzare il Python SDK o l'API REST per avviare la sincronizzazione.

Python SDK

index.sync()

REST API

Consultare la documentazione di riferimento dell'API REST: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Aggiornare un indice di accesso diretto ai vettori

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

REST API

Consulta la documentazione di riferimento dell'API REST: POST /api/2.0/vector-search/indexes.

Nell'esempio di codice seguente viene illustrato come aggiornare un indice usando un token di accesso personale (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": [...]}'

Nell'esempio di codice seguente viene illustrato come aggiornare un indice usando un'entità servizio.

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": [...]}'

Eseguire una query su un endpoint di ricerca vettoriale

È possibile eseguire query solo sull'endpoint di ricerca vettoriale usando il Python SDK, l'API REST o la funzione AI SQL vector_search().

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:

  • USE CATALOG nel catalogo che contiene l'indice di ricerca vettoriale.
  • USE SCHEMA sullo schema che contiene l'indice di ricerca vettoriale.
  • SELECT sull'indice di ricerca vettoriale.

Per eseguire una ricerca ibrida di somiglianza con parole chiave, impostare il parametro query_type su hybrid. Il valore predefinito è ann (vicino più prossimo approssimativo).

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

Consultare la documentazione di riferimento dell'API REST: POST /api/2.0/vector-search/indexes/{index_name}/query.

Nell'esempio di codice seguente viene illustrato come eseguire query su un indice usando un token di accesso personale ( 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}'

Nell'esempio di codice seguente viene illustrato come eseguire una query su un indice usando un principale del servizio.

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

Importante

La funzione di intelligenza artificiale vector_search() è disponibile in anteprima pubblica.

Per utilizzare la funzione di intelligenza artificiale , consultare la funzione di ricerca vettoriale .

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 di filtro 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 200 corrisponde ai documenti in cui il prezzo è minore di 200. {"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 200 corrisponde ai documenti in cui il prezzo è minore o uguale a 200. {"id <=": 200}
> Controlla se il valore del campo è maggiore del valore del filtro. La chiave deve terminare con " >". Ad esempio, "price >" con valore 200 corrisponde ai documenti in cui il prezzo è maggiore di 200. {"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 200 corrisponde ai documenti in cui il prezzo è maggiore o uguale a 200. {"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 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
    )

REST API

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

Notebook di esempio

Gli esempi in questa sezione illustrano l'uso di Python SDK per la ricerca vettoriale.

Esempi di LangChain

Vedi Come utilizzare LangChain con la Ricerca Vettoriale di Mosaic AI per l'integrazione della Ricerca Vettoriale di Mosaic AI con i pacchetti LangChain.

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

Ricerca vettoriale con il notebook Python SDK

Prendi notebook

Notebook : esempi per chiamare un modello di embedding

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

Chiamare un modello di embedding di OpenAI utilizzando il notebook Mosaic AI Model Serving

Prendi notebook

Chiamare un modello di incorporamento GTE usando il notebook Mosaic AI Model Serving

Prendi notebook

Registrare e gestire un notebook del modello di incorporamento osS

Prendi notebook