Magasin de vecteurs Upstash

La classe UpstashVector propose une recherche vectorielle à l’aide d’Upstash 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'

= cosine

Métrique de distance pour la recherche de similarité

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

= 10

Nombre de résultats à renvoyer

filter?:

Record<string, any>

Filtres de métadonnées pour la requête

includeVector?:

boolean

= false

Indique s’il faut inclure les vecteurs dans les résultats

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 :

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

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

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

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

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 :

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

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

Ajoutez le code suivant à votre agent :

src/mastra/agents/example-upstash-agent.ts

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