データ モデルの定義 (プレビュー)
警告
セマンティック カーネル ベクター ストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。
概要
セマンティック カーネル ベクター ストア コネクタは、データベースとの対話にモデルの最初のアプローチを使用します。
レコードをアップサートまたは取得するすべてのメソッドでは、厳密に型指定されたモデル クラスが使用されます。 これらのクラスのプロパティは、各プロパティの目的を示す属性で修飾されます。
ヒント
属性を使用する代わりに、 レコード定義を使用したスキーマの定義を参照してください。
ヒント
独自のデータ モデルを定義する代わりに、独自のデータ モデルを定義せずにベクター ストアの抽象化を使用する を参照してください。
これらの属性で修飾されたモデルの例を次に示します。
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; }
[VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
[VectorStoreRecordData(IsFilterable = true)]
public string[] Tags { get; set; }
}
属性
VectorStoreRecordKeyAttribute
この属性を使用して、プロパティがレコードのキーであることを示します。
[VectorStoreRecordKey]
public ulong HotelId { get; set; }
VectorStoreRecordKeyAttribute パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| StoragePropertyName | いいえ | データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのコネクタでサポートされているわけではありません。 |
ヒント
StoragePropertyName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。
VectorStoreRecordDataAttribute
この属性を使用して、プロパティにキーまたはベクターではない一般的なデータが含まれていることを示します。
[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }
VectorStoreRecordDataAttribute パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| IsFilterable | いいえ | データベースでプロパティごとのインデックス作成をオプトインする必要がある場合に、フィルター処理のためにプロパティのインデックスを作成するかどうかを示します。 既定値は False です。 |
| IsFullTextSearchable | いいえ | フルテキスト検索をサポートするデータベースのフルテキスト検索に対してプロパティのインデックスを作成するかどうかを示します。 既定値は False です。 |
| StoragePropertyName | いいえ | データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのコネクタでサポートされているわけではありません。 |
ヒント
StoragePropertyName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。
VectorStoreRecordVectorAttribute
この属性を使用して、プロパティにベクターが含まれていることを示します。
[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
VectorStoreRecordVectorAttribute パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| Dimensions | コレクション作成の場合ははい。それ以外の場合は省略可能 | ベクトルに含まれる次元の数。 これは通常、コレクションのベクター インデックスを作成するときに必要です。 |
| IndexKind | いいえ | ベクターにインデックスを付けるインデックスの型。 既定値は、ベクター ストアの種類によって異なります。 |
| DistanceFunction | いいえ | このベクトルに対するベクトル検索中にベクトル比較を行うときに使用する距離関数の型。 既定値は、ベクター ストアの種類によって異なります。 |
| StoragePropertyName | いいえ | データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのコネクタでサポートされているわけではありません。 |
一般的なインデックスの種類と距離関数の種類は、 Microsoft.SemanticKernel.Data.IndexKind クラスと Microsoft.SemanticKernel.Data.DistanceFunction クラスで静的な値として提供されます。
個々のベクター ストアの実装では、データベースが通常とは異なる型をサポートする独自のインデックスの種類と距離関数を使用することもできます。
ヒント
StoragePropertyName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。
レコードをアップサートまたは取得するすべてのメソッドは、クラスとベクター ストア レコード定義を使用します。
これを行うには、フィールドの注釈を使用して独自のクラスを定義するか、クラス/型をレコード定義と組み合わせて使用します。 クラスに対して 2 つの作業を行う必要があります。1 つ目はフィールド型で注釈を追加することです。2 つ目は、クラスを vectorstoremodel デコレーターで装飾することです。
ヒント
レコード定義を使用する別の方法については、 レコード定義を使用したスキーマの定義を参照してください。
これらの注釈で装飾されたモデルの例を次に示します。
from dataclasses import dataclass, field
from typing import Annotated
from semantic_kernel.data import (
DistanceFunction,
IndexKind,
VectorStoreRecordDataField,
VectorStoreRecordDefinition,
VectorStoreRecordKeyField,
VectorStoreRecordVectorField,
vectorstoremodel,
)
@vectorstoremodel
@dataclass
class Hotel:
hotel_id: Annotated[str, VectorStoreRecordKeyField()] = field(default_factory=lambda: str(uuid4()))
hotel_name: Annotated[str, VectorStoreRecordDataField(is_filterable=True)]
description: Annotated[str, VectorStoreRecordDataField(is_full_text_searchable=True)]
description_embedding: Annotated[list[float], VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)]
tags: Annotated[list[str], VectorStoreRecordDataField(is_filterable=True)]
ヒント
これらの注釈を使用してクラスを定義するには、複数の方法で行うことができます。そのうちの 1 つは Python の dataclasses モジュールを使用しています。次に示します。 この サンプル では、他のアプローチ (Pydantic BaseModel とバニラ python クラスを使用) も示します。
注釈
使用する注釈には 3 種類あり、共通の基底クラスがあります。
VectorStoreRecordField
これはすべての注釈の基本クラスであり、直接使用するためのものではありません。
VectorStoreRecordField パラメーター
| パラメーター | 必須 | 内容 |
|---|---|---|
| name | いいえ | 直接追加できますが、モデルの解析中に設定されます。 |
| property_type | いいえ | 文字列にする必要があります。解析中にも派生します。 |
ヒント
注釈は vectorstoremodel デコレーターによって解析され、クラスのレコード定義を作成することです。そのため、パラメーターが設定されていないときにフィールド クラスをインスタンス化する必要はありません。フィールドには、次のようにクラスだけで注釈を付けることができます。
hotel_id: Annotated[str, VectorStoreRecordKeyField]
VectorStoreRecordKeyField
この属性がレコードのキーであることを示すには、この注釈を使用します。
VectorStoreRecordKeyField()
VectorStoreRecordKeyField パラメーター
基底クラス以外の他のパラメーターは定義されていません。
VectorStoreRecordDataField
この注釈を使用して、属性にキーまたはベクターではない一般的なデータが含まれていることを示します。
VectorStoreRecordDataField(is_filterable=True)
VectorStoreRecordDataField パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| has_embedding | いいえ | プロパティに埋め込みプロパティが関連付けられているかどうかを示します。既定値は None です。 |
| embedding_property_name | いいえ | 埋め込みを含むプロパティの名前。既定値は None です。 |
| is_filterable | いいえ | データベースでプロパティごとのインデックス作成をオプトインする必要がある場合に、フィルター処理のためにプロパティのインデックスを作成するかどうかを示します。 既定値は False です。 |
| is_full_text_searchable | いいえ | フルテキスト検索をサポートするデータベースのフルテキスト検索に対してプロパティのインデックスを作成するかどうかを示します。 既定値は False です。 |
VectorStoreRecordVectorField
この注釈を使用して、属性にベクターが含まれていることを示します。
VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)
VectorStoreRecordVectorField パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| dimensions | コレクション作成の場合ははい。それ以外の場合は省略可能 | ベクトルに含まれる次元の数。 これは通常、コレクションのベクター インデックスを作成するときに必要です。 |
| index_kind | いいえ | ベクターにインデックスを付けるインデックスの型。 既定値は、ベクター ストアの種類によって異なります。 |
| distance_function | いいえ | このベクトルに対するベクトル検索中にベクトル比較を行うときに使用する距離関数の型。 既定値は、ベクター ストアの種類によって異なります。 |
| local_embedding | いいえ | プロパティにローカル埋め込み機能が関連付けられているかどうかを示します。既定値は None です。 |
| embedding_settings | いいえ | 埋め込みの設定は、キーとしてservice_id、PromptExecutionSettings を値として指定した dict の形式で、既定値は None です。 |
| serialize_function | いいえ | 型が list[float | int] でない場合、この関数が必要な場合、またはモデル全体をシリアル化する必要がある場合に、ベクターのシリアル化に使用する関数。 |
| deserialize_function | いいえ | 型が list[float | int] でない場合、この関数が必要な場合、またはモデル全体を逆シリアル化する必要がある場合、ベクターの逆シリアル化に使用する関数。 |
一般的なインデックスの種類と距離関数の種類は、 semantic_kernel.data.IndexKind クラスと semantic_kernel.data.DistanceFunction クラスで静的な値として提供されます。
個々のベクター ストアの実装では、データベースが通常とは異なる型をサポートする独自のインデックスの種類と距離関数を使用することもできます。
レコードをアップサートまたは取得するすべてのメソッドでは、厳密に型指定されたモデル クラスが使用されます。 これらのクラスのフィールドは、各フィールドの目的を示す注釈で修飾されます。
ヒント
属性を使用する代わりに、 レコード定義を使用したスキーマの定義を参照してください。
これらの注釈で装飾されたモデルの例を次に示します。 既定では、ほとんどの既定のベクター ストアでは Jackson が使用されるため、モデル オブジェクトを Jackson によってシリアル化できるようにするのが良い方法です。つまり、クラスが表示され、getter、コンストラクター、注釈などが含まれます。
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordData;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordKey;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordVector;
import com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction;
import com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind;
import java.util.List;
public class Hotel {
@VectorStoreRecordKey
private String hotelId;
@VectorStoreRecordData(isFilterable = true)
private String name;
@VectorStoreRecordData(isFullTextSearchable = true)
private String description;
@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;
@VectorStoreRecordData(isFilterable = true)
private List<String> tags;
public Hotel() { }
public Hotel(String hotelId, String name, String description, List<Float> descriptionEmbedding, List<String> tags) {
this.hotelId = hotelId;
this.name = name;
this.description = description;
this.descriptionEmbedding = descriptionEmbedding;
this.tags = tags;
}
public String getHotelId() { return hotelId; }
public String getName() { return name; }
public String getDescription() { return description; }
public List<Float> getDescriptionEmbedding() { return descriptionEmbedding; }
public List<String> getTags() { return tags; }
}
注釈
VectorStoreRecordKey
この注釈を使用して、フィールドがレコードのキーであることを示します。
@VectorStoreRecordKey
private String hotelId;
VectorStoreRecordKey パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| storageName | いいえ | データベース内のフィールドの別名を指定するために使用できます。 このパラメーターは、Jackson が使用されている場合など、すべてのコネクタでサポートされているわけではありません。その場合、Jackson 注釈を使用してストレージ名を指定できます。 |
ヒント
storageName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。
VectorStoreRecordData
この注釈を使用して、フィールドにキーまたはベクターではない一般的なデータが含まれていることを示します。
@VectorStoreRecordData(isFilterable = true)
private String name;
VectorStoreRecordData パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| isFilterable | いいえ | データベースでフィールドごとのインデックス作成をオプトインする必要がある場合に、フィルター処理のためにフィールドのインデックスを作成するかどうかを示します。 既定値は False です。 |
| isFullTextSearchable | いいえ | フルテキスト検索をサポートするデータベースのフルテキスト検索用にフィールドのインデックスを作成するかどうかを示します。 既定値は False です。 |
| storageName | いいえ | データベース内のフィールドの別名を指定するために使用できます。 このパラメーターは、Jackson が使用されている場合など、すべてのコネクタでサポートされているわけではありません。その場合、Jackson 注釈を使用してストレージ名を指定できます。 |
ヒント
storageName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。
VectorStoreRecordVector
この注釈を使用して、フィールドにベクターが含まれていることを示します。
@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;
VectorStoreRecordVector パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| dimensions | コレクション作成の場合ははい。それ以外の場合は省略可能 | ベクトルに含まれる次元の数。 これは通常、コレクションのベクター インデックスを作成するときに必要です。 |
| indexKind | いいえ | ベクターにインデックスを付けるインデックスの型。 既定値は、ベクター ストアの種類によって異なります。 |
| distanceFunction | いいえ | このベクトルに対するベクトル検索中にベクトル比較を行うときに使用する距離関数の型。 既定値は、ベクター ストアの種類によって異なります。 |
| storageName | いいえ | データベース内のフィールドの別名を指定するために使用できます。 このパラメーターは、Jackson が使用されている場合など、すべてのコネクタでサポートされているわけではありません。その場合、Jackson 注釈を使用してストレージ名を指定できます。 |
一般的なインデックスの種類と距離関数の種類は、 com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind および com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction 列挙型で提供されます。
個々のベクター ストアの実装では、データベースが通常とは異なる型をサポートする独自のインデックスの種類と距離関数を使用することもできます。
ヒント
storageName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。
詳細については、近日公開予定です。