Compartir a través de


Uso del conector Qdrant (versión preliminar)

Advertencia

La funcionalidad Almacén de vectores de kernel semántico está en versión preliminar y las mejoras que requieren cambios importantes pueden producirse en circunstancias limitadas antes de la versión.

Información general

El conector de almacén de vectores de Qdrant se puede usar para acceder a los datos y administrarlos en Qdrant. El conector tiene las siguientes características.

Área de características Soporte técnico
La colección se asigna a Colección Qdrant con índices de carga para campos de datos filtrables
Tipos de propiedades de clave admitidos
  • ulong
  • GUID
Tipos de propiedad de datos admitidos
  • string
  • int
  • long
  • double
  • FLOAT
  • bool
  • y enumerables de cada uno de estos tipos
Tipos de propiedades vectoriales admitidos ReadOnlyMemory<float>
Tipos de índice admitidos Hnsw
Funciones de distancia admitidas
  • CosineSimilarity
  • DotProductSimilarity
  • EuclideanDistance
  • ManhattanDistance
Admite varios vectores en un registro Sí (configurable)
¿Se admite IsFilterable?
¿Se admite IsFullTextSearchable?
¿Se admite StoragePropertyName?

Introducción

Agregue el paquete NuGet del conector del almacén de vectores de Qdrant al 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 IServiceCollection contenedor de inserción de dependencias mediante métodos de extensión proporcionados por kernel semántico.

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

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

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

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

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

Asignación de datos

El conector Qdrant proporciona un asignador predeterminado al asignar 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 invalidación para usarlos en el almacenamiento que es diferente 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 invalidación del nombre de propiedad se realiza estableciendo la StoragePropertyName opción 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 StoragePropertyName establecido en sus atributos y cómo se representará en 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],
    }
}

Introducción

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

pip install semantic-kernel[qdrant]

A continuación, puede crear una instancia de almacén de vectores mediante la QdrantStore clase , lo que creará a AsyncQdrantClient mediante las variables QDRANT_URLde entorno , QDRANT_API_KEY, QDRANT_HOST, QDRANT_PORTQDRANT_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.memory.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.memory.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.memory.qdrant import QdrantCollection

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

Serialización

El conector Qdrant usa 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 de vector 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 se anulará el nombre en el modelo de almacenamiento en 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]
}
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],
    }
}
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 de contenedor de inserción de dependencias proporcionados.

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

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", 
    data_model_type=Hotel, 
    named_vectors=False,
)