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

警告

Azure CosmosDB MongoDB (仮想コア) ベクター ストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

警告

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

警告

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

概要

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

機能領域	サポート
コレクションは～に対応する	Azure Cosmos DB MongoDB (仮想コア) コレクション + インデックス
サポートされているキー プロパティの種類	ストリング
サポートされているデータ プロパティ型	ストリング 整数 長い 倍 浮動小数点数 小数 ブール (bool) 日付時刻 これらの各型の列挙可能体
サポートされているベクター プロパティ型	読み取り専用メモリ<float> 埋め込み<float> float[]
サポートされているインデックスの種類	Hnsw IvfFlat
サポートされている距離関数	CosineDistance ドットプロダクトシミラリティ EuclideanDistance
サポートされているフィルター句	EqualTo
レコード内の複数のベクターをサポートします	はい
IsIndexed はサポートされていますか?	はい
IsFullTextIndexed がサポートされていますか?	いいえ
StorageName がサポートされていますか?	いいえ。代わりに BsonElementAttribute を使用してください。 詳細については、こちらを参照してください。
HybridSearch はサポートされていますか?	いいえ

機能領域	サポート
コレクションは～に対応する	Azure Cosmos DB MongoDB (仮想コア) コレクション + インデックス
サポートされているキー プロパティの種類	ストリング
サポートされているデータ プロパティ型	ストリング 整数 長い 倍 浮動小数点数 小数 ブール (bool) 日付時刻 これらの各型のイテラブル
サポートされているベクター プロパティ型	リスト[float] リスト[整数] ndarray
サポートされているインデックスの種類	Hnsw IvfFlat
サポートされている距離関数	CosineDistance ドットプロダクトシミラリティ EuclideanDistance
サポートされているフィルター句	EqualTo AnyTagsEqualTo
レコード内の複数のベクターをサポートします	はい
IsFilterable がサポートされていますか?	はい
IsFullTextSearchable がサポートされていますか?	いいえ

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

制限

このコネクタは Azure Cosmos DB MongoDB (仮想コア) と互換性があり、Azure Cosmos DB MongoDB (RU) とは互換性が ない ように設計されています。

作業の開始

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

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

セマンティック カーネルによって提供される拡張メソッドを使用して、 KernelBuilder で使用できる依存関係挿入コンテナーまたは IServiceCollection 依存関係挿入コンテナーにベクター ストアを追加できます。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

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

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

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

パラメーターを受け取たない拡張メソッドも提供されます。 これらには、 MongoDB.Driver.IMongoDatabase のインスタンスを依存関係挿入コンテナーに個別に登録する必要があります。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using MongoDB.Driver;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<IMongoDatabase>(
    sp =>
    {
        var mongoClient = new MongoClient(connectionString);
        return mongoClient.GetDatabase(databaseName);
    });
kernelBuilder.Services.AddCosmosMongoVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using MongoDB.Driver;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IMongoDatabase>(
    sp =>
    {
        var mongoClient = new MongoClient(connectionString);
        return mongoClient.GetDatabase(databaseName);
    });
builder.Services.AddCosmosMongoVectorStore();

Azure CosmosDB MongoDB ベクター ストア インスタンスを直接構築できます。

using Microsoft.SemanticKernel.Connectors.CosmosMongoDB;
using MongoDB.Driver;

var mongoClient = new MongoClient(connectionString);
var database = mongoClient.GetDatabase(databaseName);
var vectorStore = new CosmosMongoVectorStore(database);

名前付きコレクションへの直接参照を構築できます。

using Microsoft.SemanticKernel.Connectors.CosmosMongoDB;
using MongoDB.Driver;

var mongoClient = new MongoClient(connectionString);
var database = mongoClient.GetDatabase(databaseName);
var collection = new CosmosMongoCollection<ulong, Hotel>(
    database,
    "skhotels");

データ マッピング

Azure CosmosDB MongoDB ベクター ストア コネクタは、データ モデルからストレージにデータをマッピングするときに、既定のマッパーを提供します。

このマッパーは、データ モデルのプロパティの一覧を Azure CosmosDB MongoDB のフィールドに直接変換し、 MongoDB.Bson.Serialization を使用してストレージ スキーマに変換します。 つまり、データ モデルのプロパティ名に別のストレージ名が必要な場合は、 MongoDB.Bson.Serialization.Attributes.BsonElement の使用がサポートされます。 唯一の例外は、すべての CosmosDB MongoDB レコードで ID にこの名前を使用する必要があるため、 _idという名前のデータベース フィールドにマップされるレコードのキーです。

プロパティ名のオーバーライド

データ プロパティとベクター プロパティの場合、データ モデルのプロパティ名とは異なるストレージで使用するオーバーライド フィールド名を指定できます。 MongoDB ではキーの名前が固定されているため、これはキーではサポートされません。

プロパティ名のオーバーライドは、データ モデルのプロパティに BsonElement 属性を設定することによって行われます。

BsonElementセットを持つデータ モデルの例を次に示します。

using Microsoft.Extensions.VectorData;

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

    [BsonElement("hotel_name")]
    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

    [BsonElement("hotel_description")]
    [VectorStoreData(IsFullTextIndexed = true)]
    public string Description { get; set; }

    [BsonElement("hotel_description_embedding")]
    [VectorStoreVector(4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

作業の開始

Azure CosmosDB MongoDB ベクター ストアの依存関係を環境に追加します。 Azure CosmosDB MongoDB コネクタは MongoDB Atlas コネクタ上に構築され、そのクライアントと同じクライアントを使用するため、次の追加機能を使用してインストールする必要があります。

pip install semantic-kernel[azure, mongo]

その後、ベクター ストアを作成できます。

from semantic_kernel.connectors.azure_cosmos_db import CosmosMongoStore

# If the right environment settings are set, namely AZURE_COSMOS_DB_MONGODB_CONNECTION_STRING and optionally AZURE_COSMOS_DB_MONGODB_DATABASE_NAME, this is enough to create the Store:
store = CosmosMongoStore()

または、クライアントの構築をより詳細に制御する場合は、独自の mongodb クライアントを渡すこともできます。

from pymongo import AsyncMongoClient
from semantic_kernel.connectors.azure_cosmos_db import CosmosMongoStore

client = AsyncMongoClient(...)
store = CosmosMongoStore(mongo_client=client)

クライアントが渡されると、セマンティック カーネルは接続を閉じないため、async with ステートメントなどを使用して接続を閉じる必要があります。

ストアを使用せずにコレクションを直接作成することもできます。

from semantic_kernel.connectors.azure_cosmos_db import CosmosMongoCollection

# `Hotel` is a class created with the @vectorstoremodel decorator
collection = CosmosMongoCollection(
    record_type=Hotel,
    collection_name="my_collection"
)

シリアル化

Azure CosmosDB for MongoDB コネクタでは、入力としてインデックスに対応するフィールドを含む単純な dict が必要であるため、シリアル化は非常に簡単です。事前に定義されたキー _idのみを使用するため、データ モデルのキーを、まだ _idされていない場合はそれに置き換えます。

この概念の詳細については、シリアル化ドキュメントを参照してください。

まもなく

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