Définition de votre modèle de données (préversion)

Toutes les méthodes pour upsert ou obtenir des enregistrements utilisent des classes de modèle fortement typées. Les propriétés de ces classes sont décorées avec des attributs qui indiquent l’objectif de chaque propriété.

Voici un exemple de modèle décoré avec ces attributs.

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

Attributs

VectorStoreRecordKeyAttribute

Utilisez cet attribut pour indiquer que votre propriété est la clé de l’enregistrement.

[VectorStoreRecordKey]
public ulong HotelId { get; set; }

Paramètres VectorStoreRecordKeyAttribute

VectorStoreRecordDataAttribute

Utilisez cet attribut pour indiquer que votre propriété contient des données générales qui ne sont pas une clé ou un vecteur.

[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }

Paramètres VectorStoreRecordDataAttribute

VectorStoreRecordVectorAttribute

Utilisez cet attribut pour indiquer que votre propriété contient un vecteur.

[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

Paramètres VectorStoreRecordVectorAttribute

Les types de fonctions d’index courants et de distance sont fournis sous forme de valeurs statiques sur les classes et Microsoft.SemanticKernel.Data.DistanceFunction les Microsoft.SemanticKernel.Data.IndexKind classes. Les implémentations de magasin de vecteurs individuels peuvent également utiliser leurs propres types d’index et fonctions de distance, où la base de données prend en charge des types inhabituels.

Toutes les méthodes permettant d’effectuer un upsert ou d’obtenir des enregistrements utilisent une classe et une définition d’enregistrement de magasin vectoriel.

Pour ce faire, vous pouvez définir votre propre classe avec des annotations pour les champs, ou en utilisant une classe/type en combinaison avec une définition d’enregistrement. Deux choses doivent être effectuées pour une classe, la première consiste à ajouter les annotations avec les types de champs, la seconde consiste à décorer la classe avec le vectorstoremodel décorateur.

Voici un exemple de modèle décoré avec ces annotations.

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

Annotations

Il existe trois types d’annotations à utiliser, et ils ont une classe de base commune.

VectorStoreRecordField

Il s’agit de la classe de base pour toutes les annotations, elle n’est pas destinée à être utilisée directement.

Paramètres VectorStoreRecordField

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Utilisez cette annotation pour indiquer que cet attribut est la clé de l’enregistrement.

VectorStoreRecordKeyField()

Paramètres VectorStoreRecordKeyField

Aucun autre paramètre en dehors de la classe de base n’est défini.

VectorStoreRecordDataField

Utilisez cette annotation pour indiquer que votre attribut contient des données générales qui ne sont pas une clé ou un vecteur.

VectorStoreRecordDataField(is_filterable=True)

Paramètres VectorStoreRecordDataField

VectorStoreRecordVectorField

Utilisez cette annotation pour indiquer que votre attribut contient un vecteur.

VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)

Paramètres VectorStoreRecordVectorField

Les types de fonctions d’index courants et de distance sont fournis sous forme de valeurs statiques sur les classes et semantic_kernel.data.DistanceFunction les semantic_kernel.data.IndexKind classes. Les implémentations de magasin de vecteurs individuels peuvent également utiliser leurs propres types d’index et fonctions de distance, où la base de données prend en charge des types inhabituels.

Toutes les méthodes pour upsert ou obtenir des enregistrements utilisent des classes de modèle fortement typées. Les champs de ces classes sont décorés avec des annotations qui indiquent l’objectif de chaque champ.

Voici un exemple de modèle décoré avec ces annotations. Par défaut, la plupart des magasins de vecteurs sortants utilisent Jackson, c’est donc une bonne pratique pour s’assurer que l’objet modèle peut être sérialisé par Jackson, c’est-à-dire que la classe est visible, a des getters, constructeur, annotations, etc.

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

Annotations

VectorStoreRecordKey

Utilisez cette annotation pour indiquer que votre champ est la clé de l’enregistrement.

@VectorStoreRecordKey
private String hotelId;

Paramètres VectorStoreRecordKey

VectorStoreRecordData

Utilisez cette annotation pour indiquer que votre champ contient des données générales qui ne sont pas une clé ou un vecteur.

@VectorStoreRecordData(isFilterable = true)
private String name;

Paramètres VectorStoreRecordData

VectorStoreRecordVector

Utilisez cette annotation pour indiquer que votre champ contient un vecteur.

@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;

Paramètres VectorStoreRecordVector

Les types de fonctions d’index courants et de distance sont fournis sur les com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind énumérations et com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction les énumérations. Les implémentations de magasin de vecteurs individuels peuvent également utiliser leurs propres types d’index et fonctions de distance, où la base de données prend en charge des types inhabituels.

Plus d’informations prochainement.