Serialisatie van uw gegevensmodel naar en van verschillende winkels (preview)

Als u wilt dat uw gegevensmodel in een database wordt opgeslagen, moet het worden geconverteerd naar een indeling die de database kan begrijpen. Voor verschillende databases zijn verschillende opslagschema's en indelingen vereist. Sommige hebben een strikt schema waaraan moet worden voldaan, terwijl andere toestaan dat het schema door de gebruiker wordt gedefinieerd.

Koppelingsopties

De vector store connectors die worden geleverd door Semantic Kernel bieden meerdere manieren om deze toewijzing te bereiken.

Ingebouwde mappers

De vectoropslagconnectors van Semantic Kernel hebben ingebouwde mappers die uw gegevensmodel naar en van de databaseschema's vertalen. Zie de pagina voor elke connector voor meer informatie over hoe de ingebouwde mappers gegevens voor elke database toewijzen.

Aangepaste mappers

De vector store-connectors van Semantische Kernel ondersteunen de mogelijkheid om aangepaste mappers in combinatie met een VectorStoreRecordDefinitionaan te bieden. In dit geval kan de VectorStoreRecordDefinition afwijken van het opgegeven gegevensmodel. De VectorStoreRecordDefinition wordt gebruikt om het databaseschema te definiëren, terwijl het gegevensmodel wordt gebruikt door de ontwikkelaar om te communiceren met het vectorarchief. In dit geval is een aangepaste mapper vereist om het gegevensmodel toe te wijzen aan het aangepaste databaseschema dat door de VectorStoreRecordDefinitionis gedefinieerd.

Fooi

Zie Een aangepaste mapper maken voor een Vector Store-connector voor een voorbeeld van het maken van uw eigen aangepaste mapper.

Als u wilt dat uw gegevensmodel is gedefinieerd als een klasse of een definitie die in een database moet worden opgeslagen, moet het worden geserialiseerd naar een indeling die de database kan begrijpen.

Er zijn twee manieren waarop u kunt doen door gebruik te maken van de ingebouwde serialisatie die wordt geleverd door de Semantische kernel of door uw eigen serialisatielogica op te geven.

In de volgende twee diagrammen ziet u dat de stromen worden weergegeven voor zowel serialisatie als deserialisatie van gegevensmodellen naar en van een archiefmodel.

Serialisatiestroom (gebruikt in Upsert)

Deserialisatiestroom (gebruikt in Ophalen en Zoeken)

De stappen die zijn gemarkeerd met * (in beide diagrammen) worden geïmplementeerd door de ontwikkelaar van een specifieke connector en verschillen voor elke winkel. De stappen die zijn gemarkeerd met ** (in beide diagrammen) worden geleverd als een methode voor een record of als onderdeel van de recorddefinitie. Dit wordt altijd door de gebruiker verstrekt. Zie Direct Serialization voor meer informatie.

(De)Serialisatiebenaderingen

Directe serialisatie (Gegevensmodel naar Opslagmodel)

De directe serialisatie is de beste manier om volledige controle te garanderen over hoe uw modellen worden geserialiseerd en om de prestaties te optimaliseren. Het nadeel is dat het specifiek is voor een dataopslag en daarom niet zo eenvoudig is om tussen verschillende opslagplaatsen met hetzelfde gegevensmodel te schakelen.

U kunt dit gebruiken door een methode te implementeren die volgt op het SerializeMethodProtocol-protocol in uw gegevensmodel of door functies toe te voegen die de SerializeFunctionProtocol volgen aan uw recorddefinitie, beide vindt u in semantic_kernel/data/vector_store_model_protocols.py.

Wanneer een van deze functies aanwezig is, wordt het gebruikt om het gegevensmodel rechtstreeks te serialiseren naar het winkelmodel.

U kunt zelfs slechts een van de twee implementeren en de ingebouwde (de)serialisatie voor de andere richting gebruiken. Dit kan bijvoorbeeld handig zijn bij het omgaan met een verzameling die buiten uw beheer is gemaakt en u moet een aanpassing uitvoeren op de manier waarop deze wordt gedeserialiseerd (en u kunt toch geen upsert uitvoeren).

Ingebouwde (de)serialisatie (gegevensmodel naar Dict en Dict naar opslagmodel en omgekeerd)

De ingebouwde serialisatie wordt uitgevoerd door eerst het gegevensmodel te converteren naar een woordenlijst en het vervolgens te serialiseren naar het model dat wordt begrepen, voor elk archief dat anders is en gedefinieerd als onderdeel van de ingebouwde connector. Deserialisatie wordt uitgevoerd in de omgekeerde volgorde.

Serialisatie stap 1: Gegevensmodel naar Dict

Afhankelijk van het type gegevensmodel dat u hebt, worden de stappen op verschillende manieren uitgevoerd. Er zijn vier manieren waarop het gegevensmodel wordt geserialiseerd naar een woordenlijst:

1. to_dict methode voor de definitie (komt overeen met het to_dict-attribuut van het gegevensmodel, volgens de ToDictFunctionProtocol)
2. controleer of de record een ToDictMethodProtocol is en gebruik de methode to_dict
3. controleer of de record een Pydantic-model is en gebruik de model_dump van het model. Zie de onderstaande opmerking voor meer informatie.
4. de velden in de definitie doorlopen en de woordenlijst maken

Serialisatie stap 2: Dict to Store Model

Er moet een methode worden opgegeven door de connector voor het omzetten van de woordenlijst naar het opslagmodel. Dit wordt gedaan door de ontwikkelaar van de connector en verschilt voor elke winkel.

Deserialisatie stap 1: Model opslaan in Dict

Er moet een methode worden opgegeven door de connector voor het converteren van het winkelmodel naar een woordenlijst. Dit wordt gedaan door de ontwikkelaar van de connector en verschilt voor elke winkel.

Deserialisatie stap 2: Dicteren naar gegevensmodel

De deserialisatie wordt uitgevoerd in de omgekeerde volgorde en probeert deze opties:

1. from_dict methode voor de definitie (wordt uitgelijnd op het from_dict kenmerk van het gegevensmodel, volgens de FromDictFunctionProtocol)
2. controleer of de record een FromDictMethodProtocol is en gebruik de methode from_dict
3. controleer of de record een Pydantic-model is en gebruik de model_validate van het model. Zie de onderstaande opmerking voor meer informatie.
4. doorloop de velden in de definitie en stel de waarden in, dan wordt deze dict doorgegeven aan de constructor van het gegevensmodel als benoemde argumenten (tenzij het gegevensmodel een dict zelf is, in dat geval wordt deze geretourneerd als is)

Notitie

Pydantic gebruiken met ingebouwde serialisatie

Wanneer u een Model definieert met behulp van een Pydantic BaseModel, worden de model_dump en model_validate methoden gebruikt om het gegevensmodel naar en van een dict te serialiseren en deserialiseren. Dit gebeurt met behulp van de model_dump-methode zonder parameters. Als u hier controle over wilt hebben, overweeg dan ToDictMethodProtocol op uw gegevensmodel te implementeren, aangezien dit eerst wordt geprobeerd.

Serialisatie van vectoren

Wanneer u een vector in uw gegevensmodel hebt, moet het een lijst met floats of een lijst met ints zijn, omdat dat de meeste winkels nodig hebben, als u wilt dat uw klasse de vector in een andere indeling opslaat, kunt u de serialize_function en gedefinieerde aantekening deserialize_function gebruiken.VectorStoreRecordVectorField Voor een numpymatrix kunt u bijvoorbeeld de volgende aantekening gebruiken:

import numpy as np

vector: Annotated[
    np.ndarray | None,
    VectorStoreRecordVectorField(
        dimensions=1536,
        serialize_function=np.ndarray.tolist,
        deserialize_function=np.array,
    ),
] = None

Als u wel een vectorarchief gebruikt waarmee systeemeigen numpymatrices kunnen worden verwerkt en u ze niet heen en weer wilt laten converteren, moet u de directe serialisatie en deserialisatie instellen methoden voor het model en dat archief.

Notitie

Dit wordt alleen gebruikt bij het gebruik van de ingebouwde serialisatie, wanneer u de directe serialisatie gebruikt, kunt u de vector op elke gewenste manier verwerken.

Binnenkort beschikbaar

Binnenkort meer informatie.