Usando o conector de Armazenamento de Vetor Postgres (Pré-visualização)

Artigo
01/30/2025

Advertência

A funcionalidade de armazenamento vetorial do Semantic Kernel está em pré-visualização, e melhorias que exigem alterações significativas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Visão geral

O conector Postgres Vetor Store pode ser usado para acessar e gerenciar dados no Postgres. O conector tem as seguintes características.

Área de Destaque	Suporte
Mapeamento da coleção para	Tabela Postgres
Tipos de propriedade de chave suportados	curtas Int Longo string Guid
Tipos de propriedade de dados suportados	Bool curto Int Longo flutuar duplo decimais string Data e Hora DateTimeOffset Guid byte[] bool Enumeráveis Enumeráveis curtos int Enumeráveis Enumeráveis longos float Enumeráveis Enumeráveis duplos Enumeráveis decimais Enumeráveis de cadeia de caracteres DateTime Enumeráveis Enumeráveis DateTimeOffset Enumeráveis Guid
Tipos de propriedade vetorial suportados	ReadOnlyMemory<float>
Tipos de índice suportados	Hnsw
Funções de distância suportadas	CosineDistância Similaridade do Cosseno DotProductSimilarity Distância Euclidiana Distância de Manhattan
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
É o IsFilterable suportado?	Não
IsFullTextSearchable é suportado?	Não
¿StoragePropertyName suportado?	Sim

Primeiros passos

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

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

Você pode adicionar o armazenamento de vetores ao contêiner de injeção de dependência IServiceCollection usando métodos de extensão fornecidos pelo Semantic Kernel.

Nesse caso, uma instância da classe Npgsql.NpgsqlDataSource, que tem recursos de vetor habilitados, também será registrada no contêiner.

using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPostgresVectorStore("Host=localhost;Port=5432;Username=postgres;Password=example;Database=postgres;");

Métodos de extensão que não usam parâmetros também são fornecidos. Isto necessita que uma instância da classe Npgsql.NpgsqlDataSource seja registada separadamente no contêiner de injeção de dependência.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Npgsql;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<NpgsqlDataSource>(sp => 
{
    NpgsqlDataSourceBuilder dataSourceBuilder = new("Host=localhost;Port=5432;Username=postgres;Password=example;Database=postgres;");
    dataSourceBuilder.UseVector();
    return dataSourceBuilder.Build();
});

builder.Services.AddPostgresVectorStore();

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

using Microsoft.SemanticKernel.Connectors.Postgres;
using Npgsql;

NpgsqlDataSourceBuilder dataSourceBuilder = new("Host=localhost;Port=5432;Username=postgres;Password=example;Database=postgres;");
dataSourceBuilder.UseVector();
var dataSource = dataSourceBuilder.Build();

var connection = new PostgresVectorStore(dataSource);

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

using Microsoft.SemanticKernel.Connectors.Postgres;
using Npgsql;

NpgsqlDataSourceBuilder dataSourceBuilder = new("Host=localhost;Port=5432;Username=postgres;Password=example;Database=postgres;");
dataSourceBuilder.UseVector();
var dataSource = dataSourceBuilder.Build();

var collection = new PostgresVectorStoreRecordCollection<string, Hotel>(dataSource, "skhotels");

Mapeamento de dados

O conector Postgres Vetor Store fornece um mapeador padrão ao mapear do modelo de dados para o armazenamento. Este mapeador faz uma conversão direta da lista de propriedades no modelo de dados para as colunas no Postgres.

Também é possível substituir o comportamento do mapeador padrão fornecendo um mapeador personalizado por meio da propriedade PostgresVectorStoreRecordCollectionOptions<TRecord>.DictionaryCustomMapper.

Substituição do nome da propriedade

Você pode substituir os nomes de propriedade usados no armazenamento, que são diferentes dos nomes de propriedade no modelo de dados. A substituição do nome da propriedade é realizada configurando a opção StoragePropertyName nos atributos de propriedade do modelo de dados ou na definição de registo.

Aqui está um exemplo de um modelo de dados com StoragePropertyName definido em seus atributos e como isso será representado na consulta Postgres.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public ulong HotelId { get; set; }

    [VectorStoreRecordData(StoragePropertyName = "hotel_name")]
    public string? HotelName { get; set; }

    [VectorStoreRecordData(StoragePropertyName = "hotel_description")]
    public string? Description { get; set; }

    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

CREATE TABLE public."Hotels" (
    "HotelId" INTEGER NOT NULL,
    "hotel_name" TEXT ,
    "hotel_description" TEXT ,
    "DescriptionEmbedding" VECTOR(4) ,
    PRIMARY KEY ("HotelId")
);

Brevemente

Mais informações em breve.

JDBC

O conector JDBC pode ser usado para se conectar ao Postgres.

Partilhar via