使用 Redis 連接器（預覽）

發行項
11/03/2024

警告

語意核心向量存放區功能處於預覽狀態，且需要重大變更的改善可能仍會在發行前有限的情況下發生。

概觀

Redis 向量存放區連接器可用來存取和管理 Redis 中的數據。連接器同時支援哈希和 JSON 模式，以及您挑選的模式將決定支援哪些其他功能。

連接器具有下列特性。

功能區域	支援
集合對應至	已將前置詞設定為的 Redis 索引 `<collectionname>:`
支援的索引鍵屬性類型	字串
支援的數據類型	使用哈希時：字串 int uint long ulong double float bool 使用 JSON 時：任何可串行化為 JSON 的類型
支援的向量屬性類型	ReadOnlyMemory<float> ReadOnlyMemory<double>
支援的索引類型	Hnsw 一般
支援的距離函式	CosineSimilarity DotProductSimilarity EuclideanDistance
支援記錄中的多個向量	Yes
是否支援IsFilterable？	Yes
是否支援IsFullTextSearchable？	Yes
支援的 StoragePropertyName？	使用哈希時：是使用 JSON 時：否，請改用 `JsonSerializerOptions` 和 `JsonPropertyNameAttribute` 。如需詳細資訊，請參閱這裡。

開始使用

將 Redis Vector Store 連接器 nuget 套件新增至您的專案。

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

您可以使用 Semantic Kernel 所提供的擴充方法，將向量存放區新增至 IServiceCollection 上KernelBuilder可用的相依性插入容器或相依性插入容器。

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

也提供不採用任何參數的擴充方法。這些要求 Redis IDatabase 的實例必須個別向相依性插入容器註冊。

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

您可以直接建構 Redis 向量存放區實例。

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

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

可以建構具名集合的直接參考。這樣做時，您必須根據您想要如何將數據儲存在 Redis 中，在 JSON 或 Hashes 實例之間進行選擇。

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

建構 RedisVectorStore 或向相依性插入容器註冊它時，可以傳遞 RedisVectorStoreOptions 實例來設定所使用的慣用記憶體類型/模式：哈希或 JSON。如果未指定，則預設值為 JSON。

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

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

開始使用

使用 redis 額外項目安裝語意核心，其中包含 redis 用戶端。

pip install semantic-kernel[redis]

接著，您可以使用類別建立向量存放區實例 RedisStore ，這會使用環境變數 REDIS_CONNECTION_STRING 來連線到 Redis 實例，也可以直接提供這些值。


from semantic_kernel.connectors.memory.redis import RedisStore

vector_store = RedisStore()

您也可以使用自己的 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)

您也可以直接建立集合，但有兩種類型的集合，一種用於哈希，一種用於 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)

從向量存放區建立集合時，您可以傳入集合類型，做為列舉： RedisCollectionTypes，預設值為哈希集合。

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

序列化

redis 集合在向上插入時都會使用聽寫作為數據格式，但是聽寫的結構在兩者之間不同。

如需 JSON 集合，請參閱 redis 檔以取得範例。

如果是 Hashset 集合，它會使用 hset 命令，並將索引鍵欄位當做、數據欄位和向量當做 namemapping -> [vector_field_name] ，如需詳細資訊，請參閱這裡。mapping -> metadata

如需此概念的詳細資訊，請參閱串行化檔。

開始使用

在 Maven 專案中加入下列相依性 pom.xml，以在 Maven 專案中加入最新版本的 Semantic Kernel Redis 數據連接器：

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

接著，您可以使用類別來建立向量存放區實例 RedisVectorStore ，並將 Redis 用戶端（JedisPooled）作為參數。

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

您也可以直接擷取集合。

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

索引前置詞

Redis 會使用索引鍵前置詞系統，將記錄與索引產生關聯。建立索引時，您可以指定要與該索引搭配使用的一或多個前置詞。如果您想要將記錄與該索引產生關聯，您必須將前置詞新增至該記錄的索引鍵。

例如，如果您在設定具有索引鍵h1的記錄時，使用前置詞建立名為 skhotelsjson 的skhotelsjson:索引，則記錄索引鍵必須加上如下skhotelsjson:h1的前置詞，才能新增至索引。

使用 Redis 連接器建立新的集合時，連接器會在 Redis 中建立索引，其前置詞包含集合名稱和冒號，如下所示 <collectionname>:。根據預設，連接器也會在執行 Get、Upsert 和 Delete 等記錄作業時，將此前置詞加上此前置詞的所有索引鍵。

如果您不想使用包含集合名稱和冒號的前置詞，則可以關閉前置詞行為，並將完整前置詞索引鍵傳入記錄作業。

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

資料對應

Redis 支援兩種儲存數據的模式：JSON 和哈希。 Redis 連接器支援這兩種記憶體類型，而且對應會根據所選的記憶體類型而有所不同。

使用 JSON 記憶體類型時的數據對應

使用 JSON 記憶體類型時，Redis 連接器會用來 System.Text.Json.JsonSerializer 進行對應。由於 Redis 會以個別的索引鍵和值來儲存記錄，因此對應程式會將索引鍵以外的所有屬性串行化為 JSON 物件，並使用該屬性做為值。

JsonPropertyNameAttribute如果需要與資料模型屬性名稱不同的記憶體名稱，則支援使用。您也可以使用自定義實例搭配自定義 JsonSerializerOptions 屬性命名原則。若要啟用此功能， JsonSerializerOptions 必須將傳遞至 RedisJsonVectorStoreRecordCollection 建構時。

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

由於已選擇蛇大小寫上限的命名原則，以下是如何在 Redis 中設定此數據類型的範例。另請注意，在 JsonPropertyNameAttribute 屬性上使用 Description 來進一步自定義記憶體命名。

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] }'

使用哈希儲存類型時的數據對應

使用哈希儲存類型時，Redis 連接器會提供自己的對應程式來執行對應。此對應程式會將每個屬性對應至 Redis HSET 命令所支援的域值組。

針對數據屬性和向量屬性，您可以提供覆寫功能變數名稱，以用於與數據模型上屬性名稱不同的記憶體中。密鑰不支援此功能，因為索引鍵無法在 Redis 中命名。

透過資料模型屬性或記錄定義來設定 StoragePropertyName 選項，即可覆寫屬性名稱。

以下是在其屬性上設定的數據模型 StoragePropertyName 範例，以及這些模型如何在 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>

共用方式為

使用 Redis 連接器（預覽）

概觀

開始使用

開始使用

序列化

開始使用

索引前置詞

資料對應

使用 JSON 記憶體類型時的數據對應

使用哈希儲存類型時的數據對應

其他資源

共用方式為

使用 Redis 連接器 （預覽）

概觀

開始使用

開始使用

序列化

開始使用

索引前置詞

資料對應

使用 JSON 記憶體類型時的數據對應

使用哈希儲存類型時的數據對應

其他資源

使用 Redis 連接器（預覽）