Uw opslagschema definiëren met behulp van een recorddefinitie (preview)

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 interactie heeft met databases en maakt het mogelijk om aantekeningen te maken bij gegevensmodellen met informatie die nodig is voor het maken van indexen of toewijzingsgegevens aan het databaseschema.

Een andere manier om deze informatie op te geven, is via recorddefinities die kunnen worden gedefinieerd en afzonderlijk aan het gegevensmodel kunnen worden verstrekt. Dit kan handig zijn in meerdere scenario's:

• Het kan gebeuren dat een ontwikkelaar hetzelfde gegevensmodel met meer dan één configuratie wil gebruiken.
• Het kan gebeuren dat de ontwikkelaar gegevens wil opslaan met behulp van een heel ander schema voor het model en een aangepaste mapper wil opgeven voor conversie tussen het gegevensmodel en het opslagschema.
• Het kan gebeuren dat een ontwikkelaar een ingebouwd type wil gebruiken, zoals een dict, of een geoptimaliseerde indeling zoals een dataframe en nog steeds gebruik wil maken van de functionaliteit van het vectorarchief.

Hier volgt een voorbeeld van het maken van een recorddefinitie.

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

Wanneer u een definitie maakt, moet u altijd een naam en type opgeven voor elke eigenschap in uw schema, omdat dit vereist is voor het maken van indexen en het toewijzen van gegevens.

Als u de definitie wilt gebruiken, geeft u deze door aan de Methode GetCollection.

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

Configuratieklassen recordeigenschappen

VectorStoreRecordKeyProperty

Gebruik deze klasse om aan te geven dat uw eigenschap de sleutel van de record is.

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

Configuratie-instellingen vectorStoreRecordKeyProperty

Parameter	Vereist	Beschrijving
DataModelPropertyName	Ja	De naam van de eigenschap in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
PropertyType	Ja	Het type eigenschap in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
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.

VectorStoreRecordDataProperty

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

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

Configuratie-instellingen vectorStoreRecordDataProperty

Parameter	Vereist	Beschrijving
DataModelPropertyName	Ja	De naam van de eigenschap in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
PropertyType	Ja	Het type eigenschap in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
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.

VectorStoreRecordVectorProperty

Gebruik deze klasse om aan te geven dat uw eigenschap een vector bevat.

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

Configuratie-instellingen vectorStoreRecordVectorProperty

Parameter	Vereist	Beschrijving
DataModelPropertyName	Ja	De naam van de eigenschap in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
PropertyType	Ja	Het type eigenschap in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
Afmetingen	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.

Tip

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

Hier volgt een voorbeeld van het maken van een recorddefinitie voor gebruik met een Pandas DataFrame.

Notitie

Dezelfde velden als in de definitie van het gegevensmodel worden hier gebruikt voor een gegevensmodel dat ze als aantekeningen worden toegevoegd, hier als een dict met de naam.

Er zijn een aantal belangrijke dingen die u moet noteren, andere dan de veldendefinities zelf. De eerste is de container_mode parameter. Als dit is ingesteld op Waar, geeft dit aan dat het gegevensmodel een containertype is, zoals een DataFrame, en dat het gegevensmodel daarom een container met records is, in plaats van één record, kan een containerrecord op exact dezelfde manier worden gebruikt, het belangrijkste verschil is dat get en get_batch hetzelfde gegevenstype wordt geretourneerd, met één record voor een get en een of meer voor een get_batch. Als u een upsert upsert wilt uitvoeren en upsert_batch door elkaar kunt worden gebruikt, met andere woorden, het doorgeven van een container aan upsert resulteert in meerdere upserts, in plaats van één.

De tweede is de toevoeging van de to_dict en from_dict methoden, die worden gebruikt om te converteren tussen het gegevensmodel en het opslagschema. In dit geval wordt de to_dict methode gebruikt om het DataFrame te converteren naar een lijst met records en wordt de from_dict methode gebruikt om een lijst met records te converteren naar een DataFrame. Er kunnen ook een serialize en deserialize methode zijn (niet weergegeven in het onderstaande voorbeeld), voor meer informatie over het verschil tussen de methoden in de serialisatiedocumentatie.

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

Bij het maken van een definitie moet u altijd een naam opgeven (als sleutel in de fields dict) en het type voor elke eigenschap in uw schema, omdat dit vereist is voor het maken van indexen en het toewijzen van gegevens.

Als u de definitie wilt gebruiken, geeft u deze door aan de Methode GetCollection of een verzamelingsconstructor, samen met het gegevensmodeltype.

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

Hier volgt een voorbeeld van het maken van een recorddefinitie.

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

Wanneer u een definitie maakt, moet u altijd een naam en type opgeven voor elk veld in uw schema, omdat dit vereist is voor het maken van indexen en het toewijzen van gegevens.

Als u de definitie wilt gebruiken, geeft u deze door aan de Methode GetCollection.

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

Configuratieklassen recordveld

VectorStoreRecordKeyField

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

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

Configuratie-instellingen vectorStoreRecordKeyField

Parameter	Vereist	Description
naam	Ja	De naam van het veld in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
fieldType	Ja	Het type veld in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
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.

VectorStoreRecordDataField

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

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

Configuratie-instellingen vectorStoreRecordDataField

Parameter	Vereist	Description
naam	Ja	De naam van het veld in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
fieldType	Ja	Het type veld in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
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.

VectorStoreRecordVectorField

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

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

Configuratie-instellingen vectorStoreRecordVectorField

Parameter	Vereist	Description
naam	Ja	De naam van het veld in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
fieldType	Ja	Het type veld in het gegevensmodel. Wordt gebruikt door de ingebouwde mappers om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
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.

Tip

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