Utilisation du connecteur Pinecone (Aperçu)

Vue d’ensemble

Le connecteur Pinecone Vector Store peut être utilisé pour accéder aux données et les gérer dans Pinecone. Le connecteur présente les caractéristiques suivantes.

Mise en route

Ajoutez le package NuGet du connecteur Pinecone Vector Store à votre projet.

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

Vous pouvez ajouter le magasin de vecteurs soit au conteneur d'injection de dépendances disponible sur le KernelBuilder, soit au conteneur IServiceCollection à l'aide des méthodes d'extension fournies par le noyau sémantique.

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

Les méthodes d’extension qui ne prennent aucun paramètre sont également fournies. Celles-ci nécessitent qu'une instance de PineconeClient soit enregistrée séparément dans le conteneur d'injection de dépendances.

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

Vous pouvez construire directement une instance pinecone Vector Store.

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

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

Il est possible de construire une référence directe à une collection nommée.

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

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

Espace de noms d’index

L’abstraction Vector Store ne prend pas en charge de mécanisme de regroupement d’enregistrements à plusieurs niveaux. Les collections dans l'abstraction correspondent à un index serverless Pinecone et aucun deuxième niveau n'existe dans l'abstraction. Pinecone prend en charge un deuxième niveau de regroupement appelé espaces de noms.

Par défaut, le connecteur Pinecone passe une valeur nulle comme espace de noms pour toutes les opérations. Toutefois, il est possible de passer un espace de noms unique à la collection Pinecone lors de sa construction et de l’utiliser à la place pour toutes les opérations.

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

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

Mappage de données

Le connecteur Pinecone fournit un mappeur par défaut lors du mappage des données du modèle de données au stockage. Pinecone nécessite que les propriétés soient mappées en id, métadonnées et regroupements de valeurs. Le mappeur par défaut utilise les annotations de modèle ou la définition d’enregistrement pour déterminer le type de chaque propriété et effectuer ce mappage.

• La propriété de modèle de données annotée en tant que clé sera mise en correspondance avec la propriété d'id Pinecone.
• Les propriétés du modèle de données annotées en tant que données seront mappées à l’objet de métadonnées Pinecone.
• La propriété de modèle de données annotée en tant que vecteur sera mappée à la propriété de vecteur Pinecone.

Écrasement du nom de propriété

Pour les propriétés de données, vous pouvez fournir des noms de champs de remplacement pour le stockage, différents des noms de propriétés du modèle de données. Cela n’est pas pris en charge pour les clés, car une clé a un nom fixe dans Pinecone. Il n’est pas non plus pris en charge pour les vecteurs, car le vecteur est stocké sous un nom valuesfixe. Le remplacement du nom de propriété est effectué en définissant l’option StorageName via les attributs du modèle de données ou la définition d’enregistrement.

Voici un exemple de modèle de données avec StorageName configuré sur ses attributs et la manière dont cela sera représenté dans 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." }
}

Vue d’ensemble

Le connecteur Pinecone Vector Store peut être utilisé pour accéder aux données et les gérer dans Pinecone. Le connecteur présente les caractéristiques suivantes.

Mise en route

Ajoutez le connecteur Pinecone Vector Store supplémentaire à votre projet.

pip install semantic-kernel[pinecone]

Vous pouvez ensuite créer une instance PineconeStore et l’utiliser pour créer une collection. Cette opération lit la clé API Pinecone à partir de la variable d’environnement PINECONE_API_KEY.

from semantic_kernel.connectors.pinecone import PineconeStore

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

Il est possible de construire une référence directe à une collection nommée.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Vous pouvez également créer votre propre client Pinecone et le transmettre au constructeur. Le client doit être soit PineconeAsyncio, soit PineconeGRPC (voir prise en charge de GRPC).

from semantic_kernel.connectors.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", record_type=DataModel)

Prise en charge de GRPC

Nous prenons également en charge deux options sur le constructeur de collection, dont la première active la prise en charge de GRPC :

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Ou avec votre propre client :

from semantic_kernel.connectors.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", record_type=DataModel)

Incorporations intégrées

La seconde consiste à utiliser les incorporations intégrées de Pinecone, ce qui recherche une variable d’environnement appelée PINECONE_EMBED_MODEL avec le nom du modèle, ou vous pouvez passer une dictée embed_settings, qui peut contenir uniquement la clé de modèle, ou les paramètres complets du modèle incorporé. Dans l’ancien cas, les autres paramètres seront dérivés de la définition du modèle de données.

Consultez la documentation Pinecone, puis les sections Use integrated embeddings.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Vous pouvez également passer les paramètres d'incorporation dans le constructeur lorsque vous ne définissez pas la variable d'environnement.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Cela peut inclure d’autres détails sur la configuration vectorielle, comme la métrique et le mappage de champs. Vous pouvez également transmettre les paramètres incorporés à la méthode ensure_collection_exists, ce qui remplace les paramètres par défaut définis lors de l’initialisation.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Important : les incorporations GRPC et intégrées ne peuvent pas être utilisées ensemble.

Espace de noms d’index

L’abstraction Vector Store ne prend pas en charge de mécanisme de regroupement d’enregistrements à plusieurs niveaux. Les collections dans l'abstraction correspondent à un index serverless Pinecone et aucun deuxième niveau n'existe dans l'abstraction. Pinecone prend en charge un deuxième niveau de regroupement appelé espaces de noms.

Par défaut, le connecteur Pinecone passe '' en tant qu’espace de noms pour toutes les opérations. Toutefois, il est possible de passer un espace de noms unique à la collection Pinecone lors de sa construction et de l’utiliser à la place pour toutes les opérations.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Le connecteur Pinecone n’est pas encore disponible en Java.