Использование соединителя Couchbase (предварительная версия)

Предупреждение

Функции хранилища векторов семантического ядра доступны в предварительной версии и улучшения, требующие критических изменений, могут по-прежнему возникать в ограниченных обстоятельствах перед выпуском.

Обзор

Соединитель Хранилища векторов Couchbase можно использовать для доступа к данным и управления ими в Couchbase. Соединитель имеет следующие характеристики.

Функциональная область	Поддержка
Коллекция сопоставляется с	Коллекция Couchbase
Поддерживаемые типы свойств ключей	струна
Поддерживаемые типы свойств данных	Все типы, поддерживаемые System.Text.Json (встроенные или с помощью пользовательского преобразователя)
Поддерживаемые типы свойств вектора	ReadOnlyMemory<float>
Поддерживаемые типы индексов	N/A
Поддерживаемые функции расстояния	CosineSimilarity DotProductSimilarity EuclideanDistance
Поддерживаемые условия фильтров	AnyTagEqualTo EqualTo
Поддержка нескольких векторов в записи	Да
Поддерживается IsFilterable?	Нет
Поддерживается ЛиFullTextSearchable?	Нет
Поддерживается StoragePropertyName?	Нет, используйте вместо этого JsonSerializerOptions и JsonPropertyNameAttribute. дополнительные сведения см. здесь.

Начало работы

Добавьте пакет NuGet коннектора Couchbase Vector Store в ваш проект.

dotnet add package CouchbaseConnector.SemanticKernel --prerelease

Хранилище векторов можно добавить в контейнер внедрения зависимостей, доступный в KernelBuilder, или в контейнер внедрения зависимостей IServiceCollection с помощью методов расширения, предоставляемыми Семантическим Ядром.

using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder()
    .AddCouchbaseVectorStore(
        connectionString: "couchbases://your-cluster-address",
        username: "username",
        password: "password",
        bucketName: "bucket-name",
        scopeName: "scope-name");

using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name");

Методы расширения, которые не принимают параметров, также предоставляются. Для них требуется, чтобы экземпляр класса IScope был отдельно зарегистрирован в контейнере внедрения зависимостей.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Couchbase;
using Couchbase.KeyValue;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<ICluster>(sp =>
{
    var clusterOptions = new ClusterOptions
    {
        ConnectionString = "couchbases://your-cluster-address",
        UserName = "username",
        Password = "password"
    };

    return Cluster.ConnectAsync(clusterOptions).GetAwaiter().GetResult();
});

kernelBuilder.Services.AddSingleton<IScope>(sp =>
{
    var cluster = sp.GetRequiredService<ICluster>();
    var bucket = cluster.BucketAsync("bucket-name").GetAwaiter().GetResult();
    return bucket.Scope("scope-name");
});

// Add Couchbase Vector Store
kernelBuilder.Services.AddCouchbaseVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Couchbase.KeyValue;
using Couchbase;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ICluster>(sp =>
{
    var clusterOptions = new ClusterOptions
    {
        ConnectionString = "couchbases://your-cluster-address",
        UserName = "username",
        Password = "password"
    };

    return Cluster.ConnectAsync(clusterOptions).GetAwaiter().GetResult();
});

builder.Services.AddSingleton<IScope>(sp =>
{
    var cluster = sp.GetRequiredService<ICluster>();
    var bucket = cluster.BucketAsync("bucket-name").GetAwaiter().GetResult();
    return bucket.Scope("scope-name");
});

// Add Couchbase Vector Store
builder.Services.AddCouchbaseVectorStore();

Экземпляр Хранилища векторов Couchbase можно создать напрямую.

using Couchbase;
using Couchbase.KeyValue;
using Couchbase.SemanticKernel;

var clusterOptions = new ClusterOptions
{
    ConnectionString = "couchbases://your-cluster-address",
    UserName = "username",
    Password = "password"
};

var cluster = await Cluster.ConnectAsync(clusterOptions);

var bucket = await cluster.BucketAsync("bucket-name");
var scope = bucket.Scope("scope-name");

var vectorStore = new CouchbaseVectorStore(scope);

Можно создать прямую ссылку на именованную коллекцию.

using Couchbase;
using Couchbase.KeyValue;
using Couchbase.SemanticKernel;

var clusterOptions = new ClusterOptions
{
    ConnectionString = "couchbases://your-cluster-address",
    UserName = "username",
    Password = "password"
};

var cluster = await Cluster.ConnectAsync(clusterOptions);
var bucket = await cluster.BucketAsync("bucket-name");
var scope = bucket.Scope("scope-name");

var collection = new CouchbaseFtsVectorStoreRecordCollection<Hotel>(
    scope,
    "hotelCollection");

Сопоставление данных

Соединитель Couchbase использует System.Text.Json.JsonSerializer для сопоставления данных. Свойства в модели данных сериализуются в объект JSON и сопоставляются с хранилищем Couchbase.

Используйте атрибут JsonPropertyName для сопоставления свойства с другим именем в хранилище Couchbase. Кроме того, можно настроить JsonSerializerOptions для расширенной настройки.

using Couchbase.SemanticKernel;
using Couchbase.KeyValue;
using System.Text.Json;

var jsonSerializerOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

var options = new CouchbaseFtsVectorStoreRecordCollectionOptions<Hotel>
{
    JsonSerializerOptions = jsonSerializerOptions
};

var collection = new CouchbaseFtsVectorStoreRecordCollection<Hotel>(scope, "hotels", options);

Используя приведенный выше пользовательский JsonSerializerOptions, который использует CamelCase, следующая модель данных будет сопоставлена с приведенным ниже json.

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

public class Hotel
{
    [JsonPropertyName("hotelId")]
    [VectorStoreRecordKey]
    public string HotelId { get; set; }

    [JsonPropertyName("hotelName")]
    [VectorStoreRecordData]
    public string HotelName { get; set; }

    [JsonPropertyName("description")]
    [VectorStoreRecordData]
    public string Description { get; set; }

    [JsonPropertyName("descriptionEmbedding")]
    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.DotProductSimilarity)]
    public ReadOnlyMemory<float> DescriptionEmbedding { get; set; }
}

{
  "hotelId": "h1",
  "hotelName": "Hotel Happy",
  "description": "A place where everyone can be happy",
  "descriptionEmbedding": [0.9, 0.1, 0.1, 0.1]
}

Не поддерживается

Не поддерживается.

Не поддерживается

Не поддерживается.