Använda Couchbase-anslutningsappen (förhandsversion)

Överblick

Couchbase Vector Store-anslutningsappen kan användas för att komma åt och hantera data i Couchbase. Anslutningsappen har följande egenskaper.

Komma igång

Lägg till NuGet-paketet för Couchbase Vector Store-anslutningsappen i projektet.

dotnet add package CouchbaseConnector.SemanticKernel --prerelease

Du kan lägga till vektorlagret i beroendeinjektionscontainern som är tillgänglig på KernelBuilder eller i beroendeinjektionscontainern IServiceCollection med hjälp av tilläggsmetoder som tillhandahålls av 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");

Konfigurera indextyp

Vektorlagret använder som standard Hyperskala-index. Du kan ange en annan indextyp genom att skicka 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
    });

Tilläggsmetoder som inte har några parametrar tillhandahålls också. Dessa kräver att en instans av klassen IScope registreras separat med containern för beroendeinmatning.

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

Du kan skapa en Couchbase Vector Store-instans direkt.

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

Det går att skapa en direktreferens till en namngiven samling.

Använda frågesamling (hyperskala eller sammansatt index)

För vektorsökning med höga prestanda med Hyperskala-index:

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

Använda söksamling (Search Vector Index)

För hybridsökningsscenarier som kombinerar fulltextsökning:

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

Jämförelse av indextyp

Couchbase erbjuder tre typer av index för vektorsökning:

Vektorindex för hyperskala

• Bäst för rena vektorsökningar – identifiering av innehåll, rekommendationer, semantisk sökning
• Hög prestanda med lågt minnesfotavtryck – utformat för att skala till miljarder vektorer
• Optimerad för samtidiga åtgärder – stöder samtidiga sökningar och infogningar
• Använd när: Du utför främst frågor med endast vektorer utan komplex skalärfiltrering
• Perfekt för: Storskalig semantisk sökning, rekommendationssystem, innehållsidentifiering
• Kräver: Couchbase Server 8.0+ eller Capella

Sammansatta vektorindex

• Bäst för filtrerade vektorsökningar – kombinerar vektorsökning med filtrering av skalärt värde
• Effektiv förfiltrering – skalära attribut minskar vektorjämförelseomfånget
• Använd när: Dina frågor kombinerar vektorlikhet med skalära filter som eliminerar stora delar av data
• Perfekt för: Efterlevnadsbaserad filtrering, användarspecifika sökningar, tidsbegränsade frågor
• Kräver: Couchbase Server 8.0+ eller Capella

Sökvektorindex

• Bäst för hybridsökningar som kombinerar fulltextsökning med vektorlikhet
• Tillåter semantisk sökning tillsammans med traditionell nyckelordsmatchning
• Stöder geospatiala sökningar utöver vektor och text
• Använd när: Du måste kombinera traditionell nyckelordssökning med vektorlikhetssökning i samma fråga
• Perfekt för: Produktsökning för e-handel, reserekommendationer, innehållsidentifiering med flera sökvillkor
• Kräver: Couchbase Server 7.6+ eller Capella

Välja rätt indextyp:

• Börja med Hyperskala Index för rena vektorsökningar och stora datamängder (skalar till miljarder)
• Välj Sammansatt index när skalära filter avsevärt minskar sökutrymmet (fungerar bra för tiotals miljoner till miljarder vektorer)
• Använda Search Vector Index för hybridsökning som kombinerar text och vektorer

Detaljerad jämförelse av vektorindextyper

Datakartläggning

Couchbase-kopplingen kommer att använda System.Text.Json.JsonSerializer för att utföra mappning. Egenskaper i datamodellen serialiseras till ett JSON-objekt och lagras som dokumentvärde i Couchbase.

Användning av JsonPropertyNameAttribute stöds om ett annat lagringsnamn än datamodellens egenskapsnamn krävs. Du kan också använda en anpassad JsonSerializerOptions instans med en anpassad namngivningsprincip för egenskaper.

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

Eftersom en namngivningsprincip för orm_case_upper valdes, här är ett exempel på hur den här datatypen kommer att lagras i Couchbase. Observera också användningen av JsonPropertyNameAttribute på Description egenskapen för att ytterligare anpassa lagringsnamngivningen.

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

Stöds inte

Stöds inte.

Stöds inte

Stöds inte.