Определение схемы хранилища с помощью определения записи (предварительная версия)

Предупреждение

Функции хранилища векторов семантического ядра доступны в предварительной версии и улучшения, требующие критических изменений, могут по-прежнему возникать в ограниченных обстоятельствах перед выпуском.

Обзор

Соединители хранилища векторов семантического ядра используют модель первого подхода к взаимодействию с базами данных и позволяют аннотировать модели данных с информацией, необходимой для создания индексов или сопоставления данных с схемой базы данных.

Другим способом предоставления этой информации является определение записей, которое можно определить и предоставить отдельно модели данных. Это может быть полезно в нескольких сценариях:

• Может возникнуть случай, когда разработчик хочет использовать ту же модель данных с несколькими конфигурациями.
• Может возникнуть случай, когда разработчик хочет хранить данные с помощью очень другой схемы модели и хочет предоставить настраиваемую схему сопоставления для преобразования между моделью данных и схемой хранения.
• Может возникнуть случай, когда разработчик хочет использовать встроенный тип, например дикт, или оптимизированный формат, например кадр данных, и по-прежнему хочет использовать функции векторного хранилища.

Ниже приведен пример создания определения записи.

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

При создании определения всегда необходимо указать имя и тип для каждого свойства в схеме, так как это необходимо для создания индекса и сопоставления данных.

Чтобы использовать определение, передайте его методу GetCollection.

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

Классы конфигурации свойств записи

VectorStoreRecordKeyProperty

Используйте этот класс, чтобы указать, что свойство является ключом записи.

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

Параметры конфигурации VectorStoreRecordKeyProperty

Параметр	Обязательное поле	Описание
DataModelPropertyName	Да	Имя свойства модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
PropertyType	Да	Тип свойства модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
StoragePropertyName	No	Можно использовать для указания альтернативного имени свойства в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где поддерживаются альтернативные варианты JsonPropertyNameAttribute .

Совет

Дополнительные сведения о том, какие соединители поддерживают StoragePropertyName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.

VectorStoreRecordDataProperty

Используйте этот класс, чтобы указать, что свойство содержит общие данные, которые не являются ключом или вектором.

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

Параметры конфигурации VectorStoreRecordDataProperty

Параметр	Обязательное поле	Описание
DataModelPropertyName	Да	Имя свойства модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
PropertyType	Да	Тип свойства модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
IsFilterable	No	Указывает, следует ли индексировать свойство для фильтрации в случаях, когда для базы данных требуется использовать индексирование для каждого свойства. По умолчанию — false.
IsFullTextSearchable	No	Указывает, следует ли индексировать свойство для полнотекстового поиска баз данных, поддерживающих полнотекстовый поиск. По умолчанию — false.
StoragePropertyName	No	Можно использовать для указания альтернативного имени свойства в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где поддерживаются альтернативные варианты JsonPropertyNameAttribute .

Совет

Дополнительные сведения о том, какие соединители поддерживают StoragePropertyName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.

VectorStoreRecordVectorProperty

Используйте этот класс, чтобы указать, что свойство содержит вектор.

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

Параметры конфигурации VectorStoreRecordVectorProperty

Параметр	Обязательное поле	Описание
DataModelPropertyName	Да	Имя свойства модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
PropertyType	Да	Тип свойства модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
Измерения	Да для создания коллекции, необязательно в противном случае	Число измерений, которые имеет вектор. Обычно это необходимо при создании векторного индекса для коллекции.
IndexKind	No	Тип индекса для индексирования вектора. Значение по умолчанию зависит от типа векторного хранилища.
DistanceFunction	No	Тип функции расстояния, используемой при сравнении векторов во время векторного поиска по этому вектору. Значение по умолчанию зависит от типа векторного хранилища.
StoragePropertyName	No	Можно использовать для указания альтернативного имени свойства в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где поддерживаются альтернативные варианты JsonPropertyNameAttribute .

Совет

Дополнительные сведения о том, какие соединители поддерживают StoragePropertyName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.

Ниже приведен пример создания определения записи для использования с кадром данных pandas.

Примечание.

Те же поля, что и в определении модели данных, используются здесь, для модели данных они добавляются в виде заметок, здесь как дикт с именем.

Есть несколько важных вещей, которые следует отметить, другие, а затем определения полей сами. Первым является container_mode параметр. Если задано значение True, это означает, что модель данных является типом контейнера, например DataFrame, и что модель данных, следовательно, является контейнером записей, а не одной, запись контейнера может использоваться точно так же, основное различие заключается в том, что get и get_batch возвращает тот же тип данных. с одной записью для get одной или нескольких для get_batch. Если вы хотите сделать upsert и upsert_batch может использоваться взаимозаменяемо, upsert другими словами, передача контейнера в upsert результате нескольких upserts вместо одного.

Второй — это добавление to_dict методов и from_dict методов, которые используются для преобразования между моделью данных и схемой хранения. В этом случае to_dict метод используется для преобразования кадра данных в список записей, а from_dict метод используется для преобразования списка записей в кадр данных. Также можно использовать serialize метод и deserialize метод (не показан в приведенном ниже примере), чтобы получить подробные сведения о различиях между ними в документации по сериализации.

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

При создании определения всегда необходимо указать имя (в качестве ключа в fields дикте) и ввести для каждого свойства в схеме, так как это необходимо для создания индекса и сопоставления данных.

Чтобы использовать определение, передайте его методу GetCollection или конструктору коллекции вместе с типом модели данных.

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

Ниже приведен пример создания определения записи.

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()
    )
);

При создании определения всегда необходимо указать имя и тип для каждого поля в схеме, так как это необходимо для создания индекса и сопоставления данных.

Чтобы использовать определение, передайте его методу GetCollection.

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

Классы конфигурации поля записи

VectorStoreRecordKeyField

Используйте этот класс, чтобы указать, что поле является ключом записи.

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

Параметры конфигурации VectorStoreRecordKeyField

Параметр	Обязательное поле	Description
name	Да	Имя поля в модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
fieldType	Да	Тип поля в модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
storageName	No	Можно использовать для указания альтернативного имени поля в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где используется Джексон, в этом случае имя хранилища можно указать с помощью заметок Джексона.

Совет

Дополнительные сведения о том, какие соединители поддерживают storageName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.

VectorStoreRecordDataField

Используйте этот класс, чтобы указать, что свойство содержит общие данные, которые не являются ключом или вектором.

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

Параметры конфигурации VectorStoreRecordDataField

Параметр	Обязательное поле	Description
name	Да	Имя поля в модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
fieldType	Да	Тип поля в модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
isFilterable	No	Указывает, следует ли индексировать поле для фильтрации в случаях, когда для базы данных требуется выбрать индексирование для каждого поля. По умолчанию — false.
isFullTextSearchable	No	Указывает, следует ли индексировать поле для полнотекстового поиска баз данных, поддерживающих полнотекстовый поиск. По умолчанию — false.
storageName	No	Можно использовать для указания альтернативного имени поля в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где используется Джексон, в этом случае имя хранилища можно указать с помощью заметок Джексона.

Совет

Дополнительные сведения о том, какие соединители поддерживают storageName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.

VectorStoreRecordVectorField

Используйте этот класс, чтобы указать, что поле содержит вектор.

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

Параметры конфигурации VectorStoreRecordVectorField

Параметр	Обязательное поле	Description
name	Да	Имя поля в модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
fieldType	Да	Тип поля в модели данных. Используется встроенными средствами сопоставления для автоматической сопоставления между схемой хранилища и моделью данных и для создания индексов.
dimensions	Да для создания коллекции, необязательно в противном случае	Число измерений, которые имеет вектор. Обычно это необходимо при создании векторного индекса для коллекции.
indexKind	No	Тип индекса для индексирования вектора. Значение по умолчанию зависит от типа векторного хранилища.
distanceFunction	No	Тип функции расстояния, используемой при сравнении векторов во время векторного поиска по этому вектору. Значение по умолчанию зависит от типа векторного хранилища.
storageName	No	Можно использовать для указания альтернативного имени поля в базе данных. Обратите внимание, что этот параметр не поддерживается всеми соединителями, например, где используется Джексон, в этом случае имя хранилища можно указать с помощью заметок Джексона.

Совет

Дополнительные сведения о том, какие соединители поддерживают storageName и какие альтернативные варианты доступны, см . в документации по каждому соединителю.