使用 Pinecone 连接器 （预览版）

概述

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

入门

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

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

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

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

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

using Microsoft.Extensions.DependencyInjection;

// 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.Services.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 PineconeCollection<string, Hotel>(
    new PineconeClient(pineconeApiKey),
    "skhotels");

索引命名空间

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

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

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

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

数据映射

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

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

属性名称重写

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

下面是一个在其属性上设置 StorageName 的数据模型示例，以及它将如何在 Pinecone 中被表示。

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public string 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(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = 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 矢量存储连接器可用于访问和管理 Pinecone 中的数据。 连接器具有以下特征。

入门

将 Pinecone Vector Store 额外连接器添加到项目中。

pip install semantic-kernel[pinecone]

然后，可以创建 PineconeStore 实例，并使用它来创建集合。 这将从环境变量 PINECONE_API_KEY中读取 Pinecone API 密钥。

from semantic_kernel.connectors.memory.pinecone import PineconeStore

store = PineconeStore()
collection = store.get_collection(collection_name="collection_name", data_model=DataModel)

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

from semantic_kernel.connectors.memory.pinecone import PineconeCollection

collection = PineconeCollection(collection_name="collection_name", data_model=DataModel)

还可以创建自己的 Pinecone 客户端并将其传递到构造函数中。 客户端必须是 PineconeAsyncio 或 PineconeGRPC （请参阅 GRPC 支持）。

from semantic_kernel.connectors.memory.pinecone import PineconeStore, PineconeCollection
from pinecone import PineconeAsyncio

client = PineconeAsyncio(api_key="your_api_key") 
store = PineconeStore(client=client)
collection = store.get_collection(collection_name="collection_name", data_model=DataModel)

GRPC 支持

我们还支持集合构造函数上的两个选项，第一个选项是启用 GRPC 支持：

from semantic_kernel.connectors.memory.pinecone import PineconeCollection

collection = PineconeCollection(collection_name="collection_name", data_model=DataModel, use_grpc=True)

或者，使用自己的客户端：

from semantic_kernel.connectors.memory.pinecone import PineconeStore
from pinecone.grpc import PineconeGRPC

client = PineconeGRPC(api_key="your_api_key")
store = PineconeStore(client=client)
collection = store.get_collection(collection_name="collection_name", data_model=DataModel)

集成嵌入

第二种方法是使用 Pinecone 的集成嵌入，这将检查一个名为 PINECONE_EMBED_MODEL 的环境变量，或者您可以传入一个 embed_settings 字典，它可以仅包含模型键，或者嵌入模型的完整设置。 在前一种情况下，其他设置将派生自数据模型定义。

请参阅 Pinecone 文档 ，然后查看 Use integrated embeddings 各节。

from semantic_kernel.connectors.memory.pinecone import PineconeCollection

collection = PineconeCollection(collection_name="collection_name", data_model=DataModel)

或者，如果不设置环境变量，可以将嵌入设置传递到构造函数中：

from semantic_kernel.connectors.memory.pinecone import PineconeCollection

collection = PineconeCollection(collection_name="collection_name", data_model=DataModel, embed_settings={"model": "multilingual-e5-large"})

这可以包括有关矢量设置的其他详细信息，例如指标和字段映射。 还可以将嵌入设置传递到 create_collection 方法中，这将替代初始化期间设置的默认设置。

from semantic_kernel.connectors.memory.pinecone import PineconeCollection

collection = PineconeCollection(collection_name="collection_name", data_model=DataModel)
await collection.create_collection(embed_settings={"model": "multilingual-e5-large"})

重要说明：GRPC 和集成嵌入不能一起使用。

索引命名空间

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

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

from semantic_kernel.connectors.memory.pinecone import PineconeCollection

collection = PineconeCollection(
    collection_name="collection_name", 
    data_model=DataModel, 
    namespace="seasidehotels"
)

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