Serialisierung Ihres Datenmodells in und aus verschiedenen Stores (Vorschau)

Damit Ihr Datenmodell in einer Datenbank gespeichert werden kann, muss es in ein Format konvertiert werden, das die Datenbank verstehen kann. Für unterschiedliche Datenbanken sind unterschiedliche Speicherschemas und Formate erforderlich. Einige haben ein strenges Schema, das eingehalten werden muss, während andere zulassen, dass das Schema vom Benutzer definiert wird.

Die vom Semantic Kernel bereitgestellten Vektorspeicher-Connectoren verfügen über integrierte Mapper, die Ihr Datenmodell auf die Datenbankschemas abbilden. Weitere Informationen dazu, wie die integrierten Mapper Daten für jede Datenbank zuordnen, finden Sie auf der Seite für jeden Connector.

Damit Ihr Datenmodell entweder als Klasse oder definition in einer Datenbank gespeichert werden kann, muss es in einem Format serialisiert werden, das die Datenbank verstehen kann.

Es gibt zwei Möglichkeiten, die durchgeführt werden können, entweder mithilfe der integrierten Serialisierung, die vom semantischen Kernel bereitgestellt wird, oder indem Sie Ihre eigene Serialisierungslogik bereitstellen.

Die folgenden beiden Diagramme zeigen, dass die Flüsse sowohl für die Serialisierung als auch für die Deserialisierung von Datenmodellen in und von einem Speichermodell angezeigt werden.

Serialisierungsfluss (verwendet in Upsert)

Deserialisierungsfluss (verwendet in Get and Search)

Die Schritte, die mit * (in beiden Diagrammen) gekennzeichnet sind, werden vom Entwickler eines bestimmten Connectors implementiert und unterscheiden sich für jeden Shop. Die mit ** (in beiden Diagrammen) markierten Schritte werden entweder als Methode für einen Datensatz oder als Teil der Datensatzdefinition bereitgestellt, dies wird immer vom Benutzer bereitgestellt, weitere Informationen finden Sie unter Direct Serialization .

(De)Serialisierungsansätze

Direkte Serialisierung (Datenmodell zu Speicher-Modell)

Die direkte Serialisierung ist die beste Möglichkeit, um die vollständige Kontrolle darüber zu gewährleisten, wie Ihre Modelle serialisiert werden und um die Leistung zu optimieren. Der Nachteil besteht darin, dass es spezifisch für einen Datenspeicher ist und daher bei Verwendung dieses Systems man nicht so leicht zwischen verschiedenen Speichern mit demselben Datenmodell wechseln kann.

Sie können dies verwenden, indem Sie eine Methode implementieren, die dem SerializeMethodProtocol-Protokoll in Ihrem Datenmodell folgt, oder indem Sie Funktionen hinzufügen, die dem SerializeFunctionProtocol in Ihrer Datensatzdefinition folgen, und beides finden Sie in semantic_kernel/data/vector_store_model_protocols.py.

Wenn eine dieser Funktionen vorhanden ist, wird sie verwendet, um das Datenmodell direkt auf das Speichermodell zu serialisieren.

Sie können sogar nur eine der beiden Optionen implementieren und die integrierte (De-)Serialisierung für die andere Richtung verwenden. Dies kann zum Beispiel nützlich sein, wenn Sie es mit einer Sammlung zu tun haben, die außerhalb Ihres Einflusses erstellt wurde, und Sie müssen einige Anpassungen an der Art und Weise vornehmen, wie sie deserialisiert wird, wobei ein Upsert ohnehin nicht möglich ist.

Eingebaute (De-)Serialisierung (Datenmodell zu Wörterbuch und Wörterbuch zum Speichermodell und umgekehrt)

Die integrierte Serialisierung erfolgt, indem zuerst das Datenmodell in ein Wörterbuch konvertiert und dann in das Modell serialisiert wird, das vom Speicher verstanden wird, für jeden Speicher, der anders und als Teil des integrierten Connectors definiert ist. Die Deserialisierung erfolgt in umgekehrter Reihenfolge.

Serialisierung Schritt 1: Datenmodell zum Diktieren

Je nachdem, welche Art von Datenmodell Sie haben, werden die Schritte auf unterschiedliche Weise ausgeführt. Es gibt vier Möglichkeiten, das Datenmodell in ein Wörterbuch zu serialisieren:

1. to_dict Methode bezüglich der Definition (entspricht dem to_dict-Attribut des Datenmodells gemäß ToDictFunctionProtocol)
2. Überprüfen, ob der Datensatz ein ToDictMethodProtocol ist und die to_dict-Methode verwenden
3. Überprüfen Sie, ob es sich bei dem Datensatz um ein Pydantic-Modell handelt, und verwenden Sie die model_dump des Modells, siehe die nachstehende Notiz für weitere Informationen.
4. Die Felder in der Definition durchlaufen und das Wörterbuch erstellen.

Serialisierung Schritt 2: Diktieren zum Store-Modell

Eine Methode muss vom Connector bereitgestellt werden, um das Wörterbuch in das Speichermodell zu konvertieren. Dies wird durch den Entwickler des Connectors ausgeführt und unterscheidet sich für jeden Shop.

Deserialisierung Schritt 1: Modell in Dict speichern

Eine Methode muss vom Connector zum Konvertieren des Speichermodells in ein Wörterbuch bereitgestellt werden. Dies wird durch den Entwickler des Connectors ausgeführt und unterscheidet sich für jeden Shop.

Deserialisierung Schritt 2: Diktieren des Datenmodells

Die Deserialisierung erfolgt in umgekehrter Reihenfolge. Dabei versucht sie folgende Optionen:

1. from_dict-Methode zur Definition (entspricht dem from_dict Attribut des Datenmodells, entsprechend der FromDictFunctionProtocol)
2. Überprüfen, ob der Datensatz ein FromDictMethodProtocol ist und die from_dict-Methode verwenden
3. Überprüfen Sie, ob es sich bei dem Datensatz um ein Pydantic-Modell handelt, und verwenden Sie die model_validate des Modells, siehe die nachstehende Notiz für weitere Informationen.
4. durchlaufen Sie die Felder in der Definition, und legen Sie die Werte fest. Dieses Diktat wird dann als benannte Argumente an den Konstruktor des Datenmodells übergeben (es sei denn, das Datenmodell ist selbst ein Diktat, in diesem Fall wird es wie folgt zurückgegeben)

Anmerkung

Verwenden von Pydantic mit integrierter Serialisierung

Wenn Sie ein Modell mit einem Pydantic BaseModel definieren, verwendet es die model_dump methoden und model_validate serialisieren das Datenmodell in und von einem Diktat. Dies erfolgt mithilfe der model_dump-Methode ohne Angabe von Parametern. Wenn Sie dies steuern möchten, ziehen Sie in Betracht, die ToDictMethodProtocol in Ihrem Datenmodell zu implementieren, da dies zuerst versucht wird.

Serialisierung von Vektoren

Wenn Sie einen Vektor in Ihrem Datenmodell haben, muss es sich entweder um eine Liste von Floats oder eine Liste von Ints handeln, da dies die meisten Speicher benötigen, wenn Ihre Klasse den Vektor in einem anderen Format speichern soll, können Sie die serialize_function in der deserialize_function Anmerkung definierte und VectorStoreRecordVectorField verwenden. Für ein numpyes Array können Sie z. B. die folgende Anmerkung verwenden:

import numpy as np

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

Wenn Sie einen Vektorspeicher verwenden, der eigenen numpy-Arrays verarbeiten kann und Sie nicht möchten, dass sie hin- und herkonvertiert werden, sollten Sie die direkten Serialisierungs- und Deserialisierungsmethoden für das Modell und diesen Speicher einrichten.

Anmerkung

Dies wird nur bei Verwendung der integrierten Serialisierung verwendet, wenn Sie die direkte Serialisierung verwenden, können Sie den Vektor beliebig behandeln.

In Kürze verfügbar

Weitere Informationen werden in Kürze verfügbar sein.