使用 Postgres 矢量存储库连接器（预览版）

2025-05-20

警告

Postgres 向量存储功能处于预览状态，需要重大更改的改进可能在发布前的有限情况下发生。

警告

语义内核向量存储功能处于预览状态，在发布前的某些有限情况下，可能仍会进行需要重大更改的改进。

警告

语义内核向量存储功能处于预览状态，在发布前的某些有限情况下，可能仍会进行需要重大更改的改进。

概述

Postgres 矢量存储连接器可用于访问和管理 Postgres 中的数据，并支持 Neon 无服务器 Postgres。

连接器具有以下特征。

功能区域	支持
集合映射到	Postgres 表
支持的键属性类型	短整数长字符串 Guid
支持的数据属性类型	布尔短整数长浮动两倍十进制字符串日期时间日期时间偏移 (DateTimeOffset) Guid byte[] bool 枚举集合简短枚举ables int 枚举类型长可枚举对象浮点数枚举双 Enumerables 十进制可枚举的字符串可枚举集合 DateTime 可枚举对象 DateTimeOffset 枚举集合指导枚举器
支持的向量属性类型	只读内存（ReadOnlyMemory）<浮点数（float）> <嵌入浮点> float[] 只读内存<Half> 嵌入<一半> 一半[] BitArray Pgvector.SparseVector
支持的索引类型	Hnsw
支持的距离函数	CosineDistance 余弦相似度点积相似度 (DotProductSimilarity) EuclideanDistance 曼哈顿距离
支持的过滤条件	AnyTagEqualTo EqualTo
支持记录中的多个向量	是的
是否支持 IsIndexed？	不
是否支持FullTextIndexed？	不
StorageName支持吗？	是的
支持 HybridSearch？	不

局限性

重要

手动初始化 NpgsqlDataSource 时，必须在 UseVector 上调用 NpgsqlDataSourceBuilder。这可实现向量支持。如果没有此情况，VectorStore 实现的使用将失败。

下面是如何调用 UseVector的示例。

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

使用 AddPostgresVectorStore 依赖项注入注册方法并结合连接字符串时，数据源将通过此方法构造，并自动应用 UseVector。

入门指南

将 Postgres Vector Store 连接器 NuGet 包添加到项目。

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

可以使用语义内核提供的扩展方法将矢量存储添加到 IServiceCollection 依赖项注入容器。

在这种情况下，还将向容器注册已启用向量功能的 Npgsql.NpgsqlDataSource 类的实例。

using Microsoft.Extensions.DependencyInjection;

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

还提供不带参数的扩展方法。这些要求将 Npgsql.NpgsqlDataSource 类的实例单独注册到依赖项注入容器。

using Microsoft.Extensions.DependencyInjection;
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();

可以使用自定义数据源或连接字符串直接构造 Postgres Vector Store 实例。

using Microsoft.SemanticKernel.Connectors.PgVector;
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, ownsDataSource: true);

using Microsoft.SemanticKernel.Connectors.PgVector;

var connection = new PostgresVectorStore("Host=localhost;Port=5432;Username=postgres;Password=example;Database=postgres;");

可以使用自定义数据源或连接字符串构造对命名集合的直接引用。

using Microsoft.SemanticKernel.Connectors.PgVector;
using Npgsql;

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

var collection = new PostgresCollection<string, Hotel>(dataSource, "skhotels", ownsDataSource: true);

using Microsoft.SemanticKernel.Connectors.PgVector;

var collection = new PostgresCollection<string, Hotel>("Host=localhost;Port=5432;Username=postgres;Password=example;Database=postgres;", "skhotels");

数据映射

从数据模型映射到存储时，Postgres Vector Store 连接器提供默认映射器。此映射器将数据模型上的属性列表直接转换为 Postgres 中的列。

属性名称重写

可以提供替代属性名称，用于存储中与数据模型的属性名称不同的属性名称。属性名称的重写是通过在数据模型属性或记录定义中设置 StorageName 选项来完成的。

下面是一个在其属性上设置 `StorageName` 的数据模型示例，及其如何在 Postgres 命令中表示。

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public int HotelId { get; set; }

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

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

    [VectorStoreVector(Dimensions: 4, DistanceFunction = 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")
);

即将推出

更多信息即将推出。

JDBC

JDBC 连接器可用于连接到 Postgres。

通过