Použití konektoru Qdrant (Preview)

Článek
11/03/2024

Upozorňující

Funkce sémantického úložiště vektorů jádra je ve verzi Preview a vylepšení, která vyžadují zásadní změny, se můžou vyskytovat za omezených okolností před vydáním.

Přehled

Konektor Qdrant Vector Store je možné použít pro přístup k datům v Qdrantu a jejich správě. Konektor má následující charakteristiky.

Oblast funkcí	Technická podpora
Kolekce map na	Kolekce Qdrant s indexy datové části pro filtrovatelná datová pole
Podporované typy vlastností klíče	ulong Guid
Podporované typy datových vlastností	string int long double float (číslo s plovoucí řádovou čárkou) bool a výčty každého z těchto typů
Podporované typy vektorových vlastností	ReadOnlyMemory<float>
Podporované typy indexů	Hnsw
Podporované funkce vzdálenosti	KosineSimilarita DotProductSimilarity EuclideanDistance ManhattanDistance
Podporuje více vektorů v záznamu.	Ano (konfigurovatelné)
Je podporováno Filtrování?	Ano
Podporuje se IsFullTextSearchable?	Ano
StoragePropertyName se podporuje?	Ano

Začínáme

Přidejte do projektu balíček NuGet konektoru Qdrant Vector Store.

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

Vektorové úložiště můžete přidat do kontejneru injektáže závislostí dostupného IServiceCollection v KernelBuilder kontejneru injektáže závislostí nebo do kontejneru injektáže závislostí pomocí rozšiřujících metod poskytovaných sémantickým jádrem.

using Microsoft.SemanticKernel;

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

using Microsoft.SemanticKernel;

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

K dispozici jsou také metody rozšíření, které nepoužívají žádné parametry. Vyžadují samostatnou registraci instance Qdrant.Client.QdrantClient třídy v kontejneru injektáže závislostí.

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

Instanci Qdrant Vector Store můžete vytvořit přímo.

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

var vectorStore = new QdrantVectorStore(new QdrantClient("localhost"));

Je možné vytvořit přímý odkaz na pojmenovanou kolekci.

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

var collection = new QdrantVectorStoreRecordCollection<Hotel>(
    new QdrantClient("localhost"),
    "skhotels");

Mapování dat

Konektor Qdrant poskytuje výchozí mapovač při mapování dat z datového modelu do úložiště. Qdrant vyžaduje, aby se vlastnosti mapovaly na id, datovou část a vektory seskupování. Výchozí mapovač používá k určení typu každé vlastnosti a k tomuto mapování poznámky modelu nebo definici záznamu.

Vlastnost datového modelu anotovaná jako klíč bude mapována na ID bodu Qdrant.
Vlastnosti datového modelu anotované jako data budou mapovány na objekt datové části bodu Qdrant.
Vlastnosti datového modelu anotované jako vektory budou mapovány na objekt vektoru bodu Qdrant.

Přepsání názvu vlastnosti

U vlastností dat a vektorových vlastností (pokud používáte režim pojmenovaných vektorů), můžete zadat názvy polí přepsání pro použití v úložišti, které se liší od názvů vlastností datového modelu. U klíčů se to nepodporuje, protože klíč má pevný název v Qdrantu. Nepodporuje se také u vektorů v režimu jednoho nepojmenovaného vektoru , protože vektor je uložen pod pevným názvem.

Přepsání názvu vlastnosti se provádí nastavením StoragePropertyName možnosti prostřednictvím atributů datového modelu nebo definice záznamu.

Tady je příklad datového modelu se StoragePropertyName sadou jeho atributů a způsobu, jakým se bude v Qdrantu reprezentovat.

using Microsoft.Extensions.VectorData;

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

    [VectorStoreRecordData(IsFilterable = true, StoragePropertyName = "hotel_name")]
    public string HotelName { get; set; }

    [VectorStoreRecordData(IsFullTextSearchable = true, StoragePropertyName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw, StoragePropertyName = "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],
    }
}

Začínáme

Nainstalujte sémantické jádro pomocí extra qdrantu, které zahrnuje klienta qdrant.

pip install semantic-kernel[qdrant]

Pak můžete vytvořit instanci vektorového úložiště pomocí QdrantStore třídy, tím se vytvoří AsyncQdrantClient pomocí proměnných QDRANT_URLprostředí , , QDRANT_API_KEY, QDRANT_PORTQDRANT_HOST, , QDRANT_GRPC_PORT, a QDRANT_PATHQDRANT_LOCATION QDRANT_PREFER_GRPS připojit k instanci Qdrant, tyto hodnoty lze také zadat přímo. Pokud se nic nedodá, vrátí se zpět .location=:memory:


from semantic_kernel.connectors.memory.qdrant import QdrantStore

vector_store = QdrantStore()

Vektorové úložiště můžete vytvořit také pomocí vlastní instance klienta qdrant.

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

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

Kolekci můžete vytvořit také přímo.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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

Serializace

Konektor Qdrant používá model, který volá PointStruct čtení a zápis do obchodu. To lze importovat z from qdrant_client.models import PointStruct. Metody serializace očekává výstup seznamu PointStruct objekty a deserializace metoda recievest seznam PointStruct objekty.

Existuje několik zvláštních aspektů, které musí s pojmenovanými nebo nepojmenovanými vektory dělat, viz níže.

Další podrobnosti o tomto konceptu najdete v dokumentaci k serializaci.

Režimy vektoru Qdrant

Qdrant podporuje dva režimy pro úložiště vektorů a konektor Qdrant s výchozím mapovačem podporuje oba režimy. Výchozí režim je jeden nepojmenovaný vektor.

Jeden nepojmenovaný vektor

S touto možností může kolekce obsahovat pouze jeden vektor a v modelu úložiště v Qdrantu bude bez názvu. Tady je příklad, jak je objekt reprezentován v Qdrantu při použití režimu jednoho nepojmenovaného vektoru :

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

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

Pojmenované vektory

Pokud používáte režim pojmenovaných vektorů, znamená to, že každý bod v kolekci může obsahovat více než jeden vektor a každý z nich bude pojmenován. Tady je příklad znázornění objektu v Qdrantu při použití režimu pojmenovaných vektorů :

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

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

Pokud chcete povolit režim pojmenovaných vektorů, předejte tuto možnost jako možnost při vytváření vektorového úložiště nebo kolekce. Stejné možnosti lze předat také libovolné z poskytnutých metod rozšíření kontejneru injektáže závislostí.

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

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

var collection = new QdrantVectorStoreRecordCollection<Hotel>(
    new QdrantClient("localhost"),
    "skhotels",
    new() { HasNamedVectors = true });

V Pythonu je výchozí hodnota named_vectors True, ale můžete ji také zakázat, jak je znázorněno níže.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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

Sdílet prostřednictvím

Použití konektoru Qdrant (Preview)

Přehled

Začínáme

Mapování dat

Přepsání názvu vlastnosti

Začínáme

Serializace

Režimy vektoru Qdrant

Jeden nepojmenovaný vektor

Pojmenované vektory

Další materiály