次の方法で共有

レコード定義を使用したストレージ スキーマの定義 (プレビュー)

  • [アーティクル]

警告

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

概要

セマンティック カーネル ベクター ストア コネクタは、データベースを操作するためのモデルの最初のアプローチを使用し、インデックスの作成やデータベース スキーマへのデータのマッピングに必要な情報を使用してデータ モデルに注釈を付けることができます。

この情報を提供するもう 1 つの方法は、データ モデルに個別に定義および指定できるレコード定義を使用することです。 これは、複数のシナリオで役立ちます。

  • 開発者が複数の構成で同じデータ モデルを使用したい場合があります。
  • 開発者が、非常に異なるスキーマを使用してモデルにデータを格納し、データ モデルとストレージ スキーマの間で変換するためのカスタム マッパーを提供したい場合があります。
  • 開発者が、dict などの組み込み型、またはデータフレームのような最適化された形式を使用し、ベクター ストア機能を活用したい場合があります。

レコード定義を作成する方法の例を次に示します。

using Microsoft.Extensions.VectorData;

var hotelDefinition = new VectorStoreRecordDefinition
{
    Properties = new List<VectorStoreRecordProperty>
    {
        new VectorStoreRecordKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },
        new VectorStoreRecordDataProperty("Description", typeof(string)) { IsFullTextSearchable = true },
        new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },
    }
};

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

定義を使用するには、GetCollection メソッドに渡します。

var collection = vectorStore.GetCollection<ulong, Hotel>("skhotels", hotelDefinition);

Record プロパティの構成クラス

VectorStoreRecordKeyProperty

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

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

VectorStoreRecordKeyProperty 構成設定

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

ヒント

StoragePropertyName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。

VectorStoreRecordDataProperty

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

new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },

VectorStoreRecordDataProperty 構成設定

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

ヒント

StoragePropertyName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。

VectorStoreRecordVectorProperty

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

new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },

VectorStoreRecordVectorProperty 構成設定

パラメーター 必須 説明
DataModelPropertyName はい データ モデルのプロパティの名前。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
PropertyType はい データ モデルのプロパティの型。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
Dimensions コレクション作成の場合ははい。それ以外の場合は省略可能 ベクトルに含まれる次元の数。 これは通常、コレクションのベクター インデックスを作成するときに必要です。
IndexKind いいえ ベクターにインデックスを付けるインデックスの型。 既定値は、ベクター ストアの種類によって異なります。
DistanceFunction いいえ このベクトルに対するベクトル検索中にベクトル比較を行うときに使用する距離関数の型。 既定値は、ベクター ストアの種類によって異なります。
StoragePropertyName いいえ データベース内のプロパティの代替名を指定するために使用できます。 このパラメーターは、 JsonPropertyNameAttribute などの代替手段がサポートされている場合など、すべてのコネクタでサポートされているわけではありません。

ヒント

StoragePropertyName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。

pandas DataFrameで使用するレコード定義を作成する方法の例を次に示します。

Note

ここでは、 data モデル定義と同じフィールド をデータ モデルに対して使用し、注釈として追加し、ここでは名前を付けたディクテーションとして追加します。

注意すべき重要な点がいくつかありますが、他のフィールド定義自体も重要です。 1 つ目は、 container_mode パラメーターです。 True に設定すると、これは、データ モデルが DataFrame のようなコンテナー型であり、データ モデルがレコードのコンテナーであることを示します。そのため、1 つではなく、コンテナー レコードをまったく同じ方法で使用できます。主な違いは、 get と get_batch が同じデータ型を返すということです。 1 つの get 用に 1 つのレコード、 get_batch用に 1 つ以上のレコードを含む。 アップサートを実行する場合は、 upsert と upsert_batch を同じ意味で使用できます。つまり、コンテナーを upsert に渡すと、1 つではなく複数のアップサートが発生します。

2 つ目は、データ モデルとストレージ スキーマの間の変換に使用される to_dict メソッドと from_dict メソッドの追加です。 この場合、 to_dict メソッドを使用して DataFrame をレコードのリストに変換し、 from_dict メソッドを使用してレコードのリストを DataFrame に変換します。 また、 serialize と deserialize メソッド (以下の例では示されていません) を使用することもできます。その違いの詳細については、 erialization のドキュメントを参照してください。

from semantic_kernel.data import (
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
)

hotel_definition = VectorStoreRecordDefinition(
    fields={
        "hotel_id": VectorStoreRecordKeyField(property_type="str"),
        "hotel_name": VectorStoreRecordDataField(property_type="str", is_filterable=True),
        "description": VectorStoreRecordDataField(
            property_type="str", has_embedding=True, embedding_property_name="description_embedding"
        ),
        "description_embedding": VectorStoreRecordVectorField(property_type="list[float]"),
    },
    container_mode=True,
    to_dict=lambda record, **_: record.to_dict(orient="records"),
    from_dict=lambda records, **_: DataFrame(records),
)

定義を作成するときは、インデックスの作成とデータ マッピングに必要であるため、常に名前 ( fields dict のキー) とスキーマ内の各プロパティの型を指定する必要があります。

定義を使用するには、データ モデル型と共に GetCollection メソッドまたはコレクション コンストラクターに渡します。

collection = vector_store.get_collection(
    collection_name="skhotels", 
    data_model_type=pd.DataFrame, 
    data_model_definition=hotel_definition,
)

レコード定義を作成する方法の例を次に示します。

var hotelDefinition = VectorStoreRecordDefinition.fromFields(
    Arrays.asList(
        VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),
        VectorStoreRecordDataField.builder()
            .withName("name")
            .withFieldType(String.class)
            .isFilterable(true).build(),
        VectorStoreRecordDataField.builder()
            .withName("description")
            .withFieldType(String.class)
            .isFullTextSearchable(true).build(),
        VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
            .withDimensions(4)
            .withIndexKind(IndexKind.HNSW)
            .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
            .withFieldType(List.class).build()
    )
);

定義を作成するときは、インデックスの作成とデータ マッピングに必要であるため、スキーマ内の各フィールドの名前と型を常に指定する必要があります。

定義を使用するには、GetCollection メソッドに渡します。

var collection = vectorStore.getCollection("skhotels",
        JDBCVectorStoreRecordCollectionOptions.builder()
            .withRecordDefinition(hotelDefinition)
            .build()
    );

レコード フィールド構成クラス

VectorStoreRecordKeyField

このクラスを使用して、フィールドがレコードのキーであることを示します。

VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),

VectorStoreRecordKeyField の構成設定

パラメーター 必須 内容
name はい データ モデルのフィールドの名前。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
fieldType はい データ モデルのフィールドの型。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
storageName いいえ データベース内のフィールドの別名を指定するために使用できます。 このパラメーターは、Jackson が使用されている場合など、すべてのコネクタでサポートされているわけではありません。その場合、Jackson 注釈を使用してストレージ名を指定できます。

ヒント

storageName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。

VectorStoreRecordDataField

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

VectorStoreRecordDataField.builder()
    .withName("name")
    .withFieldType(String.class)
    .isFilterable(true).build(),

VectorStoreRecordDataField の構成設定

パラメーター 必須 内容
name はい データ モデルのフィールドの名前。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
fieldType はい データ モデルのフィールドの型。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
isFilterable いいえ データベースでフィールドごとのインデックス作成をオプトインする必要がある場合に、フィルター処理のためにフィールドのインデックスを作成するかどうかを示します。 既定値は False です。
isFullTextSearchable いいえ フルテキスト検索をサポートするデータベースのフルテキスト検索用にフィールドのインデックスを作成するかどうかを示します。 既定値は False です。
storageName いいえ データベース内のフィールドの別名を指定するために使用できます。 このパラメーターは、Jackson が使用されている場合など、すべてのコネクタでサポートされているわけではありません。その場合、Jackson 注釈を使用してストレージ名を指定できます。

ヒント

storageName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。

VectorStoreRecordVectorField

このクラスを使用して、フィールドにベクターが含まれていることを示します。

VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
    .withDimensions(4)
    .withIndexKind(IndexKind.HNSW)
    .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
    .withFieldType(List.class).build(),

VectorStoreRecordVectorField の構成設定

パラメーター 必須 内容
name はい データ モデルのフィールドの名前。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
fieldType はい データ モデルのフィールドの型。 ストレージ スキーマとデータ モデルの間で自動的にマップし、インデックスを作成するために、組み込みのマッパーによって使用されます。
dimensions コレクション作成の場合ははい。それ以外の場合は省略可能 ベクトルに含まれる次元の数。 これは通常、コレクションのベクター インデックスを作成するときに必要です。
indexKind いいえ ベクターにインデックスを付けるインデックスの型。 既定値は、ベクター ストアの種類によって異なります。
distanceFunction いいえ このベクトルに対するベクトル検索中にベクトル比較を行うときに使用する距離関数の型。 既定値は、ベクター ストアの種類によって異なります。
storageName いいえ データベース内のフィールドの別名を指定するために使用できます。 このパラメーターは、Jackson が使用されている場合など、すべてのコネクタでサポートされているわけではありません。その場合、Jackson 注釈を使用してストレージ名を指定できます。

ヒント

storageName をサポートするコネクタと使用可能な代替手段の詳細については、 各コネクタのドキュメントを参照してください。