使用 Pinecone 连接器 （预览版）

警告

语义内核向量存储功能处于预览状态，需要中断性变更的改进可能仍发生在发布前的有限情况下。

概述

Pinecone 矢量存储连接器可用于访问和管理 Pinecone 中的数据。 连接器具有以下特征。

功能区域	支持
集合映射到	Pinecone 无服务器索引
支持的键属性类型	string
支持的数据属性类型	string int long double float 布尔 十进制 字符串类型的 枚举
支持的向量属性类型	ReadOnlyMemory<float>
支持的索引类型	PGA （Pinecone 图形算法）
支持的距离函数	CosineSimilarity DotProductSimilarity 欧几里得平方距离
支持的过滤条件	EqualTo
支持记录中的多个向量	否
是否支持Filterable？	是
是否支持FullTextSearchable？	否
支持 StoragePropertyName？	是

入门

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

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

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

using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddPineconeVectorStore(pineconeApiKey);

using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPineconeVectorStore(pineconeApiKey);

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

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using PineconeClient = Pinecone.PineconeClient;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<PineconeClient>(
    sp => new PineconeClient(pineconeApiKey));
kernelBuilder.AddPineconeVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using PineconeClient = Pinecone.PineconeClient;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<PineconeClient>(
    sp => new PineconeClient(pineconeApiKey));
builder.Services.AddPineconeVectorStore();

可以直接构造 Pinecone 矢量存储实例。

using Microsoft.SemanticKernel.Connectors.Pinecone;
using PineconeClient = Pinecone.PineconeClient;

var vectorStore = new PineconeVectorStore(
    new PineconeClient(pineconeApiKey));

可以构造对命名集合的直接引用。

using Microsoft.SemanticKernel.Connectors.Pinecone;
using PineconeClient = Pinecone.PineconeClient;

var collection = new PineconeVectorStoreRecordCollection<Hotel>(
    new PineconeClient(pineconeApiKey),
    "skhotels");

索引命名空间

矢量存储抽象不支持多层记录分组机制。 抽象中的集合映射到 Pinecone 无服务器索引，抽象中不存在第二级。 Pinecone 支持名为命名空间的第二级分组。

默认情况下，Pinecone 连接器将传递 null 作为所有操作的命名空间。 但是，在构造一个命名空间并将其用于所有操作时，可以将单个命名空间传递给 Pinecone 集合。

using Microsoft.SemanticKernel.Connectors.Pinecone;
using PineconeClient = Pinecone.PineconeClient;

var collection = new PineconeVectorStoreRecordCollection<Hotel>(
    new PineconeClient(pineconeApiKey),
    "skhotels",
    new() { IndexNamespace = "seasidehotels" });

数据映射

当将数据从数据模型映射到存储时，Pinecone 连接器提供默认映射器。 Pinecone 要求将属性映射到 ID、元数据和值分组。 默认映射器使用模型注释或记录定义来确定每个属性的类型并执行此映射。

• 批注为键的数据模型属性将映射到 Pinecone ID 属性。
• 作为数据批注的数据模型属性将映射到 Pinecone 元数据对象。
• 作为向量批注的数据模型属性将映射到 Pinecone 向量属性。

属性名称重写

对于数据属性，可以提供替代字段名称，以便在存储中使用的字段名称与数据模型中的属性名称不同。 密钥不支持此功能，因为 Key 在 Pinecone 中具有固定名称。 矢量也不支持它，因为矢量存储在固定名称 values下。 属性名称重写是通过数据模型属性或记录定义设置 StoragePropertyName 选项来完成的。

下面是一 StoragePropertyName 个基于其属性设置的数据模型示例，以及如何在 Pinecone 中表示数据模型。

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(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": "h1", 
    "values": [0.9, 0.1, 0.1, 0.1], 
    "metadata": { "hotel_name": "Hotel Happy", "hotel_description": "A place where everyone can be happy." }
}

Pinecone 连接器在 Python 中尚不可用。

Pinecone 连接器在 Java 中尚不可用。