DatabaseConfig

Le type DatabaseConfig vous permet de spécifier des configurations propres à chaque base de données lorsque vous utilisez des outils de requête vectorielle. Ces configurations vous permettent d’utiliser les fonctionnalités et les optimisations proposées par différents magasins de vecteurs.

Définition de type

export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  turbopuffer?: TurbopufferConfig
  [key: string]: any // Extensible for future databases
}

Types propres aux bases de données

PineconeConfig

Options de configuration propres au magasin de vecteurs Pinecone.

namespace?:

string

Espace de noms Pinecone permettant d’organiser et d’isoler les vecteurs au sein d’un même index. Utile pour le multi-tenancy ou la séparation des environnements.

sparseVector?:

{ indices: number[]; values: number[]; }

Vecteur creux pour la recherche hybride combinant des embeddings denses et creux. Améliore la qualité de recherche pour les requêtes fondées sur des mots-clés. Les tableaux indices et values doivent avoir la même longueur.

object

indices:

number[]

Tableau d’indices pour les composantes du vecteur creux

values:

number[]

Tableau de valeurs correspondant aux indices

Cas d’utilisation :

• Applications multi-tenant (espaces de noms distincts par tenant)
• Isolation des environnements (espaces de noms de développement, préproduction et production)
• Recherche hybride combinant correspondances sémantiques et par mots-clés

PgVectorConfig

Options de configuration propres à PostgreSQL avec l’extension pgvector.

minScore?:

number

Seuil minimal de score de similarité pour les résultats. Seuls les vecteurs dont le score de similarité est supérieur à cette valeur seront renvoyés.

ef?:

number

Paramètre de recherche HNSW qui contrôle la taille de la liste dynamique de candidats pendant la recherche. Des valeurs plus élevées améliorent la précision au détriment de la vitesse. Généralement défini entre topK et 200.

probes?:

number

Paramètre de sondage IVFFlat qui indique le nombre de cellules d’index à parcourir pendant la recherche. Des valeurs plus élevées améliorent le rappel au détriment de la vitesse.

Recommandations de performance :

• ef : commencez avec 2 à 4 fois votre valeur topK, puis augmentez-la pour améliorer la précision
• probes : commencez entre 1 et 10, puis augmentez-la pour améliorer le rappel
• minScore : utilisez des valeurs entre 0,5 et 0,9 selon vos exigences de qualité

Cas d’utilisation :

• Optimisation des performances pour les scénarios à forte charge
• Filtrage de qualité pour supprimer les résultats non pertinents
• Réglage fin du compromis entre précision et vitesse de recherche

ChromaConfig

Options de configuration propres au magasin de vecteurs Chroma.

where?:

Record<string, any>

Conditions de filtrage des métadonnées utilisant une syntaxe de requête de style MongoDB. Filtre les résultats selon les champs de métadonnées.

whereDocument?:

Record<string, any>

Conditions de filtrage du contenu des documents. Permet de filtrer selon le contenu textuel réel du document.

Exemples de syntaxe de filtre :

// Simple equality
where: { "category": "technical" }

// Operators
where: { "price": { "$gt": 100 } }

// Multiple conditions
where: {
  "category": "electronics",
  "inStock": true
}

// Document content filtering
whereDocument: { "$contains": "API documentation" }

Cas d’utilisation :

• Filtrage avancé des métadonnées
• Filtrage des documents fondé sur leur contenu
• Combinaisons de requêtes complexes

TurbopufferConfig

Options de configuration propres au magasin de vecteurs Turbopuffer.

consistency?:

'strong' | 'eventual'

Niveau de cohérence des requêtes. "strong" (valeur par défaut) garantit que les requêtes voient toutes les données écrites avant leur début, au prix d’une latence plus élevée. "eventual" offre une latence plus faible, mais les données récemment écrites peuvent ne pas être encore visibles.

Cas d’utilisation :

• Requêtes sensibles à la latence pour lesquelles des données légèrement obsolètes sont acceptables (eventual)
• Flux de travail de lecture après écriture qui doivent voir les données les plus récentes (strong)

Exemples d’utilisation

Utilisation de base

Configuration de base d’une base de données

import { createVectorQueryTool } from '@mastra/rag'

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'production',
    },
  },
})

Remplacement à l’exécution

Remplacement de configuration à l’exécution

import { RequestContext } from '@mastra/core/request-context'

// Initial configuration
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'development',
    },
  },
})

// Override at runtime
const requestContext = new RequestContext()
requestContext.set('databaseConfig', {
  pinecone: {
    namespace: 'production',
  },
})

await vectorTool.execute({ queryText: 'search query' }, { mastra, requestContext })

Plusieurs bases de données

Configuration de plusieurs bases de données

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'dynamic', // Will be determined at runtime
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'default',
    },
    pgvector: {
      minScore: 0.8,
      ef: 150,
    },
    chroma: {
      where: { type: 'documentation' },
    },
  },
})

remarque

Prise en charge de plusieurs bases de données : lorsque vous configurez plusieurs bases de données, seule la configuration correspondant au magasin de vecteurs réellement utilisé est appliquée.

Réglage des performances

Réglage des performances

// High accuracy configuration
const highAccuracyTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 400, // High accuracy
      probes: 20, // High recall
      minScore: 0.85, // High quality threshold
    },
  },
})

// High speed configuration
const highSpeedTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 50, // Lower accuracy, faster
      probes: 3, // Lower recall, faster
      minScore: 0.6, // Lower quality threshold
    },
  },
})

Extensibilité

Le type DatabaseConfig est conçu pour être extensible. Pour ajouter la prise en charge d’une nouvelle base de données vectorielle :

// 1. Define the configuration interface
export interface NewDatabaseConfig {
  customParam1?: string
  customParam2?: number
}

// 2. Extend DatabaseConfig type
export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  newdatabase?: NewDatabaseConfig
  [key: string]: any
}

// 3. Use in vector query tool
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'newdatabase',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    newdatabase: {
      customParam1: 'value',
      customParam2: 42,
    },
  },
})

Bonnes pratiques

1. Configuration des environnements : utilisez différents espaces de noms ou configurations pour différents environnements
2. Réglage des performances : commencez avec les valeurs par défaut et ajustez-les selon vos besoins spécifiques
3. Filtrage de qualité : utilisez minScore pour exclure les résultats de faible qualité
4. Flexibilité à l’exécution : remplacez les configurations à l’exécution pour les scénarios définis à l’exécution
5. Documentation : documentez vos choix de configuration spécifiques pour les membres de l’équipe

Guide de migration

Les outils de requête vectorielle existants continuent de fonctionner sans modification. Pour ajouter des configurations de base de données :

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
+ databaseConfig: {
+   pinecone: {
+     namespace: 'production'
+   }
+ }
});

Ressources associées

• createVectorQueryTool()
• Recherche vectorielle hybride
• Filtres de métadonnées