Uso del conector de Redis (versión preliminar)

Cómo empezar

Agregue el paquete NuGet del conector del almacén de vectores de Redis a su proyecto.

dotnet add package Microsoft.SemanticKernel.Connectors.Redis --prerelease

Puede agregar el almacén de vectores al contenedor de inserción de dependencias disponible en KernelBuilder o al IServiceCollection contenedor de inserción de dependencias mediante métodos de extensión proporcionados por el Kernel Semántico.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder();
kernelBuilder.Services
    .AddRedisVectorStore("localhost:6379");

using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRedisVectorStore("localhost:6379");

También se proporcionan métodos de extensión que no toman parámetros. Estos requieren que una instancia de Redis IDatabase se registre por separado con el contenedor de inserción de dependencias.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using StackExchange.Redis;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<IDatabase>(sp => ConnectionMultiplexer.Connect("localhost:6379").GetDatabase());
kernelBuilder.Services.AddRedisVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using StackExchange.Redis;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IDatabase>(sp => ConnectionMultiplexer.Connect("localhost:6379").GetDatabase());
builder.Services.AddRedisVectorStore();

Puede construir una instancia de Redis Vector Store directamente.

using Microsoft.SemanticKernel.Connectors.Redis;
using StackExchange.Redis;

var vectorStore = new RedisVectorStore(ConnectionMultiplexer.Connect("localhost:6379").GetDatabase());

Es posible construir una referencia directa a una colección con nombre. Al hacerlo, debe elegir entre la instancia JSON o Hashes en función de cómo desea almacenar datos en Redis.

using Microsoft.SemanticKernel.Connectors.Redis;
using StackExchange.Redis;

// Using Hashes.
var hashesCollection = new RedisHashSetCollection<string, Hotel>(
    ConnectionMultiplexer.Connect("localhost:6379").GetDatabase(),
    "skhotelshashes");

using Microsoft.SemanticKernel.Connectors.Redis;
using StackExchange.Redis;

// Using JSON.
var jsonCollection = new RedisJsonCollection<string, Hotel>(
    ConnectionMultiplexer.Connect("localhost:6379").GetDatabase(),
    "skhotelsjson");

Al construir RedisVectorStore o registrarlo con el contenedor de inserción de dependencias, es posible pasar una RedisVectorStoreOptions instancia que configure el tipo de almacenamiento o modo preferido usado: Hashes o JSON. Si no se especifica, el valor predeterminado es JSON.

using Microsoft.SemanticKernel.Connectors.Redis;
using StackExchange.Redis;

var vectorStore = new RedisVectorStore(
    ConnectionMultiplexer.Connect("localhost:6379").GetDatabase(),
    new() { StorageType = RedisStorageType.HashSet });

Cómo empezar

Instale el kernel semántico con los extras de Redis, que incluye el cliente de Redis.

pip install semantic-kernel[redis]

A continuación, puede crear una instancia de almacén de vectores mediante la RedisStore clase , que usará las variables REDIS_CONNECTION_STRING de entorno para conectarse a una instancia de Redis, esos valores también se pueden proporcionar directamente.

from semantic_kernel.connectors.redis import RedisStore

vector_store = RedisStore()

También puede crear el almacén de vectores con su propia instancia del cliente de base de datos redis.

from redis.asyncio.client import Redis
from semantic_kernel.connectors.redis import RedisStore

redis_database = Redis.from_url(url="https://<your-redis-service-name>")
vector_store = RedisStore(redis_database=redis_database)

También puede crear una colección directamente, pero hay dos tipos de colecciones, una para Hashes y otra para JSON.

from semantic_kernel.connectors.redis import RedisHashsetCollection, RedisJsonCollection

hash_collection = RedisHashsetCollection(collection_name="skhotels", record_type=Hotel)
json_collection = RedisJsonCollection(collection_name="skhotels", record_type=Hotel)

Al crear una colección a partir del almacén de vectores, puede especificar el tipo de colección como una enumeración: RedisCollectionTypes. Por defecto, se utiliza una colección hash.

from semantic_kernel.connectors.redis import RedisStore, RedisCollectionTypes

vector_store = RedisStore()
collection = vector_store.get_collection(
    collection_name="skhotels", 
    record_type=Hotel, 
    collection_type=RedisCollectionTypes.JSON,
)

Serialización

Las colecciones redis usan un dict como formato de datos al subir, pero la estructura de los dicts son diferentes entre ellas.

Para las colecciones JSON, consulte la documentación de redis para obtener un ejemplo.

En el caso de las colecciones hashset, usa el comando hset con el campo de clave como name, los campos de datos como mapping -> metadata y los vectores como mapping -> [vector_field_name] , consulte aquí para obtener más información.

Para obtener más información sobre este concepto, consulte la documentación de serialización.

Cómo empezar

Incluya la versión más reciente del conector de datos Semantic Kernel Redis en el proyecto de Maven agregando la siguiente dependencia a pom.xml:

<dependency>
    <groupId>com.microsoft.semantic-kernel</groupId>
    <artifactId>semantickernel-data-redis</artifactId>
    <version>[LATEST]</version>
</dependency>

A continuación, puede crear una instancia de almacén de vectores mediante la RedisVectorStore clase , teniendo el cliente de Redis (JedisPooled) como parámetro.

import com.microsoft.semantickernel.data.redis.RedisJsonVectorStoreRecordCollectionOptions;
import com.microsoft.semantickernel.data.redis.RedisStorageType;
import com.microsoft.semantickernel.data.redis.RedisVectorStore;
import com.microsoft.semantickernel.data.redis.RedisVectorStoreOptions;
import redis.clients.jedis.JedisPooled;

public class Main {
    public static void main(String[] args) {
        JedisPooled jedis = new JedisPooled("<your-redis-url>");

        // Build a Redis Vector Store
        // Available storage types are JSON and HASHSET. Default is JSON.
        var vectorStore = RedisVectorStore.builder()
            .withClient(jedis)
            .withOptions(
                RedisVectorStoreOptions.builder()
                    .withStorageType(RedisStorageType.HASH_SET).build())
            .build();
    }
}

También puede recuperar una colección directamente.

var collection = vectorStore.getCollection("skhotels",
    RedisJsonVectorStoreRecordCollectionOptions.<Hotel>builder()
        .withRecordClass(Hotel.class)
        .build());

using Microsoft.SemanticKernel.Connectors.Redis;
using StackExchange.Redis;

var collection = new RedisJsonCollection<string, Hotel>(
    ConnectionMultiplexer.Connect("localhost:6379").GetDatabase(),
    "skhotelsjson",
    new() { PrefixCollectionNameToKeyNames = false });

await collection.GetAsync("myprefix_h1");

from semantic_kernel.connectors.redis import RedisJsonCollection

collection = RedisJsonCollection(collection_name="skhotels", record_type=hotel, prefix_collection_name_to_key_names=False)

await collection.get("myprefix_h1")

var collection = vectorStore.getCollection("skhotels",
    RedisJsonVectorStoreRecordCollectionOptions.<Hotel>builder()
        .withRecordClass(Hotel.class)
        .withPrefixCollectionName(false)
        .build());

collection.getAsync("myprefix_h1", null).block();

Asignación de datos

Redis admite dos modos para almacenar datos: JSON y Hashes. El conector de Redis admite ambos tipos de almacenamiento y la asignación difiere en función del tipo de almacenamiento elegido.

Mapeo de datos cuando se usa el tipo de almacenamiento JSON

Al usar el tipo de almacenamiento JSON, el conector de Redis usará System.Text.Json.JsonSerializer para realizar la asignación. Dado que Redis almacena registros con una clave y un valor independientes, el asignador serializará todas las propiedades excepto la clave en un objeto JSON y la usará como valor.

Se admite el uso de JsonPropertyNameAttribute si se requiere un nombre de almacenamiento diferente al nombre de la propiedad del modelo de datos. También es posible usar una instancia personalizada JsonSerializerOptions con una directiva de nomenclatura de propiedades personalizada. Para habilitar esto, JsonSerializerOptions debe pasarse a la RedisJsonCollection durante la construcción.

var jsonSerializerOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper };
var collection = new RedisJsonCollection<string, Hotel>(
    ConnectionMultiplexer.Connect("localhost:6379").GetDatabase(),
    "skhotelsjson",
    new() { JsonSerializerOptions = jsonSerializerOptions });

Dado que se eligió una política de nomenclatura estilo snake case en mayúsculas, este es un ejemplo de cómo se establecerá este tipo de datos en Redis. Tenga en cuenta también el uso de JsonPropertyNameAttribute en la Description propiedad para personalizar aún más la nomenclatura del almacenamiento.

using System.Text.Json.Serialization;
using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public string HotelId { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

    [JsonPropertyName("HOTEL_DESCRIPTION")]
    [VectorStoreData(IsFullTextIndexed = true)]
    public string Description { get; set; }

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

JSON.SET skhotelsjson:h1 $ '{ "HOTEL_NAME": "Hotel Happy", "HOTEL_DESCRIPTION": "A place where everyone can be happy.", "DESCRIPTION_EMBEDDING": [0.9, 0.1, 0.1, 0.1] }'

Asignación de datos al usar el tipo de almacenamiento Hashes

Al usar el tipo de almacenamiento Hashes, el conector de Redis proporciona su propio asignador para realizar la asignación. Este asignador mapeará cada propiedad a un par campo-valor tal como lo admite el comando Redis HSET.

En el caso de las propiedades de datos y las propiedades vectoriales, puede proporcionar nombres de campo de reemplazo para usarlos en el almacenamiento en lugar de los nombres de propiedad del modelo de datos. Esto no se admite para las claves, ya que las claves no se pueden denominar en Redis.

La sobreescritura del nombre de propiedad se realiza mediante el establecimiento de la StorageName opción a través de los atributos del modelo de datos o la definición de registro.

Este es un ejemplo de un modelo de datos con StorageName establecido en sus atributos y cómo se establecen en Redis.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public string HotelId { get; set; }

    [VectorStoreData(IsIndexed = true, StorageName = "hotel_name")]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true, StorageName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw, StorageName = "hotel_description_embedding")]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

HSET skhotelshashes:h1 hotel_name "Hotel Happy" hotel_description 'A place where everyone can be happy.' hotel_description_embedding <vector_bytes>