Definiowanie schematu magazynu przy użyciu definicji rekordu (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 i umożliwia dodawanie adnotacji do modeli danych z informacjami wymaganymi do tworzenia indeksów lub mapowania danych do schematu bazy danych.

Innym sposobem dostarczania tych informacji jest użycie definicji rekordów, które można zdefiniować i dostarczyć oddzielnie do modelu danych. Może to być przydatne w wielu scenariuszach:

• Może wystąpić sytuacja, w której deweloper chce użyć tego samego modelu danych z więcej niż jedną konfiguracją.
• Może wystąpić sytuacja, w której deweloper chce przechowywać dane przy użyciu zupełnie innego schematu do modelu i chce podać niestandardowy maper do konwersji między modelem danych a schematem magazynu.
• Może wystąpić sytuacja, w której deweloper chce użyć wbudowanego typu, takiego jak dykt, lub zoptymalizowanego formatu, takiego jak ramka danych, i nadal chce korzystać z funkcji magazynu wektorów.

Oto przykład tworzenia definicji rekordu.

using Microsoft.Extensions.VectorData;

var hotelDefinition = new VectorStoreRecordDefinition
{
    Properties = new List<VectorStoreRecordProperty>
    {
        new VectorStoreRecordKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },
        new VectorStoreRecordDataProperty("Description", typeof(string)) { IsFullTextSearchable = true },
        new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },
    }
};

Podczas tworzenia definicji zawsze musisz podać nazwę i typ każdej właściwości w schemacie, ponieważ jest to wymagane do tworzenia indeksu i mapowania danych.

Aby użyć definicji, przekaż ją do metody GetCollection.

var collection = vectorStore.GetCollection<ulong, Hotel>("skhotels", hotelDefinition);

Klasy konfiguracji właściwości rekordu

VectorStoreRecordKeyProperty

Użyj tej klasy, aby wskazać, że właściwość jest kluczem rekordu.

new VectorStoreRecordKeyProperty("HotelId", typeof(ulong)),

Ustawienia konfiguracji VectorStoreRecordKeyProperty

Parametr	Wymagania	opis
DataModelPropertyName	Tak	Nazwa właściwości modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
Typ właściwości	Tak	Typ właściwości w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksó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 .

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.

VectorStoreRecordDataProperty

Użyj tej klasy, aby wskazać, że właściwość zawiera ogólne dane, które nie są kluczem ani wektorem.

new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },

Ustawienia konfiguracji VectorStoreRecordDataProperty

Parametr	Wymagania	opis
DataModelPropertyName	Tak	Nazwa właściwości modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
Typ właściwości	Tak	Typ właściwości w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
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.

VectorStoreRecordVectorProperty

Użyj tej klasy, aby wskazać, że właściwość zawiera wektor.

new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },

Ustawienia konfiguracji VectorStoreRecordVectorProperty

Parametr	Wymagania	opis
DataModelPropertyName	Tak	Nazwa właściwości modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
Typ właściwości	Tak	Typ właściwości w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
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 .

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.

Oto przykład tworzenia definicji rekordu do użycia z ramką danych biblioteki pandas.

Uwaga

W tym miejscu są używane te same pola, co w definicji modelu danych, dla modelu danych są dodawane jako adnotacje w tym miejscu jako dykt z nazwą.

Istnieje kilka ważnych rzeczy do zanotowania, inne, a następnie same definicje pól. Pierwszy to container_mode parametr . W przypadku ustawienia wartości True oznacza to, że model danych jest typem kontenera, takim jak ramka danych, i że model danych jest w związku z tym kontenerem rekordów, a nie pojedynczym, rekord kontenera może być używany w dokładnie taki sam sposób, główną różnicą jest to, że get i get_batch zwróci ten sam typ danych, z pojedynczym rekordem dla elementu get i i co najmniej jeden dla elementu get_batch. Jeśli chcesz wykonać operację upsert i upsert upsert_batch można jej używać zamiennie, innymi słowy, przekazanie kontenera do upsert spowoduje powstanie wielu operacji upsert, zamiast jednego.

Drugi to dodanie to_dict metod i from_dict , które są używane do konwertowania między modelem danych a schematem magazynu. W takim przypadku to_dict metoda jest używana do konwertowania ramki danych na listę rekordów, a from_dict metoda służy do konwertowania listy rekordów na ramkę danych. Istnieje również serialize metoda i deserialize (nie pokazana w poniższym przykładzie), aby uzyskać szczegółowe informacje na temat różnic między tymi, które znajdują się w dokumentacji serializacji.

from semantic_kernel.data import (
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
)

hotel_definition = VectorStoreRecordDefinition(
    fields={
        "hotel_id": VectorStoreRecordKeyField(property_type="str"),
        "hotel_name": VectorStoreRecordDataField(property_type="str", is_filterable=True),
        "description": VectorStoreRecordDataField(
            property_type="str", has_embedding=True, embedding_property_name="description_embedding"
        ),
        "description_embedding": VectorStoreRecordVectorField(property_type="list[float]"),
    },
    container_mode=True,
    to_dict=lambda record, **_: record.to_dict(orient="records"),
    from_dict=lambda records, **_: DataFrame(records),
)

Podczas tworzenia definicji zawsze musisz podać nazwę (jako klucz w dykt) fields i wpisać dla każdej właściwości w schemacie, ponieważ jest to wymagane do tworzenia indeksu i mapowania danych.

Aby użyć definicji, przekaż ją do metody GetCollection lub konstruktora kolekcji wraz z typem modelu danych.

collection = vector_store.get_collection(
    collection_name="skhotels", 
    data_model_type=pd.DataFrame, 
    data_model_definition=hotel_definition,
)

Oto przykład tworzenia definicji rekordu.

var hotelDefinition = VectorStoreRecordDefinition.fromFields(
    Arrays.asList(
        VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),
        VectorStoreRecordDataField.builder()
            .withName("name")
            .withFieldType(String.class)
            .isFilterable(true).build(),
        VectorStoreRecordDataField.builder()
            .withName("description")
            .withFieldType(String.class)
            .isFullTextSearchable(true).build(),
        VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
            .withDimensions(4)
            .withIndexKind(IndexKind.HNSW)
            .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
            .withFieldType(List.class).build()
    )
);

Podczas tworzenia definicji zawsze trzeba podać nazwę i typ dla każdego pola w schemacie, ponieważ jest to wymagane do tworzenia indeksu i mapowania danych.

Aby użyć definicji, przekaż ją do metody GetCollection.

var collection = vectorStore.getCollection("skhotels",
        JDBCVectorStoreRecordCollectionOptions.builder()
            .withRecordDefinition(hotelDefinition)
            .build()
    );

Klasy konfiguracji pola rekordu

VectorStoreRecordKeyField

Użyj tej klasy, aby wskazać, że pole jest kluczem rekordu.

VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),

Ustawienia konfiguracji VectorStoreRecordKeyField

Parametr	Wymagania	opis
name	Tak	Nazwa pola w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
fieldType	Tak	Typ pola w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksó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.

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.

VectorStoreRecordDataField

Użyj tej klasy, aby wskazać, że właściwość zawiera ogólne dane, które nie są kluczem ani wektorem.

VectorStoreRecordDataField.builder()
    .withName("name")
    .withFieldType(String.class)
    .isFilterable(true).build(),

Ustawienia konfiguracji VectorStoreRecordDataField

Parametr	Wymagania	opis
name	Tak	Nazwa pola w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
fieldType	Tak	Typ pola w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
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.

VectorStoreRecordVectorField

Użyj tej klasy, aby wskazać, że pole zawiera wektor.

VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
    .withDimensions(4)
    .withIndexKind(IndexKind.HNSW)
    .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
    .withFieldType(List.class).build(),

Ustawienia konfiguracji VectorStoreRecordVectorField

Parametr	Wymagania	opis
name	Tak	Nazwa pola w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
fieldType	Tak	Typ pola w modelu danych. Używane przez wbudowane mapery do automatycznego mapowania między schematem magazynu a modelem danych i tworzenia indeksów.
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.

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.