Freigeben über

Erstellen und Abfragen eines Vektorsuchindex

  • Artikel

In diesem Artikel erfahren Sie, wie Sie einen Vektorsuchindex mithilfe der Databricks-Vektorsuche erstellen und abfragen.

Sie können Vektorsuchkomponenten wie einen Vektorsuchendpunkt und Vektorsuchindizes erstellen und verwalten, indem Sie die Benutzeroberfläche, das Python SDK oder die REST-API verwenden.

Anforderungen

  • Arbeitsbereich mit Unity Catalog-Unterstützung
  • Aktiviertes serverloses Computing
  • Die Quelltabelle muss „Datenfeed ändern“ aktiviert haben.
  • Zum Erstellen eines Indexes müssen Sie über CREATE TABLE-Berechtigungen für Katalogschemas verfügen, um Indizes zu erstellen. Um einen Index abzufragen, der einem anderen Benutzer gehört, müssen Sie über zusätzliche Berechtigungen verfügen. Weitere Informationen unter Abfrage eines Vektorsuchendpunkts.
  • Wenn Sie persönliche Zugriffstoken verwenden möchten (nicht für Produktionsworkloads empfohlen), vergewissern Sie sich, dass persönliche Zugriffstokenaktiviert sind. Um stattdessen ein Dienstprinzipaltoken zu verwenden, übergeben Sie es explizit mithilfe von SDK- oder API-Aufrufen.

Um das SDK zu verwenden, müssen Sie es in Ihrem Notebook installieren. Verwenden Sie den folgenden Code:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Erstellen eines Vektorsuchendpunkts

Sie können einen Vektorsuchendpunkt mithilfe der Databricks-Benutzeroberfläche, des Python SDK oder der API erstellen.

Erstellen eines Vektorsuchendpunkts mithilfe der Benutzeroberfläche

Führen Sie die folgenden Schritte aus, um einen Vektorsuchendpunkt mithilfe der Benutzeroberfläche zu erstellen.

  1. Klicken Sie in der linken Randleiste auf Compute.

  2. Klicken Sie auf die Registerkarte Vektorsuche und dann auf Erstellen.

    Erstellen eines Endpunktformulars

  3. Das Formular zum Erstellen von Endpunkten wird geöffnet. Geben Sie einen Namen für diesen Endpunkt ein.

  4. Klicken Sie auf Confirm (Bestätigen).

Erstellen eines Vektorsuchendpunkts mit dem Python SDK

Im folgenden Beispiel wird die SDK-Funktion create_endpoint() verwendet, um einen Vektorsuchendpunkt zu erstellen.

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

Erstellen eines Vektorsuchendpunkts mithilfe der REST-API

Weitere Informationen unter POST /api/2.0/vector-search/endpoints.

(Optional) Erstellen und Konfigurieren eines Endpunkts für das Einbettungsmodell

Wenn Sie sich dafür entscheiden, dass Databricks die Einbettungen berechnet, müssen Sie ein Modell einrichten, das dem Einbettungsmodell dient. Anweisungen finden Sie unter Erstellen von Foundation Model-Bereitstellungsendpunkten. Beispiele für Notebooks finden Sie unter Notebook-Beispiele zum Aufrufen eines Einbettungsmodells.

Wenn Sie einen Einbettungsendpunkt konfigurieren, empfiehlt Databricks, die Standardauswahl von Auf Null skalieren zu entfernen. Die Aufwärmphase von Bereitstellungsendpunkten kann einige Minuten dauern, und die anfängliche Abfrage eines Index mit einem herunterskalierten Endpunkt kann zu einem Timeout führen.

Hinweis

Bei der Initialisierung des Vektorsuchindex kann ein Timeout auftreten, wenn der Einbettungsendpunkt nicht ordnungsgemäß für das Dataset konfiguriert wird. Für kleine Datasets und Tests sollten Sie nur CPU-Endpunkte verwenden. Verwenden Sie für größere Datasets einen GPU-Endpunkt, um eine optimale Leistung zu erzielen.

Erstellen eines Vektorsuchindex

Sie können einen Vektorsuchindex mithilfe der Benutzeroberfläche, des Python SDK oder der REST-API erstellen. Die Benutzeroberfläche ist der einfachste Ansatz.

Es gibt zwei Arten von Indizes:

  • Der Delta-Synchronisierungsindex wird automatisch mit einer Delta-Quelltabelle synchronisiert und inkrementell aktualisiert, wenn sich die zugrunde liegenden Daten in der Delta-Tabelle ändern.
  • Der Direct Vector Access-Index unterstützt das direkte Lesen und Schreiben von Vektoren und Metadaten. Der Benutzer ist für die Aktualisierung dieser Tabelle mit der REST-API oder dem Python SDK verantwortlich. Dieser Indextyp kann nicht mithilfe der Benutzeroberfläche erstellt werden. Sie müssen die REST-API oder das SDK verwenden.

Erstellen eines Indexes mithilfe der Benutzeroberfläche

  1. Klicken Sie in der linken Randleiste auf Katalog, um die Benutzeroberfläche des Katalog-Explorers zu öffnen.

  2. Navigieren Sie zu der Delta-Tabelle, die Sie verwenden möchten.

  3. Wählen Sie oben rechts die Schaltfläche Erstellen, und wählen Sie im Dropdownmenü den Vektorsuchindex aus.

    Schaltfläche zum Erstellen eines Index

  4. Verwenden Sie die Selektoren im Dialogfeld, um den Index zu konfigurieren.

    Dialogfeld zum Erstellen eines Index

    Name: Name, der für die Onlinetabelle in Unity Catalog verwendet werden soll Der Name erfordert einen Namespace mit drei Ebenen, <catalog>.<schema>.<name>. Es sind nur alphanumerische Zeichen und Unterstriche zulässig.

    Primärschlüssel: Spalte, die als Primärschlüssel verwendet werden soll.

    Endpunkt: Wählen Sie das Modell aus, das den Endpunkt bedient, den Sie verwenden möchten.

    Einbettungsquelle: Geben Sie an, ob Databricks Einbettungen für eine Textspalte in der Delta-Tabelle (Compute Embeddings) berechnen soll oder ob Ihre Delta-Tabelle vorkompilierte Einbettungen enthält (Vorhandene Einbettungsspalte verwenden).

    • Wenn Sie Einbettungen berechnen ausgewählt haben, wählen Sie die Spalte aus, für die Sie Einbettungen berechnen möchten, und den Endpunkt, der das Einbettungsmodell bedient. Nur Textspalten werden unterstützt.
    • Wenn Sie Vorhandene Einbettungsspalte verwenden ausgewählt haben, wählen Sie die Spalte aus, welche die vorkompilierten Einbettungen und die Dimension für das Einbetten enthält. Das Format der vorkompilierten Einbettungsspalte sollte array[float] sein.

    Berechnete Einbettungen synchronisieren: Aktivieren Sie diese Einstellung, um die generierten Einbettungen in einer Unity Catalog-Tabelle zu speichern. Weitere Informationen finden Sie unter Speichern der generierten Einbettungstabelle.

    Synchronisierungsmodus: Fortlaufend hält den Index mit wenigen Sekunden Latenz synchronisiert. Er ist jedoch mit höheren Kosten verbunden, da ein Computecluster bereitgestellt wird, um die Streamingpipeline für fortlaufende Synchronisierung auszuführen. Ausgelöst ist kostengünstiger, muss jedoch manuell über die API gestartet werden. Sowohl bei Fortlaufend als auch bei Ausgelöst ist das Update inkrementell: Es werden nur Daten verarbeitet, die seit der letzten Synchronisierung geändert wurden.

  5. Wenn Sie die Konfiguration des Index abgeschlossen haben, klicken Sie auf Erstellen.

Erstellen eines Indexes mit dem Python SDK

In dem folgenden Beispiel wird ein Delta-Synchronisierungsindex mit von Databricks berechneten Einbettungen erstellt.

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

Im folgenden Beispiel wird ein Direct Vector Access-Index erstellt.


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

Erstellen eines Indexes mithilfe der REST-API

Weitere Informationen unter POST /api/2.0/vector-search/indexes.

Speichern der generierten Einbettungstabelle

Wenn Databricks die Einbettungen generiert, können Sie die generierten Einbettungen in einer Tabelle im Unity Catalog speichern. Diese Tabelle wird im gleichen Schema wie der Vektorindex erstellt und auf der Vektorindexseite verknüpft.

Der Name der Tabelle ist der Name des Vektorsuchindex, an den _writeback_table angefügt wird. Der Name kann nicht bearbeitet werden.

Sie können auf die Tabelle wie jede andere Tabelle im Unity Catalog zugreifen und diese abfragen. Sie sollten die Tabelle jedoch nicht löschen oder ändern, da sie nicht manuell aktualisiert werden soll. Die Tabelle wird automatisch gelöscht, wenn der Index gelöscht wird.

Aktualisieren eines Vektorsuchindex

Aktualisieren eines Delta-Synchronisierungsindex

Indizes, die im Synchronisierungsmodus Fortlaufend erstellt wurden, werden automatisch aktualisiert, wenn sich die Quelldeltatabelle ändert. Wenn Sie den Synchronisierungsmodus Triggeredverwenden, können Sie das Python SDK oder die REST-API verwenden, um die Synchronisierung zu starten.

Python SDK

index.sync()

REST-API

Weitere Informationen unter REST-API (POST /api/2.0/vector-search/indexes/{index_name}/sync).

Aktualisieren eines Direct Vector Access-Index

Sie können das Python SDK oder die REST-API verwenden, um Daten aus einem Direct Vector Access-Index einzufügen, zu aktualisieren oder zu löschen.

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

Weitere Informationen unter REST-API (POST /api/2.0/vector-search/indexes).

Abfragen eines Vektorsuchendpunkts

Sie können den Vektorsuchendpunkt nur mit dem Python SDK oder der REST-API abfragen.

Hinweis

Wenn der Benutzer, der den Endpunkt abfragt, nicht der Besitzer des Vektorsuchindex ist, muss der Benutzer über die folgenden UC-Berechtigungen verfügen:

  • USE CATALOG für den Katalog, der den Vektorsuchindex enthält.
  • USE SCHEMA für das Schema, das den Vektorsuchindex enthält.
  • SELECT für den Vektorsuchindex.

Python SDK

results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

results

REST-API

Weitere Informationen unter POST /api/2.0/vector-search/indexes/{index_name}/query.

Verwenden von Filtern für Abfragen

Eine Abfrage kann Filter basierend auf einer beliebigen Spalte in der Delta-Tabelle definieren. similarity_search gibt nur Zeilen zurück, die den angegebenen Filtern entsprechen. Folgende Filter werden unterstützt:

Filteroperator Behavior Beispiele
NOT Negiert den Filter. Der Schlüssel muss mit „NOT“ enden. Beispielsweise entspricht „Farbe NOT“ mit dem Wert „rot“ Dokumenten, bei denen die Farbe nicht Rot ist. {"id NOT": 2} {“color NOT”: “red”}
< Überprüft, ob der Feldwert kleiner als der Filterwert ist. Der Schlüssel muss mit „<“ enden. Beispielsweise entspricht „Preis <“ mit dem Wert „100“ Dokumenten, bei denen der Preis kleiner als 100 ist. {"id <": 200}
<= Überprüft, ob der Feldwert kleiner als oder gleich dem Filterwert ist. Der Schlüssel muss mit „<=“ enden. Beispielsweise entspricht „Preis <=“ mit dem Wert „100“ Dokumenten, bei denen der Preis kleiner oder gleich 100 ist. {"id <=": 200}
> Überprüft, ob der Feldwert größer als der Filterwert ist. Der Schlüssel muss mit „>“ enden. Beispielsweise entspricht „Preis >“ mit dem Wert „100“ Dokumenten, bei denen der Preis größer als 100 ist. {"id >": 200}
>= Überprüft, ob der Feldwert größer als oder gleich dem Filterwert ist. Der Schlüssel muss mit „>=“ enden. Beispielsweise entspricht „Preis >=“ mit dem Wert „100“ Dokumenten, bei denen der Preis größer oder gleich 100 ist. {"id >=": 200}
OR Überprüft, ob der Feldwert einem der Filterwerte entspricht. Der Schlüssel muss „OR“ enthalten, um mehrere Unterschlüssel zu trennen. Beispielsweise entspricht „color1 OR color2“ mit dem Wert „["red", "blue"]“ Dokumenten, bei denen entweder color1red oder color2blue ist. {"color1 OR color2": ["red", "blue"]}
LIKE Gleicht Teilzeichenfolgen ab. {"column LIKE": "hello"}
Kein Filteroperator angegeben Der Filter prüft auf eine genaue Übereinstimmung. Wenn mehrere Werte angegeben werden, wird eine Übereinstimmung mit einem der Werte gesucht. {"id": 200} {"id": [200, 300]}

Sehen Sie sich dazu den folgenden Beispielcode an:

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

Weitere Informationen unter POST /api/2.0/vector-search/indexes/{index_name}/query.

Beispielnotebooks

Die Beispiele in diesem Abschnitt veranschaulichen die Verwendung des Vector Search Python SDK.

LangChain-Beispiele

Siehe Verwenden von LangChain mit Databricks Vektorsuche für die Verwendung der Databricks-Vektorsuche wie in die Integration in LangChain-Pakete.

Das folgende Notebook zeigt, wie Sie Ihre Ähnlichkeitssuchergebnisse in LangChain-Dokumente konvertieren.

Vektorsuche mit dem Python SDK-Notebook

Notebook abrufen

Notebookbeispiele zum Aufrufen eines Einbettungsmodells

Die folgenden Notebooks veranschaulichen, wie Sie einen Databricks-Modellbereitstellungsendpunkt für die Generierung von Einbettungen konfigurieren.

Aufrufen eines OpenAI-Einbettungsmodells mithilfe des Notebooks für die Databricks-Modellbereitstellung

Notebook abrufen

Aufrufen eines BGE-Einbettungsmodells mithilfe des Notebooks für die Databricks-Modellbereitstellung

Notebook abrufen

Registrieren und Bereitstellen eines Notebooks für OSS-Einbettungsmodelle

Notebook abrufen