> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Stockage vectoriel MongoDB

La classe `MongoDBVector` fournit une recherche vectorielle au moyen de [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). Elle permet d’effectuer efficacement des recherches par similarité et de filtrer les métadonnées au sein de vos collections MongoDB.

## Installation

**npm**:

```bash
npm install @mastra/mongodb@latest
```

**pnpm**:

```bash
pnpm add @mastra/mongodb@latest
```

**Yarn**:

```bash
yarn add @mastra/mongodb@latest
```

**Bun**:

```bash
bun add @mastra/mongodb@latest
```

## Exemple d’utilisation

```typescript
import { MongoDBVector } from '@mastra/mongodb'

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DB_NAME,
})
```

### Chemin personnalisé du champ d’Embedding

Si vous devez stocker des Embeddings dans une structure de champs imbriqués, par exemple pour les intégrer à des collections MongoDB existantes, utilisez l’option `embeddingFieldPath` :

```typescript
import { MongoDBVector } from '@mastra/mongodb'

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DB_NAME,
  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
})
```

## Options du constructeur

**id** (`string`): Identifiant unique de cette instance de stockage vectoriel

**uri** (`string`): Chaîne de connexion MongoDB

**dbName** (`string`): Nom de la base de données MongoDB à utiliser

**options** (`MongoClientOptions`): Options facultatives du client MongoDB

**embeddingFieldPath** (`string`): Chemin du champ qui stocke les Embeddings vectoriels. Prend en charge les chemins imbriqués au moyen de la notation par points, par exemple 'text.contentEmbedding'. (Default: `embedding`)

## Méthodes

### `connect()`

Établit la connexion au serveur MongoDB. Cette méthode est appelée automatiquement à la première utilisation, mais peut être appelée explicitement si nécessaire.

```typescript
await store.connect()
```

### `createIndex()`

Crée un nouvel index vectoriel (collection) dans MongoDB.

**indexName** (`string`): Nom de la collection à créer

**dimension** (`number`): Dimension du vecteur (doit correspondre à votre modèle d’Embedding)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Métrique de distance pour la recherche par similarité (Default: `cosine`)

**filterFields** (`string[]`): Noms des champs de métadonnées à déclarer comme champs de filtre dans l’index Atlas vectorSearch (enregistrés sous la forme metadata.\<field>). Les requêtes qui filtrent uniquement sur des champs déclarés sont transmises directement à $vectorSearch au lieu de préfiltrer les \_id candidats, ce qui évite la limite BSON de 16 Mo pour les grands ensembles de résultats. Les filtres qui font référence à un champ non déclaré ou utilisent un opérateur non pris en charge par $vectorSearch reviennent automatiquement au préfiltrage.

**collectionName** (`string`): Stocke les vecteurs dans une collection existante (opérationnelle) plutôt que dans une collection gérée portant le nom de l’index. Lorsque cette option est définie, ce stockage ne crée ni ne supprime jamais la collection. Utilise par défaut indexName.

**searchIndexName** (`string`): Nom de l’index Atlas vectorSearch créé dans la collection. Utilise par défaut ${indexName}\_vector\_index.

**allowWrites** (`boolean`): Active explicitement les opérations d’écriture (upsert, updateVector, deleteVector, deleteVectors) dans une collection existante (BYO). Par défaut, un index BYO est en lecture seule : le stockage ne modifie ni ne supprime jamais les documents opérationnels appartenant à l’appelant. Cette option est ignorée pour les collections gérées, qui sont toujours accessibles en écriture. La politique est persistée avec l’enregistrement de l’index et survit aux redémarrages. (Default: `false`)

### `waitForIndexReady()`

Attend qu’un index soit prêt après sa création. Cette méthode est utile lorsque vous devez vous assurer qu’un index est prêt avant d’effectuer des opérations.

**indexName** (`string`): Nom de l’index dont il faut attendre la disponibilité

**timeoutMs** (`number`): Durée d’attente maximale en millisecondes (Default: `60000`)

**checkIntervalMs** (`number`): Intervalle entre les vérifications d’état, en millisecondes (Default: `2000`)

### `upsert()`

Ajoute ou met à jour des vecteurs et leurs métadonnées dans la collection. Pour un index existant (BYO), cette opération exige `allowWrites: true` lors de l’appel à `createIndex()`, car les collections BYO sont en lecture seule par défaut.

**indexName** (`string`): Nom de la collection dans laquelle effectuer l’insertion

**vectors** (`number[][]`): Tableau de vecteurs d’Embedding

**metadata** (`Record<string, any>[]`): Métadonnées de chaque vecteur

**ids** (`string[]`): ID facultatifs des vecteurs (générés automatiquement s’ils ne sont pas fournis)

**documents** (`string[]`): Contenu textuel facultatif des documents à stocker avec les vecteurs

### `query()`

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

**indexName** (`string`): Nom de la collection dans laquelle effectuer la recherche

**queryVector** (`number[]`): Vecteur de requête pour lequel rechercher des vecteurs similaires

**topK** (`number`): Nombre de résultats à renvoyer (Default: `10`)

**filter** (`Record<string, any>`): Filtres de métadonnées (s’appliquent au champ metadata)

**documentFilter** (`Record<string, any>`): Filtres sur les champs du document d’origine (pas uniquement sur les métadonnées)

**includeVector** (`boolean`): Indique si les données vectorielles doivent être incluses dans les résultats (Default: `false`)

**numCandidates** (`number`): Nombre de candidats examinés par le graphe HNSW avant la sélection des résultats top-K. Des valeurs plus élevées améliorent le rappel au prix d’une latence accrue. Consultez : https\://www\.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/ (Default: `20 * topK (plafonné à 10000)`)

**metadataMode** (`'field' | 'document'`): 'field' (valeur par défaut) projette les champs gérés metadata/document, et les champs de filter sont comparés au sous-document metadata. 'document' renvoie le document source complet comme metadata — utilisez ce mode pour les collections opérationnelles existantes dont les documents possèdent leur propre structure — et les champs de filter sont comparés au document \*\*racine\*\* (sans préfixe metadata.). Par défaut, le champ d’Embedding est omis de metadata afin d’éviter d’alourdir la charge utile ; définissez includeVector: true pour le conserver dans metadata et l’exposer également comme vector de premier niveau. (Default: `field`)

### `createSearchIndex()`

Provisionne un index Atlas Search (BM25/plein texte) dans la collection sous-jacente à un index et l’enregistre comme index de recherche textuelle ciblé par `textQuery()` et `hybridQuery()`.

**Collections gérées ou existantes (BYO) :**

- Pour un index **géré** (créé sans `collectionName`), `createIndex()` provisionne déjà un index plein texte _dynamique_ nommé `${collectionName}_search_index` qui couvre tous les champs de type chaîne. `createSearchIndex()` n’est donc nécessaire que pour obtenir un mappage **limité à certains champs** ou un **nom d’index personnalisé**.
- Pour un index **existant (BYO)** (créé avec `collectionName`), `createIndex()` ne crée automatiquement aucun index plein texte. L’activation de `textQuery()`/`hybridQuery()` sur une collection opérationnelle appartenant à l’appelant doit être explicite. Appelez explicitement `createSearchIndex()` pour provisionner l’index textuel (facturable). Tant que vous ne le faites pas, `textQuery()`/`hybridQuery()` lèvent une erreur explicite au lieu d’interroger un index inexistant.

Nommage :

- Lorsque `fields` est fourni **sans** `searchIndexName` explicite, l’index mappé aux champs est créé sous un nom par défaut **distinct** (`${collectionName}_${indexName}_search_fields_index`, unique pour chaque index logique), afin qu’il n’entre pas en conflit avec l’index dynamique créé automatiquement pour une collection gérée et ne soit pas ignoré silencieusement. Cet index distinct est persisté comme index de recherche textuelle ; `textQuery()`/`hybridQuery()` utilisent donc automatiquement le mappage restreint.
- Lorsque `searchIndexName` est fourni, ce nom exact est utilisé et persisté. `textQuery()`/`hybridQuery()` résolvent automatiquement le nom persisté. Vous pouvez également remplacer le nom à chaque appel au moyen de leurs paramètres `searchIndexName` / `textSearchIndexName`.

**indexName** (`string`): Nom de l’index Mastra dont la collection accueillera l’index de recherche

**fields** (`string[]`): Noms des champs à indexer pour la recherche plein texte. Omettez-les pour un mappage dynamique (tous les champs de type chaîne).

**searchIndexName** (`string`): Nom de l’index Atlas Search. Lorsque fields est fourni et que cette valeur est omise, un nom par défaut distinct et propre à chaque index logique est utilisé. Le mappage des champs n’est ainsi pas masqué par l’index dynamique créé automatiquement, et deux index logiques d’une même collection n’entrent pas en conflit. (Default: ``${collectionName}_search_index (ou ${collectionName}_${indexName}_search_fields_index lorsque `fields` est fourni)``)

**waitUntilReady** (`boolean`): Lorsque cette valeur vaut true, bloque jusqu’à ce que l’index plein texte provisionné signale l’état READY avant de résoudre la Promise. Utilise false par défaut afin d’éviter une latence inattendue ; appelez explicitement waitForSearchIndexReady() si vous préférez effectuer l’attente séparément. (Default: `false`)

```typescript
await store.createSearchIndex({
  indexName: 'precedents',
  fields: ['note', 'description'],
})
```

Le nom de l’index mappé aux champs inclut l’`indexName` logique ; deux index logiques d’une même collection obtiennent donc des index textuels distincts. Recréer le _même_ index logique avec des `fields` différents exige toujours de supprimer d’abord l’index existant (`IndexAlreadyExists`).

### `waitForSearchIndexReady()`

Attend que l’index de recherche plein texte (BM25) d’un index passe à l’état READY. `waitForIndexReady()` interroge uniquement l’index vectorSearch ; `createSearchIndex()` renvoie son résultat alors que l’index plein texte Atlas Search est encore en cours de création. Un appel immédiat à `textQuery()`/`hybridQuery()` peut donc échouer de façon intermittente. Appelez cette méthode (ou transmettez `waitUntilReady: true` à `createSearchIndex()`) pour bloquer jusqu’à ce que l’index textuel résolu signale l’état READY.

**indexName** (`string`): Nom logique de l’index dont il faut attendre l’index textuel

**searchIndexName** (`string`): Remplace le nom résolu de l’index de recherche textuelle

**timeoutMs** (`number`): Durée d’attente maximale en millisecondes (Default: `60000`)

**checkIntervalMs** (`number`): Intervalle entre les vérifications d’état, en millisecondes (Default: `2000`)

```typescript
await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
await store.waitForSearchIndexReady({ indexName: 'precedents' })
```

### `textQuery()`

Exécute une recherche plein texte (BM25) sur un index Atlas Search. Par défaut, elle cible l’index de recherche textuelle enregistré pour cet index (défini par `createSearchIndex()`, ou l’index dynamique `${collectionName}_search_index` créé automatiquement par `createIndex()`). Transmettez `searchIndexName` pour cibler un index précis lors de cet appel.

Ici, les filtres de métadonnées, comme avec `hybridQuery()`, sont appliqués au moyen d’une étape `$match`. Pour la branche vectorielle de `hybridQuery()`, les filtres portant sur des champs non déclarés avec `filterFields` lors de la création de l’index sont matérialisés de manière transparente sous forme d’`_id` candidats (le même mécanisme de repli que celui utilisé par `query()`) ; les filtres sur des champs non déclarés ne provoquent donc pas d’erreur.

**indexName** (`string`): Nom de l’index Mastra dans lequel effectuer la recherche

**query** (`string`): Chaîne de requête pour la recherche plein texte

**paths** (`string[]`): Chemins des champs dans lesquels effectuer la recherche, par exemple \["note", "description"]

**topK** (`number`): Nombre de résultats à renvoyer (Default: `10`)

**filter** (`Record<string, any>`): Filtres de métadonnées (s’appliquent au champ metadata)

**metadataMode** (`'field' | 'document'`): 'field' (valeur par défaut) projette les champs gérés metadata/document. 'document' renvoie le document source complet comme metadata. (Default: `field`)

**searchIndexName** (`string`): Remplace le nom résolu de l’index de recherche plein texte pour cet appel. Utilise par défaut l’index persisté par createSearchIndex() / createIndex().

```typescript
const results = await store.textQuery({
  indexName: 'precedents',
  query: 'shell company offshore',
  paths: ['note'],
  topK: 10,
})
```

### `hybridQuery()`

Exécute une recherche hybride qui fusionne les résultats de similarité vectorielle et de recherche plein texte au moyen de l’opérateur `$rankFusion` côté serveur de MongoDB. Elle nécessite MongoDB >= 8.0 et est généralement disponible à partir de la version 8.1. Sous la version 8.0.x, son activation peut nécessiter une demande auprès du support MongoDB ; elle fonctionne dans les environnements où elle est activée, comme Atlas 8.0.x. Un index de recherche plein texte doit exister : il est créé automatiquement pour les index gérés, mais vous devez d’abord appeler explicitement `createSearchIndex()` pour une collection existante.

**indexName** (`string`): Nom de l’index Mastra dans lequel effectuer la recherche

**queryVector** (`number[]`): Vecteur de requête pour la recherche par similarité

**query** (`string`): Chaîne de requête pour la recherche plein texte

**paths** (`string[]`): Chemins des champs dans lesquels effectuer la recherche plein texte, par exemple \["note", "description"]

**topK** (`number`): Nombre de résultats à renvoyer (Default: `10`)

**filter** (`Record<string, any>`): Filtres de métadonnées (s’appliquent aux branches vectorielle et textuelle)

**weights** (`{ vector?: number; text?: number }`): Poids relatifs des résultats vectoriels et textuels dans la fusion (valeur par défaut : 1:1)

**numCandidates** (`number`): Nombre de candidats pour la branche de recherche vectorielle (Default: `20 * topK (plafonné à 10000)`)

**metadataMode** (`'field' | 'document'`): 'field' (valeur par défaut) projette les champs gérés metadata/document. 'document' renvoie le document source complet comme metadata. (Default: `field`)

**textSearchIndexName** (`string`): Remplace le nom résolu de l’index de recherche plein texte pour cet appel. Utilise par défaut l’index persisté par createSearchIndex() / createIndex().

```typescript
const results = await store.hybridQuery({
  indexName: 'precedents',
  queryVector: embedding,
  query: 'shell company offshore',
  paths: ['note'],
  topK: 10,
  weights: { vector: 1, text: 1.5 }, // Favor text matches
})
```

`hybridQuery()` nécessite MongoDB >= 8.0 pour l’étape `$rankFusion`. Celle-ci est généralement disponible à partir de la version 8.1. Sous la version 8.0.x, son activation peut nécessiter une demande auprès du support MongoDB ; elle fonctionne dans les environnements où elle est activée, comme Atlas 8.0.x. Si vous utilisez une version antérieure ou si `$rankFusion` n’est pas activé dans votre déploiement 8.0.x, utilisez séparément `query()` et `textQuery()`, puis fusionnez les résultats côté client.

### `describeIndex()`

Renvoie des informations sur l’index (collection).

**indexName** (`string`): Nom de la collection à décrire

**Renvoie :**

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

### `deleteIndex()`

Supprime un index vectoriel. Le comportement dépend de la manière dont l’index a été créé :

- **Index géré** (créé sans `collectionName`) : supprime toute la collection et l’ensemble de ses données.
- **Index existant (BYO)** (créé avec `collectionName`) : supprime l’index Atlas vectorSearch et, si un index a été provisionné avec `createSearchIndex()`, l’index de recherche plein texte associé. La collection opérationnelle de l’appelant et ses documents sont conservés. Ce stockage ne supprime jamais une collection qu’il n’a pas créée.

La classification BYO est enregistrée durablement lors de la création de l’index ; elle est donc appliquée correctement, même par un autre processus, par exemple lorsqu’un index est créé par une tâche de configuration puis supprimé ultérieurement par un service de longue durée. Transmettez toujours le **nom logique de l’index** (l’`indexName` utilisé avec `createIndex`), et non le nom physique de la collection.

**indexName** (`string`): Nom logique de l’index à supprimer

### `listIndexes()`

Répertorie les noms d’index Mastra **logiques** (les valeurs `indexName` transmises à `createIndex`), et non les noms physiques des collections. Pour un index existant dont les données résident dans une collection opérationnelle, le nom logique de l’index est renvoyé à la place du nom physique de la collection. Cette valeur peut être retransmise directement à `deleteIndex()` / `describeIndex()`. Les index gérés créés avant l’introduction des métadonnées durables sont toujours découverts au moyen de leur index de recherche `${name}_vector_index`. La collection du registre interne n’est jamais répertoriée.

**Renvoie :** `Promise<string[]>`

### `updateVector()`

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

> **Les collections existantes sont en lecture seule par défaut.** `upsert()`, `updateVector()`, `deleteVector()` et `deleteVectors()` lèvent une erreur de catégorie USER sur un index BYO, sauf s’il a été créé avec `allowWrites: true`. Consultez la section [Indexer une collection existante](#indexing-an-existing-collection).

**indexName** (`string`): Nom de la collection 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 précise à partir de son ID.

**indexName** (`string`): Nom de la collection contenant le vecteur

**id** (`string`): ID de l’entrée vectorielle à supprimer

### `deleteVectors()`

Supprime plusieurs vecteurs à partir de leurs ID ou d’un filtre de métadonnées. Vous devez fournir `ids` ou `filter`, mais pas les deux.

**indexName** (`string`): Nom de la collection 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)

### `disconnect()`

Ferme la connexion du client MongoDB. Cette méthode doit être appelée lorsque vous avez terminé d’utiliser le stockage.

## Types de réponses

Les résultats des requêtes sont renvoyés au format suivant :

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

## Gestion des erreurs

Le stockage lève des erreurs typées qui peuvent être interceptées :

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

## Indexer une collection existante

Vous pouvez créer un index vectoriel dans une collection opérationnelle existante plutôt que d’utiliser une collection gérée. Cette approche est utile lorsque vous souhaitez ajouter des fonctionnalités de recherche vectorielle à des documents déjà présents dans votre base de données MongoDB.

```typescript
import { MongoDBVector } from '@mastra/mongodb'

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DB_NAME,
})

// Create a vector index on an existing 'transactions' collection
await store.createIndex({
  indexName: 'precedents',
  dimension: 1024,
  collectionName: 'transactions', // Use existing collection
  searchIndexName: 'txn_vec_idx', // Custom search index name
})

// Wait for the index to be ready
await store.waitForIndexReady({ indexName: 'precedents' })

// Query using document mode to get full source documents
const hits = await store.query({
  indexName: 'precedents',
  queryVector: embeddings,
  topK: 5,
  metadataMode: 'document', // Returns full document as metadata
})

// hits[0].metadata now contains all fields from the source document
console.log(hits[0].metadata.amount, hits[0].metadata.customField)

// Full-text / hybrid search on a BYO collection is opt-in: provision the text index first.
await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
```

**Remarques importantes :**

- La collection doit déjà exister et contenir des documents avec un champ `embedding` (ou l’`embeddingFieldPath` personnalisé que vous avez configuré).
- La collection n’est jamais créée ni supprimée lorsque vous utilisez `collectionName`.
- **Un index BYO est en lecture seule par défaut.** `upsert()`, `updateVector()`, `deleteVector()` et `deleteVectors()` lèvent une erreur explicite au lieu de modifier les documents opérationnels appartenant à l’appelant. Pour permettre au stockage d’écrire des Embeddings dans votre collection, ou d’en supprimer des documents, activez explicitement cette possibilité avec `createIndex({ ..., allowWrites: true })`. La politique est persistée et survit aux redémarrages. Les entrées écrites par d’anciennes versions sans ce flag sont traitées en lecture seule (échec sécurisé).
- Utilisez `metadataMode: 'document'` lors des requêtes afin de récupérer le document source complet comme `metadata`.
- En mode `'document'`, l’Embedding est omis de `metadata` par défaut ; transmettez `includeVector: true` pour le conserver et l’exposer également comme `vector` de premier niveau.
- **En mode `'document'`, le filtrage s’effectue sur les champs du document racine**, et non sur un sous-document `metadata.` imbriqué. `filter: { lane: 'fraud' }` correspond au champ `lane` de premier niveau de vos documents opérationnels (dans le mode `'field'` par défaut, les champs nus sont réécrits sous la forme `metadata.<field>` pour les collections gérées). Les chemins de transmission directe et de repli `$match` respectent tous deux ce comportement.
- **Les `ObjectId` `_id` natifs sont pris en charge.** Les collections opérationnelles utilisent souvent des clés `ObjectId` ; les résultats des requêtes convertissent `_id` en chaîne (conformément au contrat `QueryResult.id`), et `deleteVector()`/`updateVector()`/`deleteVectors()` acceptent cette chaîne et la font correspondre au document `ObjectId` sous-jacent. Les collections gérées (dont les `_id` sont des chaînes) ne sont pas affectées.
- La recherche plein texte et la recherche hybride dans une collection BYO doivent être **activées explicitement** : aucun index plein texte n’est créé automatiquement. Appelez donc `createSearchIndex()` avant `textQuery()`/`hybridQuery()`. L’index plein texte est créé de façon asynchrone. Appelez `waitForSearchIndexReady()` (ou transmettez `waitUntilReady: true`) avant une requête textuelle ou hybride immédiate.
- Sur un index BYO, `deleteIndex()` supprime l’index vectoriel (ainsi que l’index textuel s’il en existe un), mais **conserve** la collection et ses documents.

## Bonnes pratiques

- Indexez les champs de métadonnées utilisés dans les filtres afin d’optimiser les performances des requêtes.
- Adoptez une convention de nommage cohérente pour les champs de métadonnées afin d’éviter des résultats inattendus.
- Surveillez régulièrement les statistiques des index et des collections pour garantir l’efficacité des recherches.
- Lorsque vous indexez des collections existantes, assurez-vous que tous les documents possèdent le champ `embedding` requis.

## Exemple d’utilisation

### Embeddings vectoriels avec `MongoDB`

Les Embeddings sont des vecteurs numériques utilisés par le `semanticRecall` de la mémoire pour récupérer les messages associés en fonction de leur sens, et non de mots-clés.

> **Remarque:** MongoDB Atlas Vector Search est recommandé pour une utilisation en production. Pour les déploiements auto-hébergés, Vector Search est disponible avec les [déploiements Atlas locaux au moyen de l’interface CLI Atlas](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local/).

Cette configuration utilise FastEmbed, un modèle d’Embedding local, pour générer des Embeddings vectoriels. Pour l’utiliser, installez `@mastra/fastembed` :

**npm**:

```bash
npm install @mastra/fastembed@latest
```

**pnpm**:

```bash
pnpm add @mastra/fastembed@latest
```

**Yarn**:

```bash
yarn add @mastra/fastembed@latest
```

**Bun**:

```bash
bun add @mastra/fastembed@latest
```

Ajoutez le code suivant à votre Agent :

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
import { fastembed } from '@mastra/fastembed'

export const mongodbAgent = new Agent({
  id: 'mongodb-agent',
  name: 'mongodb-agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new MongoDBStore({
      id: 'mongodb-storage',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    vector: new MongoDBVector({
      id: 'mongodb-vector',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
      generateTitle: true, // generates descriptive thread titles automatically
    },
  }),
})
```

### Embeddings vectoriels avec VoyageAI

VoyageAI fournit des modèles d’Embedding spécialisés et optimisés pour les tâches de récupération. VoyageAI est également intégré à MongoDB Atlas pour les Embeddings multimodaux.

**npm**:

```bash
npm install @mastra/voyageai@latest
```

**pnpm**:

```bash
pnpm add @mastra/voyageai@latest
```

**Yarn**:

```bash
yarn add @mastra/voyageai@latest
```

**Bun**:

```bash
bun add @mastra/voyageai@latest
```

Exemple d’utilisation de base :

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
import { voyage } from '@mastra/voyageai'

export const mongodbVoyageAgent = new Agent({
  id: 'mongodb-voyage-agent',
  name: 'MongoDB VoyageAI Agent',
  instructions: 'You are an AI agent with semantic recall powered by VoyageAI and MongoDB.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new MongoDBStore({
      id: 'mongodb-storage',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    vector: new MongoDBVector({
      id: 'mongodb-vector',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    embedder: voyage, // VoyageAI's default model (voyage-3.5, 1024 dimensions)
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 5,
        messageRange: 2,
      },
    },
  }),
})
```

Pour obtenir des exemples détaillés d’Embeddings VoyageAI, notamment avec des modèles spécialisés, des Embeddings multimodaux et l’optimisation de la récupération, consultez la [documentation des Embeddings VoyageAI](https://mastra.zisheng.pro/fr/models/embeddings).

## Voir aussi

- [Filtres de métadonnées](https://mastra.zisheng.pro/fr/reference/rag/metadata-filters)
- [Documentation des Embeddings VoyageAI](https://mastra.zisheng.pro/fr/models/embeddings)