Azure CosmosDB NoSQL ベクター ストア コネクタの使用 (プレビュー)

警告

セマンティック カーネル ベクター ストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

概要

Azure CosmosDB NoSQL ベクター ストア コネクタを使用して、Azure CosmosDB NoSQL のデータにアクセスして管理できます。 コネクタには次の特性があります。

機能領域	サポート
コレクションのマップ	Azure Cosmos DB NoSQL コンテナー
サポートされているキー プロパティの種類	string AzureCosmosDBNoSQLCompositeKey
サポートされているデータ プロパティ型	string INT long 倍精度浮動小数点 float [bool] DateTimeOffset これらの各型の列挙可能な値
サポートされているベクター プロパティ型	ReadOnlyMemory<float> ReadOnlyMemory<byte> ReadOnlyMemory<sbyte> ReadOnlyMemory<Half>
サポートされているインデックスの種類	フラット クオンタイズドフラット DiskAnn
サポートされている距離関数	CosineSimilarity DotProductSimilarity EuclideanDistance
サポートされているフィルター句	AnyTagEqualTo EqualTo
レコード内の複数のベクターをサポートします	はい
IsFilterable がサポートされていますか?	はい
IsFullTextSearchable がサポートされていますか?	はい
StoragePropertyName がサポートされていますか?	いいえ。代わりに JsonSerializerOptions と JsonPropertyNameAttribute を使用してください。 詳細については、こちらを参照してください。

制限

CosmosClient を手動で初期化するときは、既定のシリアライザーの制限により、CosmosClientOptions.UseSystemTextJsonSerializerWithOptions を指定する必要があります。 このオプションは、JsonSerializerOptions.Default に設定することも、特定の構成ニーズを満たすために他のシリアライザー オプションと共にカスタマイズすることもできます。

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

作業の開始

Azure CosmosDB NoSQL ベクター ストア コネクタ NuGet パッケージをプロジェクトに追加します。

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 の使用がサポートされます。 唯一の例外は、すべての CosmosDB NoSQL レコードで ID にこの名前を使用する必要があるため、 idという名前のデータベース フィールドにマップされるレコードのキーです。

カスタマイズされたプロパティの名前付けポリシーでカスタム 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 for NoSQL コネクタでは、パーティション キー プロパティの既定値はキー プロパティ (id) です。 AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> クラスの PartitionKeyPropertyName プロパティを使用すると、パーティション キーとして別のプロパティを指定できます。

AzureCosmosDBNoSQLVectorStoreRecordCollection クラスは、string と AzureCosmosDBNoSQLCompositeKeyの 2 つのキー型をサポートしています。 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"));

間もなく利用できます

詳細については、近日公開予定です。

間もなく利用できます

詳細については、近日公開予定です。