Creare endpoint e indici di ricerca vettoriali

Questo articolo descrive come creare endpoint e indici di ricerca vettoriali usando Ricerca vettoriale.

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

Ad esempio, per i notebook che illustrano come creare ed eseguire query sugli endpoint di ricerca vettoriale, consultare Notebook di esempio di ricerca vettoriale. Per informazioni di riferimento, vedere le informazioni di riferimento Python SDK.

Requisiti

• Area di lavoro con Unity Catalog abilitato.
• Calcolo serverless attivato. Per le istruzioni, consulta Connetti al calcolo senza server.
• Per gli endpoint standard, la tabella di origine deve avere il feed di dati delle modifiche abilitato. Consulta Usare il feed di dati di modifica di Delta Lake in Azure Databricks.
• Per creare un indice di ricerca vettoriale, è necessario disporre di CREATE TABLE privilegi sullo schema del catalogo in cui verrà creato l'indice.
• Per eseguire una query su un indice di proprietà di un altro utente, è necessario disporre di privilegi aggiuntivi. Vedere Come eseguire query su un indice di ricerca vettoriale.

L'autorizzazione per creare e gestire gli endpoint di ricerca vettoriali viene configurata usando gli elenchi di controllo di accesso. Vedere ACL dell'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

Per informazioni sull'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 endpoint.

   

3. Si apre il modulo Crea un endpoint. Immettere un nome per questo endpoint.

   

4. Nel campo Tipo selezionare Standard o Ottimizzato per l'archiviazione. Vedere Opzioni endpoint.

5. (Facoltativo) In Impostazioni avanzate selezionare un criterio di utilizzo. Vedere Criteri di utilizzo della ricerca vettoriale.

6. Cliccare Conferma.

Creare un endpoint di ricerca vettoriale usando 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" # or "STORAGE_OPTIMIZED"
)

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.

Creare un endpoint di ricerca vettoriale usando bundle di automazione dichiarativa

È possibile definire un endpoint di ricerca vettoriale come risorsa in Bundle di automazione dichiarativa per gestirlo come codice insieme a processi, pipeline e altri asset dell'area di lavoro. Per una panoramica dei bundle, vedere Che cosa sono i bundle di automazione dichiarativa?.

L'esempio seguente definisce un endpoint di ricerca vettoriale standard:

resources:
  vector_search_endpoints:
    my_vector_search_endpoint:
      name: my_vector_search_endpoint
      endpoint_type: STANDARD

Per l'elenco completo dei campi supportati, tra cui endpoint_type, budget_policy_idmin_qps, e permissions, vedere vector_search_endpoint.

Crea un endpoint con un QPS di destinazione per carichi di lavoro a throughput elevato

Per i carichi di lavoro a throughput elevato, è possibile creare un endpoint con un QPS target. Questa funzionalità è disponibile solo per gli endpoint standard.

Per impostare un QPS di destinazione, usare il target_qps parametro . Consulta Aumentare il throughput degli endpoint con QPS elevato.

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD",
    target_qps=500,  # target QPS for high-throughput workloads
)

Per modificare il QPS di destinazione in un endpoint esistente, usare update_endpoint().

from databricks.vector_search.client import VectorSearchClient

client = VectorSearchClient()

# Set or update target QPS
response = client.update_endpoint(name="vector_search_endpoint_name", target_qps=500)

# Check scaling status
scaling_info = response.get("endpoint", {}).get("scaling_info", {})
print(f"State: {scaling_info.get('state')}")  # SCALING_CHANGE_IN_PROGRESS or SCALING_CHANGE_APPLIED

Dopo aver aggiornato il QPS di destinazione, sincronizza gli indici per applicare la nuova configurazione.

(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 notebook di esempio, vedere Notebook di esempio di ricerca vettoriale.

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.

Creare un indice di ricerca vettoriale

È possibile creare un indice di ricerca vettoriale usando l'interfaccia utente, l'SDK di Python 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 l'SDK di Python. Questo tipo di indice non può essere creato usando l'interfaccia utente. È necessario usare l'API REST o l'SDK.

Gli indici di sincronizzazione delta supportano le modalità di ricerca seguenti:

• Ricerca vettoriale (ANN o ibrida): richiede l'incorporamento di colonne. Supporta endpoint sia standard che ottimizzati per l'archiviazione. È anche possibile usare query_type="FULL_TEXT" per la ricerca di parole chiave in questi indici.
• Indice di ricerca full-text dedicato (Beta): Indice di Sincronizzazione Delta creato senza colonne di embedding, per la ricerca esclusivamente di parole chiave. Disponibile solo sugli endpoint ottimizzati per l'archiviazione usando la modalità di sincronizzazione attivata. Vedere Creare un indice di ricerca full-text.

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.

   

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

   

   Struttura dell'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.

   Tipo di indice: selezionare Ibrido per supportare sia la semantica (vettore) che la ricerca di parole chiave nello stesso indice. Selezionare Full-Text per la ricerca solo parole chiave senza incorporamenti. Per i requisiti dell'indice di ricerca full-text, vedere Creare un indice di ricerca full-text (Beta).

   chiave primaria: colonna da usare come chiave primaria.

   Embeddings

   Origine degli embedding: indica se vuoi che Databricks calcoli gli embedding per una colonna di testo nella tabella Delta (Calcola embedding) o se la tua tabella Delta contiene embedding precalcolati (Usa embedding esistenti).

   • Se hai selezionato Calcola embedding, seleziona la colonna per la quale desideri calcolare gli embedding. Per impostazione predefinita, viene selezionato un modello di incorporamento gestito da Databricks. Per usare un modello diverso, espandere Impostazioni avanzate e scegliere dall'elenco a discesa Incorpora modello . Sono supportate solo le colonne di testo.

     • Per le applicazioni di produzione che usano endpoint standard, Databricks consiglia di usare il modello foundation databricks-qwen3-embedding-0-6b con un endpoint di servizio con capacità throughput provisionata.

     • Per le applicazioni di produzione che usano endpoint ottimizzati per l'archiviazione con modelli ospitati in Databricks, usare direttamente il nome del modello (ad esempio, databricks-qwen3-embedding-0-6b) come endpoint del modello di incorporamento. Gli endpoint ottimizzati per l'archiviazione usano ai_query con inferenza batch in fase di inserimento, offrendo una velocità effettiva elevata per il processo di incorporamento. Se si preferisce usare un endpoint di throughput con provisioning per l'esecuzione di query, specificarlo nel campo model_endpoint_name_for_query quando si crea l'indice.

   • Se è stata selezionata l'opzione Usa incorporamenti esistenti, selezionare la colonna contenente gli incorporamenti precompilate e la dimensione di incorporamento. Il formato della colonna di incorporamento pre-calcolata deve essere array[float]. Per gli endpoint ottimizzati per l'archiviazione, la dimensione di incorporamento deve essere divisibile in modo uniforme per 16.

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

   Risorse di calcolo

   Endpoint di ricerca vettoriale: selezionare l'endpoint di ricerca vettoriale per archiviare l'indice.

   modalità di sincronizzazione: continua mantiene la sincronizzazione dell'indice con i secondi di latenza. Tuttavia, è associato a costi più elevati poiché viene effettuato il provisioning di un cluster di calcolo per eseguire la pipeline di streaming di sincronizzazione continua.

   • Per gli endpoint standard, sia continuous che triggered eseguono aggiornamenti incrementali, quindi vengono elaborati solo i dati modificati dall'ultima sincronizzazione.
   • Per gli endpoint ottimizzati per l'archiviazione, ogni sincronizzazione ricompila parzialmente l'indice. Per gli indici gestiti nelle sincronizzazioni successive, gli incorporamenti generati in cui la riga di origine non è stata modificata vengono riutilizzate e non devono essere ricalcolate. Vedere Limitazioni degli endpoint ottimizzati per l'archiviazione.

   Con Triggered modalità di sincronizzazione, usare Python SDK o l'API REST per avviare la sincronizzazione. Vedere Aggiornare un indice di sincronizzazione delta.

   Per gli endpoint ottimizzati per l'archiviazione, è supportata solo la modalità di sincronizzazione attivata .

   Impostazioni avanzate

   

   La sezione Impostazioni avanzate è compressa per impostazione predefinita. La maggior parte degli utenti può accettare le impostazioni predefinite. Espandilo per regolare uno qualsiasi dei seguenti elementi:

   Modello di incorporamento: eseguire l'override del modello di incorporamento predefinito. Il modello ospitato da Databricks predefinito funziona per la maggior parte delle aree di lavoro. Modificarlo qui se è necessario uno diverso o se non si ha accesso all'impostazione predefinita.

   Colonne da indicizzare: selezionare le colonne da includere nell'indice. Se si lascia vuoto questo campo, tutte le colonne della tabella di origine vengono indicizzate. La chiave primaria e le colonne di embedding sono sempre incluse. Solo le colonne indicizzate possono essere restituite nei risultati della ricerca o usate come filtri.

   Criteri di utilizzo: applicare criteri di utilizzo per contrassegnare i costi dell'indice per il rilevamento in base al team o al progetto. Vedere Criteri di utilizzo della ricerca vettoriale.

   Usare un modello di incorporamento separato per le query: se sono stati selezionati incorporamenti di calcolo, selezionare questa opzione per specificare un modello di incorporamento separato che gestisce l'endpoint per l'esecuzione di query sull'indice. Ciò può essere utile se ti serve un endpoint ad alta capacità di trasmissione per l'acquisizione dei dati, ma un endpoint a bassa latenza per le query. Il modello specificato nel campo Modello di incorporamento viene sempre usato per l'inserimento e viene usato anche per l'esecuzione di query, a meno che non si specifichi un modello diverso qui.

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. Per informazioni dettagliate, vedere le informazioni di riferimento Python SDK.

In questo esempio viene illustrato anche il parametro facoltativo model_endpoint_name_for_query, che specifica un endpoint di modello di embedding separato da usare per interrogare l'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_source_column="text",
  embedding_model_endpoint_name="e5-small-v2", # This model is used for ingestion, and is also used for querying unless model_endpoint_name_for_query is specified.
  model_endpoint_name_for_query="e5-mini-v2"   # Optional. If specified, used only for querying the index.
)

Nell'esempio seguente viene creato un indice Delta Sync con incorporamenti autogestiti.

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 selezionare un subset di colonne da sincronizzare, 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.
)

Creare un indice di ricerca full-text (Beta)

Un indice di ricerca full-text consente la ricerca basata su parole chiave sulle colonne di testo senza richiedere incorporamenti vettoriali. Ciò è utile quando si desidera cercare termini, identificatori o parole chiave esatte anziché somiglianza semantica.

Gli indici di ricerca full-text hanno i requisiti seguenti:

• Deve usare un endpoint ottimizzato per l'archiviazione . Gli endpoint standard non sono supportati.
• Deve usare la modalità di sincronizzazione attivata . La sincronizzazione continua non è supportata.
• I parametri embedding_source_column, embedding_vector_columne embedding_dimension non sono supportati.

L'esempio seguente crea un indice di ricerca full-text usando Python SDK.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="storage_optimized_endpoint",
  source_table_name="catalog.schema.source_table",
  index_name="catalog.schema.full_text_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  columns_to_sync=["id", "text", "metadata_column"],
  index_subtype="FULL_TEXT"
)

Dopo aver creato l'indice, attivare una sincronizzazione per popolarla:

index.sync()

Per eseguire una query sull'indice full-text, usare query_type="FULL_TEXT". Per informazioni dettagliate, vedere Eseguire query su un indice di ricerca vettoriale .

results = index.similarity_search(
  query_text="search terms",
  columns=["id", "text"],
  num_results=10,
  query_type="FULL_TEXT"
)

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=f"{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 usa Triggered modalità di sincronizzazione, è possibile avviare la sincronizzazione usando l'interfaccia utente, Python SDK o l'API REST.

Interfaccia utente di Databricks

1. In Esplora cataloghi passare all'indice di ricerca vettoriale.

2. Nella sezione Inserimento dati della scheda Panoramica fare clic su Sincronizza.

   

PYTHON SDK

Per informazioni dettagliate, vedere le informazioni di riferimento Python SDK.

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

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 l'SDK di Python o l'API REST per inserire, aggiornare o eliminare dati da un indice di accesso a vettore diretto.

PYTHON SDK

Per informazioni dettagliate, vedere le informazioni di riferimento Python SDK.

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

REST API

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

Per le applicazioni di produzione, Databricks consiglia di usare principali di servizio anziché token di accesso personali. Le prestazioni possono essere migliorate di fino a 100 millisecondi per ogni query.

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

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

Come apportare modifiche allo schema senza tempi di inattività

Le modifiche dello schema alla tabella di origine non sono supportate a meno che non si ricompila l'indice. Ciò include la modifica delle colonne esistenti e l'aggiunta di nuove colonne. Lo schema dell'indice è fisso in fase di creazione, pertanto tutte le modifiche dello schema richiedono la creazione di un nuovo indice per rendere effettivo.

Seguire questa procedura per ricompilare e distribuire l'indice senza tempi di inattività:

1. Eseguire la modifica dello schema nella tabella di origine.
2. Creare un nuovo indice usando lo schema aggiornato.
3. Dopo aver pronto il nuovo indice, passare il traffico al nuovo indice.
4. Eliminare l'indice originale.