De Redis-connector gebruiken (preview)

Waarschuwing

De Semantische Kernel Vector Store-functionaliteit is in preview en verbeteringen waarvoor wijzigingen die fouten veroorzaken, kunnen nog steeds in beperkte omstandigheden optreden voordat ze worden uitgebracht.

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
Verzamelingstoewijzingen aan	Redis-index met voorvoegsel ingesteld op <collectionname>:
Ondersteunde sleuteleigenschapstypen	tekenreeks
Ondersteunde gegevenseigenschapstypen	Wanneer u Hashes gebruikt: tekenreeks int uint long ulong dubbel zwevend bool Wanneer u JSON gebruikt: Alle typen serialiseerbaar voor JSON
Ondersteunde vectoreigenschappentypen	ReadOnlyMemory<float> ReadOnlyMemory<double>
Ondersteunde indextypen	Hnsw Vast
Ondersteunde afstandsfuncties	CosineSimilariteit DotProductsimilarity EuclideanDistance
Ondersteunt meerdere vectoren in een record	Ja
Wordt Filterable ondersteund?	Ja
WordtFullTextSearchable ondersteund?	Ja
Ondersteunde StoragePropertyName?	Wanneer u Hashes gebruikt: Ja Gebruik JSON: Nee, gebruik JsonSerializerOptions en JsonPropertyNameAttribute in plaats daarvan. Zie hier voor meer informatie.

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 het vectorarchief toevoegen aan de container voor afhankelijkheidsinjectie die beschikbaar is op of KernelBuilder aan de IServiceCollection container voor afhankelijkheidsinjectie met behulp van extensiemethoden die worden geleverd door 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 de gegevensindeling bij upserting, maar de structuur van de dicteren verschilt ertussen.

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 maakt die wordt aangeroepen skhotelsjson met een voorvoegsel van , bij het instellen van skhotelsjson:een record met sleutel h1, moet de recordsleutel als volgt skhotelsjson:h1 worden toegevoegd aan de index.

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 gedrag van voorvoegsels uit te schakelen en de volledig voorvoegselsleutel door te geven aan 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();

Gegevenstoewijzing

Redis ondersteunt twee modi voor het opslaan van gegevens: JSON en Hashes. De Redis-connector ondersteunt zowel opslagtypen als toewijzingen verschillen, afhankelijk van het gekozen opslagtype.

Gegevenstoewijzing bij gebruik van het JSON-opslagtype

Wanneer u het JSON-opslagtype gebruikt, wordt de Redis-connector gebruikt 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 aangepast exemplaar JsonSerializerOptions te gebruiken met een aangepast naamgevingsbeleid voor eigenschappen. Om dit mogelijk te maken, moet de JsonSerializerOptions aanbouw worden doorgegeven.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 de Description eigenschap 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.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] }'

Gegevenstoewijzing bij gebruik van het opslagtype Hashes

Wanneer u het hashes-opslagtype gebruikt, biedt de Redis-connector een eigen mapper om toewijzingen uit te voeren. 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.

De eigenschapsnaam wordt overschreven door de StoragePropertyName optie in te stellen via de kenmerken van het gegevensmodel of de recorddefinitie.

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