Udostępnij za pośrednictwem

Korzystanie z łącznika Qdrant (wersja zapoznawcza)

Ostrzeżenie

Funkcjonalność sklepu wektorów Qdrant jest dostępna w wersji zapoznawczej, a ulepszenia, które wymagają wprowadzania zmian mogących powodować niezgodność, mogą jeszcze wystąpić w ograniczonych okolicznościach przed wydaniem.

Ostrzeżenie

Funkcjonalność Semantycznego Magazynu Wektorów Kernela jest dostępna w wersji zapoznawczej, a w ograniczonych przypadkach przed wydaniem mogą pojawić się zmiany wymagające istotnych modyfikacji.

Ostrzeżenie

Funkcjonalność Semantycznego Magazynu Wektorów Kernela jest dostępna w wersji zapoznawczej, a w ograniczonych przypadkach przed wydaniem mogą pojawić się zmiany wymagające istotnych modyfikacji.

Omówienie

Łącznik magazynu wektorów Qdrant może służyć do uzyskiwania dostępu do danych w usłudze Qdrant i zarządzania nimi. Łącznik ma następujące cechy.

Obszar funkcji Wsparcie
Mapowania kolekcji Kolekcja Qdrant z indeksami ładunków dla pól danych z możliwością filtrowania
Obsługiwane typy właściwości kluczy
  • ulong
  • Identyfikator GUID
Obsługiwane typy właściwości danych
  • sznurek
  • int (integer)
  • długi
  • podwójny
  • liczba zmiennoprzecinkowa
  • Bool
  • i elementy wyliczalne każdego z tych typów
Obsługiwane typy właściwości wektorów
  • ReadOnlyMemory<float>
  • Osadzanie<float>
  • float[]
Obsługiwane typy indeksów Hnsw
Obsługiwane funkcje odległości
  • Podobieństwo cosinusowe
  • DotProductSimilarity
  • EuclideanDistance
  • ManhattanDistance
Obsługiwane klauzule filtru
  • AnyTagEqualTo
  • EqualTo
Obsługuje wiele wektorów w rekordzie Tak (konfigurowalne)
Czy funkcja IsIndexed jest obsługiwana? Tak
Czy funkcja FullTextIndexed jest obsługiwana? Tak
Czy StorageName jest obsługiwany? Tak
Obsługiwane jest wyszukiwanie hybrydowe? Tak
Obszar funkcji Wsparcie
Mapowania kolekcji Kolekcja Qdrant z indeksami ładunków dla pól danych z możliwością filtrowania
Obsługiwane typy właściwości kluczy
  • ulong
  • Identyfikator GUID
Obsługiwane typy właściwości danych
  • sznurek
  • int (integer)
  • długi
  • podwójny
  • liczba zmiennoprzecinkowa
  • Bool
  • i iterowalne każdego z tych typów
Obsługiwane typy właściwości wektorów
  • lista[float]
Obsługiwane typy indeksów Hnsw
Obsługiwane funkcje odległości
  • Podobieństwo cosinusowe
  • DotProductSimilarity
  • EuclideanDistance
  • ManhattanDistance
Obsługiwane klauzule filtru
  • AnyTagEqualTo
  • EqualTo
Obsługuje wiele wektorów w rekordzie Tak (konfigurowalne)
Czy filtrowanie jest obsługiwane? Tak
Czy jest obsługiwany element IsFullTextSearchable? Tak
Czy StorageName jest obsługiwany? Tak

Niewspierany

Obecnie nie jest obsługiwane.

Wprowadzenie

Dodaj pakiet NuGet łącznika Qdrant Vector Store do swojego projektu.

dotnet add package Microsoft.SemanticKernel.Connectors.Qdrant --prerelease

Można dodać sklep wektorów do kontenera iniekcji zależności dostępnego w KernelBuilder lub do IServiceCollection przy użyciu metod rozszerzeń udostępnianych przez jądro semantyczne.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder();
kernelBuilder.Services
    .AddQdrantVectorStore("localhost");

using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddQdrantVectorStore("localhost");

Dostępne są również metody rozszerzeń, które nie przyjmują parametrów. Aby to zrobić, należy osobno zarejestrować wystąpienie klasy Qdrant.Client.QdrantClient w kontenerze wstrzykiwania zależności.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Qdrant.Client;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<QdrantClient>(sp => new QdrantClient("localhost"));
kernelBuilder.Services.AddQdrantVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Qdrant.Client;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<QdrantClient>(sp => new QdrantClient("localhost"));
builder.Services.AddQdrantVectorStore();

Można bezpośrednio utworzyć instancję magazynu Qdrant Vector Store.

using Microsoft.SemanticKernel.Connectors.Qdrant;
using Qdrant.Client;

var vectorStore = new QdrantVectorStore(new QdrantClient("localhost"), ownsClient: true);

Istnieje możliwość utworzenia bezpośredniego odwołania do nazwanej kolekcji.

using Microsoft.SemanticKernel.Connectors.Qdrant;
using Qdrant.Client;

var collection = new QdrantCollection<ulong, Hotel>(
    new QdrantClient("localhost"),
    "skhotels",
    ownsClient: true);

Mapowanie danych

Łącznik Qdrant udostępnia domyślnego mapera przy mapowaniu danych z modelu danych do magazynu. Qdrant wymaga mapowania właściwości do grup id, ładunku i wektorów. Domyślny maper używa adnotacji modelu lub definicji rekordu, aby określić typ każdej właściwości i wykonać to mapowanie.

  • Właściwość modelu danych oznaczona adnotacją jako klucz zostanie przypisana do identyfikatora punktu Qdrant.
  • Właściwości modelu danych oznaczone jako dane zostaną zamapowane na obiekt ładunku punktu Qdrant.
  • Właściwości modelu danych oznaczone jako wektory zostaną zamapowane na obiekt wektora punktu Qdrant.

Nadpisanie nazwy właściwości

Dla właściwości danych i właściwości wektorów (jeśli używasz trybu nazwanych wektorów) można podać nazwy pól przesłaniających do użycia w pamięci, która różni się od nazw właściwości w modelu danych. Nie jest to obsługiwane w przypadku kluczy, ponieważ klucz ma stałą nazwę w języku Qdrant. Nie jest to również obsługiwane dla wektora w trybie pojedynczego wektora bez nazwy, ponieważ wektor jest przechowywany pod stałą nazwą.

Zastąpienie nazwy właściwości jest realizowane poprzez ustawienie opcji StorageName za pomocą atrybutów modelu danych lub definicji rekordu.

Oto przykład modelu danych z StorageName ustawionym na jego atrybuty i sposób, w jaki będzie on reprezentowany w języku Qdrant.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public ulong HotelId { get; set; }

    [VectorStoreData(IsIndexed = true, StorageName = "hotel_name")]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true, StorageName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreVector(4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw, StorageName = "hotel_description_embedding")]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": 1,
    "payload": { "hotel_name": "Hotel Happy", "hotel_description": "A place where everyone can be happy." },
    "vector": {
        "hotel_description_embedding": [0.9, 0.1, 0.1, 0.1],
    }
}

Wprowadzenie

Zainstaluj jądro semantyczne z dodatkami qdrant, które obejmują klienta qdrant.

pip install semantic-kernel[qdrant]

Następnie można utworzyć instancję magazynu wektorów, używając klasy QdrantStore, co spowoduje utworzenie AsyncQdrantClient, który korzysta ze zmiennych środowiskowych QDRANT_URL, QDRANT_API_KEY, QDRANT_HOST, QDRANT_PORT, QDRANT_GRPC_PORT, QDRANT_PATH, QDRANT_LOCATION i QDRANT_PREFER_GRPS do połączenia z instancją Qdrant. Te wartości można również dostarczyć bezpośrednio. Jeśli nic nie zostanie dostarczone, powróci do location=:memory:.


from semantic_kernel.connectors.qdrant import QdrantStore

vector_store = QdrantStore()

Możesz również utworzyć magazyn wektorów, używając własnej instancji klienta "qdrant".

from qdrant_client.async_qdrant_client import AsyncQdrantClient
from semantic_kernel.connectors.qdrant import QdrantStore

client = AsyncQdrantClient(host='localhost', port=6333)
vector_store = QdrantStore(client=client)

Możesz również utworzyć kolekcję bezpośrednio.

from semantic_kernel.connectors.qdrant import QdrantCollection

collection = QdrantCollection(collection_name="skhotels", record_type=hotel)

Serializacja

Łącznik Qdrant używa modelu o nazwie PointStruct do odczytywania i zapisywania w repozytorium. Można to zaimportować z from qdrant_client.models import PointStruct. Metody serializacji oczekują jako danych wyjściowych listy obiektów PointStruct, a metoda deserializacji otrzymuje listę tych obiektów.

Istnieją pewne specjalne zagadnienia, które dotyczą nazwanych lub nienazwanych wektorów, zobacz poniżej.

Aby uzyskać więcej informacji na temat tej koncepcji, zobacz dokumentację serializacji.

Tryby wektorów Qdrant

Technologia Qdrant obsługuje dwa tryby przechowywania wektorów, a łącznik Qdrant z domyślnym maperem obsługuje oba tryby. Tryb domyślny to pojedynczy nienazwany wektor.

Jeden nienazwany wektor

W przypadku tej opcji kolekcja może zawierać tylko jeden wektor i będzie nienazwana w modelu przechowywania w Qdrant. Oto przykład sposobu reprezentowania obiektu w funkcji Qdrant w przypadku korzystania z pojedynczego nienazwanego trybu wektorowego :

new Hotel
{
    HotelId = 1,
    HotelName = "Hotel Happy",
    Description = "A place where everyone can be happy.",
    DescriptionEmbedding = new float[4] { 0.9f, 0.1f, 0.1f, 0.1f }
};

{
    "id": 1,
    "payload": { "HotelName": "Hotel Happy", "Description": "A place where everyone can be happy." },
    "vector": [0.9, 0.1, 0.1, 0.1]
}

Tryby wektorów Qdrant

Technologia Qdrant obsługuje dwa tryby przechowywania wektorów, a łącznik Qdrant z domyślnym maperem obsługuje oba tryby. Tryb domyślny to pojedynczy nienazwany wektor.

Jeden nienazwany wektor

W przypadku tej opcji kolekcja może zawierać tylko jeden wektor i będzie nienazwana w modelu przechowywania w Qdrant. Oto przykład sposobu reprezentowania obiektu w funkcji Qdrant w przypadku korzystania z pojedynczego nienazwanego trybu wektorowego :

Hotel(
    hotel_id = 1,
    hotel_name = "Hotel Happy",
    description = "A place where everyone can be happy.",
    description_embedding = [0.9f, 0.1f, 0.1f, 0.1f],
)

from qdrant_client.models import PointStruct

PointStruct(
    id=1,
    payload={ "hotel_name": "Hotel Happy", "description": "A place where everyone can be happy." },
    vector=[0.9, 0.1, 0.1, 0.1],
)

Wektory z nazwami

Jeśli używasz trybu nazwanych wektorów, oznacza to, że każdy punkt w kolekcji może zawierać więcej niż jeden wektor, a każdy z nich będzie nazwany. Oto przykład sposobu, w jaki obiekt jest reprezentowany w funkcji Qdrant podczas korzystania z trybu nazwanych wektorów :

new Hotel
{
    HotelId = 1,
    HotelName = "Hotel Happy",
    Description = "A place where everyone can be happy.",
    HotelNameEmbedding = new float[4] { 0.9f, 0.5f, 0.5f, 0.5f }
    DescriptionEmbedding = new float[4] { 0.9f, 0.1f, 0.1f, 0.1f }
};

{
    "id": 1,
    "payload": { "HotelName": "Hotel Happy", "Description": "A place where everyone can be happy." },
    "vector": {
        "HotelNameEmbedding": [0.9, 0.5, 0.5, 0.5],
        "DescriptionEmbedding": [0.9, 0.1, 0.1, 0.1],
    }
}

Wektory z nazwami

Jeśli używasz trybu nazwanych wektorów, oznacza to, że każdy punkt w kolekcji może zawierać więcej niż jeden wektor, a każdy z nich będzie nazwany. Oto przykład sposobu, w jaki obiekt jest reprezentowany w funkcji Qdrant podczas korzystania z trybu nazwanych wektorów :

Hotel(
    hotel_id = 1,
    hotel_name = "Hotel Happy",
    description = "A place where everyone can be happy.",
    hotel_name_embedding = [0.9f, 0.5f, 0.5f, 0.5f],
    description_embedding = [0.9f, 0.1f, 0.1f, 0.1f],
)

from qdrant_client.models import PointStruct

PointStruct(
    id=1,
    payload={ "hotel_name": "Hotel Happy", "description": "A place where everyone can be happy." },
    vector={
        "hotel_name_embedding": [0.9, 0.5, 0.5, 0.5],
        "description_embedding": [0.9, 0.1, 0.1, 0.1],
    },
)

Aby włączyć tryb nazwanych wektorów, przekaż tę opcję jako ustawienie podczas konstruowania Sklepu Wektorów lub kolekcji. Te odpowiednie opcje można również przekazać do dowolnej z podanych metod rozszerzenia kontenera do iniekcji zależności.

using Microsoft.SemanticKernel.Connectors.Qdrant;
using Qdrant.Client;

var vectorStore = new QdrantVectorStore(
    new QdrantClient("localhost"),
    ownsClient: true,
    new() { HasNamedVectors = true });

var collection = new QdrantCollection<ulong, Hotel>(
    new QdrantClient("localhost"),
    "skhotels",
    ownsClient: true,
    new() { HasNamedVectors = true });

Aby włączyć tryb nazwanych wektorów, przekaż tę opcję jako ustawienie podczas konstruowania Sklepu Wektorów lub kolekcji. Te odpowiednie opcje można również przekazać do dowolnej z podanych metod rozszerzenia kontenera do iniekcji zależności.

W języku Python wartość domyślna parametru named_vectors to True, ale możesz również wyłączyć tę wartość, jak pokazano poniżej.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

collection = QdrantCollection(
    collection_name="skhotels", 
    record_type=Hotel, 
    named_vectors=False,
)