Definování schématu úložiště pomocí definice záznamu (Preview)

Upozorňující

Funkce sémantického úložiště vektorů jádra je ve verzi Preview a vylepšení, která vyžadují zásadní změny, se můžou vyskytovat za omezených okolností před vydáním.

Přehled

Konektory sémantického úložiště vektorů jádra používají první přístup modelu k interakci s databázemi a umožňují přidávání poznámek k datovým modelům s informacemi potřebnými k vytváření indexů nebo mapování dat na schéma databáze.

Další způsob, jak tyto informace poskytnout, je prostřednictvím definic záznamů, které je možné definovat a zadat samostatně do datového modelu. To může být užitečné v několika scénářích:

• Může se stát, že vývojář chce použít stejný datový model s více než jednou konfigurací.
• Může se stát, že vývojář chce ukládat data pomocí velmi odlišného schématu modelu a chce zadat vlastní mapovač pro převod mezi datovým modelem a schématem úložiště.
• Může se stát, že vývojář chce použít předdefinovaný typ, například diktování, nebo optimalizovaný formát, jako je datový rámec, a přesto chce využívat funkci úložiště vektorů.

Tady je příklad vytvoření definice záznamu.

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 },
    }
};

Při vytváření definice musíte vždy zadat název a typ pro každou vlastnost ve schématu, protože to je vyžadováno pro vytvoření indexu a mapování dat.

Chcete-li použít definici, předejte ji getCollection metoda.

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

Třídy konfigurace vlastností záznamu

VectorStoreRecordKeyProperty

Tuto třídu použijte k označení, že vaše vlastnost je klíčem záznamu.

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

Nastavení konfigurace VectorStoreRecordKeyProperty

Parametr	Požadováno	Popis
DataModelPropertyName	Ano	Název vlastnosti datového modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
PropertyType	Ano	Typ vlastnosti datového modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
StoragePropertyName	No	Lze použít k zadání alternativního názvu vlastnosti v databázi. Všimněte si, že tento parametr nejsou podporovány všemi konektory, například pokud se podporují alternativy, jako JsonPropertyNameAttribute jsou podporované.

Tip

Další informace o tom, které konektory podporují StoragePropertyName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordDataProperty

Tuto třídu použijte k označení, že vaše vlastnost obsahuje obecná data, která nejsou klíčem nebo vektorem.

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

Nastavení konfigurace VectorStoreRecordDataProperty

Parametr	Požadováno	Popis
DataModelPropertyName	Ano	Název vlastnosti datového modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
PropertyType	Ano	Typ vlastnosti datového modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
IsFilterable	No	Určuje, zda má být vlastnost indexována pro filtrování v případech, kdy databáze vyžaduje souhlas s indexováním na vlastnost. Výchozí hodnota je False.
IsFullTextSearchable	No	Určuje, zda má být vlastnost indexována pro fulltextové vyhledávání databází, které podporují fulltextové vyhledávání. Výchozí hodnota je False.
StoragePropertyName	No	Lze použít k zadání alternativního názvu vlastnosti v databázi. Všimněte si, že tento parametr nejsou podporovány všemi konektory, například pokud se podporují alternativy, jako JsonPropertyNameAttribute jsou podporované.

Tip

Další informace o tom, které konektory podporují StoragePropertyName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordVectorProperty

Tuto třídu použijte k označení, že vaše vlastnost obsahuje vektor.

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

Nastavení konfigurace VectorStoreRecordVectorProperty

Parametr	Požadováno	Popis
DataModelPropertyName	Ano	Název vlastnosti datového modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
PropertyType	Ano	Typ vlastnosti datového modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
Dimenze	Ano pro vytvoření kolekce, volitelné v opačném případě	Počet dimenzí, které vektor má. To se obvykle vyžaduje při vytváření vektorového indexu pro kolekci.
IndexKind	No	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
VzdálenostFunction	No	Typ funkce vzdálenosti, která se má použít při porovnávání vektorů při hledání vektorů nad tímto vektorem. Výchozí nastavení se liší podle typu úložiště vektorů.
StoragePropertyName	No	Lze použít k zadání alternativního názvu vlastnosti v databázi. Všimněte si, že tento parametr nejsou podporovány všemi konektory, například pokud se podporují alternativy, jako JsonPropertyNameAttribute jsou podporované.

Tip

Další informace o tom, které konektory podporují StoragePropertyName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

Tady je příklad vytvoření definice záznamu pro použití s datovým rámcem pandas.

Poznámka:

Stejná pole jako v definici datového modelu se tady používají pro datový model, který se přidají jako poznámky, tady jako diktování s názvem.

Je potřeba poznamenat několik důležitých věcí, jiné pak samotné definice polí. První je container_mode parametr. Pokud je nastavená hodnota True, znamená to, že datový model je typ kontejneru, jako je datový rámec, a že datový model je tedy kontejner záznamů, nikoli jeden záznam kontejneru, lze použít úplně stejným způsobem, hlavní rozdíl je v tom, že get a get_batch vrátí stejný datový typ, s jedním záznamem get pro jeden a jeden nebo více pro get_batch. Pokud chcete provést upsert a upsert upsert_batch lze ho použít zaměnitelně, jinými slovy předání kontejneru, aby upsert výsledkem bylo více upsertů místo jednoho.

Druhým je přidání to_dict metod a from_dict metod, které se používají k převodu mezi datovým modelem a schématem úložiště. V tomto případě se metoda používá k převodu to_dict datového rámce na seznam záznamů a from_dict metoda slouží k převodu seznamu záznamů na datový rámec. Může existovat serialize také metoda a deserialize (která není uvedena v následujícím příkladu), kde najdete podrobnosti o rozdílu mezi metodami, které najdete v dokumentaci k serializaci.

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),
)

Při vytváření definice musíte vždy zadat název (jako klíč ve fields diktování) a zadat pro každou vlastnost ve schématu, protože to je vyžadováno pro vytvoření indexu a mapování dat.

Chcete-li použít definici, předejte ji getCollection metoda nebo konstruktor kolekce společně s datovým modelem.

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

Tady je příklad vytvoření definice záznamu.

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()
    )
);

Při vytváření definice musíte vždy zadat název a typ pro každé pole ve schématu, protože to je vyžadováno pro vytvoření indexu a mapování dat.

Chcete-li použít definici, předejte ji getCollection metoda.

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

Třídy konfigurace záznamu polí

VectorStoreRecordKeyField

Tuto třídu použijte k označení, že pole je klíčem záznamu.

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

Nastavení konfigurace VectorStoreRecordKeyField

Parametr	Požadováno	Popis
name	Ano	Název pole v datovém modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
fieldType	Ano	Typ pole v datovém modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
storageName	No	Lze použít k zadání alternativního názvu pole v databázi. Všimněte si, že tento parametr nejsou podporovány všemi spojnicemi, například pokud se používá Jackson, je možné zadat název úložiště pomocí poznámek Jackson.

Tip

Další informace o tom, které konektory podporují storageName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordDataField

Tuto třídu použijte k označení, že vaše vlastnost obsahuje obecná data, která nejsou klíčem nebo vektorem.

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

Nastavení konfigurace VectorStoreRecordDataField

Parametr	Požadováno	Popis
name	Ano	Název pole v datovém modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
fieldType	Ano	Typ pole v datovém modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
isFilterable	No	Určuje, jestli má být pole indexováno pro filtrování v případech, kdy databáze vyžaduje přihlášení k indexování pro jednotlivá pole. Výchozí hodnota je False.
isFullTextSearchable	No	Určuje, jestli má být pole indexováno pro fulltextové vyhledávání databází, které podporují fulltextové vyhledávání. Výchozí hodnota je False.
storageName	No	Lze použít k zadání alternativního názvu pole v databázi. Všimněte si, že tento parametr nejsou podporovány všemi spojnicemi, například pokud se používá Jackson, je možné zadat název úložiště pomocí poznámek Jackson.

Tip

Další informace o tom, které konektory podporují storageName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordVectorField

Tuto třídu použijte k označení, že vaše pole obsahuje vektor.

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

Nastavení konfigurace VectorStoreRecordVectorField

Parametr	Požadováno	Popis
name	Ano	Název pole v datovém modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
fieldType	Ano	Typ pole v datovém modelu. Integrované mapovače se používají k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
dimensions	Ano pro vytvoření kolekce, volitelné v opačném případě	Počet dimenzí, které vektor má. To se obvykle vyžaduje při vytváření vektorového indexu pro kolekci.
indexKind	No	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
vzdálenostFunction	No	Typ funkce vzdálenosti, která se má použít při porovnávání vektorů při hledání vektorů nad tímto vektorem. Výchozí nastavení se liší podle typu úložiště vektorů.
storageName	No	Lze použít k zadání alternativního názvu pole v databázi. Všimněte si, že tento parametr nejsou podporovány všemi spojnicemi, například pokud se používá Jackson, je možné zadat název úložiště pomocí poznámek Jackson.

Tip

Další informace o tom, které konektory podporují storageName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.