Definiera ditt lagringsschema med hjälp av en postdefinition (förhandsversion)

Varning

Funktionen Semantic Kernel Vector Store är i förhandsversion, och förbättringar som kräver icke-bakåtkompatibla ändringar kan fortfarande ske under begränsade omständigheter före lanseringen.

Översikt

Anslutningsappar för semantisk kernelvektorlagring använder en modell för att interagera med databaser och gör det möjligt att kommentera datamodeller med information som behövs för att skapa index eller mappa data till databasschemat.

Ett annat sätt att tillhandahålla den här informationen är via postdefinitioner som kan definieras och levereras separat till datamodellen. Detta kan vara användbart i flera scenarier:

• Det kan finnas ett fall där en utvecklare vill använda samma datamodell med mer än en konfiguration.
• Det kan finnas ett fall där utvecklaren vill lagra data med ett helt annat schema än modellen och vill ange en anpassad mappare för konvertering mellan datamodellen och lagringsschemat.
• Det kan finnas ett fall där en utvecklare vill använda en inbyggd typ, till exempel en diktamen, eller ett optimerat format som en dataram och ändå vill utnyttja funktionerna för vektorlagring.

Här är ett exempel på hur du skapar en postdefinition.

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

När du skapar en definition måste du alltid ange ett namn och en typ för varje egenskap i schemat, eftersom detta krävs för att skapa index och datamappning.

Om du vill använda definitionen skickar du den till metoden GetCollection.

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

Konfigurationsklasser för postegenskap

VectorStoreRecordKeyProperty

Använd den här klassen för att ange att din egenskap är nyckeln för posten.

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

Konfigurationsinställningar för VectorStoreRecordKeyProperty

Parameter	Obligatoriskt	Beskrivning
DataModelPropertyName	Ja	Namnet på egenskapen för datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
PropertyType	Ja	Typen av egenskap för datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
StoragePropertyName	Nej	Kan användas för att ange ett alternativt namn för egenskapen i databasen. Observera att den här parametern inte stöds av alla anslutningsappar, t.ex. där alternativ som JsonPropertyNameAttribute stöds.

Dricks

Mer information om vilka anslutningsappar som stöder StoragePropertyName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.

VectorStoreRecordDataProperty

Använd den här klassen för att ange att egenskapen innehåller allmänna data som inte är en nyckel eller en vektor.

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

Konfigurationsinställningar för VectorStoreRecordDataProperty

Parameter	Obligatoriskt	Beskrivning
DataModelPropertyName	Ja	Namnet på egenskapen för datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
PropertyType	Ja	Typen av egenskap för datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
IsFilterable	Nej	Anger om egenskapen ska indexeras för filtrering i fall där en databas kräver att du väljer att indexera per egenskap. Standardvärdet är falskt.
IsFullTextSearchable	Nej	Anger om egenskapen ska indexeras för fulltextsökning efter databaser som stöder fulltextsökning. Standardvärdet är falskt.
StoragePropertyName	Nej	Kan användas för att ange ett alternativt namn för egenskapen i databasen. Observera att den här parametern inte stöds av alla anslutningsappar, t.ex. där alternativ som JsonPropertyNameAttribute stöds.

Dricks

Mer information om vilka anslutningsappar som stöder StoragePropertyName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.

VectorStoreRecordVectorProperty

Använd den här klassen för att ange att egenskapen innehåller en vektor.

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

Konfigurationsinställningar för VectorStoreRecordVectorProperty

Parameter	Obligatoriskt	Beskrivning
DataModelPropertyName	Ja	Namnet på egenskapen för datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
PropertyType	Ja	Typen av egenskap för datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
Dimensioner	Ja för samlingsskapande, valfritt annars	Antalet dimensioner som vektorn har. Detta krävs vanligtvis när du skapar ett vektorindex för en samling.
IndexKind	Nej	Vilken typ av index som vektorn ska indexeras med. Standard varierar beroende på typ av vektorlager.
DistanceFunction	Nej	Den typ av avståndsfunktion som ska användas vid jämförelse av vektorer under vektorsökning över den här vektorn. Standard varierar beroende på typ av vektorlager.
StoragePropertyName	Nej	Kan användas för att ange ett alternativt namn för egenskapen i databasen. Observera att den här parametern inte stöds av alla anslutningsappar, t.ex. där alternativ som JsonPropertyNameAttribute stöds.

Dricks

Mer information om vilka anslutningsappar som stöder StoragePropertyName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.

Här är ett exempel på hur du skapar en postdefinition för användning med en Pandas DataFrame.

Kommentar

Samma fält som i datamodelldefinitionen används här, för en datamodell läggs de till som anteckningar, här som en diktamen med namnet.

Det finns ett par viktiga saker att notera, andra sedan själva fältdefinitionerna. Den första är parametern container_mode . När värdet är True anger detta att datamodellen är en containertyp, som en DataFrame, och att datamodellen därför är en container med poster, i stället för en enda, en containerpost kan användas på exakt samma sätt, den största skillnaden är att get och get_batch returnerar samma datatyp. med en enda post för en och en get eller flera för en get_batch. När du vill göra en upsert upsert , och upsert_batch kan användas omväxlande, med andra ord, att skicka en container till upsert resulterar i flera upserts, i stället för en enda.

Den andra är tillägget av to_dict metoderna och from_dict som används för att konvertera mellan datamodellen och lagringsschemat. I det här fallet to_dict används metoden för att konvertera DataFrame till en lista med poster, och from_dict metoden används för att konvertera en lista med poster till en DataFrame. Det kan också finnas en serialize metod (deserializevisas inte i exemplet nedan) för mer information om skillnaden mellan dem i serialiseringsdokumentationen.

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

När du skapar en definition måste du alltid ange ett namn (som nyckeln i diktamen fields ) och skriva för varje egenskap i schemat, eftersom detta krävs för att skapa index och datamappning.

Om du vill använda definitionen skickar du den till metoden GetCollection eller en samlingskonstruktor, tillsammans med datamodelltypen.

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

Här är ett exempel på hur du skapar en postdefinition.

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

När du skapar en definition måste du alltid ange ett namn och en typ för varje fält i schemat, eftersom detta krävs för att skapa index och datamappning.

Om du vill använda definitionen skickar du den till metoden GetCollection.

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

Konfigurationsklasser för postfält

VectorStoreRecordKeyField

Använd den här klassen för att ange att fältet är nyckeln för posten.

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

Konfigurationsinställningar för VectorStoreRecordKeyField

Parameter	Obligatoriskt	Beskrivning
name	Ja	Namnet på fältet i datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
fieldType	Ja	Typ av fält i datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
storageName	Nej	Kan användas för att ange ett alternativt namn för fältet i databasen. Observera att den här parametern inte stöds av alla anslutningsappar, t.ex. där Jackson används, i så fall kan lagringsnamnet anges med jacksonanteckningar.

Dricks

Mer information om vilka anslutningsappar som stöder storageName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.

VectorStoreRecordDataField

Använd den här klassen för att ange att egenskapen innehåller allmänna data som inte är en nyckel eller en vektor.

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

Konfigurationsinställningar för VectorStoreRecordDataField

Parameter	Obligatoriskt	Beskrivning
name	Ja	Namnet på fältet i datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
fieldType	Ja	Typ av fält i datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
isFilterable	Nej	Anger om fältet ska indexeras för filtrering i fall där en databas kräver att du väljer att indexera per fält. Standardvärdet är falskt.
isFullTextSearchable	Nej	Anger om fältet ska indexeras för fulltextsökning efter databaser som stöder fulltextsökning. Standardvärdet är falskt.
storageName	Nej	Kan användas för att ange ett alternativt namn för fältet i databasen. Observera att den här parametern inte stöds av alla anslutningsappar, t.ex. där Jackson används, i så fall kan lagringsnamnet anges med jacksonanteckningar.

Dricks

Mer information om vilka anslutningsappar som stöder storageName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.

VectorStoreRecordVectorField

Använd den här klassen för att ange att fältet innehåller en vektor.

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

Konfigurationsinställningar för VectorStoreRecordVectorField

Parameter	Obligatoriskt	Beskrivning
name	Ja	Namnet på fältet i datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
fieldType	Ja	Typ av fält i datamodellen. Används av de inbyggda mapparna för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
dimensioner	Ja för samlingsskapande, valfritt annars	Antalet dimensioner som vektorn har. Detta krävs vanligtvis när du skapar ett vektorindex för en samling.
indexKind	Nej	Vilken typ av index som vektorn ska indexeras med. Standard varierar beroende på typ av vektorlager.
distanceFunction	Nej	Den typ av avståndsfunktion som ska användas vid jämförelse av vektorer under vektorsökning över den här vektorn. Standard varierar beroende på typ av vektorlager.
storageName	Nej	Kan användas för att ange ett alternativt namn för fältet i databasen. Observera att den här parametern inte stöds av alla anslutningsappar, t.ex. där Jackson används, i så fall kan lagringsnamnet anges med jacksonanteckningar.

Dricks

Mer information om vilka anslutningsappar som stöder storageName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.