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.

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 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 VectorStoreCollectionDefinition
{
    Properties = new List<VectorStoreProperty>
    {
        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 },
    }
};

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

VectorStoreKeyProperty

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

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

Nastavení konfigurace VectorStoreKeyProperty

Parametr	Požadováno	Popis
Název	Ano	Název vlastnosti datového modelu. Mapovač se používá k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
Typ	Ne	Typ vlastnosti datového modelu. Mapovač se používá k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
Název úložiště	Ne	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é.

Návod

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

VectorStoreDataProperty

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

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

Nastavení konfigurace VectorStoreDataProperty

Parametr	Požadováno	Popis
Název	Ano	Název vlastnosti datového modelu. Mapovač se používá k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
Typ	Ne	Typ vlastnosti datového modelu. Mapovač se používá k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
IsIndexed	Ne	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.
IsFullTextIndexed	Ne	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.
Název úložiště	Ne	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é.

Návod

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

VectorStoreVectorProperty

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

new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4) { DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw },

Nastavení konfigurace VectorStoreVectorProperty

Parametr	Požadováno	Popis
Název	Ano	Název vlastnosti datového modelu. Mapovač se používá k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
Typ	Ne	Typ vlastnosti datového modelu. Mapovač se používá k automatickému mapování mezi schématem úložiště a datovým modelem a k vytváření indexů.
Dimenze	Ano	Počet dimenzí, které vektor má. To je vyžadováno pro vytvoření vektorového indexu pro kolekci.
IndexKind	Ne	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
VzdálenostFunction	Ne	Typ funkce, 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ů.
Název úložiště	Ne	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é.
EmbeddingGenerator	Ne	Umožňuje zadat Microsoft.Extensions.AI.IEmbeddingGenerator instanci, která se má použít pro generování vkládání automaticky pro dekorovanou vlastnost.

Návod

Další informace o tom, které konektory podporují StorageName 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 upsertupsert_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", 
    record_type=pd.DataFrame, 
    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
název	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ů.
Název_úložiště	Ne	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.

Návod

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
název	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	Ne	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	Ne	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.
Název_úložiště	Ne	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.

Návod

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
název	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ů.
rozměry	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	Ne	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
vzdálenostFunction	Ne	Typ funkce, 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ů.
Název_úložiště	Ne	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.

Návod

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