Vectorzoekeindpunten en -indexen maken

In dit artikel wordt beschreven hoe u eindpunten en indexen voor vectorzoekopdrachten maakt met behulp van Mozaïek AI Vector Search.

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 Naslaginformatie over de Python SDK 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-wijzigingsgegevensfeed gebruiken in 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.

Klik in de linkerzijbalk op Compute.
Klik op het tabblad Vector Search en klik op Maken.
Het formulier voor het maken van een eindpunt wordt geopend. Voer een naam in voor dit eindpunt.
Selecteer in het veld Typede optie Standard of Storage Optimized. Zie eindpuntopties.
(Optioneel) Selecteer onder Geavanceerde instellingen een budgetbeleid. Zie Mozaïek AI Vector Search: Budgetbeleid.
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.

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

Opmerking

Er kan een time-out optreden voor de initialisatie van de vectorzoekindex als het embedden eindpunt niet juist is geconfigureerd voor de gegevensset. Gebruik alleen CPU-eindpunten voor kleine gegevenssets en tests. Gebruik voor grotere gegevenssets een GPU-eindpunt voor optimale prestaties.

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.

Opmerking

De kolomnaam _id is gereserveerd. Als de brontabel een kolom heeft met de naam _id, wijzigt u de naam ervan voordat u een vectorzoekindex maakt.

index maken met behulp van de gebruikersinterface

Klik in de linkerzijbalk op Catalogus om de gebruikersinterface van Catalog Explorer te openen.
Navigeer naar de Delta-tabel die u wilt gebruiken.
Klik op de Creeër-knop in de rechterbovenhoek en selecteer vectorzoekindex uit de vervolgkeuzelijst.
Gebruik de selectors in het dialoogvenster om de index te configureren.

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.

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

Kolommen die moeten worden gesynchroniseerd: (alleen ondersteund voor standaardeindpunten.) Selecteer de kolommen die u wilt synchroniseren met de vectorindex. Als u dit veld leeg laat, worden alle kolommen uit de brontabel gesynchroniseerd met de index. De primaire sleutelkolom en de insluitingsbronkolom of de insluitvectorkolom worden altijd gesynchroniseerd. Voor eindpunten die zijn geoptimaliseerd voor opslag, worden alle kolommen uit de brontabel altijd gesynchroniseerd.

Bron insluiten: Geef aan of Databricks insluitingen voor een tekstkolom in de Delta-tabel (Compute-insluitingen) moet berekenen of als uw Delta-tabel vooraf berekende insluitingen bevat (Bestaande insluitingskolom gebruiken).
- Als u Compute-insluitingen hebt geselecteerd, selecteert u de kolom waarvoor u berekende insluitingen wilt insluiten en het insluitmodel dat moet worden gebruikt voor de berekening. Alleen tekstkolommen worden ondersteund.
  - Voor productietoepassingen die gebruikmaken van standaardeindpunten, raadt Databricks aan om het basismodel databricks-gte-large-en 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-gte-large-en) 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 insluitingskolom gebruikenhebt 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 synchroniseren: schakel deze instelling in om de gegenereerde insluitingen op te slaan in een Unity Catalog-tabel. Zie Gegenereerde insluitingstabel opslaanvoor meer informatie.

Eindpunt voor vectorzoekopdrachten: 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 geactiveerde synchronisatiemodus gebruikt u de Python SDK of de REST API om de synchronisatie te starten. Zie Een Delta Sync Index bijwerken.

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

Geavanceerde instellingen: (optioneel) Als u Compute-insluitingen hebt geselecteerd, kunt u een afzonderlijk insluitingsmodel opgeven om een query uit te voeren op uw vectorzoekindex. 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 op de index. 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. Als u een ander model wilt opgeven, klikt u op Afzonderlijk insluitmodel kiezen om een query uit te voeren op de index en selecteert u een model in de vervolgkeuzelijst.
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 Naslaginformatie over de Python SDK 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.

Op standaardeindpunten kunt u een subset van kolommen selecteren die u wilt synchroniseren met behulp van 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.
)

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 geactiveerd gebruikt, kunt u de synchronisatie starten met behulp van de gebruikersinterface, de Python SDK of de REST API.

Databricks-gebruikersinterface

Navigeer in Catalog Explorer naar de vectorzoekindex.
Klik op het tabblad Overzicht in de sectie Gegevensopname op Nu synchroniseren.

.

Python SDK

Zie de Naslaginformatie over de Python SDK 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 Naslaginformatie over de Python SDK 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

Als het schema van bestaande kolommen in de brontabel wordt gewijzigd, moet u de index opnieuw opbouwen. Als de write-backtabel is ingeschakeld, moet u ook de index opnieuw opbouwen wanneer er nieuwe kolommen worden toegevoegd aan de brontabel. Als de write-backtabel niet is ingeschakeld, hoeven nieuwe kolommen de index niet opnieuw te bouwen.

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

Voer de schemawijziging uit in de brontabel.
Maak een nieuwe index.
Nadat de nieuwe index gereed is, schakelt u verkeer over naar de nieuwe index.
Verwijder de oorspronkelijke index.

Feedback

Is deze pagina nuttig?

Last updated on 2025-12-06

Delen via

Vectorzoekeindpunten en -indexen maken

Requirements

Installatie

Een vectorzoekeindpunt maken

Een vectorzoekeindpunt maken met behulp van de gebruikersinterface

Een vectorzoekeindpunt maken met behulp van de Python SDK

Een vectorzoekeindpunt maken met behulp van de REST API

(Optioneel) Een eindpunt maken en configureren voor het insluitmodel

Een vectorzoekindex maken

index maken met behulp van de gebruikersinterface

Index maken met behulp van de Python SDK

Index maken met behulp van de REST API

Gegenereerde insluitingstabel opslaan

Een vectorzoekindex bijwerken

een Delta Sync-index bijwerken

Databricks-gebruikersinterface

Python SDK

REST API

Een Direct Vector Access-index bijwerken

Python SDK

REST API

Schemawijzigingen aanbrengen zonder uitvaltijd

Feedback

Aanvullende resources