Uso del conector Qdrant (versión preliminar)

No soportado

No se admite actualmente.

Cómo empezar

Agregue el paquete NuGet del conector del almacén de vectores de Qdrant a tu proyecto.

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

Puede agregar el almacén de vectores al contenedor de inserción de dependencias disponible en KernelBuilder o al contenedor de inserción de dependencias IServiceCollection mediante los métodos de extensión proporcionados por el Kernel Semántico.

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

También se proporcionan métodos de extensión que no toman parámetros. Estos requieren que una instancia de la Qdrant.Client.QdrantClient clase se registre por separado con el contenedor de inserción de dependencias.

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

Puede construir directamente una instancia de almacén de vectores de Qdrant.

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

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

Es posible construir una referencia directa a una colección con nombre.

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

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

Mapeo de datos

El conector Qdrant ofrece un mapeador predeterminado para la conversión de datos del modelo de datos al almacenamiento. Qdrant requiere que las propiedades se asignen a agrupaciones id, payload y vectores. El asignador predeterminado usa las anotaciones del modelo o la definición de registro para determinar el tipo de cada propiedad y para realizar esta asignación.

• La propiedad del modelo de datos anotada como clave se asignará al identificador de punto de Qdrant.
• Las propiedades del modelo de datos anotadas como datos se asignarán al objeto de carga de punto Qdrant.
• Las propiedades del modelo de datos anotadas como vectores se asignarán al objeto vectorial de punto Qdrant.

Invalidación del nombre de propiedad

En el caso de las propiedades de datos y las propiedades vectoriales (si se usa el modo de vectores con nombre), puede proporcionar nombres de campo de sustitución para usarlos en el almacenamiento que sean diferentes a los nombres de propiedad del modelo de datos. Esto no se admite para las claves, ya que una clave tiene un nombre fijo en Qdrant. Tampoco se admite para vectores en modo de vector sin nombre único, ya que el vector se almacena bajo un nombre fijo.

La sobrescritura del nombre de propiedad se realiza estableciendo la opción StorageName a través de los atributos del modelo de datos o la definición de registro.

Este es un ejemplo de un modelo de datos con StorageName establecido en sus atributos y cómo se representará en 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],
    }
}

Cómo empezar

Instale el kernel semántico con los extras qdrant, que incluyen el cliente qdrant.

pip install semantic-kernel[qdrant]

A continuación, puede crear una instancia de almacén de vectores mediante la clase QdrantStore, lo que creará un AsyncQdrantClient usando las variables de entorno QDRANT_URL, QDRANT_API_KEY, QDRANT_HOST, QDRANT_PORT, QDRANT_GRPC_PORT, QDRANT_PATH, QDRANT_LOCATION y QDRANT_PREFER_GRPS para conectarse a la instancia de Qdrant. Esos valores también se pueden proporcionar directamente. Si no se proporciona nada, vuelve a location=:memory:.

from semantic_kernel.connectors.qdrant import QdrantStore

vector_store = QdrantStore()

También puede crear el almacén de vectores con su propia instancia del cliente 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)

También puede crear una colección directamente.

from semantic_kernel.connectors.qdrant import QdrantCollection

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

Serialización

El conector Qdrant utiliza un modelo llamado PointStruct para leer y escribir en el almacén. Esto se puede importar desde from qdrant_client.models import PointStruct. Los métodos de serialización esperan una salida de una lista de objetos PointStruct y el método de deserialización recibe una lista de objetos PointStruct.

Hay algunas consideraciones especiales para esto que tienen que ver con vectores con nombre o sin nombre, consulte a continuación.

Para obtener más información sobre este concepto, consulte la documentación de serialización.

Modos vectoriales de Qdrant

Qdrant admite dos modos para el almacenamiento vectorial y el conector Qdrant con asignador predeterminado admite ambos modos. El modo predeterminado es un vector sin nombre único.

Vector sin nombre único

Con esta opción, una colección solo puede contener un único vector y no tendrá nombre dentro del modelo de almacenamiento de Qdrant. Este es un ejemplo de cómo se representa un objeto en Qdrant cuando se usa el modo de vector sin nombre único:

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

Modos vectoriales de Qdrant

Qdrant admite dos modos para el almacenamiento vectorial y el conector Qdrant con asignador predeterminado admite ambos modos. El modo predeterminado es un vector sin nombre único.

Vector sin nombre único

Con esta opción, una colección solo puede contener un único vector y no tendrá nombre dentro del modelo de almacenamiento de Qdrant. Este es un ejemplo de cómo se representa un objeto en Qdrant cuando se usa el modo de vector sin nombre único:

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

Vectores con nombre

Si usa el modo de vectores con nombre, significa que cada punto de una colección puede contener más de un vector y cada uno se denominará. Este es un ejemplo de cómo se representa un objeto en Qdrant cuando se usa el modo de vectores con nombre:

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

Vectores con nombre

Si usa el modo de vectores con nombre, significa que cada punto de una colección puede contener más de un vector y cada uno se denominará. Este es un ejemplo de cómo se representa un objeto en Qdrant cuando se usa el modo de vectores con nombre:

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

Para habilitar el modo de vectores con nombre, pase esto como una opción al construir un almacén de vectores o una colección. Las mismas opciones también se pueden pasar a cualquiera de los métodos de extensión proporcionados del contenedor de inyección de dependencias.

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

Para habilitar el modo de vectores con nombre, pase esto como una opción al construir un almacén de vectores o una colección. Las mismas opciones también se pueden pasar a cualquiera de los métodos de extensión proporcionados del contenedor de inyección de dependencias.

En Python, el valor predeterminado de named_vectors es True, pero también puede deshabilitarlo como se muestra a continuación.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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