Definování datového modelu (Preview)

Upozorňující

Funkce sémantického úložiště vektorů jádra je ve verzi Preview a vylepšení, která vyžadují zásadní změny, se můžou vyskytovat za omezených okolností před vydáním.

Přehled

Konektory sémantického úložiště vektorů jádra používají první přístup modelu k interakci s databázemi.

Všechny metody pro přenesení nebo získání záznamů používají třídy modelu silného typu. Vlastnosti těchto tříd jsou zdobeny atributy, které označují účel každé vlastnosti.

Tip

Alternativu k použití atributů najdete v definování schématu s definicí záznamu.

Tip

Alternativu k definování vlastního datového modelu najdete v abstrakcích vektorového úložiště bez definování vlastního datového modelu.

Tady je příklad modelu, který je zdoben těmito atributy.

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

Atributy

VectorStoreRecordKeyAttribute

Tento atribut použijte k označení, že vaše vlastnost je klíčem záznamu.

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

Parametry VectorStoreRecordKeyAttribute

Parametr	Požadováno	Popis
StoragePropertyName	No	Lze použít k zadání alternativního názvu vlastnosti v databázi. Všimněte si, že tento parametr nejsou podporovány všemi konektory, například pokud se podporují alternativy, jako JsonPropertyNameAttribute jsou podporované.

Tip

Další informace o tom, které konektory podporují StoragePropertyName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordDataAttribute

Tento atribut použijte k označení, že vlastnost obsahuje obecná data, která nejsou klíčem nebo vektorem.

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

Parametry VectorStoreRecordDataAttribute

Parametr	Požadováno	Popis
IsFilterable	No	Určuje, zda má být vlastnost indexována pro filtrování v případech, kdy databáze vyžaduje souhlas s indexováním na vlastnost. Výchozí hodnota je False.
IsFullTextSearchable	No	Určuje, zda má být vlastnost indexována pro fulltextové vyhledávání databází, které podporují fulltextové vyhledávání. Výchozí hodnota je False.
StoragePropertyName	No	Lze použít k zadání alternativního názvu vlastnosti v databázi. Všimněte si, že tento parametr nejsou podporovány všemi konektory, například pokud se podporují alternativy, jako JsonPropertyNameAttribute jsou podporované.

Tip

Další informace o tom, které konektory podporují StoragePropertyName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordVectorAttribute

Tento atribut použijte k označení, že vlastnost obsahuje vektor.

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

Parametry VectorStoreRecordVectorAttribute

Parametr	Požadováno	Popis
Dimenze	Ano pro vytvoření kolekce, volitelné v opačném případě	Počet dimenzí, které vektor má. To se obvykle vyžaduje při vytváření vektorového indexu pro kolekci.
IndexKind	No	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
VzdálenostFunction	No	Typ funkce vzdálenosti, která se má použít při porovnávání vektorů při hledání vektorů nad tímto vektorem. Výchozí nastavení se liší podle typu úložiště vektorů.
StoragePropertyName	No	Lze použít k zadání alternativního názvu vlastnosti v databázi. Všimněte si, že tento parametr nejsou podporovány všemi konektory, například pokud se podporují alternativy, jako JsonPropertyNameAttribute jsou podporované.

Běžné typy indexů a typy funkcí vzdálenosti jsou zadány jako statické hodnoty v těchto Microsoft.SemanticKernel.Data.IndexKind třídách Microsoft.SemanticKernel.Data.DistanceFunction . Implementace jednotlivých vektorových úložiště mohou také používat vlastní typy indexů a funkce vzdálenosti, kde databáze podporuje neobvyklé typy.

Tip

Další informace o tom, které konektory podporují StoragePropertyName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

Všechny metody pro upsertování nebo získání záznamů používají třídu a definici záznamu úložiště vektorů.

To lze provést definováním vlastní třídy s poznámkami pro pole nebo pomocí třídy/typu v kombinaci s definicí záznamu. Pro třídu je potřeba udělat dvě věci, první je přidat poznámky k typům polí, druhý je ozdobit třídu dekorátorem vectorstoremodel .

Tip

Alternativní přístup s použitím definice záznamu najdete v definici schématu pomocí definice záznamu.

Tady je příklad modelu, který je zdoben těmito poznámkami.

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

Tip

Definování třídy s těmito poznámkami lze provádět několika způsoby, z nichž jeden používá dataclasses modul v Pythonu, který je zde uvedený. Tato ukázka ukazuje i další přístupy (pomocí Pydantic BaseModels a vanilla pythonových tříd).

Poznámky

Existují tři typy poznámek, které se mají použít, a mají společnou základní třídu.

VectorStoreRecordField

Toto je základní třída pro všechny poznámky, není určena k přímému použití.

Parametry VectorStoreRecordField

Parametr	Požadováno	Popis
name	No	Můžete přidat přímo, ale během analýzy modelu se nastaví.
property_type	No	Měl by to být řetězec, který bude také odvozen během analýzy.

Tip

Poznámky jsou analyzovány dekorátorem vectorstoremodel a jednou z věcí, které dělá, je vytvořit definici záznamu pro třídu, proto není nutné vytvořit instanci třídy pole, pokud nejsou nastaveny žádné parametry, pole může být anotováno pouze třídou, jako je tato:

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Tato poznámka slouží k označení, že tento atribut je klíčem záznamu.

VectorStoreRecordKeyField()

Parametry VectorStoreRecordKeyField

Nejsou definovány žádné jiné parametry mimo základní třídu.

VectorStoreRecordDataField

Tuto poznámku použijte k označení, že atribut obsahuje obecná data, která nejsou klíčem nebo vektorem.

VectorStoreRecordDataField(is_filterable=True)

Parametry VectorStoreRecordDataField

Parametr	Požadováno	Popis
has_embedding	No	Určuje, zda má vlastnost přidružené vložení, výchozí hodnota None.
embedding_property_name	No	Název vlastnosti, která obsahuje vkládání, výchozí hodnota None.
is_filterable	No	Určuje, zda má být vlastnost indexována pro filtrování v případech, kdy databáze vyžaduje souhlas s indexováním na vlastnost. Výchozí hodnota je False.
is_full_text_searchable	No	Určuje, zda má být vlastnost indexována pro fulltextové vyhledávání databází, které podporují fulltextové vyhledávání. Výchozí hodnota je False.

VectorStoreRecordVectorField

Tuto poznámku použijte k označení, že atribut obsahuje vektor.

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

Parametry VectorStoreRecordVectorField

Parametr	Požadováno	Popis
dimensions	Ano pro vytvoření kolekce, volitelné v opačném případě	Počet dimenzí, které vektor má. To se obvykle vyžaduje při vytváření vektorového indexu pro kolekci.
index_kind	No	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
distance_function	No	Typ funkce vzdálenosti, která se má použít při porovnávání vektorů při hledání vektorů nad tímto vektorem. Výchozí nastavení se liší podle typu úložiště vektorů.
local_embedding	No	Určuje, zda má vlastnost přiřazené místní vložení, výchozí hodnota None.
embedding_settings	No	Nastavení pro vložení ve formě diktování s service_id jako klíč a PromptExecutionSettings jako hodnota je výchozí hodnota None.
serialize_function	No	Funkce, která se má použít k serializaci vektoru, pokud typ není seznam [float | int] tato funkce potřebná nebo musí být serializován celý model.
deserialize_function	No	Funkce, která se má použít k deserializaci vektoru, pokud typ není seznam [float | int] tato funkce nutná nebo je potřeba deserializovat celý model.

Běžné typy indexů a typy funkcí vzdálenosti jsou zadány jako statické hodnoty v těchto semantic_kernel.data.IndexKind třídách semantic_kernel.data.DistanceFunction . Implementace jednotlivých vektorových úložiště mohou také používat vlastní typy indexů a funkce vzdálenosti, kde databáze podporuje neobvyklé typy.

Všechny metody pro přenesení nebo získání záznamů používají třídy modelu silného typu. Pole v těchto třídách jsou zdobena poznámkami, které označují účel každého pole.

Tip

Alternativu k použití atributů najdete v definování schématu s definicí záznamu.

Tady je příklad modelu, který je zdoben těmito poznámkami. Ve výchozím nastavení většina z krabicových vektorových úložišť používá Jackson, takže je vhodné zajistit, aby objekt modelu mohl být serializován Jacksonem, tj. třída je viditelná, má getters, konstruktor, poznámky atd.

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

Poznámky

VectorStoreRecordKey

Tuto poznámku použijte k označení, že pole je klíčem záznamu.

@VectorStoreRecordKey
private String hotelId;

Parametry VectorStoreRecordKey

Parametr	Požadováno	Popis
storageName	No	Lze použít k zadání alternativního názvu pole v databázi. Všimněte si, že tento parametr nejsou podporovány všemi spojnicemi, například pokud se používá Jackson, je možné zadat název úložiště pomocí poznámek Jackson.

Tip

Další informace o tom, které konektory podporují storageName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordData

Tato poznámka slouží k označení, že pole obsahuje obecná data, která nejsou klíčem nebo vektorem.

@VectorStoreRecordData(isFilterable = true)
private String name;

Parametry VectorStoreRecordData

Parametr	Požadováno	Popis
isFilterable	No	Určuje, jestli má být pole indexováno pro filtrování v případech, kdy databáze vyžaduje přihlášení k indexování pro jednotlivá pole. Výchozí hodnota je False.
isFullTextSearchable	No	Určuje, jestli má být pole indexováno pro fulltextové vyhledávání databází, které podporují fulltextové vyhledávání. Výchozí hodnota je False.
storageName	No	Lze použít k zadání alternativního názvu pole v databázi. Všimněte si, že tento parametr nejsou podporovány všemi spojnicemi, například pokud se používá Jackson, je možné zadat název úložiště pomocí poznámek Jackson.

Tip

Další informace o tom, které konektory podporují storageName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

VectorStoreRecordVector

Pomocí této poznámky můžete určit, že pole obsahuje vektor.

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

Parametry VectorStoreRecordVector

Parametr	Požadováno	Popis
dimensions	Ano pro vytvoření kolekce, volitelné v opačném případě	Počet dimenzí, které vektor má. To se obvykle vyžaduje při vytváření vektorového indexu pro kolekci.
indexKind	No	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
vzdálenostFunction	No	Typ funkce vzdálenosti, která se má použít při porovnávání vektorů při hledání vektorů nad tímto vektorem. Výchozí nastavení se liší podle typu úložiště vektorů.
storageName	No	Lze použít k zadání alternativního názvu pole v databázi. Všimněte si, že tento parametr nejsou podporovány všemi spojnicemi, například pokud se používá Jackson, je možné zadat název úložiště pomocí poznámek Jackson.

Běžné typy indexů a typy funkcí vzdálenosti jsou dodávány na výčtech com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind a com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction výčtech. Implementace jednotlivých vektorových úložiště mohou také používat vlastní typy indexů a funkce vzdálenosti, kde databáze podporuje neobvyklé typy.

Tip

Další informace o tom, které konektory podporují storageName a jaké alternativy jsou k dispozici, najdete v dokumentaci ke každému konektoru.

Další informace budou brzy k dispozici.