Поделиться через

Использование соединителя Pinecone (предварительная версия)

Предупреждение

Функция векторного хранилища Pinecone находится в предварительной версии, и улучшения, требующие критических изменений, могут по-прежнему возникать в ограниченных обстоятельствах перед выпуском.

Предупреждение

Функции хранилища векторов семантического ядра доступны в предварительной версии, и улучшения, требующие кардинальных изменений, все еще могут возникнуть в отдельных случаях перед выпуском.

Предупреждение

Функции хранилища векторов семантического ядра доступны в предварительной версии, и улучшения, требующие кардинальных изменений, все еще могут возникнуть в отдельных случаях перед выпуском.

Обзор

Соединитель Pinecone Vector Store можно использовать для доступа к данным и управления ими в Pinecone. Соединитель имеет следующие характеристики.

Область функций Поддержка
Коллекция сопоставляется с Бессерверный индекс Pinecone
Поддерживаемые типы свойств ключей строка
Поддерживаемые типы свойств данных
  • строка
  • INT
  • длинный
  • двойной
  • плавающий
  • булевая переменная (bool)
  • десятичная дробь
  • Перечисляемые объекты типа строка
Поддерживаемые типы свойств вектора
  • ПамятьТолькоДляЧтения<float>
  • Внедрение с плавающей запятой<>
  • float[]
Поддерживаемые типы индексов PGA (Алгоритм Графа Снайконе)
Поддерживаемые функции расстояния
  • CosineSimilarity
  • DotProductSimilarity
  • Евклидово квадратное расстояние
Поддерживаемые условия фильтрации
  • EqualTo
Поддержка нескольких векторов в записи Нет
Поддерживается ли функция IsIndexed? Да
Поддерживается ли полнотекстовый индекс? Нет
Поддерживается StorageName? Да
Поддерживается гибридный поиск? Нет
Поддерживаемые интегрированные внедрения? Нет

Начало работы

Добавьте в проект пакет NuGet коннектора Pinecone Vector Store.

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 требует, чтобы свойства сопоставлялись с идентификаторами, метаданными и группами значений. Средство сопоставления по умолчанию использует аннотации модели или определение записи для определения типа каждого свойства и выполнения сопоставления.

  • Свойство модели данных, помеченное как ключ, будет сопоставлено с свойством Идентификатора Pinecone.
  • Свойства модели данных, аннотированные как данные будут сопоставлены с объектом метаданных Pinecone.
  • Свойство модели данных, помеченное как вектор, будет сопоставлено со свойством вектора Pinecone.

Переопределение имени свойства

Для свойств данных можно указать заменяющие имена полей для использования в хранилище, отличающемся от имен свойств в модели данных. Это не поддерживается для ключей, так как ключ имеет фиксированное имя в 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 Vector Store можно использовать для доступа к данным и управления ими в Pinecone. Соединитель имеет следующие характеристики.

Область функций Поддержка
Коллекция сопоставляется с Бессерверный индекс Pinecone
Поддерживаемые типы свойств ключей строка
Поддерживаемые типы свойств данных
  • строка
  • INT
  • длинный
  • двойной
  • плавающий
  • десятичная дробь
  • булевая переменная (bool)
  • дата и время
  • и итерируемые объекты каждого из этих типов
Поддерживаемые типы свойств вектора
  • список[float]
  • список[int]
  • массив numpy
Поддерживаемые типы индексов PGA (Алгоритм Графа Снайконе)
Поддерживаемые функции расстояния
  • CosineSimilarity
  • DotProductSimilarity
  • Евклидово квадратное расстояние
Поддерживаемые условия фильтрации
  • EqualTo
  • AnyTagEqualTo
Поддержка нескольких векторов в записи Нет
Поддерживается IsFilterable? Да
Поддерживается ЛиFullTextSearchable? Нет
Поддерживаемые интегрированные внедрения? Да, смотрите здесь
Поддерживается GRPC? Да, смотрите здесь

Начало работы

Добавьте в проект дополнительный коннектор Pinecone Vector Store.

pip install semantic-kernel[pinecone]

Затем можно создать экземпляр PineconeStore и использовать его для создания коллекции. Это будет считывать ключ API Pinecone из переменной среды PINECONE_API_KEY.

from semantic_kernel.connectors.pinecone import PineconeStore

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

Можно создать прямую ссылку на именованную коллекцию.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Вы также можете создать собственный клиент Pinecone и передать его в конструктор. Клиент должен быть PineconeAsyncio или PineconeGRPC (см. поддержку 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)

Поддержка GRPC

Мы также поддерживаем два варианта конструктора коллекции, первое — включить поддержку GRPC:

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Или с собственным клиентом:

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)

Интегрированные внедрения

Во-вторых, следует использовать интегрированные вложения Pinecone, это проверяет переменную среды, которая называется PINECONE_EMBED_MODEL с именем модели, или можно передать в embed_settings словарь, который может содержать только ключ модели или полные параметры для модели вложения. В предыдущем случае другие параметры будут производными от определения модели данных.

Обратитесь к документации по Pinecone , а затем к разделам Use integrated embeddings.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Кроме того, если переменная среды не задана, можно передать параметры внедрения в конструктор:

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Это может включать другие сведения о настройке векторов, таких как сопоставление метрик и полей. Вы также можете передать настройки внедрения в метод ensure_collection_exists, это переопределит настройки по умолчанию, установленные во время инициализации.

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

Важно: интеграции GRPC и внедренные в систему элементы нельзя использовать вместе.

Пространство имен индекса

Абстракция векторного хранилища не поддерживает многоуровневый механизм группировки записей. Коллекции в карте абстракции отображаются на бессерверный индекс Pinecone, и второго уровня в абстракции не существует. Pinecone поддерживает второй уровень группировки, называемый пространствами имен.

По умолчанию соединитель Pinecone передает '' в качестве пространства имен для всех операций. Однако при конструировании коллекции Pinecone можно передать единственное пространство имен и использовать его для всех операций.

from semantic_kernel.connectors.pinecone import PineconeCollection

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

Соединитель Pinecone еще недоступен в Java.