Definiowanie modelu danych (wersja zapoznawcza)
Ostrzeżenie
Funkcja semantycznego magazynu wektorów jądra jest dostępna w wersji zapoznawczej, a ulepszenia wymagające zmian powodujących niezgodność mogą nadal występować w ograniczonych okolicznościach przed wydaniem.
Omówienie
Łączniki semantycznego magazynu wektorów jądra używają modelu pierwszego podejścia do interakcji z bazami danych.
Wszystkie metody operacji upsert lub pobierania rekordów używają silnie typiowanych klas modeli. Właściwości tych klas są ozdobione atrybutami wskazującymi przeznaczenie każdej właściwości.
Napiwek
Alternatywą dla używania atrybutów jest definiowanie schematu przy użyciu definicji rekordu.
Napiwek
Alternatywą dla definiowania własnego modelu danych jest użycie abstrakcji magazynu wektorów bez definiowania własnego modelu danych.
Oto przykład modelu, który jest ozdobiony tymi atrybutami.
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; }
}
Atrybuty
VectorStoreRecordKeyAttribute
Użyj tego atrybutu, aby wskazać, że właściwość jest kluczem rekordu.
[VectorStoreRecordKey]
public ulong HotelId { get; set; }
Parametry VectorStoreRecordKeyAttribute
| Parametr | Wymagania | opis |
|---|---|---|
| StoragePropertyName | Nie. | Może służyć do podawania alternatywnej nazwy właściwości w bazie danych. Należy pamiętać, że ten parametr nie jest obsługiwany przez wszystkie łączniki, np. jeśli są obsługiwane alternatywy, takie jak JsonPropertyNameAttribute . |
Napiwek
Aby uzyskać więcej informacji na temat łączników obsługujących usługę StoragePropertyName i dostępne alternatywy, zapoznaj się z dokumentacją każdego łącznika.
VectorStoreRecordDataAttribute
Użyj tego atrybutu, aby wskazać, że właściwość zawiera ogólne dane, które nie są kluczem ani wektorem.
[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }
Parametry VectorStoreRecordDataAttribute
| Parametr | Wymagania | opis |
|---|---|---|
| IsFilterable | Nie. | Wskazuje, czy właściwość powinna być indeksowana do filtrowania w przypadkach, gdy baza danych wymaga zgody na indeksowanie poszczególnych właściwości. Wartość domyślna to „fałsz”. |
| IsFullTextSearchable | Nie. | Wskazuje, czy właściwość powinna być indeksowana w celu wyszukiwania pełnotekstowego baz danych obsługujących wyszukiwanie pełnotekstowe. Wartość domyślna to „fałsz”. |
| StoragePropertyName | Nie. | Może służyć do podawania alternatywnej nazwy właściwości w bazie danych. Należy pamiętać, że ten parametr nie jest obsługiwany przez wszystkie łączniki, np. jeśli są obsługiwane alternatywy, takie jak JsonPropertyNameAttribute . |
Napiwek
Aby uzyskać więcej informacji na temat łączników obsługujących usługę StoragePropertyName i dostępne alternatywy, zapoznaj się z dokumentacją każdego łącznika.
VectorStoreRecordVectorAttribute
Użyj tego atrybutu, aby wskazać, że właściwość zawiera wektor.
[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
Parametry VectorStoreRecordVectorAttribute
| Parametr | Wymagania | opis |
|---|---|---|
| Wymiary | Tak w przypadku tworzenia kolekcji, opcjonalnie w przeciwnym razie | Liczba wymiarów, które ma wektor. Jest to zwykle wymagane podczas tworzenia indeksu wektorowego dla kolekcji. |
| IndexKind | Nie. | Typ indeksu do indeksowania wektora. Wartość domyślna różni się w zależności od typu magazynu wektorów. |
| Funkcja odległości | Nie. | Typ funkcji odległości do użycia podczas porównywania wektorów podczas wyszukiwania wektorów w tym wektorze. Wartość domyślna różni się w zależności od typu magazynu wektorów. |
| StoragePropertyName | Nie. | Może służyć do podawania alternatywnej nazwy właściwości w bazie danych. Należy pamiętać, że ten parametr nie jest obsługiwany przez wszystkie łączniki, np. jeśli są obsługiwane alternatywy, takie jak JsonPropertyNameAttribute . |
Typowe rodzaje indeksów i typy funkcji odległości są dostarczane jako wartości statyczne w klasach Microsoft.SemanticKernel.Data.IndexKind i Microsoft.SemanticKernel.Data.DistanceFunction .
Implementacje poszczególnych magazynów wektorów mogą również używać własnych typów indeksów i funkcji odległości, w których baza danych obsługuje nietypowe typy.
Napiwek
Aby uzyskać więcej informacji na temat łączników obsługujących usługę StoragePropertyName i dostępne alternatywy, zapoznaj się z dokumentacją każdego łącznika.
Wszystkie metody operacji upsert lub pobierania rekordów używają klasy i definicji rekordów magazynu wektorów.
Można to zrobić, definiując własną klasę z adnotacjami dla pól lub używając klasy/typu w połączeniu z definicją rekordu. Należy wykonać dwie czynności dla klasy, pierwszą jest dodanie adnotacji z typami pól, druga to udekorowanie klasy dekoratorem vectorstoremodel .
Napiwek
Aby użyć alternatywnej metody przy użyciu definicji rekordu, zapoznaj się z definicją rekordu w celu zdefiniowania schematu.
Oto przykład modelu, który jest ozdobiony tymi adnotacjami.
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)]
Napiwek
Definiowanie klasy z tymi adnotacjami można wykonać na wiele sposobów, z których jeden korzysta z modułu dataclasses w języku Python, pokazanego tutaj. W tym przykładzie przedstawiono również inne podejścia (korzystające z modeli bazowych Pydantic i waniliowych klas języka Python).
Adnotacje
Istnieją trzy typy adnotacji do użycia i mają wspólną klasę bazową.
VectorStoreRecordField
Jest to klasa bazowa dla wszystkich adnotacji, nie jest przeznaczona do bezpośredniego użycia.
Parametry VectorStoreRecordField
| Parametr | Wymagania | opis |
|---|---|---|
| name | Nie. | Można dodać bezpośrednio, ale zostanie ustawiony podczas analizowania modelu. |
| property_type | Nie. | Powinien być ciągiem, będzie również uzyskiwany podczas analizowania. |
Napiwek
Adnotacje są analizowane przez vectorstoremodel dekorator, a jedną z rzeczy, które wykonuje, jest utworzenie definicji rekordu dla klasy, dlatego nie jest konieczne utworzenie wystąpienia klasy pola, gdy nie ustawiono parametrów, pole można dodać adnotację tylko do klasy, w następujący sposób:
hotel_id: Annotated[str, VectorStoreRecordKeyField]
VectorStoreRecordKeyField
Użyj tej adnotacji, aby wskazać, że ten atrybut jest kluczem rekordu.
VectorStoreRecordKeyField()
Parametry VectorStoreRecordKeyField
Nie zdefiniowano żadnych innych parametrów poza klasą bazową.
VectorStoreRecordDataField
Użyj tej adnotacji, aby wskazać, że atrybut zawiera ogólne dane, które nie są kluczem ani wektorem.
VectorStoreRecordDataField(is_filterable=True)
Parametry VectorStoreRecordDataField
| Parametr | Wymagania | opis |
|---|---|---|
| has_embedding | Nie. | Wskazuje, czy właściwość ma skojarzone osadzanie, wartość domyślna to Brak. |
| embedding_property_name | Nie. | Nazwa właściwości, która zawiera osadzanie, wartość domyślna to Brak. |
| is_filterable | Nie. | Wskazuje, czy właściwość powinna być indeksowana do filtrowania w przypadkach, gdy baza danych wymaga zgody na indeksowanie poszczególnych właściwości. Wartość domyślna to „fałsz”. |
| is_full_text_searchable | Nie. | Wskazuje, czy właściwość powinna być indeksowana w celu wyszukiwania pełnotekstowego baz danych obsługujących wyszukiwanie pełnotekstowe. Wartość domyślna to „fałsz”. |
VectorStoreRecordVectorField
Użyj tej adnotacji, aby wskazać, że atrybut zawiera wektor.
VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)
Parametry VectorStoreRecordVectorField
| Parametr | Wymagania | opis |
|---|---|---|
| wymiary | Tak w przypadku tworzenia kolekcji, opcjonalnie w przeciwnym razie | Liczba wymiarów, które ma wektor. Jest to zwykle wymagane podczas tworzenia indeksu wektorowego dla kolekcji. |
| index_kind | Nie. | Typ indeksu do indeksowania wektora. Wartość domyślna różni się w zależności od typu magazynu wektorów. |
| distance_function | Nie. | Typ funkcji odległości do użycia podczas porównywania wektorów podczas wyszukiwania wektorów w tym wektorze. Wartość domyślna różni się w zależności od typu magazynu wektorów. |
| local_embedding | Nie. | Wskazuje, czy właściwość ma skojarzone lokalne osadzanie, wartość domyślna to Brak. |
| embedding_settings | Nie. | Ustawienia osadzania w postaci dyktowania z service_id jako klucz i PromptExecutionSettings jako wartość domyślna to Brak. |
| serialize_function | Nie. | Funkcja używana do serializacji wektora, jeśli typ nie jest list[float | int] tej funkcji jest wymagana lub cały model musi być serializowany. |
| deserialize_function | Nie. | Funkcja używana do deserializacji wektora, jeśli typ nie jest list[float | int] tej funkcji jest wymagana lub cały model musi zostać zdeserializowany. |
Typowe rodzaje indeksów i typy funkcji odległości są dostarczane jako wartości statyczne w klasach semantic_kernel.data.IndexKind i semantic_kernel.data.DistanceFunction .
Implementacje poszczególnych magazynów wektorów mogą również używać własnych typów indeksów i funkcji odległości, w których baza danych obsługuje nietypowe typy.
Wszystkie metody operacji upsert lub pobierania rekordów używają silnie typiowanych klas modeli. Pola w tych klasach są ozdobione adnotacjami wskazującymi przeznaczenie każdego pola.
Napiwek
Alternatywą dla używania atrybutów jest definiowanie schematu przy użyciu definicji rekordu.
Oto przykład modelu, który jest ozdobiony tymi adnotacjami. Domyślnie większość magazynów wektorów wektorów skrzynkowych używa Jacksona, dlatego dobrym rozwiązaniem jest zapewnienie, że obiekt modelu może być serializowany przez Jacksona, tj. klasa jest widoczna, ma metody getters, konstruktor, adnotacje itp.
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; }
}
Adnotacje
VectorStoreRecordKey
Użyj tej adnotacji, aby wskazać, że pole jest kluczem rekordu.
@VectorStoreRecordKey
private String hotelId;
Parametry VectorStoreRecordKey
| Parametr | Wymagania | opis |
|---|---|---|
| storageName | Nie. | Można użyć do podania alternatywnej nazwy pola w bazie danych. Należy pamiętać, że ten parametr nie jest obsługiwany przez wszystkie łączniki, np. gdzie jest używany Jackson, w takim przypadku można określić nazwę magazynu przy użyciu adnotacji Jacksona. |
Napiwek
Aby uzyskać więcej informacji na temat łączników obsługujących usługę storageName i dostępnych alternatyw, zapoznaj się z dokumentacją każdego łącznika.
VectorStoreRecordData
Użyj tej adnotacji, aby wskazać, że pole zawiera ogólne dane, które nie są kluczem ani wektorem.
@VectorStoreRecordData(isFilterable = true)
private String name;
Parametry VectorStoreRecordData
| Parametr | Wymagania | opis |
|---|---|---|
| isFilterable | Nie. | Wskazuje, czy pole powinno być indeksowane do filtrowania w przypadkach, gdy baza danych wymaga wyrażenia zgody na indeksowanie na pole. Wartość domyślna to „fałsz”. |
| isFullTextSearchable | Nie. | Wskazuje, czy pole powinno być indeksowane w celu wyszukiwania pełnotekstowego baz danych obsługujących wyszukiwanie pełnotekstowe. Wartość domyślna to „fałsz”. |
| storageName | Nie. | Można użyć do podania alternatywnej nazwy pola w bazie danych. Należy pamiętać, że ten parametr nie jest obsługiwany przez wszystkie łączniki, np. gdzie jest używany Jackson, w takim przypadku można określić nazwę magazynu przy użyciu adnotacji Jacksona. |
Napiwek
Aby uzyskać więcej informacji na temat łączników obsługujących usługę storageName i dostępnych alternatyw, zapoznaj się z dokumentacją każdego łącznika.
VectorStoreRecordVector
Użyj tej adnotacji, aby wskazać, że pole zawiera wektor.
@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;
Parametry VectorStoreRecordVector
| Parametr | Wymagania | opis |
|---|---|---|
| wymiary | Tak w przypadku tworzenia kolekcji, opcjonalnie w przeciwnym razie | Liczba wymiarów, które ma wektor. Jest to zwykle wymagane podczas tworzenia indeksu wektorowego dla kolekcji. |
| indexKind | Nie. | Typ indeksu do indeksowania wektora. Wartość domyślna różni się w zależności od typu magazynu wektorów. |
| distanceFunction | Nie. | Typ funkcji odległości do użycia podczas porównywania wektorów podczas wyszukiwania wektorów w tym wektorze. Wartość domyślna różni się w zależności od typu magazynu wektorów. |
| storageName | Nie. | Można użyć do podania alternatywnej nazwy pola w bazie danych. Należy pamiętać, że ten parametr nie jest obsługiwany przez wszystkie łączniki, np. gdzie jest używany Jackson, w takim przypadku można określić nazwę magazynu przy użyciu adnotacji Jacksona. |
Typowe rodzaje indeksów i typy funkcji odległości są dostarczane w wyliczeniach com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind i com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction .
Implementacje poszczególnych magazynów wektorów mogą również używać własnych typów indeksów i funkcji odległości, w których baza danych obsługuje nietypowe typy.
Napiwek
Aby uzyskać więcej informacji na temat łączników obsługujących usługę storageName i dostępnych alternatyw, zapoznaj się z dokumentacją każdego łącznika.
Więcej informacji wkrótce.