Delen via

Een vectorzoekindex maken en er query's op uitvoeren

  • Artikel

In dit artikel wordt beschreven hoe u een vectorzoekindex maakt en opvraagt 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-.

Eisen

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

Installatie

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

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Authenticatie

Zie gegevensbescherming en -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 Maken.

    Eindpuntformulier maken

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

  4. 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 = VectorSearch(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD"
)

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 Api's voor betalen per token Foundation-model of Basismodel maken voor eindpunten voor instructies. Zie bijvoorbeeld notebooks Notebook-voorbeelden voor het aanroepen van een model voor insluitingen.

Wanneer u een insluiteindpunt configureert, raadt Databricks aan dat u de standaardselectie van schalen naar nulremove. 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.

Notitie

Er kan een time-out optreden voor de initialisatie van de vectorzoekindex als het embedding-eindpunt niet juist is geconfigureerd voor de dataset. 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 bron-Delta-Table. De index wordt automatisch en incrementeel bijgewerkt wanneer de onderliggende gegevens in de Delta-Table worden gewijzigd.
  • Direct Vector Access Index ondersteunt direct lezen en schrijven van vectoren en metagegevens. De gebruiker is verantwoordelijk voor het bijwerken van deze table 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.

index maken met behulp van de gebruikersinterface

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

  2. Navigeer naar de Delta table die u wilt gebruiken.

  3. Klik op de knop Maken in de rechterbovenhoek en selecteer selectVectorzoekindex in de vervolgkeuzelijst.

    knop Index maken

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

    dialoogvenster Index creëren

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

    primaire sleutel: Column gebruiken als primaire sleutel.

    Eindpunt: Select het eindpunt voor vectorzoekopdrachten dat u wilt gebruiken.

    Columns naar sync: Select de columns met de vectorindex sync. Als u dit veld leeg laat, worden alle columns uit de bron table gesynchroniseerd met de index. De primaire sleutel column en insluitingsbron column of insluitingsvector column worden altijd gesynchroniseerd.

    Bron voor insluiten: Geef aan of u wilt dat Databricks insluitingen berekent voor een tekst column in de Delta-table (Compute-insluitingen), of als uw Delta-table vooraf berekende insluitingen bevat (Bestaande insluiting gebruiken column).

    • Als u Embeddings berekenenhebt geselecteerd, selecteert u select de column waarvoor u embeddings wilt berekenen en het eindpunt dat het embedding-model aanbiedt. Alleen tekst columns wordt ondersteund.
    • Als u Bestaande insluitings-columngebruiken hebt geselecteerd, select u de column met de vooraf berekende insluitingen en de insluitingsdimensie. De indeling van de vooraf berekende embedding column zou array[float]moeten zijn.

    Sync berekende insluitingen: schakel deze instelling in om de gegenereerde insluitingen op te slaan in een Unity-Catalogtable. Zie Gegenereerde insluiting tableopslaan voor meer informatie.

    Sync modus: Continue houdt de index in sync met seconden latentie. Er zijn echter hogere kosten aan gekoppeld omdat een rekencluster is ingericht om de pijplijn voor continue sync streaming uit te voeren. Voor zowel Continue als Geactiveerdeis het update incrementeel, alleen gegevens die zijn gewijzigd sinds de laatste sync worden verwerkt.

    Met de geactiveerde modus gebruikt u de Python SDK of de REST API om de te starten. Zie een Delta Index.

  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 zijn berekend door 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"
)

In het volgende voorbeeld wordt een Delta Sync Index gemaakt met zelfbeheerde insluitingen. In dit voorbeeld ziet u ook het gebruik van de optionele parameter columns_to_sync tot select om slechts een subset van columns te gebruiken in 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_dimension=1024,
  embedding_vector_column="text_vector"
)

Standaard worden alle columns van de bron table gesynchroniseerd met de index. Als u slechts een subset van columnswilt sync, gebruikt u columns_to_sync. De primaire sleutel en het insluiten van columns worden altijd opgenomen in de index.

Als u alleen de primaire sleutel en het insluiten columnwilt sync, moet u deze opgeven in columns_to_sync zoals wordt weergegeven:

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

Om sync extra columnsop te geven, specificeer ze zoals weergegeven. U hoeft de primaire sleutel en de embedding columnniet op te nemen, want ze worden altijd 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="{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 insluiting opslaan table

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

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

U kunt de table openen en er query's op uitvoeren, net zoals bij andere table in Unity Catalog. U moet de tableechter niet verwijderen of wijzigen, omdat het niet bedoeld is om handmatig te worden bijgewerkt. De table wordt automatisch verwijderd als de index wordt verwijderd.

een vectorzoekindex Update

Update een Delta Sync-index

Indexen die zijn gemaakt met continuesync modus, worden automatisch update wanneer de bron-Delta table verandert. Als u de geactiveerdesync-modus gebruikt, gebruik dan de Python SDK of de REST API om syncte starten.

Python SDK

index.sync()

REST API

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

een Direct Vector Access-index Update

U kunt de Python SDK of de REST API gebruiken om insert, updateof gegevens te verwijderen uit een Direct Vector Access-index.

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

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

In het volgende codevoorbeeld ziet u hoe u een index kunt update 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": [...]}'

In het volgende codevoorbeeld wordt geïllustreerd hoe u een index kunt update 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": [...]}'

een vectorzoekeindpunt opvragen

U kunt alleen een query uitvoeren op het eindpunt voor vectorzoekopdrachten met behulp van de Python SDK, de REST API of de SQL vector_search() AI-functie.

Notitie

Als de gebruiker die het eindpunt opvraagt niet de eigenaar is van de vectorzoekindex, moet de gebruiker de volgende UC-bevoegdheden hebben:

  • USE CATALOG op de catalog die de vectorzoekindex bevat.
  • USE SCHEMA op de schema die de vectorzoekindex bevat.
  • SELECT op de vectorzoekindex.

Om een hybride zoekopdracht voor trefwoord-overeenkomst uit te voeren, set de parameter query_type naar hybrid. De standaardwaarde is ann (dichtstbijzijnde buur).

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

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

In het volgende codevoorbeeld ziet u hoe u een query kunt uitvoeren op een index met behulp van een persoonlijk toegangstoken (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}'

In het volgende codevoorbeeld ziet u hoe u een query uitvoert op een index 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": "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

Belangrijk

De vector_search() AI-functie bevindt zich in openbare preview-.

Als u deze AI-functiewilt gebruiken, raadpleegt u vector_search functie.

Filters gebruiken voor query's

Een query kan filters definiëren op basis van elke column in de Delta-table. similarity_search retourneert alleen rijen die overeenkomen met de opgegeven filters. De volgende filters worden ondersteund:

Filteroperator Gedrag Voorbeelden
NOT Hiermee wordt het filter ontkend. De sleutel moet eindigen op 'NIET'. "kleur NIET" met de waarde "rood" komt bijvoorbeeld overeen met documenten zoals where waarin de kleur niet rood is. {"id NOT": 2} {“color NOT”: “red”}
< Controleert of de veldwaarde kleiner is dan de filterwaarde. De sleutel moet eindigen op ' <'. 'Prijs <' met waarde 200 komt bijvoorbeeld overeen met documenten where waarbij de prijs kleiner dan 200 is. {"id <": 200}
<= Hiermee wordt gecontroleerd of de veldwaarde kleiner is dan of gelijk is aan de filterwaarde. De sleutel moet eindigen op "<=". Bijvoorbeeld: 'price <=' met waarde 200 komt overeen met documenten where de prijs kleiner is dan of gelijk is aan 200. {"id <=": 200}
> Controleert of de veldwaarde groter is dan de filterwaarde. De sleutel moet eindigen op ' >'. Bijvoorbeeld, 'prijs >' met waarde 200 komt overeen met documenten where waarin de prijs hoger is dan 200. {"id >": 200}
>= Hiermee wordt gecontroleerd of de veldwaarde groter is dan of gelijk is aan de filterwaarde. De sleutel moet eindigen op ">=". 'price >=' met waarde 200 komt bijvoorbeeld overeen met documenten where de prijs groter is dan of gelijk is aan 200. {"id >=": 200}
OR Controleert of de veldwaarde overeenkomt met een van de filter-values. De sleutel moet OR bevatten om meerdere subsleutels te scheiden. color1 OR color2 met waarde ["red", "blue"] bijvoorbeeld overeenkomt met documenten wherecolor1 is red of color2 is blue. {"color1 OR color2": ["red", "blue"]}
LIKE Komt overeen met gedeeltelijke tekenreeksen. {"column LIKE": "hello"}
Er is geen filteroperator opgegeven Filter controleert op een exacte overeenkomst. Als er meerdere values zijn opgegeven, komt deze overeen met een van de values. {"id": 200} {"id": [200, 300]}

Zie de volgende codevoorbeelden:

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

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

voorbeeldnotitieblokken

De voorbeelden in deze sectie laten het gebruik van de Python SDK voor vectorzoekopdrachten zien.

Voorbeelden van LangChain

Zie hoe je LangChain kunt gebruiken met Mosaic AI Vector Search voor het integreren van Mosaic AI Vector Search met LangChain-pakketten.

In het volgende notebook ziet u hoe u zoekresultaten voor overeenkomsten converteert naar LangChain-documenten.

Vector zoeken met het Python SDK-notebook

Get notebook

Notebook-voorbeelden voor het aanroepen van een embeddingsmodel

In de volgende notebooks wordt gedemonstreerd hoe u een Mosaic AI Model Serving-eindpunt configureert voor het genereren van embedingen.

Een OpenAI-insluitingsmodel aanroepen met behulp van een Mozaïek AI Model Serving-notebook

Get notebook

GTE-embedding-model aanroepen met behulp van een Mosaic AI Model Serving-notebook

Get notitieboek

Een OSS-notebook voor het insluiten van modellen registreren en leveren

Get notebook