Definición del modelo de datos (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 de almacén de vectores de kernel semántico usan un primer enfoque de modelo para interactuar con las bases de datos.

Todos los métodos para upsert u obtener registros usan clases de modelo fuertemente tipadas. Las propiedades de estas clases están decoradas con atributos que indican el propósito de cada propiedad.

Sugerencia

Para obtener una alternativa al uso de atributos, consulte la definición del esquema con una definición de registro.

Sugerencia

Para obtener una alternativa a definir su propio modelo de datos, consulte el uso de abstracciones del almacén de vectores sin definir su propio modelo de datos.

Este es un ejemplo de un modelo decorado con estos atributos.

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

Atributos

VectorStoreRecordKeyAttribute

Use este atributo para indicar que la propiedad es la clave del registro.

[VectorStoreRecordKey]
public ulong HotelId { get; set; }

Parámetros VectorStoreRecordKeyAttribute

Parámetro	Obligatorio	Descripción
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.

VectorStoreRecordDataAttribute

Use este atributo para indicar que la propiedad contiene datos generales que no son una clave o un vector.

[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }

Parámetros VectorStoreRecordDataAttribute

Parámetro	Obligatorio	Descripción
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.

VectorStoreRecordVectorAttribute

Use este atributo para indicar que la propiedad contiene un vector.

[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

Parámetros VectorStoreRecordVectorAttribute

Parámetro	Obligatorio	Descripción
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 .

Los tipos comunes de índice y los tipos de función de distancia se proporcionan como valores estáticos en las Microsoft.SemanticKernel.Data.IndexKind clases y Microsoft.SemanticKernel.Data.DistanceFunction . Las implementaciones de almacén de vectores individuales también pueden usar sus propios tipos de índice y funciones de distancia, donde la base de datos admite tipos inusuales.

Sugerencia

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

Todos los métodos para upsert u obtener registros usan una clase y una definición de registro de almacén de vectores.

Esto se puede hacer definiendo su propia clase con anotaciones para los campos, o usando una clase o tipo en combinación con una definición de registro. Hay que hacer dos cosas para una clase, la primera consiste en agregar las anotaciones con los tipos de campo, la segunda consiste en decorar la clase con el vectorstoremodel decorador.

Sugerencia

Para el enfoque alternativo mediante una definición de registro, consulte definición del esquema con una definición de registro.

Este es un ejemplo de un modelo que está decorado con estas anotaciones.

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

Sugerencia

La definición de una clase con estas anotaciones se puede realizar de varias maneras, una de las cuales usa el dataclasses módulo en Python, que se muestra aquí. En este ejemplo se muestran otros métodos (mediante pydantic BaseModels y clases de Python de vainilla) también.

anotaciones

Hay tres tipos de anotaciones que se usarán y tienen una clase base común.

VectorStoreRecordField

Esta es la clase base para todas las anotaciones, no está pensada para usarse directamente.

Parámetros VectorStoreRecordField

Parámetro	Obligatorio	Descripción
nombre	No	Se puede agregar directamente, pero se establecerá durante el análisis del modelo.
property_type	No	Debe ser una cadena, también se derivará durante el análisis.

Sugerencia

El decorador analiza las vectorstoremodel anotaciones y una de las cosas que hace es crear una definición de registro para la clase, por lo tanto, no es necesario crear instancias de una clase de campo cuando no se establecen parámetros, el campo se puede anotar solo con la clase , como se muestra a continuación:

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Use esta anotación para indicar que este atributo es la clave del registro.

VectorStoreRecordKeyField()

Parámetros VectorStoreRecordKeyField

No se definen otros parámetros fuera de la clase base.

VectorStoreRecordDataField

Use esta anotación para indicar que el atributo contiene datos generales que no son una clave ni un vector.

VectorStoreRecordDataField(is_filterable=True)

Parámetros VectorStoreRecordDataField

Parámetro	Obligatorio	Descripción
has_embedding	No	Indica si la propiedad tiene una inserción asociada, el valor predeterminado es None.
embedding_property_name	No	El nombre de la propiedad que contiene la inserción, el valor predeterminado es None.
is_filterable	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.
is_full_text_searchable	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.

VectorStoreRecordVectorField

Use esta anotación para indicar que el atributo contiene un vector.

VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)

Parámetros VectorStoreRecordVectorField

Parámetro	Obligatorio	Descripción
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.
index_kind	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.
distance_function	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.
local_embedding	No	Indica si la propiedad tiene una inserción local asociada, el valor predeterminado es None.
embedding_settings	No	La configuración de la inserción, en forma de dict con service_id como clave y PromptExecutionSettings como valor, el valor predeterminado es None.
serialize_function	No	La función que se va a usar para serializar el vector, si el tipo no es una lista[float | int] se necesita esta función o es necesario serializar todo el modelo.
deserialize_function	No	La función que se va a usar para deserializar el vector, si el tipo no es una lista[float | int] se necesita esta función o es necesario deserializar todo el modelo.

Los tipos comunes de índice y los tipos de función de distancia se proporcionan como valores estáticos en las semantic_kernel.data.IndexKind clases y semantic_kernel.data.DistanceFunction . Las implementaciones de almacén de vectores individuales también pueden usar sus propios tipos de índice y funciones de distancia, donde la base de datos admite tipos inusuales.

Todos los métodos para upsert u obtener registros usan clases de modelo fuertemente tipadas. Los campos de estas clases están decorados con anotaciones que indican el propósito de cada campo.

Sugerencia

Para obtener una alternativa al uso de atributos, consulte la definición del esquema con una definición de registro.

Este es un ejemplo de un modelo que está decorado con estas anotaciones. De forma predeterminada, la mayoría de los almacenes vectoriales listos para usar Jackson, por lo tanto, es una buena práctica asegurarse de que Jackson puede serializar el objeto de modelo, es decir, la clase es visible, tiene captadores, constructores, anotaciones, etc.

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

anotaciones

VectorStoreRecordKey

Use esta anotación para indicar que el campo es la clave del registro.

@VectorStoreRecordKey
private String hotelId;

Parámetros VectorStoreRecordKey

Parámetro	Obligatorio	Descripción
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.

VectorStoreRecordData

Use esta anotación para indicar que el campo contiene datos generales que no son una clave o un vector.

@VectorStoreRecordData(isFilterable = true)
private String name;

Parámetros VectorStoreRecordData

Parámetro	Obligatorio	Descripción
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.

VectorStoreRecordVector

Use esta anotación para indicar que el campo contiene un vector.

@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;

Parámetros VectorStoreRecordVector

Parámetro	Obligatorio	Descripción
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.

Los tipos de índice comunes y los tipos de función de distancia se proporcionan en las com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind enumeraciones y com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction . Las implementaciones de almacén de vectores individuales también pueden usar sus propios tipos de índice y funciones de distancia, donde la base de datos admite tipos inusuales.

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.

Más información próximamente.