De Redis-connector gebruiken (preview)

Waarschuwing

De functionaliteit van de Semantische Kernel Vector Store is in preview en verbeteringen die doorbrekende wijzigingen vereisen, kunnen nog steeds in beperkte omstandigheden optreden voordat ze worden vrijgegeven.

Overzicht

De Redis Vector Store-connector kan worden gebruikt voor toegang tot en beheer van gegevens in Redis. De connector ondersteunt zowel Hashes- als JSON-modi en welke modus u kiest, bepaalt welke andere functies worden ondersteund.

De verbindingslijn heeft de volgende kenmerken.

Functiegebied	Ondersteuning
Verzameling verwijst naar	Redis-index met voorvoegsel ingesteld op <collectionname>:
Ondersteunde sleuteleigenschapstypen	tekenreeks
Ondersteunde gegevenseigenschapstypen	Wanneer u Hashes gebruikt: tekenreeks int uint lang ulong dubbel drijven bool Wanneer u JSON gebruikt: Alle typen serialiseerbaar voor JSON
Ondersteunde vectoreigenschappentypen	ReadOnlyMemory<float> ReadOnlyMemory<double>
Ondersteunde indextypen	Hnsw Plat
Ondersteunde afstandsfuncties	CosineSimilariteit DotProductSimilariteit Euclidische Kwadratische Afstand
Ondersteunde filterclausules	AnyTagEqualTo EqualTo
Ondersteunt meerdere vectoren in een record	Ja
Wordt Filterable ondersteund?	Ja
WordtFullTextSearchable ondersteund?	Ja
Wordt StoragePropertyName ondersteund?	Wanneer u Hashes gebruikt: Ja Gebruik JSON: Nee, gebruik JsonSerializerOptions en JsonPropertyNameAttribute in plaats daarvan. Zie hier voor meer informatie.
HybridSearch ondersteund?	Nee.

Aan de slag

Voeg het Nuget-pakket van de Redis Vector Store-connector toe aan uw project.

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

U kunt de vectormap toevoegen aan de afhankelijkheidsinjectiecontainer die beschikbaar is op KernelBuilder of aan de IServiceCollection afhankelijkheidsinjectiecontainer met behulp van de extensiemethoden die worden geleverd door de Semantische Kernel.

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

Extensiemethoden waarvoor geen parameters worden gebruikt, worden ook opgegeven. Hiervoor moet een exemplaar van redis IDatabase afzonderlijk worden geregistreerd bij de container voor afhankelijkheidsinjectie.

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

U kunt rechtstreeks een Redis Vector Store-exemplaar maken.

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

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

Het is mogelijk om een directe verwijzing naar een benoemde verzameling te maken. Als u dit doet, moet u kiezen tussen de JSON- of Hashes-instantie, afhankelijk van hoe u gegevens in Redis wilt opslaan.

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

Wanneer u een RedisVectorStore container voor afhankelijkheidsinjectie samenstelt of registreert, is het mogelijk om een RedisVectorStoreOptions exemplaar door te geven waarmee het gewenste opslagtype/de gebruikte modus wordt geconfigureerd: Hashes of JSON. Als dit niet is opgegeven, is de standaardwaarde JSON.

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

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

Aan de slag

Installeer semantische kernel met de redis-extra's, waaronder de redis-client.

pip install semantic-kernel[redis]

Vervolgens kunt u een exemplaar van een vectorarchief maken met behulp van de RedisStore klasse. Hiermee worden de omgevingsvariabelen REDIS_CONNECTION_STRING gebruikt om verbinding te maken met een Redis-exemplaar. Deze waarden kunnen ook rechtstreeks worden opgegeven.

from semantic_kernel.connectors.memory.redis import RedisStore

vector_store = RedisStore()

U kunt ook het vectorarchief maken met uw eigen exemplaar van de redis-databaseclient.

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)

U kunt ook rechtstreeks een verzameling maken, maar er zijn twee typen verzamelingen, één voor Hashes en één voor 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)

Wanneer u een verzameling maakt vanuit het vectorarchief, kunt u het verzamelingstype doorgeven als opsomming: RedisCollectionTypes, de standaardwaarde is een hash-verzameling.

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

Serialisatie

De redis-verzamelingen gebruiken beide een dict als gegevensformaat bij het upserten, maar de structuur van de dicts verschilt tussen hen.

Zie redis-documenten voor een voorbeeld voor JSON-verzamelingen.

Voor Hashset-verzamelingen wordt de hset-opdracht gebruikt met het sleutelveld als name, gegevensvelden als mapping -> metadata en vectoren mapping -> [vector_field_name] , zie hier voor meer informatie.

Zie de serialisatiedocumentatie voor meer informatie over dit concept.

Aan de slag

Neem de nieuwste versie van de Semantische Kernel Redis-gegevensconnector op in uw Maven-project door de volgende afhankelijkheid toe te voegen aan uw pom.xml:

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

U kunt vervolgens een exemplaar van een vectorarchief maken met behulp van de RedisVectorStore klasse, waarbij de Redis-client (JedisPooled) als parameter wordt gebruikt.

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

U kunt een verzameling ook rechtstreeks ophalen.

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

Indexvoorvoegsels

Redis gebruikt een systeem van sleutelvoorvoegsels om een record te koppelen aan een index. Wanneer u een index maakt, kunt u een of meer voorvoegsels opgeven die met die index moeten worden gebruikt. Als u een record aan die index wilt koppelen, moet u het voorvoegsel toevoegen aan de sleutel van die record.

Als u bijvoorbeeld een index met de naam skhotelsjson maakt en een voorvoegsel van skhotelsjson: gebruikt, moet de recordsleutel, bij het instellen van een record met sleutel h1, als volgt worden voorvoegd skhotelsjson:h1 om aan de index te worden toegevoegd.

Wanneer u een nieuwe verzameling maakt met behulp van de Redis-connector, maakt de connector een index in Redis met een voorvoegsel dat bestaat uit de naam van de verzameling en een dubbele punt, zoals deze <collectionname>:. Standaard wordt voor de connector ook alle sleutels voorafgegaan door dit voorvoegsel bij het uitvoeren van recordbewerkingen zoals Get, Upsert en Delete.

Als u geen voorvoegsel wilt gebruiken dat bestaat uit de naam van de verzameling en een dubbele punt, is het mogelijk om het voorvoegselgedrag uit te schakelen en de volledig voorgevoegde sleutel door te voeren naar de recordbewerkingen.

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

Datamapping

Redis ondersteunt twee modi voor het opslaan van gegevens: JSON en Hashes. De Redis-connector ondersteunt beide opslagtypen, en de toewijzing verschilt afhankelijk van het gekozen opslagtype.

Gegevenstoewijzing bij gebruik van het JSON-opslagtype

Wanneer u het JSON-opslagtype gebruikt, gebruikt de Redis-connector System.Text.Json.JsonSerializer om toewijzingen uit te voeren. Omdat Redis records met een afzonderlijke sleutel en waarde opslaat, serialiseert de mapper alle eigenschappen, met uitzondering van de sleutel naar een JSON-object en gebruikt deze als de waarde.

Het gebruik van de JsonPropertyNameAttribute eigenschap wordt ondersteund als een andere opslagnaam voor de naam van de gegevensmodeleigenschap is vereist. Het is ook mogelijk om een aangepaste instantie JsonSerializerOptions te gebruiken met een aangepast eigenschappen-namenbeleid. Om dit mogelijk te maken, moet de JsonSerializerOptions tijdens de constructie worden doorgegeven aan de RedisJsonVectorStoreRecordCollection.

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

Aangezien een naamgevingsbeleid van snake case upper is gekozen, is hier een voorbeeld van hoe dit gegevenstype wordt ingesteld in Redis. Let ook op het gebruik van JsonPropertyNameAttribute op de eigenschap Description om de naamgeving van de opslag verder aan te passen.

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.CosineSimilarity, 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] }'

Gegevenstoewijzing bij gebruik van het opslagtype Hashes

Wanneer u het Hashes-opslagtype gebruikt, biedt de Redis-connector een eigen mapper voor het uitvoeren van mappings. Deze mapper wijst elke eigenschap toe aan een veldwaardepaar, zoals ondersteund door de Redis-opdracht HSET .

Voor gegevenseigenschappen en vectoreigenschappen kunt u veldnamen overschrijven die moeten worden gebruikt in de opslag die verschilt van de eigenschapsnamen in het gegevensmodel. Dit wordt niet ondersteund voor sleutels, omdat sleutels niet kunnen worden benoemd in Redis.

Het overschrijven van de eigenschapsnaam wordt gedaan door de StoragePropertyName optie in te stellen via de kenmerken van het gegevensmodel of de definitie van de record.

Hier volgt een voorbeeld van een gegevensmodel dat StoragePropertyName is ingesteld op de kenmerken ervan en hoe deze worden ingesteld in Redis.

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.CosineSimilarity, 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>