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.

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.

Návod

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

Návod

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
{
    [VectorStoreKey]
    public ulong HotelId { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true)]
    public string Description { get; set; }

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

    [VectorStoreData(IsIndexed = true)]
    public string[] Tags { get; set; }
}

Atributy

VectorStoreKeyAttribute

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

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

Parametry VectorStoreKeyAttribute

Parametr	Požadováno	Popis
Název úložiště	Ne	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é.

Návod

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

VectorStoreDataAttribute

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

[VectorStoreData(IsIndexed = true)]
public string HotelName { get; set; }

Parametry VectorStoreDataAttribute

Parametr	Požadováno	Popis
IsIndexed	Ne	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.
IsFullTextIndexed	Ne	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.
Název úložiště	Ne	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é.

Návod

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

VectorStoreVectorAttribute

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

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

Je také možné použít vlastnosti VectorStoreVectorAttribute , které nemají typ vektoru, například vlastnost typu string. Když je vlastnost tímto způsobem zdobena, Microsoft.Exntesions.AI.IEmbeddingGenerator musí být instance poskytována do úložiště vektorů. Při upsertování záznamu se text, který je ve string vlastnosti, automaticky změní na vektor a uloží se jako vektor v databázi. Pomocí tohoto mechanismu není možné načíst vektor.

[VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
public string DescriptionEmbedding { get; set; }

Návod

Další informace o tom, jak používat předdefinované generování vkládání, najdete v tématu Povolení vygenerování vkládání ve službě Vector Store.

VectorStoreVectorAttribute – parametry

Parametr	Požadováno	Popis
Dimenze	Ano	Počet dimenzí, které vektor má. To se vyžaduje při vytváření vektorového indexu pro kolekci.
IndexKind	Ne	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
VzdálenostFunction	Ne	Typ funkce, 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ů.
Název úložiště	Ne	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.

Návod

Další informace o tom, které konektory podporují StorageName 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 .

Návod

Alternativní přístup pomocí definice záznamu najdete v tématu definování 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)]

Návod

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
název	Ne	Můžete přidat přímo, ale během analýzy modelu se nastaví.
property_type	Ne	Měl by to být řetězec, který bude také odvozen během analýzy.

Návod

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	Ne	Určuje, zda má vlastnost přidružené vložení, výchozí hodnota None.
embedding_property_name	Ne	Název vlastnosti, která obsahuje vkládání, výchozí hodnota None.
is_filterable	Ne	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	Ne	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
rozměry	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	Ne	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
distance_function	Ne	Typ funkce, 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	Ne	Určuje, zda má vlastnost přiřazené místní vložení, výchozí hodnota None.
embedding_settings	Ne	Nastavení pro vložení ve formě diktování s service_id jako klíč a PromptExecutionSettings jako hodnota je výchozí hodnota None.
serialize_function	Ne	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	Ne	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.

Návod

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
Název_úložiště	Ne	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.

Návod

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	Ne	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	Ne	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.
Název_úložiště	Ne	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.

Návod

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
rozměry	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	Ne	Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
vzdálenostFunction	Ne	Typ funkce, 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ů.
Název_úložiště	Ne	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.

Návod

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.