A utilização do conector Couchbase (Pré-visualização)

Visão geral

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

Introdução

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

dotnet add package CouchbaseConnector.SemanticKernel --prerelease

Você pode adicionar o armazenamento 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 Semantic Kernel.

using Microsoft.SemanticKernel;
using Couchbase.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 Couchbase.SemanticKernel;

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

Configurando o tipo de índice

O armazenamento de vetores assume como padrão o uso de índices de hiperescala. Você pode especificar um tipo de índice diferente passando CouchbaseVectorStoreOptions:

using Couchbase.SemanticKernel;

var builder = WebApplication.CreateBuilder(args);

// Option 1: Use Hyperscale index 
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name",
    options: new CouchbaseVectorStoreOptions 
    { 
        IndexType = CouchbaseIndexType.Hyperscale
    });

// Option 2: Use Composite index
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name",
    options: new CouchbaseVectorStoreOptions 
    { 
        IndexType = CouchbaseIndexType.Composite
    });

// Option 3: Use Search vector index
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name",
    options: new CouchbaseVectorStoreOptions 
    { 
        IndexType = CouchbaseIndexType.Search
    });

Métodos de extensão que não usam parâmetros também são fornecidos. Isso requer que uma instância da classe IScope seja registada separadamente no contentor 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 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 uma instância do Couchbase Vetor Store diretamente.

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.

Usando Coleção de Consultas (Hiperescala ou Índice Composto)

Para pesquisa vetorial de alto desempenho com índices Hyperscale:

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

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

// Using Hyperscale index (default)
var collection = new CouchbaseQueryCollection<string, Hotel>(
    scope,
    "skhotels",
    indexType: CouchbaseIndexType.Hyperscale);

// Or using Composite index
var collectionComposite = new CouchbaseQueryCollection<string, Hotel>(
    scope,
    "skhotels",
    indexType: CouchbaseIndexType.Composite);

Usando a Coleção de Pesquisa (Seach Vetor Index)

Para cenários de pesquisa híbridos que combinam pesquisa de texto completo:

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

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

var collection = new CouchbaseSearchCollection<string, Hotel>(
    scope,
    "skhotels");

Comparação do tipo de índice

Couchbase oferece três tipos de índices para pesquisa vetorial:

Índices vetoriais de hiperescala

• Ideal para pesquisas vetoriais puras - descoberta de conteúdo, recomendações, pesquisa semântica
• Alto desempenho com baixa pegada de memória - projetado para escalar para bilhões de vetores
• Otimizado para operações simultâneas - suporta pesquisas e inserções simultâneas
• Use quando: Você realiza principalmente consultas exclusivamente vetoriais sem a filtragem complexa de escalares.
• Ideal para: Pesquisa semântica em larga escala, sistemas de recomendação, descoberta de conteúdo
• Requer: Couchbase Server 8.0+ ou Capella

Índices vetoriais compostos

• Ideal para pesquisas vetoriais filtradas - combina pesquisa vetorial com filtragem escalar de valores
• Pré-filtragem eficiente - atributos escalares reduzem o escopo de comparação de vetores
• Use quando: Suas consultas combinam semelhança vetorial com filtros escalares que eliminam grandes porções de dados
• Ideal para: Filtragem baseada em conformidade, pesquisas específicas do usuário, consultas com limite de tempo
• Requer: Couchbase Server 8.0+ ou Capella

Índices vetoriais de pesquisa

• Ideal para pesquisas híbridas que combinam pesquisa de texto completo com semelhança vetorial
• Permite a pesquisa semântica juntamente com a correspondência tradicional de palavras-chave
• Suporta pesquisas geoespaciais, além de vetor e texto
• Use quando: Você precisa combinar a pesquisa tradicional de palavras-chave com a pesquisa de semelhança vetorial na mesma consulta
• Ideal para: Pesquisa de produtos de comércio eletrônico, recomendações de viagem, descoberta de conteúdo com vários critérios de pesquisa
• Requer: Couchbase Server 7.6+ ou Capella

Escolhendo o tipo de índice correto:

• Comece com o Índice de Hiperescala para pesquisas vetoriais puras e grandes conjuntos de dados (escala para bilhões)
• Escolha o Índice Composto quando os filtros escalares reduzem significativamente o seu espaço de pesquisa (funciona bem para dezenas de milhões a milhares de milhões de vetores)
• Usar o Índice de vetores de pesquisa para pesquisa híbrida combinando texto e vetores

Comparação detalhada dos tipos de índice vetorial

Mapeamento de dados

O conector Couchbase usará System.Text.Json.JsonSerializer para fazer o mapeamento. As propriedades no modelo de dados são serializadas em um objeto JSON e armazenadas como o valor do documento no Couchbase.

O uso do JsonPropertyNameAttribute é suportado se for necessário um nome de armazenamento diferente para o nome da propriedade de dados do modelo. Também é possível usar uma instância personalizada JsonSerializerOptions com uma política de nomenclatura de propriedade personalizada.

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

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

var options = new CouchbaseQueryCollectionOptions
{
    JsonSerializerOptions = jsonSerializerOptions
};

var collection = new CouchbaseQueryCollection<string, Hotel>(scope, "skhotelsjson", options);

Uma vez que uma política de nomenclatura de snake case upper foi escolhida, aqui está um exemplo de como esse tipo de dados será armazenado no Couchbase. Observe também o uso na propriedade JsonPropertyNameAttribute para personalizar ainda mais a nomenclatura de armazenamento do Description.

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

public class Hotel
{
    [VectorStoreKey]
    public string HotelId { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

    [JsonPropertyName("HOTEL_DESCRIPTION")]
    [VectorStoreData(IsFullTextIndexed = true)]
    public string Description { get; set; }

    [VectorStoreVector(Dimensions: 4, DistanceFunction.CosineSimilarity)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
  "_id" : "h1",
  "HOTEL_ID" : "h1",
  "HOTEL_NAME" : "Hotel Happy",
  "HOTEL_DESCRIPTION" : "A place where everyone can be happy.",
  "DESCRIPTION_EMBEDDING" : [
    0.9,
    0.1,
    0.1,
    0.1
  ]
}

Não suportado

Não suportado.

Não suportado

Não suportado.