Base vectorielle DuckDB

L’implémentation de stockage DuckDB fournit une solution de recherche vectorielle embarquée hautes performances à l’aide de DuckDB, une base de données analytique intégrée au processus. Elle utilise l’extension VSS pour la recherche de similarité vectorielle avec indexation HNSW, offrant ainsi une base vectorielle légère et efficace qui ne nécessite aucun serveur externe.

Elle fait partie du package @mastra/duckdb et fournit une recherche efficace de similarité vectorielle avec filtrage des métadonnées.

Installation

npm

npm install @mastra/duckdb@latest

pnpm

pnpm add @mastra/duckdb@latest

Yarn

yarn add @mastra/duckdb@latest

Bun

bun add @mastra/duckdb@latest

Utilisation

import { DuckDBVector } from "@mastra/duckdb";

// Create a new vector store instance
const store = new DuckDBVector({
  id: "duckdb-vector",
  path: ":memory:", // or './vectors.duckdb' for file persistence
});

// Create an index
await store.createIndex({
  indexName: "myCollection",
  dimension: 1536,
  metric: "cosine",
});

// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
  { text: "first document", category: "A" },
  { text: "second document", category: "B" },
];
await store.upsert({
  indexName: "myCollection",
  vectors,
  metadata,
});

// Query similar vectors
const queryVector = [0.1, 0.2, ...];
const results = await store.query({
  indexName: "myCollection",
  queryVector,
  topK: 10,
  filter: { category: "A" },
});

// Clean up
await store.close();

Options du constructeur

id:

string

Identifiant unique de l’instance de base vectorielle

path?:

string

= ':memory:'

Chemin du fichier de base de données. Utilisez ':memory:' pour une base en mémoire, ou un chemin tel que './vectors.duckdb' pour assurer la persistance.

dimensions?:

number

= 1536

Dimension par défaut des embeddings vectoriels

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Métrique de distance par défaut pour la recherche de similarité

Méthodes

createIndex()

Crée une nouvelle collection vectorielle avec un index HNSW facultatif pour une recherche rapide et approximative des plus proches voisins.

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 les vecteurs et leurs métadonnées dans l’index.

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 (UUID générés automatiquement s’ils ne sont pas fournis)

query()

Recherche des vecteurs similaires avec un filtrage facultatif des métadonnées.

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?:

Filter

Filtres de métadonnées utilisant une syntaxe de requête similaire à MongoDB

includeVector?:

boolean

= false

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

describeIndex()

Obtient des informations sur un 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 de la base de données.

Renvoie : Promise<string[]>

updateVector()

Met à jour un seul vecteur par ID ou par filtre de métadonnées. Vous devez fournir id ou filter, mais pas les deux.

indexName:

string

Nom de l’index contenant le vecteur

id?:

string

ID de l’entrée vectorielle à mettre à jour (mutuellement exclusif avec filter)

filter?:

Record<string, any>

Filtre de métadonnées permettant d’identifier le ou les vecteurs à mettre à jour (mutuellement exclusif avec id)

update:

object

Données de mise à jour contenant le vecteur et/ou les métadonnées

update.vector?:

number[]

Nouvelles données vectorielles à appliquer

update.metadata?:

Record<string, any>

Nouvelles métadonnées à appliquer

deleteVector()

Supprime d’un index une entrée vectorielle donnée à partir de son ID.

indexName:

string

Nom de l’index contenant le vecteur

id:

string

ID de l’entrée vectorielle à supprimer

deleteVectors()

Supprime plusieurs vecteurs par ID ou par filtre de métadonnées. Vous devez fournir ids ou filter, mais pas les deux.

indexName:

string

Nom de l’index contenant les vecteurs à supprimer

ids?:

string[]

Tableau des ID de vecteurs à supprimer (mutuellement exclusif avec filter)

filter?:

Record<string, any>

Filtre de métadonnées permettant d’identifier les vecteurs à supprimer (mutuellement exclusif avec ids)

close()

Ferme la connexion à la base de données et libère les ressources.

await store.close()

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
}

Opérateurs de filtre

La base vectorielle DuckDB prend en charge des opérateurs de filtre similaires à ceux de MongoDB :

Catégorie	Opérateurs
Comparaison	$eq, $ne, $gt, $gte, $lt, $lte
Logique	$and, $or, $not, $nor
Tableau	$in, $nin
Élément	$exists
Texte	$contains

Exemples de filtres

// Allegato operators
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: {
    $and: [
      { category: "electronics" },
      { price: { $gte: 100, $lte: 500 } },
    ],
  },
});

// Nested field access
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: { "user.profile.tier": "premium" },
});

Métriques de distance

Métrique	Description	Interprétation du score	Cas d’utilisation recommandé
cosine	Similarité cosinus	0-1 (1 = le plus similaire)	Embeddings de texte, vecteurs normalisés
euclidean	Distance L2	0-∞ (0 = le plus similaire)	Embeddings d’image, données spatiales
dotproduct	Produit scalaire	Plus élevé = plus similaire	Lorsque la norme du vecteur est importante

Gestion des erreurs

La base vectorielle déclenche des erreurs propres aux différents cas d’échec :

try {
  await store.query({
    indexName: 'my-collection',
    queryVector: queryVector,
  })
} catch (error) {
  if (error.message.includes('not found')) {
    console.error('The specified index does not exist')
  } else if (error.message.includes('Invalid identifier')) {
    console.error('Index name contains invalid characters')
  } else {
    console.error('Vector store error:', error.message)
  }
}

Les cas d’erreur courants comprennent :

• Format de nom d’index non valide
• Index/table introuvable
• Incompatibilité de dimension entre le vecteur de requête et l’index
• Filtre ou tableau d’ID vide lors des opérations de suppression/mise à jour
• Violation de l’exclusion mutuelle (fourniture simultanée de id et filter)

Cas d’utilisation

Recherche sémantique embarquée

Créez des applications d’IA capables de fonctionner hors ligne avec une recherche sémantique entièrement exécutée dans le processus :

const store = new DuckDBVector({
  id: 'offline-search',
  path: './search.duckdb',
})

Pipelines RAG locaux

Traitez localement des documents sensibles sans envoyer les données vers des bases vectorielles cloud :

const store = new DuckDBVector({
  id: 'private-rag',
  path: './confidential.duckdb',
  dimensions: 1536,
})

Développement et tests

Prototypez rapidement des fonctionnalités de recherche vectorielle sans aucune infrastructure :

const store = new DuckDBVector({
  id: 'dev-store',
  path: ':memory:', // Fast in-memory for tests
})

Ressources associées

• Filtres de métadonnées
• Documentation DuckDB