De Qdrant-connector gebruiken (preview)

Artikel
11/03/2024

Waarschuwing

De Semantische Kernel Vector Store-functionaliteit is in preview en verbeteringen waarvoor wijzigingen die fouten veroorzaken, kunnen nog steeds in beperkte omstandigheden optreden voordat ze worden uitgebracht.

Overzicht

De Qdrant Vector Store-connector kan worden gebruikt voor toegang tot en beheer van gegevens in Qdrant. De verbindingslijn heeft de volgende kenmerken.

Functiegebied	Ondersteuning
Verzamelingstoewijzingen aan	Qdrant-verzameling met nettoladingindexen voor filterbare gegevensvelden
Ondersteunde sleuteleigenschapstypen	ulong Guid
Ondersteunde gegevenseigenschapstypen	tekenreeks int long dubbel zwevend bool en opsommingen van elk van deze typen
Ondersteunde vectoreigenschappentypen	ReadOnlyMemory<float>
Ondersteunde indextypen	Hnsw
Ondersteunde afstandsfuncties	CosineSimilariteit DotProductsimilarity EuclideanDistance ManhattanDistance
Ondersteunde filterclausules	AnyTagEqualTo EqualTo
Ondersteunt meerdere vectoren in een record	Ja (configureerbaar)
Wordt Filterable ondersteund?	Ja
WordtFullTextSearchable ondersteund?	Ja
Ondersteunde StoragePropertyName?	Ja

Aan de slag

Voeg het NuGet-pakket Qdrant Vector Store-connector toe aan uw project.

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

U kunt het vectorarchief toevoegen aan de container voor afhankelijkheidsinjectie die beschikbaar is op of KernelBuilder aan de IServiceCollection container voor afhankelijkheidsinjectie met behulp van extensiemethoden die worden geleverd door Semantische kernel.

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

Extensiemethoden waarvoor geen parameters worden gebruikt, worden ook opgegeven. Hiervoor moet een exemplaar van de Qdrant.Client.QdrantClient klasse afzonderlijk worden geregistreerd bij de container voor afhankelijkheidsinjectie.

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

U kunt rechtstreeks een Qdrant Vector Store-exemplaar maken.

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

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

Het is mogelijk om een directe verwijzing naar een benoemde verzameling te maken.

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

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

Gegevenstoewijzing

De Qdrant-connector biedt een standaardtoewijzingsfunctie bij het toewijzen van gegevens uit het gegevensmodel aan opslag. Qdrant vereist dat eigenschappen worden toegewezen aan id-, nettolading- en vectorgroepen. De standaardtoewijzing gebruikt de modelaantekeningen of recorddefinitie om het type van elke eigenschap te bepalen en om deze toewijzing uit te voeren.

De eigenschap van het gegevensmodel die als sleutel wordt geannoteerd, wordt toegewezen aan de Qdrant-punt-id.
De eigenschappen van het gegevensmodel die zijn geannoteerd als gegevens, worden toegewezen aan het nettoladingobject van het Qdrant-punt.
De eigenschappen van het gegevensmodel die zijn geannoteerd als vectoren, worden toegewezen aan het Qdrant-puntvectorobject.

Eigenschapsnaam overschrijven

Voor gegevenseigenschappen en vectoreigenschappen (als u de modus benoemde vectoren gebruikt), kunt u veldnamen overschrijven die moeten worden gebruikt in de opslag die verschilt van de eigenschapsnamen in het gegevensmodel. Dit wordt niet ondersteund voor sleutels, omdat een sleutel een vaste naam heeft in Qdrant. Het wordt ook niet ondersteund voor vectoren in enkele niet-benoemde vectormodus , omdat de vector wordt opgeslagen onder een vaste naam.

De eigenschapsnaam wordt overschreven door de StoragePropertyName optie in te stellen via de kenmerken van het gegevensmodel of de recorddefinitie.

Hier volgt een voorbeeld van een gegevensmodel dat StoragePropertyName is ingesteld op de kenmerken en hoe dit wordt weergegeven in Qdrant.

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

Aan de slag

Installeer semantische kernel met de qdrant-extra's, waaronder de qdrant-client.

pip install semantic-kernel[qdrant]

Vervolgens kunt u een exemplaar van een vectorarchief maken met behulp van de QdrantStore klasse. Hiermee maakt u een AsyncQdrantClient met behulp van de omgevingsvariabelenQDRANT_URL, QDRANT_API_KEY, QDRANT_HOST, QDRANT_PORT, en QDRANT_GRPC_PORTQDRANT_PATHQDRANT_LOCATIONQDRANT_PREFER_GRPS om verbinding te maken met het Qdrant-exemplaar, kunnen deze waarden ook rechtstreeks worden opgegeven. Als er niets wordt geleverd, valt het terug op location=:memory:.


from semantic_kernel.connectors.memory.qdrant import QdrantStore

vector_store = QdrantStore()

U kunt ook het vectorarchief maken met uw eigen exemplaar van de qdrant-client.

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)

U kunt ook rechtstreeks een verzameling maken.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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

Serialisatie

De Qdrant-connector maakt gebruik van een model dat wordt aangeroepen PointStruct voor lezen en schrijven naar de store. Dit kan worden geïmporteerd uit from qdrant_client.models import PointStruct. De serialisatiemethoden verwachten een uitvoer van een lijst met PointStruct-objecten en de deserialisatiemethode ontvangt een lijst met PointStruct-objecten.

Er zijn enkele speciale overwegingen die te maken hebben met benoemde of niet-benoemde vectoren, zie hieronder.

Zie de serialisatiedocumentatie voor meer informatie over dit concept.

Qdrant-vectormodi

Qdrant ondersteunt twee modi voor vectoropslag en de Qdrant-connector met standaard mapper ondersteunt beide modi. De standaardmodus is één niet-benoemde vector.

Enkele niet-benoemde vector

Met deze optie mag een verzameling slechts één vector bevatten en wordt deze niet genoemd in het opslagmodel in Qdrant. Hier volgt een voorbeeld van hoe een object wordt weergegeven in Qdrant wanneer u één niet-benoemde vectormodus gebruikt:

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

Benoemde vectoren

Als u de modus benoemde vectoren gebruikt, betekent dit dat elk punt in een verzameling meer dan één vector kan bevatten en dat elk punt een naam krijgt. Hier volgt een voorbeeld van hoe een object wordt weergegeven in Qdrant wanneer u de modus benoemde vectoren gebruikt:

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

Als u de modus benoemde vectoren wilt inschakelen, geeft u dit door als een optie bij het maken van een Vector Store of verzameling. Dezelfde opties kunnen ook worden doorgegeven aan een van de opgegeven extensiemethoden voor afhankelijkheidsinjectiecontainers.

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

In Python is de standaardwaarde named_vectors waar, maar u kunt dit ook uitschakelen, zoals hieronder wordt weergegeven.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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

Delen via

De Qdrant-connector gebruiken (preview)

Overzicht

Aan de slag

Gegevenstoewijzing

Eigenschapsnaam overschrijven

Aan de slag

Serialisatie

Qdrant-vectormodi

Enkele niet-benoemde vector

Benoemde vectoren

Aanvullende resources