Base vectorielle Couchbase

La classe CouchbaseVector fournit une recherche vectorielle à l’aide de Couchbase Vector Search. Elle permet d’effectuer efficacement des recherches de similarité et un filtrage des métadonnées dans vos collections Couchbase.

Prérequis

• Couchbase Server 7.6.4 ou version ultérieure, ou un cluster Capella compatible
• Service Search activé sur votre déploiement Couchbase

Installation

npm

npm install @mastra/couchbase@latest

pnpm

pnpm add @mastra/couchbase@latest

Yarn

yarn add @mastra/couchbase@latest

Bun

bun add @mastra/couchbase@latest

Exemple d’utilisation

import { CouchbaseVector } from '@mastra/couchbase'

const store = new CouchbaseVector({
  id: 'couchbase-vector',
  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET,
  scopeName: process.env.COUCHBASE_SCOPE,
  collectionName: process.env.COUCHBASE_COLLECTION,
})

Options du constructeur

id:

string

Identifiant unique de cette instance de base vectorielle

connectionString:

string

Chaîne de connexion Couchbase

username:

string

Nom d’utilisateur Couchbase

password:

string

Mot de passe Couchbase

bucketName:

string

Nom du bucket Couchbase à utiliser

scopeName:

string

Nom du scope Couchbase à utiliser

collectionName:

string

Nom de la collection Couchbase à utiliser

options?:

CouchbaseClientOptions

Options facultatives du client Couchbase

Méthodes

createIndex()

Crée un nouvel index vectoriel dans Couchbase.

remarque

La création d’un index est asynchrone. Après avoir appelé createIndex, attendez un certain temps (généralement 1 à 5 secondes pour les petits jeux de données, davantage pour les plus volumineux) avant d’effectuer une requête. En production, mettez en place une interrogation périodique de l’état de l’index au lieu d’utiliser des délais fixes.

indexName:

string

Nom de l’index à créer

dimension:

number

Dimension du vecteur (doit correspondre à votre modèle d’embedding)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Métrique de distance pour la recherche de similarité

upsert()

Ajoute ou met à jour des vecteurs et leurs métadonnées dans la collection.

remarque

Vous pouvez upserter des données avant ou après la création de l’index. La méthode upsert ne nécessite pas que l’index existe. Couchbase autorise plusieurs index Search sur une même collection.

indexName:

string

Nom de l’index dans lequel effectuer l’insertion

vectors:

number[][]

Tableau de vecteurs d’embedding

metadata?:

Record<string, any>[]

Métadonnées de chaque vecteur

ids?:

string[]

ID de vecteurs facultatifs (générés automatiquement s’ils ne sont pas fournis)

query()

Recherche des vecteurs similaires.

attention

Les paramètres filter et includeVector ne sont actuellement pas pris en charge. Le filtrage doit être effectué côté client après la récupération des résultats, ou directement à l’aide des fonctionnalités Search du SDK Couchbase. Pour récupérer le vecteur d’embedding, récupérez le document complet à partir de son ID avec le SDK Couchbase.

indexName:

string

Nom de l’index dans lequel effectuer la recherche

queryVector:

number[]

Vecteur de requête pour lequel rechercher des vecteurs similaires

topK?:

number

= 10

Nombre de résultats à renvoyer

filter?:

Record<string, any>

Filtres de métadonnées

includeVector?:

boolean

= false

Indique s’il faut inclure les données vectorielles dans les résultats

minScore?:

number

= 0

Seuil minimal du score de similarité

describeIndex()

Renvoie des informations sur l’index.

indexName:

string

Nom de l’index à décrire

Renvoie :

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

Supprime un index et toutes ses données.

indexName:

string

Nom de l’index à supprimer

listIndexes()

Répertorie tous les index vectoriels du bucket Couchbase.

Renvoie : Promise<string[]>

updateVector()

Met à jour une entrée vectorielle donnée à partir de son ID avec de nouvelles données vectorielles et/ou métadonnées. Les mises à jour fondées sur des filtres ne sont pas encore implémentées pour Couchbase.

indexName:

string

Nom de l’index contenant le vecteur

id:

string

ID de l’entrée vectorielle à mettre à jour

update:

{ vector?: number[]; metadata?: Record<string, any>; }

Objet contenant le vecteur et/ou les métadonnées à mettre à jour

deleteVector()

Supprime de l’index un seul vecteur à partir de son ID.

indexName:

string

Nom de l’index contenant le vecteur

id:

string

ID du vecteur à supprimer

deleteVectors()

Supprime plusieurs vecteurs à partir de leurs ID. La suppression fondée sur des filtres n’est pas encore implémentée pour Couchbase.

indexName:

string

Nom de l’index contenant les vecteurs à supprimer

ids:

string[]

Tableau des ID de vecteurs à supprimer

disconnect()

Ferme la connexion du client Couchbase. Doit être appelée lorsque vous avez fini d’utiliser la base vectorielle.

Types de réponse

Les résultats de la requête sont renvoyés dans ce format :

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

Gestion des erreurs

La base vectorielle déclenche des erreurs typées qui peuvent être interceptées :

try {
  await store.query({
    indexName: 'my_index',
    queryVector: queryVector,
  })
} catch (error) {
  // Handle specific error cases
  if (error.message.includes('Invalid index name')) {
    console.error(
      'Index name must start with a letter or underscore and contain only valid characters.',
    )
  } else if (error.message.includes('Index not found')) {
    console.error('The specified index does not exist')
  } else {
    console.error('Vector store error:', error.message)
  }
}

Remarques

• Précaution concernant la suppression des index : la suppression d’un index Search ne supprime pas les vecteurs ou documents de la collection Couchbase associée. Les données subsistent tant qu’elles ne sont pas explicitement supprimées.
• Autorisations requises : l’utilisateur Couchbase doit être autorisé à se connecter, à lire et écrire des documents dans la collection cible (rôle kv) ainsi qu’à gérer les index Search (rôle search_admin sur le bucket/scope concerné).
• Détails de la définition de l’index et structure des documents : la méthode createIndex construit une définition d’index Search qui indexe le champ embedding (en tant que type vector) et le champ content (en tant que type text), en ciblant les documents de la valeur scopeName.collectionName indiquée. Chaque document stocke le vecteur dans le champ embedding et les métadonnées dans le champ metadata. Si metadata contient une propriété text, sa valeur est également copiée dans un champ content de niveau supérieur, indexé pour la recherche textuelle.
• Réplication et durabilité : envisagez d’utiliser les fonctionnalités intégrées de réplication et de persistance de Couchbase pour assurer la durabilité des données. Surveillez régulièrement les statistiques des index afin de garantir l’efficacité des recherches.

Limitations

• Les délais de création des index peuvent empêcher d’effectuer immédiatement des requêtes après leur création.
• La dimension des vecteurs n’est pas strictement imposée lors de l’ingestion (une incompatibilité de dimension provoquera une erreur lors de la requête).
• L’insertion de vecteurs et les mises à jour des index sont cohérentes à terme. Une cohérence forte n’est pas garantie immédiatement après les écritures.

Ressources associées

• Filtres de métadonnées