Definición del esquema de almacenamiento mediante una definición de registro (versión preliminar)

Advertencia

La funcionalidad Almacén de vectores de kernel semántico está en versión preliminar y las mejoras que requieren cambios importantes pueden producirse en circunstancias limitadas antes de la versión.

Información general

Los conectores del almacén de vectores de kernel semántico usan un primer enfoque de modelo para interactuar con bases de datos y permite anotar modelos de datos con información necesaria para crear índices o asignar datos al esquema de base de datos.

Otra forma de proporcionar esta información es a través de definiciones de registros, que se pueden definir y proporcionar por separado al modelo de datos. Esto puede ser útil en varios escenarios:

• Puede haber un caso en el que un desarrollador quiera usar el mismo modelo de datos con más de una configuración.
• Puede haber un caso en el que el desarrollador quiera almacenar datos mediante un esquema muy diferente al modelo y quiere proporcionar un asignador personalizado para la conversión entre el modelo de datos y el esquema de almacenamiento.
• Puede haber un caso en el que un desarrollador quiera usar un tipo integrado, como un dict, o un formato optimizado como una trama de datos y todavía quiere aprovechar la funcionalidad del almacén de vectores.

Este es un ejemplo de cómo crear una definición de registro.

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

Al crear una definición, siempre debe proporcionar un nombre y un tipo para cada propiedad del esquema, ya que esto es necesario para la creación de índices y la asignación de datos.

Para usar la definición, pásela al método GetCollection.

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

Clases de configuración de propiedad record

VectorStoreRecordKeyProperty

Use esta clase para indicar que la propiedad es la clave del registro.

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

Opciones de configuración de VectorStoreRecordKeyProperty

Parámetro	Obligatorio	Descripción
DataModelPropertyName	Sí	Nombre de la propiedad en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
PropertyType	Sí	Tipo de la propiedad en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
StoragePropertyName	No	Se puede usar para proporcionar un nombre alternativo para la propiedad de la base de datos. Tenga en cuenta que todos los conectores no admiten este parámetro, por ejemplo, donde se admiten alternativas como JsonPropertyNameAttribute .

Sugerencia

Para más información sobre qué conectores admiten StoragePropertyName y qué alternativas están disponibles, consulte la documentación de cada conector.

VectorStoreRecordDataProperty

Use esta clase para indicar que la propiedad contiene datos generales que no son una clave ni un vector.

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

Opciones de configuración de VectorStoreRecordDataProperty

Parámetro	Obligatorio	Descripción
DataModelPropertyName	Sí	Nombre de la propiedad en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
PropertyType	Sí	Tipo de la propiedad en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
IsFilterable	No	Indica si la propiedad debe indexarse para filtrar en casos en los que una base de datos requiere participar en la indexación por propiedad. El valor predeterminado es falso.
IsFullTextSearchable	No	Indica si la propiedad debe indexarse para la búsqueda de texto completo para las bases de datos que admiten la búsqueda de texto completo. El valor predeterminado es falso.
StoragePropertyName	No	Se puede usar para proporcionar un nombre alternativo para la propiedad de la base de datos. Tenga en cuenta que todos los conectores no admiten este parámetro, por ejemplo, donde se admiten alternativas como JsonPropertyNameAttribute .

Sugerencia

Para más información sobre qué conectores admiten StoragePropertyName y qué alternativas están disponibles, consulte la documentación de cada conector.

VectorStoreRecordVectorProperty

Utilice esta clase para indicar que la propiedad contiene un vector.

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

Opciones de configuración de VectorStoreRecordVectorProperty

Parámetro	Obligatorio	Descripción
DataModelPropertyName	Sí	Nombre de la propiedad en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
PropertyType	Sí	Tipo de la propiedad en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
Dimensiones	Sí para la creación de colecciones; de lo contrario, opcional	Número de dimensiones que tiene el vector. Esto suele ser necesario al crear un índice vectorial para una colección.
IndexKind	No	Tipo de índice con el que se indexa el vector. El valor predeterminado varía según el tipo de almacén de vectores.
DistanceFunction	No	Tipo de función de distancia que se va a usar al realizar la comparación vectorial durante la búsqueda de vectores sobre este vector. El valor predeterminado varía según el tipo de almacén de vectores.
StoragePropertyName	No	Se puede usar para proporcionar un nombre alternativo para la propiedad de la base de datos. Tenga en cuenta que todos los conectores no admiten este parámetro, por ejemplo, donde se admiten alternativas como JsonPropertyNameAttribute .

Sugerencia

Para más información sobre qué conectores admiten StoragePropertyName y qué alternativas están disponibles, consulte la documentación de cada conector.

Este es un ejemplo de cómo crear una definición de registro para su uso con un DataFrame de Pandas.

Nota:

Los mismos campos que en la definición del modelo de datos se usan aquí, para un modelo de datos se agregan como anotaciones, aquí como un dict con el nombre.

Hay un par de cosas importantes que hay que tener en cuenta, otras, las definiciones de campos en sí mismas. El primero es el container_mode parámetro . Cuando se establece en True, esto indica que el modelo de datos es un tipo de contenedor, como un DataFrame, y que el modelo de datos es, por tanto, un contenedor de registros, en lugar de uno único, se puede usar un registro de contenedor exactamente del mismo modo, la diferencia principal es que get y get_batch devolverá el mismo tipo de datos, con un único registro para y get uno o varios para .get_batch Si desea realizar un upsert upsert y upsert_batch se puede usar indistintamente, en otras palabras, pasar un contenedor a dará lugar a upsert varios upserts, en lugar de a uno único.

El segundo es la adición de los to_dict métodos y from_dict , que se usan para convertir entre el modelo de datos y el esquema de almacenamiento. En este caso, el to_dict método se usa para convertir el DataFrame en una lista de registros y el from_dict método se usa para convertir una lista de registros en un DataFrame. También puede haber un serialize método y deserialize (no se muestra en el ejemplo siguiente), para obtener más información sobre la diferencia entre los que ven la documentación de serialización.

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

Al crear una definición, siempre debe proporcionar un nombre (como clave en el fields dict) y escribir para cada propiedad del esquema, ya que esto es necesario para la creación de índices y la asignación de datos.

Para usar la definición, pásela al método GetCollection o a un constructor de colección, junto con el tipo de modelo de datos.

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

Este es un ejemplo de cómo crear una definición de registro.

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

Al crear una definición, siempre debe proporcionar un nombre y un tipo para cada campo del esquema, ya que esto es necesario para la creación de índices y la asignación de datos.

Para usar la definición, pásela al método GetCollection.

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

Clases de configuración de campo de registro

VectorStoreRecordKeyField

Use esta clase para indicar que el campo es la clave del registro.

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

Opciones de configuración de VectorStoreRecordKeyField

Parámetro	Obligatorio	Descripción
name	Sí	Nombre del campo en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
fieldType	Sí	Tipo del campo en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
storageName	No	Se puede usar para proporcionar un nombre alternativo para el campo de la base de datos. Tenga en cuenta que todos los conectores no admiten este parámetro, por ejemplo, donde se usa Jackson, en ese caso, el nombre de almacenamiento se puede especificar mediante anotaciones de Jackson.

Sugerencia

Para obtener más información sobre qué conectores admiten storageName y qué alternativas están disponibles, consulte la documentación de cada conector.

VectorStoreRecordDataField

Use esta clase para indicar que la propiedad contiene datos generales que no son una clave ni un vector.

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

Opciones de configuración de VectorStoreRecordDataField

Parámetro	Obligatorio	Descripción
name	Sí	Nombre del campo en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
fieldType	Sí	Tipo del campo en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
isFilterable	No	Indica si el campo debe indexarse para filtrar en los casos en los que una base de datos requiere participar en la indexación por campo. El valor predeterminado es falso.
isFullTextSearchable	No	Indica si el campo se debe indexar para la búsqueda de texto completo para las bases de datos que admiten la búsqueda de texto completo. El valor predeterminado es falso.
storageName	No	Se puede usar para proporcionar un nombre alternativo para el campo de la base de datos. Tenga en cuenta que todos los conectores no admiten este parámetro, por ejemplo, donde se usa Jackson, en ese caso, el nombre de almacenamiento se puede especificar mediante anotaciones de Jackson.

Sugerencia

Para obtener más información sobre qué conectores admiten storageName y qué alternativas están disponibles, consulte la documentación de cada conector.

VectorStoreRecordVectorField

Use esta clase para indicar que el campo contiene un vector.

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

Opciones de configuración de VectorStoreRecordVectorField

Parámetro	Obligatorio	Descripción
name	Sí	Nombre del campo en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
fieldType	Sí	Tipo del campo en el modelo de datos. Usado por los asignadores integrados para asignar automáticamente entre el esquema de almacenamiento y el modelo de datos y para crear índices.
dimensiones	Sí para la creación de colecciones; de lo contrario, opcional	Número de dimensiones que tiene el vector. Esto suele ser necesario al crear un índice vectorial para una colección.
indexKind	No	Tipo de índice con el que se indexa el vector. El valor predeterminado varía según el tipo de almacén de vectores.
distanceFunction	No	Tipo de función de distancia que se va a usar al realizar la comparación vectorial durante la búsqueda de vectores sobre este vector. El valor predeterminado varía según el tipo de almacén de vectores.
storageName	No	Se puede usar para proporcionar un nombre alternativo para el campo de la base de datos. Tenga en cuenta que todos los conectores no admiten este parámetro, por ejemplo, donde se usa Jackson, en ese caso, el nombre de almacenamiento se puede especificar mediante anotaciones de Jackson.

Sugerencia

Para obtener más información sobre qué conectores admiten storageName y qué alternativas están disponibles, consulte la documentación de cada conector.