Usando o conector couchbase (versão prévia)

Aviso

A funcionalidade semântica do Repositório de Vetores kernel está em versão prévia e melhorias que exigem alterações significativas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Visão geral

O conector do Couchbase Vector Store pode ser usado para acessar e gerenciar dados no Couchbase. O conector tem as seguintes características.

Área de Funcionalidades	Apoio
A coleção é mapeada para	Coleção Couchbase
Tipos de propriedade de chave com suporte	corda
Tipos de propriedade de dados com suporte	Todos os tipos que são compatíveis com System.Text.Json (seja nativamente ou usando um conversor personalizado)
Tipos de propriedade de vetor com suporte	ReadOnlyMemory<float>
Tipos de índice com suporte	N/A
Funções de distância suportadas	CosineSimilaridade DotProductSimilarity EuclideanDistance
Cláusulas de filtro com suporte	AnyTagEqualTo EqualTo
Dá suporte a vários vetores em um registro	Sim
Há suporte para o IsFilterable?	Não
Há suporte para o IsFullTextSearchable?	Não
StoragePropertyName é compatível?	Não, use JsonSerializerOptions e JsonPropertyNameAttribute em vez disso. Veja aqui para obter mais informações.

Introdução

Adicione o pacote NuGet do conector do Couchbase Vector Store ao seu projeto.

dotnet add package CouchbaseConnector.SemanticKernel --prerelease

Você pode adicionar o repositório de vetores ao contêiner de injeção de dependência disponível no KernelBuilder ou ao contêiner de injeção de dependência IServiceCollection usando métodos de extensão fornecidos pelo Kernel Semântico.

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

Métodos de extensão que não têm parâmetros também são fornecidos. Isso exige que uma instância da classe IScope seja registrada de forma separada no contêiner de injeção de dependência.

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

Você pode construir diretamente uma instância do Repositório de Vetores 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);

É possível construir uma referência direta a uma coleção nomeada.

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

Mapeamento de dados

O conector Couchbase usa System.Text.Json.JsonSerializer para mapeamento de dados. As propriedades no modelo de dados são serializadas em um objeto JSON e mapeadas para o armazenamento Couchbase.

Use o atributo JsonPropertyName para mapear uma propriedade para um nome diferente no armazenamento Couchbase. Como alternativa, você pode configurar JsonSerializerOptions para personalização avançada.

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

Usando o JsonSerializerOptions personalizado acima que está usando CamelCase, o modelo de dados a seguir será mapeado para o json abaixo.

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

Sem suporte

Não há suporte.

Sem suporte

Não há suporte.