Compartilhar via

Usando o conector Pinecone (versão prévia)

Aviso

A funcionalidade do Pinecone Vector Store está em versão prévia e melhorias que exigem alterações significativas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Aviso

A funcionalidade do Armazenamento de vetores do kernel semântico está em versão preliminar, e melhorias que exijam mudanças significativas ainda podem ocorrer em circunstâncias limitadas antes da versão.

Aviso

A funcionalidade do Armazenamento de vetores do kernel semântico está em versão preliminar, e melhorias que exijam mudanças significativas ainda podem ocorrer em circunstâncias limitadas antes da versão.

Visão geral

O conector do Pinecone Vector Store pode ser usado para acessar e gerenciar dados no Pinecone. O conector tem as seguintes características.

Área de funcionalidades Suporte
Mapas de coleção para Índice Pinecone sem servidor
Tipos de propriedades chave com suporte cadeia de caracteres
Tipos de propriedade de dados com suporte
  • cadeia de caracteres
  • int
  • long
  • double
  • float
  • bool
  • decimal
  • enumeráveis do tipo cadeia de caracteres
Tipos de propriedades vetoriais suportadas
  • ReadOnlyMemory<float>
  • Embedding<float>
  • float[]
Tipos de índice com suporte PGA (Algoritmo de Grafos Pinecone)
Funções de distância suportadas
  • CosineSimilarity
  • DotProductSimilarity
  • EuclideanSquaredDistance
Cláusulas de filtro com suporte
  • EqualTo
Suporta vários vetores em um registro Não
Há suporte para IsIndexed? Sim
Há suporte paraFullTextIndexed? Não
Existe suporte para StorageName? Sim
O HybridSearch é suportado? Não
Existe suporte para Incorporações Integradas? Não

Primeiros Passos

Adicione o pacote NuGet do conector de Armazenamento de Vetor Pinecone ao seu projeto.

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

Você pode adicionar o repositório de vetores ao contêiner de injeção de dependência disponível no KernelBuilder ou ao IServiceCollection contêiner de injeção de dependência usando métodos de extensão fornecidos pelo Semantic Kernel.

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

Métodos de extensão que não usam parâmetros também são fornecidos. Isso exige que uma instância do PineconeClient seja registrada no contêiner de injeção de dependência separadamente.

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

Você pode construir uma instância do Repositório Vetorial Pinecone diretamente.

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

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

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

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

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

Namespace do índice

A abstração do Repositório de Vetores não oferece suporte a um mecanismo de agrupamento de registros de várias camadas. As coleções na abstração são mapeadas para um índice sem servidor Pinecone e não existe nenhum segundo nível na abstração. O Pinecone suporta um segundo nível de agrupamento chamado namespaces.

Por padrão, o conector Pinecone passará null como o namespace para todas as operações. No entanto, é possível passar um único namespace para a coleção Pinecone ao construí-la e usá-lo para todas as operações.

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

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

Mapeamento de dados

O conector Pinecone fornece um mapeador padrão ao mapear dados do modelo de dados para armazenamento. O Pinecone requer que as propriedades sejam mapeadas em agrupamentos de id, metadados e valores. O mapeador padrão usa as anotações do modelo ou a definição de registro para determinar o tipo de cada propriedade e fazer esse mapeamento.

  • A propriedade do modelo de dados anotada como uma chave será mapeada para a propriedade ID do Pinecone.
  • As propriedades do modelo de dados anotadas como dados serão mapeadas para o objeto de metadados Pinecone.
  • A propriedade do modelo de dados anotada como vetor será mapeada para a propriedade vetorial Pinecone.

Substituição do nome da propriedade

Para propriedades de dados, você pode fornecer nomes de campo de substituição a serem usados no armazenamento que sejam diferentes dos nomes de propriedade no modelo de dados. Isso não é suportado para chaves, pois uma chave tem um nome fixo no Pinecone. Também não é suportado para vetores, uma vez que o vetor é armazenado sob um nome valuesfixo . A substituição do nome da propriedade é feita definindo a opção StorageName por meio dos atributos do modelo de dados ou da definição de registro.

Aqui está um exemplo de um modelo de dados com StorageName aplicado aos seus atributos e como ele será representado no 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." }
}

Visão geral

O conector do Pinecone Vector Store pode ser usado para acessar e gerenciar dados no Pinecone. O conector tem as seguintes características.

Área de funcionalidades Suporte
Mapas de coleção para Índice Pinecone sem servidor
Tipos de propriedades chave com suporte cadeia de caracteres
Tipos de propriedade de dados com suporte
  • cadeia de caracteres
  • int
  • long
  • double
  • float
  • decimal
  • bool
  • Data e Hora
  • e iteráveis de cada um desses tipos
Tipos de propriedades vetoriais suportadas
  • list[float]
  • lista[int]
  • matriz numpy
Tipos de índice com suporte PGA (Algoritmo de Grafos Pinecone)
Funções de distância suportadas
  • CosineSimilarity
  • DotProductSimilarity
  • EuclideanSquaredDistance
Cláusulas de filtro com suporte
  • EqualTo
  • AnyTagEqualTo
Suporta vários vetores em um registro Não
IsFilterable é suportado? Sim
IsFullTextSearchable é suportado? Não
Existe suporte para Incorporações Integradas? Sim, veja aqui
GRPC é suportado? Sim, veja aqui

Primeiros Passos

Adicione o conector do Pinecone Vector Store como extra ao seu projeto.

pip install semantic-kernel[pinecone]

Em seguida, você pode criar uma instância pineconeStore e usá-la para criar uma coleção. Isso lerá a chave da API Pinecone da variável de ambiente PINECONE_API_KEY.

from semantic_kernel.connectors.pinecone import PineconeStore

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

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

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Você também pode criar seu próprio cliente Pinecone e passá-lo para o construtor. O cliente precisa ser PineconeAsyncio ou PineconeGRPC (consulte Suporte 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)

Suporte a GRPC

Também oferecemos suporte a duas opções no construtor de coleção, a primeira é habilitar o suporte a GRPC:

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Ou com seu próprio cliente:

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)

Inserções Integradas

A segunda é usar as inserções integradas do Pinecone, isso verificará se há uma variável de ambiente chamada PINECONE_EMBED_MODEL com o nome do modelo ou você pode passar um ditado embed_settings, que pode conter apenas a chave de modelo ou as configurações completas para o modelo de inserção. No caso anterior, as outras configurações serão derivadas da definição do modelo de dados.

Consulte documentos Pinecone e, em seguida, as seções Use integrated embeddings.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Como alternativa, quando não configura a variável de ambiente, você pode passar as configurações de inserção para o construtor:

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Isso pode incluir outros detalhes sobre a configuração do vetor, como métrica e mapeamento de campo. Você também pode passar as configurações de inserção para o método ensure_collection_exists, o que substituirá as configurações padrão definidas durante a inicialização.

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"})

Importante: GRPC e embeddings integrados não podem ser usados em conjunto.

Namespace do índice

A abstração do Repositório de Vetores não oferece suporte a um mecanismo de agrupamento de registros de várias camadas. As coleções na abstração são mapeadas para um índice sem servidor Pinecone e não existe nenhum segundo nível na abstração. O Pinecone suporta um segundo nível de agrupamento chamado namespaces.

Por padrão, o conector pinecone passará '' como o namespace para todas as operações. No entanto, é possível passar um único namespace para a coleção Pinecone ao construí-la e usá-lo para todas as operações.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

O conector Pinecone ainda não está disponível em Java.