Použití konektoru Redis (Preview)

Upozorňující

Funkce sémantického úložiště vektorů jádra je ve verzi Preview a vylepšení, která vyžadují zásadní změny, se můžou vyskytovat za omezených okolností před vydáním.

Přehled

Konektor Redis Vector Store lze použít pro přístup k datům v Redis a jejich správě. Konektor podporuje režimy hash i JSON a ten, který režim vyberete, určí, jaké další funkce jsou podporované.

Konektor má následující charakteristiky.

Oblast funkcí	Technická podpora
Kolekce map na	Index Redis s předponou nastavenou na <collectionname>:
Podporované typy vlastností klíče	string
Podporované typy datových vlastností	Při použití hodnot hash: string int uint long ulong double float (číslo s plovoucí řádovou čárkou) bool Při použití JSON: Všechny typy serializovatelné pro JSON
Podporované typy vektorových vlastností	ReadOnlyMemory<float> ReadOnlyMemory<double>
Podporované typy indexů	Hnsw Plochý
Podporované funkce vzdálenosti	KosineSimilarita DotProductSimilarity EuclideanDistance
Podporuje více vektorů v záznamu.	Ano
Je podporováno Filtrování?	Ano
Podporuje se IsFullTextSearchable?	Ano
StoragePropertyName se podporuje?	Při použití hodnot hash: Ano Při použití JSON: Ne, použijte JsonSerializerOptions a JsonPropertyNameAttribute místo toho. Další informace najdete tady.

Začínáme

Přidejte do projektu balíček NuGet konektoru Redis Vector Store.

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

Vektorové úložiště můžete přidat do kontejneru injektáže závislostí dostupného IServiceCollection v KernelBuilder kontejneru injektáže závislostí nebo do kontejneru injektáže závislostí pomocí rozšiřujících metod poskytovaných sémantickým jádrem.

using Microsoft.SemanticKernel;

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

using Microsoft.SemanticKernel;

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

K dispozici jsou také metody rozšíření, které nepoužívají žádné parametry. Vyžadují samostatnou registraci instance Redis IDatabase v kontejneru injektáže závislostí.

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

Instanci Redis Vector Store můžete vytvořit přímo.

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

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

Je možné vytvořit přímý odkaz na pojmenovanou kolekci. Když to uděláte, musíte si vybrat mezi instancí JSON nebo Hash v závislosti na tom, jak chcete ukládat data v Redisu.

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

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

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

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

Při vytváření RedisVectorStore nebo registraci kontejneru injektáže závislostí je možné předat RedisVectorStoreOptions instanci, která konfiguruje upřednostňovaný typ úložiště nebo použitý režim: Hodnoty hash nebo JSON. Pokud není zadaný, výchozí hodnota je JSON.

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

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

Začínáme

Nainstalujte sémantické jádro pomocí extra redis, které zahrnuje klienta Redis.

pip install semantic-kernel[redis]

Pak můžete vytvořit instanci vektorového úložiště pomocí RedisStore třídy, to použije proměnné REDIS_CONNECTION_STRING prostředí pro připojení k instanci Redis, tyto hodnoty lze také zadat přímo.

from semantic_kernel.connectors.memory.redis import RedisStore

vector_store = RedisStore()

Vektorové úložiště můžete vytvořit také pomocí vlastní instance databázového klienta Redis.

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

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

Kolekci můžete vytvořit také přímo, ale existují dva typy kolekcí, jedna pro hodnoty Hash a jedna pro JSON.

from semantic_kernel.connectors.memory.redis import RedisHashsetCollection, RedisJsonCollection

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

Při vytváření kolekce z úložiště vektorů můžete předat typ kolekce jako výčet: RedisCollectionTypesvýchozí hodnota je hash kolekce.

from semantic_kernel.connectors.memory.redis import RedisStore, RedisCollectionTypes

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

Serializace

Kolekce Redis používají při přenesení datový formát diktování, ale struktura diktování se mezi nimi liší.

Příklady pro kolekce JSON najdete v dokumentaci k Redisu.

Pro kolekce hashset používá příkaz hset s polem klíče jako name, datová pole jako mapping -> metadata a vektory jako mapping -> [vector_field_name] , viz zde další informace.

Další podrobnosti o tomto konceptu najdete v dokumentaci k serializaci.

Začínáme

Přidejte do projektu Maven nejnovější verzi datového konektoru Sémantic Kernel Redis přidáním následující závislosti:pom.xml

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

Pak můžete vytvořit instanci vektorového úložiště pomocí RedisVectorStore třídy, přičemž klient Redis (JedisPooled) jako parametr.

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

Kolekci můžete také načíst přímo.

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

Předpony indexu

Redis používá systém předpon klíčů k přidružení záznamu k indexu. Při vytváření indexu můžete zadat jednu nebo více předpon, které se mají s tímto indexem použít. Pokud chcete k danému indexu přidružit záznam, musíte k klíči tohoto záznamu přidat předponu.

Například pokud vytvoříte index volaný skhotelsjson s předponou skhotelsjson:, při nastavení záznamu s klíčem h1bude nutné, aby byl klíč záznamu předponou skhotelsjson:h1 přidán do indexu.

Při vytváření nové kolekce pomocí konektoru Redis vytvoří konektor index v Redis s předponou skládající se z názvu kolekce a dvojtečky, jako je tato <collectionname>:. Ve výchozím nastavení konektor předponuje všechny klíče s touto předponou při provádění operací záznamu, jako je Get, Upsert a Delete.

Pokud jste nechtěli použít předponu skládající se z názvu kolekce a dvojtečky, je možné vypnout chování předpony a předat plně předponu klíče operacím záznamu.

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

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

await collection.GetAsync("myprefix_h1");

from semantic_kernel.connectors.memory.redis import RedisJsonCollection

collection = RedisJsonCollection(collection_name="skhotels", data_model_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();

Mapování dat

Redis podporuje dva režimy pro ukládání dat: JSON a hash. Konektor Redis podporuje oba typy úložiště a mapování se liší v závislosti na zvoleném typu úložiště.

Mapování dat při použití typu úložiště JSON

Pokud používáte typ úložiště JSON, konektor Redis použije System.Text.Json.JsonSerializer k mapování. Vzhledem k tomu, že Redis ukládá záznamy se samostatným klíčem a hodnotou, mapovač serializuje všechny vlastnosti s výjimkou klíče k objektu JSON a použije ho jako hodnotu.

JsonPropertyNameAttribute Pokud se vyžaduje jiný název úložiště pro název vlastnosti datového modelu, je použití podporované. Vlastní instanci je také možné použít JsonSerializerOptions s vlastní zásadou pojmenování vlastností. Aby to bylo možné, JsonSerializerOptions musí být předána RedisJsonVectorStoreRecordCollection do konstrukce.

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

Vzhledem k tomu, že byla zvolena zásada pojmenování hadů velká písmena, zde je příklad, jak bude tento datový typ nastaven v Redis. Všimněte si také použití JsonPropertyNameAttribute vlastnosti Description k dalšímu přizpůsobení pojmenování úložiště.

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

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

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

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

    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, 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] }'

Mapování dat při použití typu úložiště Hashes

Při použití typu úložiště Hashes poskytuje konektor Redis vlastní mapovač pro mapování. Tento mapovač namapuje každou vlastnost na dvojici hodnot polí, kterou podporuje příkaz Redis HSET .

U vlastností dat a vektorových vlastností můžete zadat názvy polí přepsání, které se mají použít v úložišti, které se liší od názvů vlastností datového modelu. U klíčů to není podporováno, protože klíče nelze v Redis pojmenovat.

Přepsání názvu vlastnosti se provádí nastavením StoragePropertyName možnosti prostřednictvím atributů datového modelu nebo definice záznamu.

Tady je příklad datového modelu s nastavenými StoragePropertyName atributy a způsob jejich nastavení v Redisu.

using Microsoft.Extensions.VectorData;

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

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

    [VectorStoreRecordData(IsFullTextSearchable = true, StoragePropertyName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw, StoragePropertyName = "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>