Freigeben über

Verwenden des Qdrant-Connectors (Vorschau)

  • Artikel

Warnung

Die Funktionalität des semantischen Kernel-Vektorspeichers befindet sich in der Vorschau, und Verbesserungen, die abwärtskompatible Änderungen erfordern, können unter begrenzten Umständen noch vor der Veröffentlichung auftreten.

Übersicht

Der Qdrant Vector Store-Connector kann für den Zugriff auf und die Verwaltung von Daten in Qdrant verwendet werden. Der Verbinder weist die folgenden Merkmale auf.

Featurebereich Unterstützung
Zuordnung der Sammlungen zu Qdrant-Sammlung mit Nutzlastindizes für filterbare Datenfelder
Unterstützte Schlüsseleigenschaften-Typen
  • ulong
  • Guid
Unterstützte Dateneigenschaftstypen
  • Zeichenfolge
  • int
  • lang
  • doppelt
  • float
  • bool
  • und Aufzählungen jedes dieser Typen
Unterstützte Vektoreigenschaftstypen ReadOnlyMemory<float>
Unterstützte Indextypen Hnsw
Unterstützte Entfernungsfunktionen
  • KosinusSimilarität
  • DotProductSimilarity
  • EuklideanDistance
  • ManhattanDistance
Unterstützte Filterklauseln
  • AnyTagEqualTo
  • EqualTo
Unterstützt mehrere Vektoren in einem Datensatz Ja (konfigurierbar)
IstFilterbar unterstützt? Ja
WirdFullTextSearchable unterstützt? Ja
Wird StoragePropertyName unterstützt? Ja
HybridSearch wird unterstützt? Ja
Funktionsbereich Unterstützung
Zuordnungen von Sammlungen zu Qdrant-Auflistung mit Nutzlastindizes für filterbare Datenfelder
Typen unterstützter Schlüsseleigenschaften
  • ulong
  • Guid
Unterstützte Dateneigenschaftstypen
  • Zeichenfolge
  • int
  • lang
  • doppelt
  • schweben
  • bool
  • und Iterables von jedem dieser Typen
Unterstützte Vektoreigenschaftstypen
  • list[float]
Unterstützte Indextypen Hnsw
Unterstützte Entfernungsfunktionen
  • KosinusSimilarität
  • Punktprodukt-Ähnlichkeit
  • EuklideanDistance
  • ManhattanDistance
Unterstützte Filterklauseln
  • AnyTagEqualTo
  • EqualTo
Unterstützt mehrere Vektoren in einem Datensatz Ja (konfigurierbar)
IstFilterbar unterstützt? Ja
WirdFullTextSearchable unterstützt? Ja
Wird StoragePropertyName unterstützt? Ja

Nicht unterstützt

Zurzeit nicht unterstützt.

Erste Schritte

Fügen Sie Ihrem Projekt das NuGet-Paket des Qdrant-Vector-Store-Connectors hinzu.

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

Sie können den Vektorspeicher dem Dependency Injection Container, der für den KernelBuilder verfügbar ist, oder dem IServiceCollection Dependency Injection Container mithilfe von Erweiterungsmethoden hinzufügen, die vom Semantischen Kernel bereitgestellt werden.

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

Erweiterungsmethoden, die keine Parameter verwenden, werden ebenfalls bereitgestellt. Dazu muss eine Instanz der Qdrant.Client.QdrantClient Klasse separat beim Abhängigkeitseinfügungscontainer registriert werden.

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

Sie können eine Qdrant Vector Store-Instanz direkt erstellen.

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

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

Es ist möglich, einen direkten Verweis auf eine benannte Auflistung zu erstellen.

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

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

Datenzuordnung

Der Qdrant-Connector stellt ein Standard-Mapping bereit, wenn Daten vom Datenmodell zum Speicher zugeordnet werden. Qdrant erfordert, dass Eigenschaften in ID-, Nutzlast- und Vektorgruppierungen zugeordnet werden. Der Standardzuordnungs-Mapper verwendet die Modellanmerkungen oder die Datensatzdefinition, um den Typ jeder Eigenschaft zu bestimmen und diese Zuordnung auszuführen.

  • Die als Schlüssel gekennzeichnete Datenmodelleigenschaft wird der Qdrant-Punkt-ID zugeordnet.
  • Die Datenmodelleigenschaften, die als Daten gekennzeichnet sind, werden dem Nutzlastobjekt des Qdrant-Punkts zugeordnet.
  • Die Als Vektoren gekennzeichneten Datenmodelleigenschaften werden dem Qdrant-Punktvektorobjekt zugeordnet.

Außerkraftsetzung des Eigenschaftsnamens

Bei Dateneigenschaften und Vektoreigenschaften (bei Verwendung des Modus mit benannten Vektoren) können Sie Feldnamen außer Kraft setzen, die im Speicher verwendet werden sollen, die sich von den Eigenschaftennamen im Datenmodell unterscheiden. Dies wird für Schlüssel nicht unterstützt, da ein Schlüssel einen festen Namen in Qdrant aufweist. Es wird auch für Vektoren im einzelnamenlosen Vektormodus nicht unterstützt, da der Vektor unter einem festen Namen gespeichert wird.

Die Außerkraftsetzung des Eigenschaftsnamens wird durch Festlegung der StoragePropertyName Option über die Datenmodellattribute oder Datensatzdefinition erreicht.

Nachfolgend finden Sie ein Beispiel für ein Datenmodell, bei dem StoragePropertyName auf seine Attribute gesetzt wurde und wie das in Qdrant dargestellt wird.

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

Erste Schritte

Installieren Sie den semantischen Kernel mit den qdrant-Extras, die den qdrant-Client enthalten.

pip install semantic-kernel[qdrant]

Anschließend können Sie eine Vektorspeicherinstanz mithilfe der QdrantStore-Klasse erstellen. Dies erstellt einen AsyncQdrantClient, der die Umgebungsvariablen QDRANT_URL, QDRANT_API_KEY, QDRANT_HOST, QDRANT_PORT, QDRANT_GRPC_PORT, QDRANT_PATH, QDRANT_LOCATION und QDRANT_PREFER_GRPS verwendet, um eine Verbindung zur Qdrant-Instanz herzustellen. Diese Werte können auch direkt bereitgestellt werden. Wenn nichts angegeben wird, fällt es zurück auf location=:memory:.


from semantic_kernel.connectors.memory.qdrant import QdrantStore

vector_store = QdrantStore()

Sie können den Vektorspeicher auch mit Ihrer eigenen Instanz des qdrant-Clients erstellen.

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)

Sie können auch eine Sammlung direkt erstellen.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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

Serialisierung

Der Qdrant-Connector verwendet ein Modell, das zum Lesen und Schreiben im Store genutzt wird. Dies kann aus from qdrant_client.models import PointStructimportiert werden. Die Serialisierungsmethoden erwarten eine Ausgabe einer Liste von PointStruct-Objekten, und die Deserialisierungsmethode erhält eine Liste von PointStruct-Objekten.

Es gibt einige besondere Aspekte dafür, die mit benannten oder nicht benannten Vektoren zu tun haben, siehe unten.

Weitere Informationen zu diesem Konzept finden Sie in der Serialisierungsdokumentation.

Qdrant-Vektormodi

Qdrant unterstützt zwei Modi für die Vektorspeicherung, und der Qdrant-Connector mit vordefiniertem Mapping unterstützt beide Modi. Der Standardmodus ist ein einzelner nicht benannter Vektor.

Einzelner nicht benannter Vektor

Mit dieser Option kann eine Auflistung nur einen einzelnen Vektor enthalten und wird im Speichermodell in Qdrant nicht benannt. Hier ist ein Beispiel dafür, wie ein Objekt in Qdrant dargestellt wird, wenn ein einzelner unbenannter Vektormodus verwendet wird:

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-Vektormodi

Qdrant unterstützt zwei Modi für die Vektorspeicherung, und der Qdrant Connector mit der Standardkonfiguration unterstützt beide Modi. Der Standardmodus ist ein einzelner nicht benannter Vektor.

Einzelner nicht benannter Vektor

Mit dieser Option kann eine Auflistung nur einen einzelnen Vektor enthalten und wird im Speichermodell in Qdrant nicht benannt. Hier ist ein Beispiel dafür, wie ein Objekt in Qdrant dargestellt wird, wenn ein einzelner unbenannter Vektormodus verwendet wird:

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

Benannte Vektoren

Wenn Sie den Modus mit benannten Vektoren verwenden, bedeutet dies, dass jeder Punkt in einer Auflistung mehrere Vektoren enthalten kann und jeder benannt wird. Hier ist ein Beispiel dafür, wie ein Objekt in Qdrant dargestellt wird, wenn der benannte Vektormodus verwendet wird:

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

Benannte Vektoren

Wenn Sie den Modus mit benannten Vektoren verwenden, bedeutet dies, dass jeder Punkt in einer Auflistung mehrere Vektoren enthalten kann und jeder benannt wird. Hier ist ein Beispiel dafür, wie ein Objekt in Qdrant dargestellt wird, wenn der benannte Vektormodus verwendet wird:

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

Um den Modus mit benannten Vektoren zu aktivieren, übergeben Sie dies als Option beim Erstellen eines Vektorspeichers oder einer Sammlung. Dieselben Optionen können auch an eine der bereitgestellten Erweiterungsmethoden für Abhängigkeitsinjektions-Container übergeben werden.

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

Um den Modus mit benannten Vektoren zu aktivieren, übergeben Sie dies als Option beim Erstellen eines Vektorspeichers oder einer Sammlung. Dieselben Optionen können auch an eine der bereitgestellten Erweiterungsmethoden für Dependency Injection-Container übergeben werden.

In Python ist der Standardwert für named_vectors "True", aber Sie können dies auch wie unten gezeigt deaktivieren.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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