Использование соединителя Хранилища векторов Azure CosmosDB NoSQL (предварительная версия)

Статья
01/23/2025

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

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

Обзор

Соединитель Хранилища векторов Azure CosmosDB NoSQL можно использовать для доступа к данным и управления ими в Azure CosmosDB NoSQL. Соединитель имеет следующие характеристики.

Область функций	Поддержка
Коллекция сопоставляется с	Контейнер NoSQL Azure Cosmos DB
Поддерживаемые типы свойств ключей	строка AzureCosmosDBNoSQLCompositeKey
Поддерживаемые типы свойств данных	строка INT длинный двойной точности с плавающей запятой bool DateTimeOffset и перечисление каждого из этих типов
Поддерживаемые типы свойств вектора	ReadOnlyMemory<float> Байт ReadOnlyMemory<> ReadOnlyMemory<sbyte> ReadOnlyMemory<Half>
Поддерживаемые типы индексов	Фиксированная QuantizedFlat DiskAnn
Поддерживаемые функции расстояния	CosineSimilarity DotProductSimilarity EuclideanDistance
Поддерживаемые предложения фильтров	AnyTagEqualTo EqualTo
Поддержка нескольких векторов в записи	Да
Поддерживается IsFilterable?	Да
Поддерживается ЛиFullTextSearchable?	Да
Поддерживается StoragePropertyName?	Нет, используйте `JsonSerializerOptions` и `JsonPropertyNameAttribute` вместо этого. Дополнительные сведения см. здесь.

Ограничения

При инициализации CosmosClient вручную необходимо указать CosmosClientOptions.UseSystemTextJsonSerializerWithOptions из-за ограничений в сериализаторе по умолчанию. Этот параметр можно задать для JsonSerializerOptions.Default или настроить с другими параметрами сериализатора в соответствии с конкретными потребностями конфигурации.

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

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

Добавьте в проект пакет NuGet соединителя Azure CosmosDB NoSQL Vector Store.

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

Хранилище векторов можно добавить в контейнер внедрения зависимостей, доступный в KernelBuilder контейнере внедрения зависимостей или в IServiceCollection контейнер внедрения зависимостей, используя методы расширения, предоставляемые семантического ядра.

using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddAzureCosmosDBNoSQLVectorStore(connectionString, databaseName);

using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAzureCosmosDBNoSQLVectorStore(connectionString, databaseName);

Методы расширения, которые не принимают параметров, также предоставляются. Для них требуется, чтобы экземпляр Microsoft.Azure.Cosmos.Database регистрировался отдельно в контейнере внедрения зависимостей.

using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<Database>(
    sp =>
    {
        var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
        {
            // When initializing CosmosClient manually, setting this property is required 
            // due to limitations in default serializer. 
            UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
        });

        return cosmosClient.GetDatabase(databaseName);
    });
kernelBuilder.AddAzureCosmosDBNoSQLVectorStore();

using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<Database>(
    sp =>
    {
        var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
        {
            // When initializing CosmosClient manually, setting this property is required 
            // due to limitations in default serializer. 
            UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
        });

        return cosmosClient.GetDatabase(databaseName);
    });
builder.Services.AddAzureCosmosDBNoSQLVectorStore();

Вы можете напрямую создать экземпляр Хранилища векторов Azure CosmosDB NoSQL.

using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

var database = cosmosClient.GetDatabase(databaseName);
var vectorStore = new AzureCosmosDBNoSQLVectorStore(database);

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

using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

var database = cosmosClient.GetDatabase(databaseName);
var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(
    database,
    "skhotels");

Сопоставление данных

Соединитель Хранилища векторов Azure CosmosDB NoSQL предоставляет инструмент сопоставления по умолчанию при сопоставлении из модели данных в хранилище.

Этот модуль сопоставления выполняет прямое преобразование списка свойств модели данных в поля в Azure CosmosDB NoSQL и использует System.Text.Json.JsonSerializer для преобразования в схему хранилища. Это означает, что использование объекта JsonPropertyNameAttribute поддерживается, если требуется другое имя хранилища для имени свойства модели данных. Единственным исключением является ключ записи, сопоставленной с полем базы данных с именем id, так как все записи NoSQL CosmosDB должны использовать это имя для идентификаторов.

Также можно использовать пользовательский JsonSerializerOptions экземпляр с настраиваемой политикой именования свойств. Чтобы включить это, JsonSerializerOptions необходимо передать в AzureCosmosDBNoSQLVectorStoreRecordCollection строительство.

using System.Text.Json;
using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var jsonSerializerOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper };

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = jsonSerializerOptions
});

var database = cosmosClient.GetDatabase(databaseName);
var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(
    database,
    "skhotels",
    new() { JsonSerializerOptions = jsonSerializerOptions });

Используя приведенный выше пользовательский код JsonSerializerOptions , который используется SnakeCaseUpper, следующая модель данных будет сопоставлена с приведенным ниже json.

using System.Text.Json.Serialization;
using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public ulong HotelId { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string HotelName { get; set; }

    [VectorStoreRecordData(IsFullTextSearchable = true)]
    public string Description { get; set; }

    [JsonPropertyName("HOTEL_DESCRIPTION_EMBEDDING")]
    [VectorStoreRecordVector(4, DistanceFunction.EuclideanDistance, IndexKind.QuantizedFlat)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": 1,
    "HOTEL_NAME": "Hotel Happy",
    "DESCRIPTION": "A place where everyone can be happy.",
    "HOTEL_DESCRIPTION_EMBEDDING": [0.9, 0.1, 0.1, 0.1],
}

Использование ключа раздела

В соединителе Azure Cosmos DB для NoSQL свойство ключа секции по умолчанию установлено на свойство ключа — id. Свойство PartitionKeyPropertyName в классе AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> позволяет указать другое свойство в качестве ключа секции.

Класс AzureCosmosDBNoSQLVectorStoreRecordCollection поддерживает два ключевых типа: string и AzureCosmosDBNoSQLCompositeKey. AzureCosmosDBNoSQLCompositeKey состоит из RecordKey и PartitionKey.

Если свойство ключа секции не задано (и используется свойство ключа по умолчанию), string ключи можно использовать для операций с записями базы данных. Однако если задано свойство ключа раздела, рекомендуется использовать AzureCosmosDBNoSQLCompositeKey для предоставления значений ключа и ключа раздела.

Укажите имя свойства ключа раздела:

var options = new AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<Hotel>
{
    PartitionKeyPropertyName = nameof(Hotel.HotelName)
};

var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(database, "collection-name", options) 
    as IVectorStoreRecordCollection<AzureCosmosDBNoSQLCompositeKey, Hotel>;

Получение с использованием ключа разбивки:

var record = await collection.GetAsync(new AzureCosmosDBNoSQLCompositeKey("hotel-id", "hotel-name"));

Скоро

Дополнительные сведения в ближайшее время.

Скоро

Дополнительные сведения в ближайшее время.

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

Использование соединителя Хранилища векторов Azure CosmosDB NoSQL (предварительная версия)

Обзор

Ограничения

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

Сопоставление данных

Использование ключа раздела

Скоро

Скоро

Дополнительные ресурсы