Vectorzoekeindpunten en -indexen maken

In dit artikel wordt beschreven hoe u vectorzoekeindpunten en indexen maakt met vectorzoekopdrachten.

U kunt vectorzoekonderdelen, zoals een vectorzoekeindpunt en vectorzoekindexen, maken en beheren met behulp van de gebruikersinterface, de Python SDK of de REST-API.

Bijvoorbeeld notebooks die laten zien hoe u eindpunten voor vectorzoekopdrachten maakt en opvraagt, zie Voorbeeldnotebooks voor vectorzoekopdrachten. Zie de Python SDK-verwijzing voor naslaginformatie.

Requirements

• Een werkruimte waarbij Unity Catalog is ingeschakeld.
• Serverloze rekenkracht ingeschakeld. Zie Verbinding maken met serverloze berekeningen voor instructies.
• Voor standaardeindpunten moet voor de brontabel Wijzigingsgegevensfeed zijn ingeschakeld. Zie Delta Lake Change Data Feed gebruiken op Azure Databricks.
• Als u een vectorzoekindex wilt maken, moet u CREATE TABLE bevoegdheden hebben voor het catalogusschema waarin de index wordt gemaakt.
• Als u een query wilt uitvoeren op een index die eigendom is van een andere gebruiker, moet u extra bevoegdheden hebben. Zie Een query uitvoeren op een vectorzoekindex.

De machtiging voor het maken en beheren van vectorzoekeindpunten wordt geconfigureerd met behulp van toegangsbeheerlijsten. Zie ACL's voor vectorzoekeindpunten.

Installatie

Als u de Vector Search SDK wilt gebruiken, moet u deze installeren in uw notebook. Gebruik de volgende code om het pakket te installeren:

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

Gebruik vervolgens de volgende opdracht om VectorSearchClientte importeren:

from databricks.vector_search.client import VectorSearchClient

Zie Gegevensbescherming en -verificatie voor meer informatie over verificatie.

Een vectorzoekeindpunt maken

U kunt een vectorzoekeindpunt maken met behulp van de Databricks-gebruikersinterface, Python SDK of de API.

Een vectorzoekeindpunt maken met behulp van de gebruikersinterface

Volg deze stappen om een vectorzoekeindpunt te maken met behulp van de gebruikersinterface.

1. Klik in de linkerzijbalk op Compute.

2. Klik op het tabblad Vector search en klik op Eindpunt maken.

   

3. Het formulier voor het maken van een eindpunt wordt geopend. Voer een naam in voor dit eindpunt.

   

4. Selecteer in het veld Typede optie Standard of Storage Optimized. Zie eindpuntopties.

5. (Optioneel) Selecteer onder Geavanceerde instellingen een gebruiksbeleid. Zie het gebruiksbeleid voor vectorzoekopdrachten.

6. Klik op Bevestigen.

Een vectorzoekeindpunt maken met behulp van de Python SDK

In het volgende voorbeeld wordt de create_endpoint() SDK-functie gebruikt om een vectorzoekeindpunt te maken.

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

Een vectorzoekeindpunt maken met behulp van de REST API

Zie de REST-API-referentiedocumentatie: POST /api/2.0/vector-search/endpoints.

Een vectorzoekeindpunt maken met behulp van declaratieve Automation-bundels

U kunt een eindpunt voor vectorzoekopdrachten definiëren als een resource in Declarative Automation Bundles om dit als code te beheren naast uw taken, pijplijnen en andere assets in de werkruimte. Zie Wat zijn bundels voor declaratieve automatisering? voor een overzicht van bundels.

In het volgende voorbeeld wordt een standaard vectorzoekeindpunt gedefinieerd:

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

Zie endpoint_type voor de volledige lijst met ondersteunde velden, waaronderbudget_policy_id, min_qps, permissionsen.

Een eindpunt maken met een beoogde QPS voor workloads met een hoge doorvoercapaciteit

Voor workloads met hoge doorvoer kunt u een eindpunt maken met een doel-QPS. Deze functie is alleen beschikbaar voor standaardeindpunten.

Als u een doel-QPS wilt instellen, gebruikt u de target_qps parameter. Zie De doorvoer van eindpunten schalen bij hoge QPS.

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

Als u de doel-QPS op een bestaand eindpunt wilt wijzigen, gebruikt u 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

Nadat u de doel-QPS hebt bijgewerkt, synchroniseert u uw indexen om de nieuwe configuratie toe te passen.

(Optioneel) Een eindpunt maken en configureren voor het insluitmodel

Als u ervoor kiest om databricks de insluitingen te laten berekenen, kunt u een vooraf geconfigureerd Foundation Model-API-eindpunt gebruiken of een model voor eindpunt maken om het insluitmodel van uw keuze te leveren. Zie Foundation Model API's op basis van betaling per token of Serve-eindpunten voor basismodellen creëren voor instructies. Zie voorbeeldnotebooks voor vectorzoekopdrachten.

Wanneer u een embedding-eindpunt configureert, raadt Databricks u aan de standaardselectie van Schaal naar nul te verwijderen. Het kan enkele minuten duren voordat de eindpunten gereed zijn. De eerste query op een index met een afgeschaald eindpunt kan een time-out opleveren.

Een vectorzoekindex maken

U kunt een vectorzoekindex maken met behulp van de gebruikersinterface, de Python SDK of de REST API. De gebruikersinterface is de eenvoudigste benadering.

Er zijn twee typen indexen:

• Delta Sync Index automatisch wordt gesynchroniseerd met een Delta-brontabel, waarbij de index automatisch en incrementeel wordt bijgewerkt wanneer de onderliggende gegevens in de Delta-tabel worden gewijzigd.
• Direct Vector Access Index ondersteunt direct lezen en schrijven van vectoren en metagegevens. De gebruiker is verantwoordelijk voor het bijwerken van deze tabel met behulp van de REST API of de Python SDK. Dit type index kan niet worden gemaakt met behulp van de gebruikersinterface. U moet de REST API of de SDK gebruiken.

Delta Sync-indexen ondersteunen de volgende zoekmodi:

• Vectorzoekopdrachten (ANN of hybride): vereist het insluiten van kolommen. Ondersteunt zowel standaard- als voor opslag geoptimaliseerde eindpunten. U kunt ook zoeken naar trefwoorden in deze indexen gebruiken query_type="FULL_TEXT" .
• Toegewezen zoekindex voor volledige tekst (bèta): een Delta Sync-index die is gemaakt zonder kolommen in te sluiten, voor zoekopdrachten met alleen trefwoorden. Alleen beschikbaar voor eindpunten die zijn geoptimaliseerd voor opslag met behulp van de geactiveerde synchronisatiemodus. Zie Een zoekindex voor volledige tekst maken.

index maken met behulp van de gebruikersinterface

1. Klik in de linkerzijbalk op Catalogus om de gebruikersinterface van Catalog Explorer te openen.

2. Navigeer naar de Delta-tabel die u wilt gebruiken.

3. Klik op de Creeër-knop in de rechterbovenhoek en selecteer vectorzoekindex uit de vervolgkeuzelijst.

   

4. Gebruik de selectors in het dialoogvenster om de index te configureren.

   

   Indexstructuur

   Naam: De naam die moet worden gebruikt voor de onlinetabel in Unity Catalog. De naam vereist een naamruimte met drie niveaus, <catalog>.<schema>.<name>. Alleen alfanumerieke tekens en onderstrepingstekens zijn toegestaan.

   Indextype: Selecteer Hybride ter ondersteuning van zowel semantische (vector) als trefwoordzoekopdrachten op dezelfde index. Selecteer Volledige tekst voor zoekopdrachten met alleen trefwoorden zonder insluitingen. Zie Een zoekindex voor volledige tekst maken (bèta) voor vereisten voor volledige tekstindexen.

   primaire sleutel: kolom die moet worden gebruikt als primaire sleutel.

   Embeddings

   Bron voor insluiten: geef aan of Databricks insluitingen moet berekenen voor een tekstkolom in de Delta-tabel (compute-insluitingen) of dat uw Delta-tabel vooraf berekende insluitingen bevat (bestaande insluitingen gebruiken).

   • Als u Compute-insluitingen hebt geselecteerd, selecteert u de kolom waarvoor u berekeningen wilt insluiten. Een door Databricks beheerd insluitmodel is standaard geselecteerd. Als u een ander model wilt gebruiken, vouwt u Geavanceerde instellingen uit en kiest u in de vervolgkeuzelijst Voor het insluiten van het model . Alleen tekstkolommen worden ondersteund.

     • Voor productietoepassingen die gebruikmaken van standaardeindpunten, raadt Databricks aan om het basismodel databricks-qwen3-embedding-0-6b te gebruiken met een ingerichte doorvoer voor eindpunten.

     • Voor productietoepassingen die gebruikmaken van eindpunten die zijn geoptimaliseerd voor opslag met door Databricks gehoste modellen, gebruikt u de modelnaam rechtstreeks (bijvoorbeeld databricks-qwen3-embedding-0-6b) als het eindpunt van het insluitmodel. Geoptimaliseerde eindpunten voor opslag gebruiken ai_query met batchinferentie tijdens inlooptijd, waardoor hoge doorvoer wordt geboden voor de embedfunctietaak. Als u liever een ingericht doorvoereindpunt gebruikt voor het uitvoeren van query's, geeft u dit op in het model_endpoint_name_for_query veld wanneer u de index maakt.

   • Als u Bestaande insluitingen gebruiken hebt geselecteerd, selecteert u de kolom die de vooraf berekende insluitingen en de insluitingsdimensie bevat. De indeling van de vooraf samengestelde insluitingskolom moet array[float]zijn. Voor eindpunten die zijn geoptimaliseerd voor opslag, moet de insluitingsdimensie gelijkmatig deelbaar zijn met 16.

   Berekende insluitingen opslaan: schakel deze instelling in om de gegenereerde insluitingen op te slaan in een Unity Catalog-tabel. Zie Gegenereerde insluitingstabel opslaanvoor meer informatie.

   Rekenresources

   Eindpunt vector zoeken: selecteer het eindpunt voor vectorzoekopdrachten om de index op te slaan.

   Synchronisatiemodus: Continue houdt de index gesynchroniseerd met seconden latentie. Er zijn echter hogere kosten aan gekoppeld omdat een rekencluster is ingericht om de pijplijn voor continue synchronisatiestreaming uit te voeren.

   • Voor standaardeindpunten voeren doorlopende en geactiveerde incrementele updates uit, dus alleen gegevens die zijn gewijzigd sinds de laatste synchronisatie wordt verwerkt.
   • Voor eindpunten die zijn geoptimaliseerd voor opslag, bouwt elke synchronisatie de index gedeeltelijk opnieuw op. Voor beheerde indexen voor volgende synchronisaties worden gegenereerde insluitingen waarvoor de bronrij niet is gewijzigd, opnieuw gebruikt en hoeven ze niet opnieuw te worden gecomputeerd. Zie beperkingen voor eindpunten die zijn geoptimaliseerd voor opslag.

   Met Triggered-synchronisatiemodus gebruikt u de Python SDK of de REST API om de synchronisatie te starten. Zie Update a Delta Sync Index.

   Voor eindpunten die zijn geoptimaliseerd voor opslag, wordt alleen de geactiveerde synchronisatiemodus ondersteund.

   Geavanceerde instellingen

   

   De sectie Geavanceerde instellingen is standaard samengevouwen. De meeste gebruikers kunnen de standaardwaarden accepteren. Klap het uit om een van de volgende instellingen aan te passen:

   Model voor insluiten: het standaardmodel voor insluiten overschrijven. Het door Databricks gehoste standaardmodel werkt voor de meeste werkruimten. Wijzig deze hier als u een andere nodig hebt of als u geen toegang hebt tot de standaardinstelling.

   Te indexeren kolommen: selecteer de kolommen die u wilt opnemen in de index. Als u dit veld leeg laat, worden alle kolommen uit de brontabel geïndexeerd. De primaire sleutel en het insluiten van kolommen worden altijd opgenomen. Alleen geïndexeerde kolommen kunnen worden geretourneerd in zoekresultaten of worden gebruikt als filters.

   Gebruiksbeleid: Pas een gebruiksbeleid toe om de kosten van de index te taggen voor het bijhouden per team of project. Zie het gebruiksbeleid voor vectorzoekopdrachten.

   Gebruik een afzonderlijk insluitmodel voor query's: als u Compute-insluitingen hebt geselecteerd, selecteert u deze optie om een afzonderlijk insluitmodel op te geven dat het eindpunt biedt voor het uitvoeren van query's op de index. Dit kan handig zijn als u een eindpunt met hoge doorvoer nodig hebt voor opname, maar een eindpunt met een lagere latentie voor het uitvoeren van query's. Het model dat is opgegeven in het veld Insluitmodel , wordt altijd gebruikt voor opname en wordt ook gebruikt voor het uitvoeren van query's, tenzij u hier een ander model opgeeft.

5. Wanneer u klaar bent met het configureren van de index, klikt u op maken.

Index maken met behulp van de Python SDK

In het volgende voorbeeld wordt een Delta Sync-index gemaakt met insluitingen die worden berekend door Databricks. Zie de Python SDK-verwijzing voor meer informatie.

In dit voorbeeld ziet u ook de optionele parameter model_endpoint_name_for_query, waarmee een afzonderlijk insluitmodel voor eindpunten wordt opgegeven die moet worden gebruikt voor het uitvoeren van query's op de index.

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

In het volgende voorbeeld wordt een Delta Sync-index gemaakt met zelfbeheerde insluitingen.

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

Standaard worden alle kolommen uit de brontabel gesynchroniseerd met de index. Als u een subset wilt selecteren van kolommen die u wilt synchroniseren, gebruikt u columns_to_sync. De primaire sleutel en het insluiten van kolommen worden altijd opgenomen in de index.

Als u alleen de primaire sleutel en de embedding-kolom wilt synchroniseren, moet u deze in columns_to_sync opgeven zoals getoond:

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

Als u extra kolommen wilt synchroniseren, geeft u deze op zoals wordt weergegeven. U hoeft de primaire sleutel en de insluitingskolom niet op te nemen, omdat ze altijd worden gesynchroniseerd.

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

Een zoekindex voor volledige tekst maken (bèta)

Met een zoekindex voor volledige tekst kunt u zoeken op basis van trefwoorden op tekstkolommen zonder vectorinsluitingen. Dit is handig als u wilt zoeken naar exacte termen, id's of trefwoorden in plaats van semantische overeenkomsten.

Zoekindexen in volledige tekst hebben de volgende vereisten:

• Moet een eindpunt gebruiken dat is geoptimaliseerd voor opslag . Standaardeindpunten worden niet ondersteund.
• Moet de geactiveerde synchronisatiemodus gebruiken. Continue synchronisatie wordt niet ondersteund.
• De parameters embedding_source_column, embedding_vector_columnen embedding_dimension worden niet ondersteund.

In het volgende voorbeeld wordt een zoekindex voor volledige tekst gemaakt met behulp van de 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"
)

Nadat u de index hebt gemaakt, activeert u een synchronisatie om deze te vullen:

index.sync()

Als u een query wilt uitvoeren op de volledige-tekstindex, gebruikt u query_type="FULL_TEXT". Zie Een vectorzoekindex opvragen voor meer informatie.

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

In het volgende voorbeeld wordt een Direct Vector Access-index gemaakt.

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

Index maken met behulp van de REST API

Raadpleeg de REST API-referentiedocumentatie: POST /api/2.0/vector-search/indexen.

Gegenereerde insluitingstabel opslaan

Als Databricks de insluitingen genereert, kunt u de gegenereerde insluitingen opslaan in een tabel in Unity Catalog. Deze tabel wordt gemaakt in hetzelfde schema als de vectorindex en is gekoppeld vanaf de vectorindexpagina.

De naam van de tabel is de naam van de vectorzoekindex, toegevoegd door _writeback_table. De naam kan niet worden bewerkt.

U kunt de tabel als elke andere tabel in Unity Catalog openen en er query's op uitvoeren. U moet de tabel echter niet verwijderen of wijzigen, omdat deze niet handmatig moet worden bijgewerkt. De tabel wordt automatisch verwijderd als de index wordt verwijderd.

Een vectorzoekindex bijwerken

een Delta Sync-index bijwerken

Indexen die zijn gemaakt met continue synchronisatiemodus, worden automatisch bijgewerkt wanneer de delta-brontabel wordt gewijzigd. Als u de synchronisatiemodus Triggered gebruikt, kunt u de synchronisatie starten met behulp van de gebruikersinterface, de Python SDK of de REST API.

Databricks-gebruikersinterface

1. Navigeer in Catalog Explorer naar de vectorzoekindex.

2. Klik op het tabblad Overzicht in de sectie Gegevensopname op Nu synchroniseren.

   .

Python SDK

Zie de Python SDK-verwijzing voor meer informatie.

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

index.sync()

REST API

Zie de referentiedocumentatie voor de REST API: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Een Direct Vector Access-index bijwerken

U kunt de Python SDK of de REST API gebruiken om gegevens in te voegen, bij te werken of te verwijderen uit een Direct Vector Access-index.

Python SDK

Zie de Python SDK-verwijzing voor meer informatie.

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

Raadpleeg de REST API-referentiedocumentatie: POST /api/2.0/vector-search/indexen.

Voor productietoepassingen raadt Databricks aan om service-principals te gebruiken in plaats van persoonlijke toegangstokens. De prestaties kunnen worden verbeterd met maximaal 100 msec per query.

In het volgende codevoorbeeld ziet u hoe u een index bijwerkt met behulp van een service-principal.

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

In het volgende codevoorbeeld ziet u hoe u een index bijwerkt met behulp van een persoonlijk toegangstoken (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": [...]}'

Schemawijzigingen aanbrengen zonder uitvaltijd

Schemawijzigingen in de brontabel worden niet ondersteund, tenzij u de index opnieuw opbouwt. Dit omvat het wijzigen van bestaande kolommen en het toevoegen van nieuwe kolommen. Het indexschema is tijdens het maken vast, dus voor alle schemawijzigingen moet een nieuwe index worden gemaakt om van kracht te worden.

Volg deze stappen om de index opnieuw te bouwen en te implementeren zonder uitvaltijd:

1. Voer de schemawijziging uit in de brontabel.
2. Maak een nieuwe index met behulp van het bijgewerkte schema.
3. Nadat de nieuwe index gereed is, schakelt u verkeer over naar de nieuwe index.
4. Verwijder de oorspronkelijke index.