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

# Magasin de vecteurs Upstash

La classe UpstashVector propose une recherche vectorielle à l’aide d’[Upstash Vector](https://upstash.com/vector), un service de base de données vectorielle serverless qui offre la recherche de similarité vectorielle avec des capacités de filtrage des métadonnées et la prise en charge de la recherche hybride.

## Options du constructeur

**url** (`string`): URL de la base de données Upstash Vector

**token** (`string`): Jeton API Upstash Vector

## Méthodes

### `createIndex()`

Remarque : cette méthode n’a aucun effet pour Upstash, car les index sont créés automatiquement.

**indexName** (`string`): Nom de l’index à 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 de similarité (Default: `cosine`)

### `upsert()`

**indexName** (`string`): Nom de l’index dans lequel effectuer l’upsert

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

**sparseVectors** (`{ indices: number[], values: number[] }[]`): Tableau de vecteurs clairsemés pour la recherche hybride. Chaque vecteur clairsemé doit avoir des tableaux indices et valeurs correspondants.

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

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

### `query()`

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

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

**sparseVector** (`{ indices: number[], values: number[] }`): Vecteur clairsemé facultatif pour la recherche hybride. Ses tableaux indices et valeurs doivent correspondre.

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

**filter** (`Record<string, any>`): Filtres de métadonnées pour la requête

**includeVector** (`boolean`): Indique s’il faut inclure les vecteurs dans les résultats (Default: `false`)

**fusionAlgorithm** (`FusionAlgorithm`): Algorithme utilisé pour combiner les résultats de recherche dense et clairsemée dans une recherche hybride (par exemple, RRF - Reciprocal Rank Fusion)

**queryMode** (`QueryMode`): Mode de recherche : 'DENSE' pour la recherche dense uniquement, 'SPARSE' pour la recherche clairsemée uniquement, ou 'HYBRID' pour la recherche combinée

### `listIndexes()`

Renvoie un tableau de noms d’index (espaces de noms) sous forme de chaînes.

### `describeIndex()`

**indexName** (`string`): Nom de l’index à décrire

Renvoie :

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

### `deleteIndex()`

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

### `updateVector()`

**indexName** (`string`): Nom de l’index à mettre à jour

**id** (`string`): ID de l’élément à mettre à jour

**update** (`object`): Objet de mise à jour contenant le vecteur, le vecteur clairsemé et/ou les métadonnées

L’objet `update` peut avoir les propriétés suivantes :

- `vector` (facultatif) : tableau de nombres représentant le nouveau vecteur dense.
- `sparseVector` (facultatif) : objet vecteur clairsemé avec les tableaux `indices` et `values` pour les index hybrides.
- `metadata` (facultatif) : enregistrement de paires clé-valeur pour les métadonnées.

### `deleteVector()`

**indexName** (`string`): Nom de l’index duquel supprimer l’élément

**id** (`string`): ID de l’élément à supprimer

Tente de supprimer un élément de l’index indiqué à partir de son ID. Journalise un message d’erreur si la suppression échoue.

## Recherche vectorielle hybride

Upstash Vector prend en charge la recherche hybride, qui combine la recherche sémantique (vecteurs denses) et la recherche par mots-clés (vecteurs clairsemés) afin d’améliorer la pertinence et la précision.

### Utilisation hybride de base

```typescript
import { UpstashVector } from '@mastra/upstash'

const vectorStore = new UpstashVector({
  id: 'upstash-vector',
  url: process.env.UPSTASH_VECTOR_URL,
  token: process.env.UPSTASH_VECTOR_TOKEN,
})

// Upsert vectors with both dense and sparse components
const denseVectors = [
  [0.1, 0.2, 0.3],
  [0.4, 0.5, 0.6],
]
const sparseVectors = [
  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] },
]

await vectorStore.upsert({
  indexName: 'hybrid-index',
  vectors: denseVectors,
  sparseVectors: sparseVectors,
  metadata: [{ title: 'Document 1' }, { title: 'Document 2' }],
})

// Query with hybrid search
const results = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  topK: 10,
})
```

### Options avancées de recherche hybride

```typescript
import { FusionAlgorithm, QueryMode } from '@upstash/vector'

// Query with specific fusion algorithm
const fusionResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  fusionAlgorithm: FusionAlgorithm.RRF,
  topK: 10,
})

// Dense-only search
const denseResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  queryMode: QueryMode.DENSE,
  topK: 10,
})

// Sparse-only search
const sparseResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  queryMode: QueryMode.SPARSE,
  topK: 10,
})
```

### Mise à jour de vecteurs hybrides

```typescript
// Update both dense and sparse components
await vectorStore.updateVector({
  indexName: 'hybrid-index',
  id: 'vector-id',
  update: {
    vector: [0.2, 0.3, 0.4],
    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
    metadata: { title: 'Updated Document' },
  },
})
```

## Types de réponse

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

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

## Gestion des erreurs

Le magasin lève des erreurs typées que vous pouvez intercepter :

```typescript
try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}
```

## Variables d’environnement

Variables d’environnement requises :

- `UPSTASH_VECTOR_URL` : URL de votre base de données Upstash Vector
- `UPSTASH_VECTOR_TOKEN` : votre jeton API Upstash Vector

## Exemple d’utilisation

### Embeddings locaux avec fastembed

Les embeddings sont des vecteurs numériques utilisés par `semanticRecall` de la mémoire pour récupérer des messages associés selon leur sens (et non selon des mots-clés). Cette configuration utilise `@mastra/fastembed` pour générer des embeddings vectoriels.

Installez `fastembed` pour commencer :

**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 { UpstashStore, UpstashVector } from '@mastra/upstash'
import { fastembed } from '@mastra/fastembed'

export const upstashAgent = new Agent({
  id: 'upstash-agent',
  name: 'Upstash 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 UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    vector: new UpstashVector({
      id: 'upstash-agent-vector',
      url: process.env.UPSTASH_VECTOR_REST_URL!,
      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
    },
  }),
})
```

## Pages associées

- [Filtres de métadonnées](https://mastra.zisheng.pro/fr/reference/rag/metadata-filters)