Definieren des Datenmodells (Vorschau)
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.
Alle Methoden zum Upsertieren oder Abrufen von Datensätzen verwenden stark typierte Modellklassen. Die Eigenschaften für diese Klassen sind mit Attributen versehen, die den Zweck jeder Eigenschaft angeben.
Tipp
Eine Alternative zur Verwendung von Attributen finden Sie unter Definieren des Schemas mit einer Datensatzdefinition.
Tipp
Eine Alternative zum Definieren Ihres eigenen Datenmodells finden Sie unter Verwendung von Vector Store-Abstraktionen, ohne ihr eigenes Datenmodell zu definieren.
Hier ist ein Beispiel für ein Modell, das mit diesen Attributen versehen ist.
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; }
}
Attribute
VectorStoreRecordKeyAttribute
Verwenden Sie dieses Attribut, um anzugeben, dass Ihre Eigenschaft der Schlüssel des Datensatzes ist.
[VectorStoreRecordKey]
public ulong HotelId { get; set; }
VectorStoreRecordKeyAttribute-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| 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.
VectorStoreRecordDataAttribute
Verwenden Sie dieses Attribut, um anzugeben, dass Ihre Eigenschaft allgemeine Daten enthält, bei denen es sich nicht um einen Schlüssel oder einen Vektor handelt.
[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }
VectorStoreRecordDataAttribute-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| 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.
VectorStoreRecordVectorAttribute
Verwenden Sie dieses Attribut, um anzugeben, dass Ihre Eigenschaft einen Vektor enthält.
[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
VectorStoreRecordVectorAttribute-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| 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. |
| 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. |
Allgemeine Indextypen und Abstandsfunktionstypen werden als statische Werte für die Microsoft.SemanticKernel.Data.IndexKind Klassen und Microsoft.SemanticKernel.Data.DistanceFunction Klassen bereitgestellt.
Einzelne Vector Store-Implementierungen können auch eigene Indextypen und Entfernungsfunktionen verwenden, bei denen die Datenbank ungewöhnliche Typen unterstützt.
Tipp
Weitere Informationen dazu, welche Connectors StoragePropertyName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.
Alle Methoden zum Upsertieren oder Abrufen von Datensätzen verwenden eine Klasse und eine Vektorspeicherdatensatzdefinition.
Dazu können Sie eine eigene Klasse mit Anmerkungen für die Felder definieren oder eine Klasse/einen Typ in Kombination mit einer Datensatzdefinition verwenden. Zwei Dinge müssen für eine Klasse durchgeführt werden, der erste besteht darin, die Anmerkungen mit den Feldtypen hinzuzufügen, die zweite besteht darin, die Klasse mit dem vectorstoremodel Dekorateur zu dekorieren.
Tipp
Informationen zum alternativen Ansatz mithilfe einer Datensatzdefinition finden Sie unter Definieren des Schemas mit einer Datensatzdefinition.
Hier ist ein Beispiel für ein Modell, das mit diesen Anmerkungen versehen ist.
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)]
Tipp
Das Definieren einer Klasse mit diesen Anmerkungen kann auf mehrere Arten erfolgen, von denen eines das dataclasses Modul in Python verwendet, das hier gezeigt wird. In diesem Beispiel werden auch andere Ansätze (unter Verwendung von Pydantic BaseModels und Vanilla Python-Klassen) gezeigt.
Anmerkungen
Es gibt drei Arten von Anmerkungen, die verwendet werden sollen, und sie verfügen über eine gemeinsame Basisklasse.
VectorStoreRecordField
Dies ist die Basisklasse für alle Anmerkungen, die nicht direkt verwendet werden sollen.
VectorStoreRecordField-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| name | No | Kann direkt hinzugefügt werden, wird aber während der Analyse des Modells festgelegt. |
| property_type | No | Sollte eine Zeichenfolge sein, wird auch während der Analyse abgeleitet. |
Tipp
Die Anmerkungen werden vom vectorstoremodel Dekorateur analysiert und einer der Dinge, die es tut, besteht darin, eine Datensatzdefinition für die Klasse zu erstellen, daher ist es nicht erforderlich, eine Feldklasse zu instanziieren, wenn keine Parameter festgelegt werden, kann das Feld mit nur der Klasse kommentiert werden, wie hier:
hotel_id: Annotated[str, VectorStoreRecordKeyField]
VectorStoreRecordKeyField
Verwenden Sie diese Anmerkung, um anzugeben, dass dieses Attribut der Schlüssel des Datensatzes ist.
VectorStoreRecordKeyField()
VectorStoreRecordKeyField-Parameter
Es werden keine anderen Parameter außerhalb der Basisklasse definiert.
VectorStoreRecordDataField
Verwenden Sie diese Anmerkung, um anzugeben, dass Ihr Attribut allgemeine Daten enthält, bei denen es sich nicht um einen Schlüssel oder einen Vektor handelt.
VectorStoreRecordDataField(is_filterable=True)
VectorStoreRecordDataField-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| has_embedding | No | Gibt an, ob der Eigenschaft eine Einbettung zugeordnet ist, standardmäßig "None". |
| embedding_property_name | No | Der Name der Eigenschaft, die die Einbettung enthält, ist "None". |
| is_filterable | No | Gibt an, ob die Eigenschaft für die Filterung indiziert werden soll, wenn eine Datenbank die Indizierung pro Eigenschaft erfordert. Standardwert ist „falsch“. |
| is_full_text_searchable | No | Gibt an, ob die Eigenschaft für die Volltextsuche für Datenbanken indiziert werden soll, die die Volltextsuche unterstützen. Standardwert ist „falsch“. |
VectorStoreRecordVectorField
Verwenden Sie diese Anmerkung, um anzugeben, dass Ihr Attribut einen Vektor enthält.
VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)
VectorStoreRecordVectorField-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| 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. |
| index_kind | No | Der Indextyp, mit dem der Vektor indiziert werden soll. Der Standardwert variiert je nach Vektorspeichertyp. |
| distance_function | No | Der Typ der Entfernungsfunktion, die beim Vektorvergleich während der Vektorsuche über diesen Vektor verwendet werden soll. Der Standardwert variiert je nach Vektorspeichertyp. |
| local_embedding | No | Gibt an, ob die Eigenschaft eine lokale Einbettung zugeordnet ist, standardmäßig "None". |
| embedding_settings | No | Die Einstellungen für das Einbetten in Form eines Diktats mit service_id als Schlüssel und PromptExecutionSettings als Wert lautet "None". |
| serialize_function | No | Die Funktion, die zum Serialisieren des Vektors verwendet werden soll, wenn der Typ keine Liste[float | int] ist, ist diese Funktion erforderlich, oder das gesamte Modell muss serialisiert werden. |
| deserialize_function | No | Die Funktion, die zum Deserialisieren des Vektors verwendet werden soll, wenn der Typ keine Liste[float | int] ist, ist diese Funktion erforderlich, oder das gesamte Modell muss deserialisiert werden. |
Allgemeine Indextypen und Abstandsfunktionstypen werden als statische Werte für die semantic_kernel.data.IndexKind Klassen und semantic_kernel.data.DistanceFunction Klassen bereitgestellt.
Einzelne Vector Store-Implementierungen können auch eigene Indextypen und Entfernungsfunktionen verwenden, bei denen die Datenbank ungewöhnliche Typen unterstützt.
Alle Methoden zum Upsertieren oder Abrufen von Datensätzen verwenden stark typierte Modellklassen. Die Felder dieser Klassen sind mit Anmerkungen versehen, die den Zweck jedes Felds angeben.
Tipp
Eine Alternative zur Verwendung von Attributen finden Sie unter Definieren des Schemas mit einer Datensatzdefinition.
Hier ist ein Beispiel für ein Modell, das mit diesen Anmerkungen versehen ist. Standardmäßig verwenden die meisten out-box-Vektorspeicher Jackson, daher ist eine bewährte Methode, um sicherzustellen, dass das Modellobjekt von Jackson serialisiert werden kann, d. h. die Klasse ist sichtbar, hat Getters, Konstruktor, Anmerkungen usw.
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; }
}
Anmerkungen
VectorStoreRecordKey
Verwenden Sie diese Anmerkung, um anzugeben, dass Ihr Feld der Schlüssel des Datensatzes ist.
@VectorStoreRecordKey
private String hotelId;
VectorStoreRecordKey-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| 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.
VectorStoreRecordData
Verwenden Sie diese Anmerkung, um anzugeben, dass Ihr Feld allgemeine Daten enthält, bei denen es sich nicht um einen Schlüssel oder einen Vektor handelt.
@VectorStoreRecordData(isFilterable = true)
private String name;
VectorStoreRecordData-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| 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.
VectorStoreRecordVector
Verwenden Sie diese Anmerkung, um anzugeben, dass Ihr Feld einen Vektor enthält.
@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;
VectorStoreRecordVector-Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| 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. |
Allgemeine Indextypen und Abstandsfunktionstypen werden für die com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind Enumerationen und com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction Enumerationen bereitgestellt.
Einzelne Vector Store-Implementierungen können auch eigene Indextypen und Entfernungsfunktionen verwenden, bei denen die Datenbank ungewöhnliche Typen unterstützt.
Tipp
Weitere Informationen dazu, welche Connectors storageName unterstützen und welche Alternativen verfügbar sind, finden Sie in der Dokumentation für jeden Connector.
Weitere Informationen werden in Kürze verfügbar sein.