Delen via

De Qdrant-connector gebruiken (preview)

  • Artikel

Waarschuwing

nl-NL: De Semantische Kernel Vector Store-functionaliteit is in preview, en verbeteringen die ingrijpende wijzigingen vereisen, kunnen nog steeds in beperkte omstandigheden plaatsvinden vóór de implementatie.

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
Verzameling koppelt aan Een Qdrant-verzameling met payloadindexen voor filterbare gegevensvelden.
Ondersteunde sleuteleigenschapstypen
  • ulong
  • Guid
Ondersteunde gegevenseigenschapstypen
  • tekenreeks
  • int
  • lang
  • 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
Wordt StoragePropertyName ondersteund? Ja
HybridSearch ondersteund? Ja
Functiegebied Ondersteuning
Komt overeen met Qdrant-collectie met payloadindexen voor filterbare gegevensvelden
Ondersteunde sleuteleigenschapstypen
  • ulong
  • Guid
Ondersteunde gegevenseigenschapstypen
  • tekenreeks
  • int
  • lang
  • dubbel
  • zwevend
  • bool
  • en iterables van elk van deze typen
Ondersteunde vectoreigenschappentypen
  • list[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
Wordt de StoragePropertyName ondersteund? Ja

Niet ondersteund

Momenteel niet ondersteund.

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 de vectorwinkel toevoegen aan de afhankelijkheidsinjectiecontainer die beschikbaar is op KernelBuilder of aan de IServiceCollection afhankelijkheidsinjectiecontainer met behulp van extensiemethoden die worden geleverd door de Semantic 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");

Datamapping

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

  • De eigenschap van het gegevensmodel die als sleutel is geannoteerd, wordt toegewezen aan de Qdrant punt-ID.
  • De eigenschappen van het datamodel die zijn geannoteerd als data, worden toegewezen aan het payloadobject 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 is een voorbeeld van een gegevensmodel waarbij StoragePropertyName op zijn attributen is ingesteld en hoe dat in Qdrant wordt weergegeven.

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.CosineSimilarity, 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 ongeïdentificeerde 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]
}

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.

Eén 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:

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

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:

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

Om de modus voor benoemde vectoren in te schakelen, geeft u dit op als optie bij het aanmaken 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 });

Als u de modus voor benoemde vectoren wilt inschakelen, geeft u dit op 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.

In Python is de standaardwaarde named_vectors ingesteld op True, 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,
)