Usando o conector Qdrant (Pré-visualização)

Não suportado

Não suportado atualmente.

Começar

Adicione ao seu projeto o pacote NuGet do conector Qdrant Vector Store.

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

Você pode adicionar o armazenamento vetorial ao contêiner de injeção de dependência disponível no KernelBuilder ou ao contêiner de IServiceCollection injeção de dependência usando métodos de extensão fornecidos pelo Semantic Kernel.

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

Métodos de extensão que não usam parâmetros também são fornecidos. Isso requer que uma instância da Qdrant.Client.QdrantClient classe seja registrada separadamente com o contêiner de injeção de dependência.

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

Você pode construir uma instância do Qdrant Vetor Store diretamente.

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

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

É possível construir uma referência direta a uma coleção nomeada.

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

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

Mapeamento de dados

O conector Qdrant fornece um mapeador padrão ao mapear dados do modelo de dados para o armazenamento. O Qdrant requer que as propriedades sejam mapeadas em agrupamentos de id, carga útil e vetor(es). O mapeador padrão usa as anotações de modelo ou a definição de registro para determinar o tipo de cada propriedade e fazer esse mapeamento.

• A propriedade do modelo de dados anotada como uma chave será mapeada para o identificador do ponto Qdrant.
• As propriedades do modelo de dados, anotadas como "dados", serão associadas ao objeto de carga do ponto Qdrant.
• As propriedades do modelo de dados anotadas como vetores serão mapeadas para o objeto de vetor de ponto Qdrant.

Sobrescrever o nome da propriedade

Para propriedades de dados e propriedades de vetor (se estiver usando o modo de vetores nomeados), você pode fornecer nomes de campo de substituição para uso no armazenamento que sejam diferentes dos nomes de propriedade no modelo de dados. Isso não é suportado para chaves, uma vez que uma chave tem um nome fixo no Qdrant. Também não é suportado para vetores no modo de vetor único sem nome, uma vez que o vetor é armazenado sob um nome fixo.

A substituição do nome da propriedade é feita definindo a StorageName opção por meio dos atributos do modelo de dados ou da definição do registro.

Aqui está um exemplo de um modelo de dados com StorageName definido nos seus atributos e como este será representado no 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],
    }
}

Começar

Instale o núcleo semântico com os extras qdrant, que incluem o cliente qdrant.

pip install semantic-kernel[qdrant]

Em seguida, você pode criar uma instância de armazenamento de vetores usando a QdrantStore classe, isso criará um AsyncQdrantClient usando as variáveis QDRANT_URLde ambiente , QDRANT_API_KEY, QDRANT_HOST, QDRANT_PORT, QDRANT_GRPC_PORT, QDRANT_PATHQDRANT_LOCATION e QDRANT_PREFER_GRPS para se conectar à instância do Qdrant, esses valores também podem ser fornecidos diretamente. Se nada for fornecido, ele cai de volta para location=:memory:.

from semantic_kernel.connectors.qdrant import QdrantStore

vector_store = QdrantStore()

Você também pode criar o repositório de vetores com sua própria instância do 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)

Você também pode criar uma coleção diretamente.

from semantic_kernel.connectors.qdrant import QdrantCollection

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

Serialização

O conector Qdrant usa um modelo chamado PointStruct para leitura e gravação na loja. Isso pode ser importado do from qdrant_client.models import PointStruct. Os métodos de serialização esperam uma saída de uma lista de objetos PointStruct e o método de desserialização recebe uma lista de objetos PointStruct.

Existem algumas considerações especiais para isso que têm a ver com vetores nomeados ou não nomeados, veja abaixo.

Para obter mais detalhes sobre esse conceito, consulte a documentação de serialização.

Modos vetoriais Qdrant

O Qdrant suporta dois modos para armazenamento vetorial e o Qdrant Connector com mapeador padrão suporta ambos os modos. O modo padrão é um único vetor sem nome.

Vetor único sem nome

Com essa opção, uma coleção pode conter apenas um único vetor e não será nomeada no modelo de armazenamento no Qdrant. Aqui está um exemplo de como um objeto é representado no Qdrant ao usar o modo de vetor único sem nome:

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 vetoriais Qdrant

O Qdrant suporta dois modos para armazenamento vetorial e o Qdrant Connector com mapeador padrão suporta ambos os modos. O modo padrão é um único vetor sem nome.

Vetor único sem nome

Com essa opção, uma coleção pode conter apenas um único vetor e não será nomeada no modelo de armazenamento no Qdrant. Aqui está um exemplo de como um objeto é representado no Qdrant ao usar o modo de vetor único sem nome:

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

Vetores nomeados

Se usar o modo de vetores nomeados, isso significa que cada ponto em uma coleção pode conter mais de um vetor e cada um será nomeado. Aqui está um exemplo de como um objeto é representado no Qdrant ao usar modo de vetores nomeados:

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

Vetores nomeados

Se usar o modo de vetores nomeados, isso significa que cada ponto em uma coleção pode conter mais de um vetor e cada um será nomeado. Aqui está um exemplo de como um objeto é representado no Qdrant ao usar modo de vetores nomeados:

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 o modo de vetores nomeados, passe isso como uma opção ao construir um Vetor Store ou coleção. As mesmas opções também podem ser passadas para qualquer um dos métodos de extensão do contentor de injeção de dependência fornecidos.

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 o modo de vetores nomeados, passe isso como uma opção ao construir um Vetor Store ou coleção. As mesmas opções também podem ser passadas para qualquer um dos métodos de extensão do contentor de injeção de dependência fornecidos.

Em python, o valor padrão para named_vectors é True, mas você também pode desativar isso como mostrado abaixo.

from semantic_kernel.connectors.memory.qdrant import QdrantCollection

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