Udostępnij za pośrednictwem

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.

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 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 VectorStoreCollectionDefinition
{
    Properties = new List<VectorStoreProperty>
    {
        new VectorStoreKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },
        new VectorStoreDataProperty("Description", typeof(string)) { IsFullTextIndexed = true },
        new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4) { DistanceFunction = DistanceFunction.CosineSimilarity, 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

VectorStoreKeyProperty

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

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

Ustawienia konfiguracji VectorStoreKeyProperty

Parametr Wymagania opis
Nazwa Tak Nazwa właściwości modelu danych. Maper służy do automatycznego mapowania między schematem magazynu a modelem danych i tworzeniem indeksów.
Typ Nie. Typ właściwości w modelu danych. Maper służy do automatycznego mapowania między schematem magazynu a modelem danych i tworzeniem indeksów.
Nazwa magazynu 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 obsługi StorageName łączników i dostępnych alternatyw, zapoznaj się z dokumentacją każdego łącznika.

VectorStoreDataProperty

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

new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },

Ustawienia konfiguracji VectorStoreDataProperty

Parametr Wymagania opis
Nazwa Tak Nazwa właściwości modelu danych. Maper służy do automatycznego mapowania między schematem magazynu a modelem danych i tworzeniem indeksów.
Typ Nie. Typ właściwości w modelu danych. Maper służy do automatycznego mapowania między schematem magazynu a modelem danych i tworzeniem indeksów.
IsIndexed 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”.
IsFullTextIndexed 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”.
Nazwa magazynu 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 obsługi StorageName łączników i dostępnych alternatyw, zapoznaj się z dokumentacją każdego łącznika.

VectorStoreVectorProperty

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

new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4) { DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw },

Ustawienia konfiguracji VectorStoreVectorProperty

Parametr Wymagania opis
Nazwa Tak Nazwa właściwości modelu danych. Maper służy do automatycznego mapowania między schematem magazynu a modelem danych i tworzeniem indeksów.
Typ Nie. Typ właściwości w modelu danych. Maper służy do automatycznego mapowania między schematem magazynu a modelem danych i tworzeniem indeksów.
Wymiary Tak Liczba wymiarów, które ma wektor. Jest to wymagane do utworzenia 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 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.
Nazwa magazynu 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 .
OsadzanieGenerator Nie. Umożliwia określenie Microsoft.Extensions.AI.IEmbeddingGenerator wystąpienia, które ma być używane do automatycznego generowania osadzonych obiektów dla właściwości ozdobionej.

Napiwek

Aby uzyskać więcej informacji na temat obsługi StorageName łączników i dostępnych alternatyw, 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 upsertupsert_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", 
    record_type=pd.DataFrame, 
    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
nazwa 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 (nazwa magazynu) 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
nazwa 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 (nazwa magazynu) 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
nazwa 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 (funkcja odległości) Nie. Typ funkcji 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 (nazwa magazynu) 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.