Dela via

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.

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

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

VectorStoreKeyProperty

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

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

Konfigurationsinställningar för VectorStoreKeyProperty

Parameter Obligatoriskt Beskrivning
Namn Ja Namnet på egenskapen för datamodellen. Används av mapparen för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
Typ Nej Typen av egenskap för datamodellen. Används av mapparen för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
Lagringsnamn 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 StorageName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.

VectorStoreDataProperty

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 VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },

Konfigurationsinställningar för VectorStoreDataProperty

Parameter Obligatoriskt Beskrivning
Namn Ja Namnet på egenskapen för datamodellen. Används av mapparen för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
Typ Nej Typen av egenskap för datamodellen. Används av mapparen för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
IsIndexed 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.
IsFullTextIndexed Nej Anger om egenskapen ska indexeras för fulltextsökning efter databaser som stöder fulltextsökning. Standardvärdet är falskt.
Lagringsnamn 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 StorageName och vilka alternativ som är tillgängliga finns i dokumentationen för varje anslutningsapp.

VectorStoreVectorProperty

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

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

Konfigurationsinställningar för VectorStoreVectorProperty

Parameter Obligatoriskt Beskrivning
Namn Ja Namnet på egenskapen för datamodellen. Används av mapparen för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
Typ Nej Typen av egenskap för datamodellen. Används av mapparen för att automatiskt mappa mellan lagringsschemat och datamodellen och för att skapa index.
Dimensioner Ja Antalet dimensioner som vektorn har. Detta krävs för att skapa 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 Vilken typ av funktion 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.
Lagringsnamn 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.
EmbeddingGenerator Nej Tillåter att du anger en Microsoft.Extensions.AI.IEmbeddingGenerator instans som ska användas för att generera inbäddningar automatiskt för den dekorerade egenskapen.

Dricks

Mer information om vilka anslutningsappar som stöder StorageName 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", 
    record_type=pd.DataFrame, 
    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
namn 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 (lagringsnamn) 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
namn 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 (lagringsnamn) 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
namn 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 Vilken typ av funktion 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 (lagringsnamn) 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.