データ モデルを定義する

Microsoft.Extensions.VectorData では、データベースとの対話にモデル優先のアプローチを使用します。

レコードをアップサートまたは取得するすべてのメソッドでは、厳密に型指定されたモデル クラスが使用されます。 データ モデルを定義するには、次の 2 つの方法があります。

• 各プロパティの目的を示す 属性 を使用して、モデル クラスのプロパティを修飾します。
• データ モデルとは別に指定する レコード定義 を使用して、ストレージ スキーマを定義します。 レコード定義は、プロパティを含むVectorStoreCollectionDefinitionです。

属性

プロパティが VectorStore*Attribute 属性で修飾されているクラスまたはデータ モデルの例を次に示します。

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

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

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

    [VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public required string[] Tags { get; set; }
}

レコード定義

レコード定義の例を次に示します。

VectorStoreCollectionDefinition hotelDefinition = new()
{
    Properties =
    [
        new VectorStoreKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },
        new VectorStoreDataProperty("Description", typeof(string)) { IsFullTextIndexed = true },
        new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4)
        {
            DistanceFunction = DistanceFunction.CosineSimilarity,
            IndexKind = IndexKind.Hnsw
        },
    ]
};

レコード定義を作成するときは、スキーマ内の各プロパティの名前と型を指定します。この情報はインデックスの作成とデータ マッピングに必要であるためです。

定義を使用するには、 GetCollection<TKey,TRecord>(String, VectorStoreCollectionDefinition) メソッドに渡します。

VectorStoreCollection<ulong, Hotel> collection =
    vectorStore.GetCollection<ulong, Hotel>("hotels", hotelDefinition);

レコード定義アプローチは、次の場合に役立ちます。

• 複数の構成で同じデータ モデルを使用する必要があります。
• Dictionaryなどの組み込み型、またはデータフレームなどの最適化された形式を使用し、ベクター ストア機能を引き続き活用する必要があります。

データ モデルのプロパティ属性

ベクター データベースのデータ モデルを定義する VectorStore*Attribute 属性は次のとおりです。

• VectorStoreKeyAttribute
• VectorStoreDataAttribute
• VectorStoreVectorAttribute

VectorStoreKeyAttribute

プロパティがレコードの主キーであることを示すには、 VectorStoreKeyAttribute 属性を使用します。

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

次の表に、 VectorStoreKeyAttributeのパラメーターを示します。

パラメーター	必須	説明
StorageName	いいえ	データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、たとえば、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのプロバイダーでサポートされているわけではありません。

VectorStoreDataAttribute

VectorStoreDataAttribute属性を使用して、プロパティにキーまたはベクターではない一般的なデータが含まれていることを示します。

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

次の表に、 VectorStoreDataAttributeのパラメーターを示します。

パラメーター	必須	説明
IsIndexed	いいえ	データベースでプロパティごとのインデックス作成をオプトインする必要がある場合に、フィルター処理のためにプロパティのインデックスを作成するかどうかを示します。 既定値は、false です。
IsFullTextIndexed	いいえ	フルテキスト検索をサポートするデータベースのフルテキスト検索に対してプロパティのインデックスを作成するかどうかを示します。 既定値は、false です。
StorageName	いいえ	データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのプロバイダーでサポートされているわけではありません。

VectorStoreVectorAttribute

プロパティにベクターが含まれていることを示すには、 VectorStoreVectorAttribute 属性を使用します。

[VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

ベクター型を持たないプロパティ (たとえば、string型のプロパティ) でVectorStoreVectorAttributeを使用することもできます。 この方法でプロパティを修飾する場合は、ベクター ストアに IEmbeddingGenerator インスタンスを指定する必要があります。 レコードをアップサートすると、 string プロパティ内のテキストが自動的に変換され、データベース内のベクターとして格納されます。 (このメカニズムを使用してベクターを取得することはできません)。

[VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
public string DescriptionEmbedding { get; set; }

ヒント

組み込みの埋め込み生成を使用する方法の詳細については、「 ベクター ストアで埋め込みを生成できるようにする」を参照してください。

次の表に、 VectorStoreVectorAttributeのパラメーターを示します。

パラメーター	必須	説明
Dimensions	はい	ベクトルに含まれる次元の数。 これは、コレクションのベクター インデックスを作成するときに必要です。
IndexKind	いいえ	ベクターにインデックスを付けるインデックスの型。 既定値は、ベクター ストアの種類によって異なります。
DistanceFunction	いいえ	このベクターのベクター検索中にベクター比較を行うときに使用する関数の型。 既定値は、ベクター ストアの種類によって異なります。
StorageName	いいえ	データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのプロバイダーでサポートされているわけではありません。

一般的なインデックスの種類と距離関数の種類は、 IndexKind クラスと DistanceFunction クラスで静的な値として提供されます。 個々のベクター ストアの実装では、独自のインデックスの種類と距離関数を使用する場合もあります。データベースでは通常とは異なる型がサポートされています。

レコード定義のプロパティ

VectorStore*Property クラスを使用して、データ モデルに渡すレコード定義を作成します。

• VectorStoreKeyProperty
• VectorStoreDataProperty
• VectorStoreVectorProperty

VectorStoreKeyProperty

プロパティがレコードのキーであることを示すには、 VectorStoreKeyProperty クラスを使用します。

new VectorStoreKeyProperty("HotelId", typeof(ulong)),

次の表に、 VectorStoreKeyPropertyの構成設定を示します。

パラメーター	必須	説明
Name	はい	データ モデルのプロパティの名前。 マッパーが、ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために使用されます。
Type	いいえ	データ モデルのプロパティの型。 マッパーが、ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために使用されます。
StorageName	いいえ	データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのプロバイダーでサポートされているわけではありません。

VectorStoreDataProperty

VectorStoreDataProperty クラスを使用して、プロパティにキーまたはベクターではない一般的なデータが含まれていることを示します。

new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },
new VectorStoreDataProperty("Description", typeof(string)) { IsFullTextIndexed = true },

次の表に、 VectorStoreDataPropertyの構成設定を示します。

パラメーター	必須	説明
Name	はい	データ モデルのプロパティの名前。 マッパーが、ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために使用されます。
Type	いいえ	データ モデルのプロパティの型。 マッパーが、ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために使用されます。
IsIndexed	いいえ	データベースでプロパティごとのインデックス作成をオプトインする必要がある場合に、フィルター処理のためにプロパティのインデックスを作成するかどうかを示します。 既定値は falseです。
IsFullTextIndexed	いいえ	フルテキスト検索をサポートするデータベースのフルテキスト検索に対してプロパティのインデックスを作成するかどうかを示します。 既定値は falseです。
StorageName	いいえ	データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのプロバイダーでサポートされているわけではありません。

VectorStoreVectorProperty

プロパティにベクターが含まれていることを示すには、 VectorStoreVectorProperty クラスを使用します。

new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4)

次の表に、 VectorStoreVectorPropertyの構成設定を示します。

パラメーター	必須	説明
Name	はい	データ モデルのプロパティの名前。 マッパーが、ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために使用されます。
Type	いいえ	データ モデルのプロパティの型。 マッパーが、ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために使用されます。
Dimensions	はい	ベクトルに含まれる次元の数。 これは、コレクションのベクター インデックスを作成するために必要です。
IndexKind	いいえ	ベクターにインデックスを付けるインデックスの型。 既定値は、ベクター ストアの種類によって異なります。
DistanceFunction	いいえ	このベクターのベクター検索中にベクター比較を行うときに使用する関数の型。 既定値は、ベクター ストアの種類によって異なります。
StorageName	いいえ	データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのプロバイダーでサポートされているわけではありません。
EmbeddingGenerator	いいえ	装飾プロパティの埋め込みを自動的に生成するために使用する Microsoft.Extensions.AI.IEmbeddingGenerator インスタンスを指定できます。

データ モデルを定義せずにベクター ストアの抽象化を使用する

独自のデータ モデルを定義するのが望ましくない、または不可能な場合があります。 たとえば、コンパイル時にデータベース スキーマがどのように見えるかが分からず、スキーマは構成によってのみ提供されるとします。 この場合、スキーマを反映するデータ モデルを作成することはできません。 代わりに、レコードの種類のDictionary<string, object?>を使用して動的にマップできます。 プロパティは、プロパティ名としてキーを、値をプロパティ値として使用して、 Dictionary に追加されます。

注

ほとんどのアプリでは、厳密に型指定された .NET 型を使用してデータをモデル化するだけです。 Dictionary<string, object?>を介した動的マッピングは、高度な任意のデータ マッピング シナリオ用です。

使用するときにスキーマ情報を指定する Dictionary

Dictionaryを使用する場合でも、プロバイダーはデータベース スキーマの外観を把握する必要があります。 スキーマ情報がないと、プロバイダーはコレクションを作成したり、各データベースが使用するストレージ表現との間のマッピング方法を把握したりできなくなります。

レコード定義を使用して、スキーマ情報を指定できます。 データ モデルとは異なり、コンパイル時にスキーマ情報が不明な場合は、 実行時 に構成からレコード定義を作成できます。

例

プロバイダーで Dictionary を使用するには、コレクションを作成するときにデータ モデルとして指定します。 レコード定義も指定します。

VectorStoreCollectionDefinition definition = new()
{
    Properties =
    [
        new VectorStoreKeyProperty("Key", typeof(string)),
        new VectorStoreDataProperty("Term", typeof(string)),
        new VectorStoreDataProperty("Definition", typeof(string)),
        new VectorStoreVectorProperty("DefinitionEmbedding", typeof(ReadOnlyMemory<float>), dimensions: 1536)
    ]
};

// Use GetDynamicCollection instead of the regular GetCollection method
// to get an instance of a collection using Dictionary<string, object?>.
VectorStoreCollection<object, Dictionary<string, object?>> dynamicDataModelCollection =
    vectorStore.GetDynamicCollection("glossary", definition);

// Since schema information is available from the record definition,
// it's possible to create a collection with the right vectors,
// dimensions, indexes, and distance functions.
await dynamicDataModelCollection.EnsureCollectionExistsAsync();

// When retrieving a record from the collection,
// access key, data, and vector values via the dictionary entries.
Dictionary<string, object?>? record = await dynamicDataModelCollection.GetAsync("SK");
Console.WriteLine(record["Definition"]);