Delen via

Uw gegevensmodel definiëren (preview)

  • Artikel

Waarschuwing

De Semantische Kernel Vector Store-functionaliteit is in preview en verbeteringen waarvoor wijzigingen die fouten veroorzaken, kunnen nog steeds in beperkte omstandigheden optreden voordat ze worden uitgebracht.

Overzicht

De Semantische Kernel Vector Store-connectors maken gebruik van een model dat eerst met databases communiceert.

Alle methoden voor upsert of het ophalen van records maken gebruik van sterk getypeerde modelklassen. De eigenschappen van deze klassen zijn versierd met kenmerken die het doel van elke eigenschap aangeven.

Tip

Raadpleeg voor een alternatief voor het gebruik van kenmerken het definiëren van uw schema met een recorddefinitie.

Tip

Als alternatief voor het definiëren van uw eigen gegevensmodel raadpleegt u Vector Store-abstracties zonder uw eigen gegevensmodel te definiëren.

Hier volgt een voorbeeld van een model dat is ingericht met deze kenmerken.

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

Kenmerken

VectorStoreRecordKeyAttribute

Gebruik dit kenmerk om aan te geven dat uw eigenschap de sleutel van de record is.

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

VectorStoreRecordKeyAttribute-parameters

Parameter Vereist Beschrijving
StoragePropertyName Nee Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Houd er rekening mee dat deze parameter niet wordt ondersteund door alle connectors, bijvoorbeeld waar alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

Tip

Raadpleeg de documentatie voor elke connector voor meer informatie over welke connectors StoragePropertyName ondersteunen en welke alternatieven beschikbaar zijn.

VectorStoreRecordDataAttribute

Gebruik dit kenmerk om aan te geven dat uw eigenschap algemene gegevens bevat die geen sleutel of vector zijn.

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

VectorStoreRecordDataAttribute-parameters

Parameter Vereist Beschrijving
IsFilterable Nee Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor filteren in gevallen waarin een database moet inschakelen voor indexering per eigenschap. Standaard ingesteld op onwaar.
IsFullTextSearchable Nee Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor zoeken in volledige tekst naar databases die zoeken in volledige tekst ondersteunen. Standaard ingesteld op onwaar.
StoragePropertyName Nee Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Houd er rekening mee dat deze parameter niet wordt ondersteund door alle connectors, bijvoorbeeld waar alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

Tip

Raadpleeg de documentatie voor elke connector voor meer informatie over welke connectors StoragePropertyName ondersteunen en welke alternatieven beschikbaar zijn.

VectorStoreRecordVectorAttribute

Gebruik dit kenmerk om aan te geven dat uw eigenschap een vector bevat.

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

VectorStoreRecordVectorAttribute-parameters

Parameter Vereist Beschrijving
Dimensies Ja voor verzameling maken, optioneel, anders Het aantal dimensies dat de vector heeft. Dit is doorgaans vereist bij het maken van een vectorindex voor een verzameling.
IndexKind Nee Het type index waarmee de vector moet worden geïndexeer. De standaardinstelling is afhankelijk van het type vectorarchief.
DistanceFunction Nee Het type afstandsfunctie dat moet worden gebruikt bij het uitvoeren van vectorvergelijking tijdens vectorzoekopdrachten over deze vector. De standaardinstelling is afhankelijk van het type vectorarchief.
StoragePropertyName Nee Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Houd er rekening mee dat deze parameter niet wordt ondersteund door alle connectors, bijvoorbeeld waar alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

Algemene indextypen en functietypen voor afstand worden geleverd als statische waarden voor de Microsoft.SemanticKernel.Data.IndexKind en Microsoft.SemanticKernel.Data.DistanceFunction klassen. Afzonderlijke Vector Store-implementaties kunnen ook hun eigen indextypen en afstandsfuncties gebruiken, waarbij de database ongebruikelijke typen ondersteunt.

Tip

Raadpleeg de documentatie voor elke connector voor meer informatie over welke connectors StoragePropertyName ondersteunen en welke alternatieven beschikbaar zijn.

Alle methoden om records te upsert of op te halen, gebruiken een klasse- en vectorarchiefrecorddefinitie.

U kunt dit doen door uw eigen klasse te definiëren met aantekeningen voor de velden of door een klasse/type te gebruiken in combinatie met een recorddefinitie. Er moeten twee dingen worden gedaan voor een klasse, de eerste is het toevoegen van de aantekeningen met de veldtypen, de tweede is het versieren van de klasse met de vectorstoremodel decorator.

Tip

Raadpleeg voor de alternatieve benadering met behulp van een recorddefinitie het definiëren van uw schema met een recorddefinitie.

Hier volgt een voorbeeld van een model dat is ingericht met deze aantekeningen.

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

Tip

Het definiëren van een klasse met deze aantekeningen kan op meerdere manieren worden uitgevoerd, waarbij een van deze methoden de dataclasses module in Python gebruikt, die hier wordt weergegeven. In dit voorbeeld ziet u ook andere benaderingen (met behulp van Pydantic BaseModels en vanille Python-klassen).

Aantekeningen

Er zijn drie typen aantekeningen die moeten worden gebruikt en ze hebben een gemeenschappelijke basisklasse.

VectorStoreRecordField

Dit is de basisklasse voor alle aantekeningen, het is niet bedoeld om rechtstreeks te worden gebruikt.

VectorStoreRecordField-parameters

Parameter Vereist Description
naam Nee Kan rechtstreeks worden toegevoegd, maar wordt ingesteld tijdens het parseren van het model.
property_type Nee Moet een tekenreeks zijn, wordt ook afgeleid tijdens het parseren.

Tip

De aantekeningen worden geparseerd door de vectorstoremodel decorator en een van de dingen die het doet, is het maken van een recorddefinitie voor de klasse, het is daarom niet nodig om een veldklasse te instantiëren wanneer er geen parameters zijn ingesteld, het veld kan worden geannoteerd met alleen de klasse, zoals deze:

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Gebruik deze aantekening om aan te geven dat dit kenmerk de sleutel van de record is.

VectorStoreRecordKeyField()

VectorStoreRecordKeyField-parameters

Er worden geen andere parameters buiten de basisklasse gedefinieerd.

VectorStoreRecordDataField

Gebruik deze aantekening om aan te geven dat uw kenmerk algemene gegevens bevat die geen sleutel of vector zijn.

VectorStoreRecordDataField(is_filterable=True)

Parameters VectorStoreRecordDataField

Parameter Vereist Beschrijving
has_embedding Nee Geeft aan of aan de eigenschap een insluiting is gekoppeld. De standaardwaarde is Geen.
embedding_property_name Nee De naam van de eigenschap die de insluiting bevat, is geen.
is_filterable Nee Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor filteren in gevallen waarin een database moet inschakelen voor indexering per eigenschap. Standaard ingesteld op onwaar.
is_full_text_searchable Nee Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor zoeken in volledige tekst naar databases die zoeken in volledige tekst ondersteunen. Standaard ingesteld op onwaar.

VectorStoreRecordVectorField

Gebruik deze aantekening om aan te geven dat uw kenmerk een vector bevat.

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

VectorStoreRecordVectorField-parameters

Parameter Vereist Beschrijving
dimensions Ja voor verzameling maken, optioneel, anders Het aantal dimensies dat de vector heeft. Dit is doorgaans vereist bij het maken van een vectorindex voor een verzameling.
index_kind Nee Het type index waarmee de vector moet worden geïndexeer. De standaardinstelling is afhankelijk van het type vectorarchief.
distance_function Nee Het type afstandsfunctie dat moet worden gebruikt bij het uitvoeren van vectorvergelijking tijdens vectorzoekopdrachten over deze vector. De standaardinstelling is afhankelijk van het type vectorarchief.
local_embedding Nee Hiermee wordt aangegeven of aan de eigenschap een lokale insluiting is gekoppeld. De standaardwaarde is Geen.
embedding_settings Nee De instellingen voor het insluiten, in de vorm van een dict met service_id als sleutel en PromptExecutionSettings als waarde, is geen.
serialize_function Nee De functie die moet worden gebruikt voor het serialiseren van de vector, als het type geen lijst[float | int] is, is deze functie nodig of moet het hele model worden geserialiseerd.
deserialize_function Nee De functie die moet worden gebruikt om de vector te deserialiseren, als het type geen lijst[float | int] is, is deze functie nodig of moet het hele model worden gedeserialiseerd.

Algemene indextypen en functietypen voor afstand worden geleverd als statische waarden voor de semantic_kernel.data.IndexKind en semantic_kernel.data.DistanceFunction klassen. Afzonderlijke Vector Store-implementaties kunnen ook hun eigen indextypen en afstandsfuncties gebruiken, waarbij de database ongebruikelijke typen ondersteunt.

Alle methoden voor upsert of het ophalen van records maken gebruik van sterk getypeerde modelklassen. De velden in deze klassen zijn versierd met aantekeningen die het doel van elk veld aangeven.

Tip

Raadpleeg voor een alternatief voor het gebruik van kenmerken het definiëren van uw schema met een recorddefinitie.

Hier volgt een voorbeeld van een model dat is ingericht met deze aantekeningen. De meeste out-of-the-box vectorarchieven maken standaard gebruik van Jackson, dus is een goede gewoonte om ervoor te zorgen dat het modelobject kan worden geserialiseerd door Jackson, d.w.: de klasse is zichtbaar, heeft getters, constructor, aantekeningen, enzovoort.

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

Aantekeningen

VectorStoreRecordKey

Gebruik deze aantekening om aan te geven dat uw veld de sleutel van de record is.

@VectorStoreRecordKey
private String hotelId;

Parameters VectorStoreRecordKey

Parameter Vereist Beschrijving
storageName Nee Kan worden gebruikt om een alternatieve naam op te geven voor het veld in de database. Houd er rekening mee dat deze parameter niet wordt ondersteund door alle connectors, bijvoorbeeld wanneer Jackson wordt gebruikt, in dat geval kan de opslagnaam worden opgegeven met behulp van Jackson-aantekeningen.

Tip

Raadpleeg de documentatie voor elke connector voor meer informatie over welke connectors storageName ondersteunen en welke alternatieven beschikbaar zijn.

VectorStoreRecordData

Gebruik deze aantekening om aan te geven dat uw veld algemene gegevens bevat die geen sleutel of vector zijn.

@VectorStoreRecordData(isFilterable = true)
private String name;

VectorStoreRecordData-parameters

Parameter Vereist Beschrijving
isFilterable Nee Hiermee wordt aangegeven of het veld moet worden geïndexeerd voor filteren in gevallen waarin een database moet inschakelen voor indexering per veld. Standaard ingesteld op onwaar.
isFullTextSearchable Nee Hiermee wordt aangegeven of het veld moet worden geïndexeerd voor zoeken in volledige tekst naar databases die zoeken in volledige tekst ondersteunen. Standaard ingesteld op onwaar.
storageName Nee Kan worden gebruikt om een alternatieve naam op te geven voor het veld in de database. Houd er rekening mee dat deze parameter niet wordt ondersteund door alle connectors, bijvoorbeeld wanneer Jackson wordt gebruikt, in dat geval kan de opslagnaam worden opgegeven met behulp van Jackson-aantekeningen.

Tip

Raadpleeg de documentatie voor elke connector voor meer informatie over welke connectors storageName ondersteunen en welke alternatieven beschikbaar zijn.

VectorStoreRecordVector

Gebruik deze aantekening om aan te geven dat uw veld een vector bevat.

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

VectorStoreRecordVector-parameters

Parameter Vereist Beschrijving
dimensions Ja voor verzameling maken, optioneel, anders Het aantal dimensies dat de vector heeft. Dit is doorgaans vereist bij het maken van een vectorindex voor een verzameling.
indexKind Nee Het type index waarmee de vector moet worden geïndexeer. De standaardinstelling is afhankelijk van het type vectorarchief.
distanceFunction Nee Het type afstandsfunctie dat moet worden gebruikt bij het uitvoeren van vectorvergelijking tijdens vectorzoekopdrachten over deze vector. De standaardinstelling is afhankelijk van het type vectorarchief.
storageName Nee Kan worden gebruikt om een alternatieve naam op te geven voor het veld in de database. Houd er rekening mee dat deze parameter niet wordt ondersteund door alle connectors, bijvoorbeeld wanneer Jackson wordt gebruikt, in dat geval kan de opslagnaam worden opgegeven met behulp van Jackson-aantekeningen.

Algemene indextypen en typen afstandsfuncties worden verstrekt op de com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind enums com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction . Afzonderlijke Vector Store-implementaties kunnen ook hun eigen indextypen en afstandsfuncties gebruiken, waarbij de database ongebruikelijke typen ondersteunt.

Tip

Raadpleeg de documentatie voor elke connector voor meer informatie over welke connectors storageName ondersteunen en welke alternatieven beschikbaar zijn.

Binnenkort meer informatie.