Definiera din datamodell (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.

Alla metoder för att öka eller hämta poster använder starkt typerade modellklasser. Egenskaperna för dessa klasser är dekorerade med attribut som anger syftet med varje egenskap.

Dricks

Ett alternativ till att använda attribut finns i definiera schemat med en postdefinition.

Dricks

Ett alternativ till att definiera din egen datamodell finns i använda Vector Store-abstraktioner utan att definiera din egen datamodell.

Här är ett exempel på en modell som är dekorerad med dessa attribut.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public ulong HotelId { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string HotelName { get; set; }

    [VectorStoreRecordData(IsFullTextSearchable = true)]
    public string Description { get; set; }

    [VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string[] Tags { get; set; }
}

Attribut

VectorStoreRecordKeyAttribute

Använd det här attributet för att ange att din egenskap är nyckeln för posten.

[VectorStoreRecordKey]
public ulong HotelId { get; set; }

VectorStoreRecordKeyAttribute-parametrar

Parameter	Obligatoriskt	Beskrivning
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.

VectorStoreRecordDataAttribute

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

[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }

VectorStoreRecordDataAttribute-parametrar

Parameter	Obligatoriskt	Beskrivning
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.

VectorStoreRecordVectorAttribute

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

[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

VectorStoreRecordVectorAttribute-parametrar

Parameter	Obligatoriskt	Beskrivning
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.

Vanliga indextyper och avståndsfunktionstyper anges som statiska värden för klasserna Microsoft.SemanticKernel.Data.IndexKind och Microsoft.SemanticKernel.Data.DistanceFunction . Implementeringar av enskilda vektorlager kan också använda sina egna indextyper och avståndsfunktioner, där databasen stöder ovanliga typer.

Dricks

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

Alla metoder för att öka eller hämta poster använder en klass och en postdefinition för vektorlager.

Detta kan göras genom att definiera din egen klass med anteckningar för fälten, eller genom att använda en klass/typ i kombination med en postdefinition. Två saker måste göras för en klass, det första är att lägga till anteckningarna med fälttyperna, det andra är att dekorera klassen med dekoratören vectorstoremodel .

Dricks

För den alternativa metoden med en postdefinition, se definiera schemat med en postdefinition.

Här är ett exempel på en modell som är dekorerad med dessa anteckningar.

from dataclasses import dataclass, field
from typing import Annotated
from semantic_kernel.data import (
    DistanceFunction,
    IndexKind,
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
    vectorstoremodel,
)

@vectorstoremodel
@dataclass
class Hotel:
    hotel_id: Annotated[str, VectorStoreRecordKeyField()] = field(default_factory=lambda: str(uuid4()))
    hotel_name: Annotated[str, VectorStoreRecordDataField(is_filterable=True)]
    description: Annotated[str, VectorStoreRecordDataField(is_full_text_searchable=True)]
    description_embedding: Annotated[list[float], VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)]
    tags: Annotated[list[str], VectorStoreRecordDataField(is_filterable=True)]

Dricks

Du kan definiera en klass med dessa anteckningar på flera olika sätt, varav en använder modulen dataclasses i Python, som visas här. Det här exemplet visar även andra metoder (med pydantiska BaseModels- och vanilj python-klasser).

Kommentarer

Det finns tre typer av anteckningar som ska användas och de har en gemensam basklass.

VectorStoreRecordField

Det här är basklassen för alla anteckningar, den är inte avsedd att användas direkt.

VectorStoreRecordField-parametrar

Parameter	Obligatoriskt	Beskrivning
name	Nej	Kan läggas till direkt men anges under parsningen av modellen.
property_type	Nej	Ska vara en sträng, kommer också att härledas under parsning.

Dricks

Anteckningarna parsas av dekoratören vectorstoremodel och en av de saker den gör är att skapa en postdefinition för klassen. Därför är det inte nödvändigt att instansiera en fältklass när inga parametrar har angetts, fältet kan kommenteras med bara klassen, så här:

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Använd den här kommentaren för att ange att det här attributet är nyckeln för posten.

VectorStoreRecordKeyField()

VectorStoreRecordKeyField-parametrar

Inga andra parametrar utanför basklassen definieras.

VectorStoreRecordDataField

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

VectorStoreRecordDataField(is_filterable=True)

VectorStoreRecordDataField-parametrar

Parameter	Obligatoriskt	Beskrivning
has_embedding	Nej	Anger om egenskapen har en associerad inbäddning, standardvärdet är Ingen.
embedding_property_name	Nej	Namnet på egenskapen som innehåller inbäddningen, standardvärdet är Ingen.
is_filterable	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.
is_full_text_searchable	Nej	Anger om egenskapen ska indexeras för fulltextsökning efter databaser som stöder fulltextsökning. Standardvärdet är falskt.

VectorStoreRecordVectorField

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

VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)

VectorStoreRecordVectorField-parametrar

Parameter	Obligatoriskt	Beskrivning
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.
index_kind	Nej	Vilken typ av index som vektorn ska indexeras med. Standard varierar beroende på typ av vektorlager.
distance_function	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.
local_embedding	Nej	Anger om egenskapen har en lokal inbäddning associerad med den, standardvärdet är Ingen.
embedding_settings	Nej	Inställningarna för inbäddningen, i form av en diktat med service_id som nyckel och PromptExecutionSettings som värde, är standard ingen.
serialize_function	Nej	Den funktion som ska användas för att serialisera vektorn, om typen inte är en lista[float | int] behövs den här funktionen eller om hela modellen måste serialiseras.
deserialize_function	Nej	Funktionen som ska användas för att deserialisera vektorn, om typen inte är en lista[float | int] behövs den här funktionen, eller om hela modellen måste deserialiseras.

Vanliga indextyper och avståndsfunktionstyper anges som statiska värden för klasserna semantic_kernel.data.IndexKind och semantic_kernel.data.DistanceFunction . Implementeringar av enskilda vektorlager kan också använda sina egna indextyper och avståndsfunktioner, där databasen stöder ovanliga typer.

Alla metoder för att öka eller hämta poster använder starkt typerade modellklasser. Fälten i dessa klasser är dekorerade med anteckningar som anger syftet med varje fält.

Dricks

Ett alternativ till att använda attribut finns i definiera schemat med en postdefinition.

Här är ett exempel på en modell som är dekorerad med dessa anteckningar. Som standard använder de flesta färdiga vektorlager Jackson, vilket är en bra praxis för att säkerställa att modellobjektet kan serialiseras av Jackson, dvs klassen är synlig, har getters, konstruktor, anteckningar osv.

import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordData;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordKey;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordVector;
import com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction;
import com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind;

import java.util.List;

public class Hotel {
    @VectorStoreRecordKey
    private String hotelId;

    @VectorStoreRecordData(isFilterable = true)
    private String name;

    @VectorStoreRecordData(isFullTextSearchable = true)
    private String description;

    @VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
    private List<Float> descriptionEmbedding;

    @VectorStoreRecordData(isFilterable = true)
    private List<String> tags;

    public Hotel() { }

    public Hotel(String hotelId, String name, String description, List<Float> descriptionEmbedding, List<String> tags) {
        this.hotelId = hotelId;
        this.name = name;
        this.description = description;
        this.descriptionEmbedding = descriptionEmbedding;
        this.tags = tags;
    }

    public String getHotelId() { return hotelId; }
    public String getName() { return name; }
    public String getDescription() { return description; }
    public List<Float> getDescriptionEmbedding() { return descriptionEmbedding; }
    public List<String> getTags() { return tags; }
}

Kommentarer

VectorStoreRecordKey

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

@VectorStoreRecordKey
private String hotelId;

VectorStoreRecordKey-parametrar

Parameter	Obligatoriskt	Beskrivning
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.

VectorStoreRecordData

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

@VectorStoreRecordData(isFilterable = true)
private String name;

VectorStoreRecordData-parametrar

Parameter	Obligatoriskt	Beskrivning
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.

VectorStoreRecordVector

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

@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;

VectorStoreRecordVector-parametrar

Parameter	Obligatoriskt	Beskrivning
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.

Vanliga indextyper och avståndsfunktionstyper tillhandahålls på com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind uppräkningar och com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction . Implementeringar av enskilda vektorlager kan också använda sina egna indextyper och avståndsfunktioner, där databasen stöder ovanliga typer.

Dricks

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

Mer information kommer snart.