Udostępnij za pośrednictwem


Jak utworzyć indeks wyszukiwania wektorowego i wykonywać względem tego zapytania

W tym artykule opisano sposób tworzenia i wykonywania zapytań względem indeksu wyszukiwania wektorów wektorów mozaiki.

Możesz tworzyć składniki wyszukiwania wektorowego i zarządzać nimi, takie jak punkt końcowy wyszukiwania wektorów i indeksy wyszukiwania wektorów, przy użyciu interfejsu użytkownika, zestawu SDK języka Python lub interfejsu API REST.

Wymagania

Aby użyć zestawu SDK, należy zainstalować go w notesie. Użyj następującego kodu:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Tworzenie punktu końcowego wyszukiwania wektorów

Punkt końcowy wyszukiwania wektorów można utworzyć przy użyciu interfejsu użytkownika usługi Databricks, zestawu SDK języka Python lub interfejsu API.

Tworzenie punktu końcowego wyszukiwania wektorów przy użyciu interfejsu użytkownika

Wykonaj następujące kroki, aby utworzyć punkt końcowy wyszukiwania wektorów przy użyciu interfejsu użytkownika.

  1. Na lewym pasku bocznym kliknij pozycję Obliczenia.

  2. Kliknij kartę Wyszukiwanie wektorowe i kliknij przycisk Utwórz.

    Tworzenie formularza punktu końcowego

  3. Zostanie otwarty formularz Tworzenie punktu końcowego. Wprowadź nazwę tego punktu końcowego.

  4. Kliknij przycisk Potwierdź.

Tworzenie punktu końcowego wyszukiwania wektorów przy użyciu zestawu SDK języka Python

W poniższym przykładzie użyto funkcji zestawu SDK create_endpoint() do utworzenia punktu końcowego wyszukiwania wektorów.

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

Tworzenie punktu końcowego wyszukiwania wektorów przy użyciu interfejsu API REST

Zobacz dokumentację referencyjną interfejsu API REST: POST /api/2.0/vector-search/endpoints.

(Opcjonalnie) Tworzenie i konfigurowanie punktu końcowego w celu obsługi modelu osadzania

Jeśli zdecydujesz się, aby usługa Databricks obliczała osadzanie, możesz użyć wstępnie skonfigurowanego punktu końcowego interfejsów API modelu foundation lub utworzyć model obsługujący punkt końcowy, aby obsłużyć wybrany model osadzania. Aby uzyskać instrukcje, zobacz Pay-per-token Foundation Model APIs or Create generative AI model obsługujący punkty końcowe . Przykładowe notesy można znaleźć w temacie Przykłady notesów dotyczące wywoływania modelu osadzania.

Podczas konfigurowania punktu końcowego osadzania usługa Databricks zaleca usunięcie domyślnego wyboru opcji Skalowanie do zera. Obsługa punktów końcowych może potrwać kilka minut, a początkowe zapytanie dotyczące indeksu ze skalowanym w dół punktem końcowym może spowodować przekroczenie limitu czasu.

Uwaga

Inicjowanie indeksu wyszukiwania wektorowego może upłynął limit czasu, jeśli punkt końcowy osadzania nie został odpowiednio skonfigurowany dla zestawu danych. W przypadku małych zestawów danych i testów należy używać tylko punktów końcowych procesora CPU. W przypadku większych zestawów danych użyj punktu końcowego procesora GPU w celu uzyskania optymalnej wydajności.

Tworzenie indeksu wyszukiwania wektorów

Indeks wyszukiwania wektorowego można utworzyć przy użyciu interfejsu użytkownika, zestawu SDK języka Python lub interfejsu API REST. Interfejs użytkownika jest najprostszym podejściem.

Istnieją dwa typy indeksów:

  • Indeks synchronizacji różnicowej automatycznie synchronizuje się ze źródłową tabelą różnicową, automatycznie i przyrostowo aktualizując indeks w miarę zmian danych bazowych w tabeli delty.
  • Indeks bezpośredniego dostępu wektorowego obsługuje bezpośredni odczyt i zapis wektorów i metadanych. Użytkownik jest odpowiedzialny za zaktualizowanie tej tabeli przy użyciu interfejsu API REST lub zestawu SDK języka Python. Nie można utworzyć tego typu indeksu przy użyciu interfejsu użytkownika. Musisz użyć interfejsu API REST lub zestawu SDK.

Tworzenie indeksu przy użyciu interfejsu użytkownika

  1. Na pasku bocznym po lewej stronie kliknij pozycję Wykaz , aby otworzyć interfejs użytkownika Eksploratora wykazu.

  2. Przejdź do tabeli delty, której chcesz użyć.

  3. Kliknij przycisk Utwórz w prawym górnym rogu i wybierz pozycję Indeks wyszukiwania wektorów z menu rozwijanego.

    Przycisk Utwórz indeks

  4. Użyj selektorów w oknie dialogowym, aby skonfigurować indeks.

    Okno dialogowe tworzenia indeksu

    Nazwa: nazwa do użycia dla tabeli online w wykazie aparatu Unity. Nazwa wymaga trzy-poziomowej przestrzeni nazw. <catalog>.<schema>.<name> Dozwolone są tylko znaki alfanumeryczne i podkreślenia.

    Klucz podstawowy: kolumna do użycia jako klucz podstawowy.

    Punkt końcowy: wybierz punkt końcowy wyszukiwania wektorów, którego chcesz użyć.

    Kolumny do synchronizacji: wybierz kolumny do synchronizacji z indeksem wektorowym. Jeśli to pole pozostanie puste, wszystkie kolumny z tabeli źródłowej zostaną zsynchronizowane z indeksem. Kolumna klucza podstawowego i osadzanie kolumny źródłowej lub wektor osadzania są zawsze synchronizowane.

    Źródło osadzania: określ, czy chcesz, aby usługa Databricks obliczała osadzanie dla kolumny tekstowej w tabeli delty (osadzanie obliczeniowe) lub jeśli tabela delta zawiera wstępnie skompilowane osadzanie (użyj istniejącej kolumny osadzania).

    • W przypadku wybrania opcji Osadzanie obliczeniowe wybierz kolumnę, dla której mają zostać osadzone elementy, oraz punkt końcowy obsługujący model osadzania. Obsługiwane są tylko kolumny tekstowe.
    • W przypadku wybrania opcji Użyj istniejącej kolumny osadzania wybierz kolumnę zawierającą wstępnie skompilowane osadzanie i wymiar osadzania. Format wstępnie skompilowanej kolumny osadzania powinien mieć wartość array[float].

    Synchronizowanie obliczonych osadzania: przełącz to ustawienie, aby zapisać wygenerowane osadzanie w tabeli wykazu aparatu Unity. Aby uzyskać więcej informacji, zobacz Zapisywanie wygenerowanej tabeli osadzania.

    Tryb synchronizacji: ciągły zachowuje indeks w synchronizacji z sekundami opóźnienia. Jednak wiąże się z nim wyższy koszt, ponieważ klaster obliczeniowy jest aprowizowany w celu uruchomienia potoku przesyłania strumieniowego ciągłej synchronizacji. Zarówno w przypadku operacji ciągłych, jak i wyzwalanych aktualizacja jest przyrostowa — tylko dane, które uległy zmianie od ostatniej synchronizacji, są przetwarzane.

    W trybie synchronizacji wyzwolonej użyjesz zestawu SDK języka Python lub interfejsu API REST, aby rozpocząć synchronizację. Zobacz Aktualizowanie indeksu synchronizacji różnicowej.

  5. Po zakończeniu konfigurowania indeksu kliknij przycisk Utwórz.

Tworzenie indeksu przy użyciu zestawu SDK języka Python

W poniższym przykładzie tworzony jest indeks synchronizacji różnicowej z osadzanymi elementami obliczonymi przez usługę 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"
)

W poniższym przykładzie tworzony jest indeks usługi Delta Sync z własnymi osadzaniami. W tym przykładzie pokazano również użycie opcjonalnego parametru columns_to_sync w celu wybrania tylko podzestawu kolumn do użycia w indeksie.

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

Domyślnie wszystkie kolumny z tabeli źródłowej są synchronizowane z indeksem. Aby zsynchronizować tylko podzbiór kolumn, użyj polecenia columns_to_sync. Klucz podstawowy i kolumny osadzania są zawsze uwzględniane w indeksie.

Aby zsynchronizować tylko klucz podstawowy i kolumnę osadzania, należy określić je w columns_to_sync następujący sposób:

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

Aby zsynchronizować dodatkowe kolumny, określ je w sposób pokazany. Nie trzeba dołączać klucza podstawowego i kolumny osadzania, ponieważ są one zawsze synchronizowane.

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

Poniższy przykład tworzy indeks dostępu bezpośredniego wektora.


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

Tworzenie indeksu przy użyciu interfejsu API REST

Zobacz dokumentację referencyjną interfejsu API REST: POST /api/2.0/vector-search/indexes.

Zapisywanie wygenerowanej tabeli osadzania

Jeśli usługa Databricks generuje osadzanie, możesz zapisać wygenerowane osadzanie w tabeli w wykazie aparatu Unity. Ta tabela jest tworzona w tym samym schemacie co indeks wektorowy i jest połączona ze strony indeksu wektorowego.

Nazwa tabeli to nazwa indeksu wyszukiwania wektorów, dołączana przez _writeback_tableelement . Nazwa nie jest edytowalna.

Możesz uzyskiwać dostęp do tabeli i wykonywać względem jej zapytania, podobnie jak każda inna tabela w wykazie aparatu Unity. Nie należy jednak usuwać ani modyfikować tabeli, ponieważ nie jest ona przeznaczona do ręcznej aktualizacji. Tabela zostanie usunięta automatycznie, jeśli indeks zostanie usunięty.

Aktualizowanie indeksu wyszukiwania wektorowego

Aktualizowanie indeksu synchronizacji różnicowej

Indeksy utworzone w trybie ciągłej synchronizacji są automatycznie aktualizowane po zmianie źródłowej tabeli delty. Jeśli używasz trybu synchronizacji wyzwolonej , użyj zestawu SDK języka Python lub interfejsu API REST, aby rozpocząć synchronizację.

Zestaw SDK dla języka Python

index.sync()

Interfejs API REST

Zobacz dokumentację referencyjną interfejsu API REST: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Aktualizowanie indeksu dostępu wektorów bezpośrednich

Zestawu SDK języka Python lub interfejsu API REST można użyć do wstawiania, aktualizowania lub usuwania danych z indeksu dostępu wektorowego bezpośredniego.

Zestaw SDK dla języka Python

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

Interfejs API REST

Zobacz dokumentację referencyjną interfejsu API REST: POST /api/2.0/vector-search/indexes.

Poniższy przykład kodu ilustruje sposób aktualizowania indeksu przy użyciu osobistego tokenu dostępu (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": [...]}'

Poniższy przykład kodu ilustruje sposób aktualizowania indeksu przy użyciu jednostki usługi.

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

Wykonywanie zapytań względem punktu końcowego wyszukiwania wektorów

Punkt końcowy wyszukiwania wektorów można wykonywać tylko za pomocą zestawu SDK języka Python, interfejsu API REST lub funkcji SQL vector_search() AI.

Uwaga

Jeśli użytkownik wykonujący zapytanie dotyczące punktu końcowego nie jest właścicielem indeksu wyszukiwania wektorowego, użytkownik musi mieć następujące uprawnienia UC:

  • UŻYJ KATALOGU w wykazie zawierającym indeks wyszukiwania wektorów.
  • UŻYJ schematu w schemacie zawierającym indeks wyszukiwania wektorów.
  • WYBIERZ w indeksie wyszukiwania wektorowego.

Aby przeprowadzić wyszukiwanie hybrydowego podobieństwa słów kluczowych, ustaw parametr query_type na hybridwartość . Wartość domyślna to ann (przybliżony najbliższy sąsiad).

Zestaw SDK dla języka Python

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

Interfejs API REST

Zobacz dokumentację referencyjną interfejsu API REST: POST /api/2.0/vector-search/indexes/{index_name}/query.

Poniższy przykład kodu ilustruje sposób wykonywania zapytań względem indeksu przy użyciu osobistego tokenu dostępu (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}'

Poniższy przykład kodu ilustruje sposób wykonywania zapytań względem indeksu przy użyciu jednostki usługi.

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

Ważne

Funkcja vector_search() sztucznej inteligencji jest dostępna w publicznej wersji zapoznawczej.

Aby użyć tej funkcji sztucznej inteligencji, zobacz vector_search funkcja.

Używanie filtrów w zapytaniach

Zapytanie może definiować filtry na podstawie dowolnej kolumny w tabeli delty. similarity_search Zwraca tylko wiersze zgodne z określonymi filtrami. Obsługiwane są następujące filtry:

Operator filtru Zachowanie Przykłady
NOT Neguje filtr. Klucz musi kończyć się ciągiem "NOT". Na przykład "color NOT" z wartością "red" pasuje do dokumentów, w których kolor nie jest czerwony. {"id NOT": 2} {“color NOT”: “red”}
< Sprawdza, czy wartość pola jest mniejsza niż wartość filtru. Klucz musi kończyć się ciągiem " <". Na przykład "price <" z wartością 200 pasuje do dokumentów, w których cena jest mniejsza niż 200. {"id <": 200}
<= Sprawdza, czy wartość pola jest mniejsza lub równa wartości filtru. Klucz musi kończyć się ciągiem " <=". Na przykład "price <=" z wartością 200 pasuje do dokumentów, w których cena jest mniejsza lub równa 200. {"id <=": 200}
> Sprawdza, czy wartość pola jest większa niż wartość filtru. Klucz musi kończyć się ciągiem " >". Na przykład "price >" z wartością 200 pasuje do dokumentów, w których cena jest większa niż 200. {"id >": 200}
>= Sprawdza, czy wartość pola jest większa lub równa wartości filtru. Klucz musi kończyć się ciągiem " >=". Na przykład "price >=" z wartością 200 pasuje do dokumentów, w których cena jest większa lub równa 200. {"id >=": 200}
OR Sprawdza, czy wartość pola jest zgodna z dowolną wartością filtru. Klucz musi zawierać OR wiele podklucza. Na przykład wartość jest zgodna z dokumentami, color1 OR color2 w których color1 wartość to red lub color2 jest blue.["red", "blue"] {"color1 OR color2": ["red", "blue"]}
LIKE Pasuje do ciągów częściowych. {"column LIKE": "hello"}
Nie określono operatora filtru Sprawdzanie filtru pod kątem dokładnego dopasowania. Jeśli określono wiele wartości, pasuje do dowolnej z wartości. {"id": 200} {"id": [200, 300]}

Zobacz następujące przykłady kodu:

Zestaw SDK dla języka Python

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

Interfejs API REST

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

Przykładowe notesy

Przykłady w tej sekcji przedstawiają użycie zestawu SDK języka Python wyszukiwania wektorowego.

Przykłady langchain

Zobacz How to use LangChain with Mosaic AI Vector Search for using Mosaic AI Vector Search as in integration with LangChain packages (Jak używać biblioteki LangChain z wyszukiwaniem wektorów mozaiki sztucznej inteligencji).

W poniższym notesie pokazano, jak przekonwertować wyniki wyszukiwania podobieństwa na dokumenty LangChain.

Wyszukiwanie wektorowe za pomocą notesu zestawu SDK języka Python

Pobierz notes

Przykłady notesów do wywoływania modelu osadzania

W poniższych notesach pokazano, jak skonfigurować punkt końcowy obsługi modelu sztucznej inteligencji mozaiki na potrzeby generowania osadzania.

Wywoływanie modelu osadzania OpenAI przy użyciu notesu obsługi modelu mozaiki sztucznej inteligencji

Pobierz notes

Wywoływanie modelu osadzania GTE przy użyciu notesu usługi Mosaic AI Model Serving

Pobierz notes

Rejestrowanie i obsługa notesu modelu osadzania systemu operacyjnego

Pobierz notes