Freigeben über

Definieren des Speicherschemas mithilfe einer Datensatzdefinition (Vorschau)

  • Artikel

Warnung

Die Funktionalität des semantischen Kernelvektorspeichers befindet sich in der Vorschau, und Verbesserungen, die fehlerhafte Änderungen erfordern, können unter begrenzten Umständen noch vor der Veröffentlichung auftreten.

Übersicht

Die Connectors für den semantischen Kernelvektorspeicher verwenden zunächst einen Modellansatz für die Interaktion mit Datenbanken und ermöglichen das Kommentieren von Datenmodellen mit Informationen, die zum Erstellen von Indizes oder zum Zuordnen von Daten zum Datenbankschema erforderlich sind.

Eine weitere Möglichkeit, diese Informationen bereitzustellen, ist über Datensatzdefinitionen, die separat für das Datenmodell definiert und bereitgestellt werden können. Dies kann in mehreren Szenarien nützlich sein:

  • Es kann vorkommen, dass ein Entwickler dasselbe Datenmodell mit mehr als einer Konfiguration verwenden möchte.
  • Es kann vorkommen, dass der Entwickler Daten mit einem sehr anderen Schema für das Modell speichern möchte und einen benutzerdefinierten Mapper für die Konvertierung zwischen dem Datenmodell und dem Speicherschema bereitstellen möchte.
  • Es kann ein Fall geben, in dem ein Entwickler einen integrierten Typ verwenden möchte, z. B. ein Diktat oder ein optimiertes Format wie ein Dataframe und dennoch die Funktionalität des Vektorspeichers nutzen möchte.

Hier ist ein Beispiel zum Erstellen einer Datensatzdefinition.

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

Beim Erstellen einer Definition müssen Sie immer einen Namen und Typ für jede Eigenschaft in Ihrem Schema angeben, da dies für die Indexerstellung und die Datenzuordnung erforderlich ist.

Um die Definition zu verwenden, übergeben Sie sie an die GetCollection-Methode.

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

Konfigurationsklassen für Datensatzeigenschaften

VectorStoreRecordKeyProperty

Verwenden Sie diese Klasse, um anzugeben, dass Ihre Eigenschaft der Schlüssel des Datensatzes ist.

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

VectorStoreRecordKeyProperty-Konfigurationseinstellungen

Parameter Erforderlich Beschreibung
DataModelPropertyName Ja Der Name der Eigenschaft für das Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
PropertyType Ja Der Typ der Eigenschaft für das Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
StoragePropertyName No Kann verwendet werden, um einen alternativen Namen für die Eigenschaft in der Datenbank anzugeben. Beachten Sie, dass dieser Parameter nicht von allen Connectors unterstützt wird, z. B. wenn Alternativen wie JsonPropertyNameAttribute unterstützt werden.

Tipp

Weitere Informationen dazu, welche Connectors StoragePropertyName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.

VectorStoreRecordDataProperty

Verwenden Sie diese Klasse, um anzugeben, dass Ihre Eigenschaft allgemeine Daten enthält, die kein Schlüssel oder ein Vektor sind.

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

VectorStoreRecordDataProperty-Konfigurationseinstellungen

Parameter Erforderlich Beschreibung
DataModelPropertyName Ja Der Name der Eigenschaft für das Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
PropertyType Ja Der Typ der Eigenschaft für das Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
IsFilterable No Gibt an, ob die Eigenschaft für die Filterung indiziert werden soll, wenn eine Datenbank die Indizierung pro Eigenschaft erfordert. Standardwert ist „falsch“.
IsFullTextSearchable No Gibt an, ob die Eigenschaft für die Volltextsuche für Datenbanken indiziert werden soll, die die Volltextsuche unterstützen. Standardwert ist „falsch“.
StoragePropertyName No Kann verwendet werden, um einen alternativen Namen für die Eigenschaft in der Datenbank anzugeben. Beachten Sie, dass dieser Parameter nicht von allen Connectors unterstützt wird, z. B. wenn Alternativen wie JsonPropertyNameAttribute unterstützt werden.

Tipp

Weitere Informationen dazu, welche Connectors StoragePropertyName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.

VectorStoreRecordVectorProperty

Verwenden Sie diese Klasse, um anzugeben, dass Ihre Eigenschaft einen Vektor enthält.

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

VectorStoreRecordVectorProperty-Konfigurationseinstellungen

Parameter Erforderlich Beschreibung
DataModelPropertyName Ja Der Name der Eigenschaft für das Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
PropertyType Ja Der Typ der Eigenschaft für das Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
Maße Ja für sammlungserstellung, andernfalls optional Die Anzahl der Dimensionen, die der Vektor hat. Dies ist in der Regel erforderlich, wenn ein Vektorindex für eine Auflistung erstellt wird.
IndexKind No Der Indextyp, mit dem der Vektor indiziert werden soll. Der Standardwert variiert je nach Vektorspeichertyp.
DistanceFunction No Der Typ der Entfernungsfunktion, die beim Vektorvergleich während der Vektorsuche über diesen Vektor verwendet werden soll. Der Standardwert variiert je nach Vektorspeichertyp.
StoragePropertyName No Kann verwendet werden, um einen alternativen Namen für die Eigenschaft in der Datenbank anzugeben. Beachten Sie, dass dieser Parameter nicht von allen Connectors unterstützt wird, z. B. wenn Alternativen wie JsonPropertyNameAttribute unterstützt werden.

Tipp

Weitere Informationen dazu, welche Connectors StoragePropertyName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.

Hier ist ein Beispiel für das Erstellen einer Datensatzdefinition für die Verwendung mit einem Pandas DataFrame.

Hinweis

Die gleichen Felder wie in der Datenmodelldefinition werden hier für ein Datenmodell verwendet, das sie als Anmerkungen hinzugefügt werden, hier als Diktat mit dem Namen.

Es gibt ein paar wichtige Dinge zu beachten, andere dann die Felder definitionen selbst. Der erste ist der container_mode Parameter. Bei Festlegung auf "True" gibt dies an, dass das Datenmodell ein Containertyp ist, z. B. ein DataFrame, und dass das Datenmodell daher ein Container mit Datensätzen anstelle eines einzelnen Datensatzes ist, kann ein Containerdatensatz auf die gleiche Weise verwendet werden. Der Hauptunterschied besteht darin, dass get und get_batch derselbe Datentyp zurückgegeben wird, mit einem einzelnen Datensatz für einen get und einen oder mehrere für ein get_batch. Wenn Sie einen Upsert ausführen möchten und upsert_batch austauschbar verwendet werden können, upsert d. h. das Übergeben eines Containers führt zu upsert mehreren Upserts anstelle eines einzigen.

Die zweite ist das Hinzufügen der to_dict Methoden und from_dict Methoden, die zum Konvertieren zwischen dem Datenmodell und dem Speicherschema verwendet werden. In diesem Fall wird die to_dict Methode verwendet, um den DataFrame in eine Liste von Datensätzen zu konvertieren, und die from_dict Methode wird verwendet, um eine Liste von Datensätzen in einen DataFrame zu konvertieren. Es kann auch eine und deserialize eine serialize Methode (nicht im folgenden Beispiel gezeigt) geben, um details zu dem Unterschied zwischen diesen informationen finden Sie in der Serialisierungsdokumentation.

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

Beim Erstellen einer Definition müssen Sie immer einen Namen (als Schlüssel im fields Diktieren) und den Typ für jede Eigenschaft in Ihrem Schema angeben, da dies für die Indexerstellung und die Datenzuordnung erforderlich ist.

Um die Definition zu verwenden, übergeben Sie sie zusammen mit dem Datentyp an die GetCollection-Methode oder einen Sammlungskonstruktor.

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

Hier ist ein Beispiel zum Erstellen einer Datensatzdefinition.

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

Beim Erstellen einer Definition müssen Sie immer einen Namen und Typ für jedes Feld in Ihrem Schema angeben, da dies für die Indexerstellung und die Datenzuordnung erforderlich ist.

Um die Definition zu verwenden, übergeben Sie sie an die GetCollection-Methode.

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

Datensatzfeldkonfigurationsklassen

VectorStoreRecordKeyField

Verwenden Sie diese Klasse, um anzugeben, dass Ihr Feld der Schlüssel des Datensatzes ist.

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

VectorStoreRecordKeyField-Konfigurationseinstellungen

Parameter Erforderlich Beschreibung
name Ja Der Name des Felds im Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
fieldType Ja Der Typ des Felds im Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
storageName No Kann verwendet werden, um einen alternativen Namen für das Feld in der Datenbank anzugeben. Beachten Sie, dass dieser Parameter nicht von allen Connectors unterstützt wird, z. B. wo Jackson verwendet wird, in diesem Fall kann der Speichername mithilfe von Jackson-Anmerkungen angegeben werden.

Tipp

Weitere Informationen dazu, welche Connectors storageName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.

VectorStoreRecordDataField

Verwenden Sie diese Klasse, um anzugeben, dass Ihre Eigenschaft allgemeine Daten enthält, die kein Schlüssel oder ein Vektor sind.

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

VectorStoreRecordDataField-Konfigurationseinstellungen

Parameter Erforderlich Beschreibung
name Ja Der Name des Felds im Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
fieldType Ja Der Typ des Felds im Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
isFilterable No Gibt an, ob das Feld für die Filterung indiziert werden soll, wenn eine Datenbank die Indizierung pro Feld erfordert. Standardwert ist „falsch“.
isFullTextSearchable No Gibt an, ob das Feld für die Volltextsuche für Datenbanken indiziert werden soll, die die Volltextsuche unterstützen. Standardwert ist „falsch“.
storageName No Kann verwendet werden, um einen alternativen Namen für das Feld in der Datenbank anzugeben. Beachten Sie, dass dieser Parameter nicht von allen Connectors unterstützt wird, z. B. wo Jackson verwendet wird, in diesem Fall kann der Speichername mithilfe von Jackson-Anmerkungen angegeben werden.

Tipp

Weitere Informationen dazu, welche Connectors storageName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.

VectorStoreRecordVectorField

Verwenden Sie diese Klasse, um anzugeben, dass Ihr Feld einen Vektor enthält.

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

VectorStoreRecordVectorField-Konfigurationseinstellungen

Parameter Erforderlich Beschreibung
name Ja Der Name des Felds im Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
fieldType Ja Der Typ des Felds im Datenmodell. Wird von den integrierten Mappern verwendet, um automatisch zwischen dem Speicherschema und dem Datenmodell und zum Erstellen von Indizes zuzuordnen.
Dimensionen Ja für sammlungserstellung, andernfalls optional Die Anzahl der Dimensionen, die der Vektor hat. Dies ist in der Regel erforderlich, wenn ein Vektorindex für eine Auflistung erstellt wird.
indexKind No Der Indextyp, mit dem der Vektor indiziert werden soll. Der Standardwert variiert je nach Vektorspeichertyp.
distanceFunction No Der Typ der Entfernungsfunktion, die beim Vektorvergleich während der Vektorsuche über diesen Vektor verwendet werden soll. Der Standardwert variiert je nach Vektorspeichertyp.
storageName No Kann verwendet werden, um einen alternativen Namen für das Feld in der Datenbank anzugeben. Beachten Sie, dass dieser Parameter nicht von allen Connectors unterstützt wird, z. B. wo Jackson verwendet wird, in diesem Fall kann der Speichername mithilfe von Jackson-Anmerkungen angegeben werden.

Tipp

Weitere Informationen dazu, welche Connectors storageName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.