Magasin de vecteurs Amazon S3

La classe S3Vectors propose une recherche vectorielle à l’aide d’Amazon S3 Vectors (Preview). Elle stocke les vecteurs dans des buckets de vecteurs et effectue des recherches de similarité dans des index vectoriels, avec des filtres de métadonnées fondés sur JSON.

attention

Amazon S3 Vectors est un service Preview. Les fonctionnalités Preview peuvent être modifiées ou supprimées sans préavis et ne sont pas couvertes par les SLA AWS. Son comportement, ses limites et sa disponibilité régionale peuvent changer à tout moment. Cette bibliothèque peut introduire des changements cassants afin de rester alignée sur AWS.

Installation

npm

npm install @mastra/s3vectors@latest

pnpm

pnpm add @mastra/s3vectors@latest

Yarn

yarn add @mastra/s3vectors@latest

Bun

bun add @mastra/s3vectors@latest

Exemple d’utilisation

import { S3Vectors } from '@mastra/s3vectors'

const store = new S3Vectors({
  vectorBucketName: process.env.S3_VECTORS_BUCKET_NAME!, // e.g. "my-vector-bucket"
  clientConfig: {
    region: process.env.AWS_REGION!, // credentials use the default AWS provider chain
  },
  // Optional: mark large/long-text fields as non-filterable at index creation time
  nonFilterableMetadataKeys: ['content'],
})

// Create an index (names are normalized: "_" → "-" and lowercased)
await store.createIndex({
  indexName: 'my_index',
  dimension: 1536,
  metric: 'cosine', // "euclidean" also supported; "dotproduct" is NOT supported
})

// Upsert vectors (ids auto-generated if omitted). Date values in metadata are serialized to epoch ms.
const ids = await store.upsert({
  indexName: 'my_index',
  vectors: [
    [0.1, 0.2 /* … */],
    [0.3, 0.4 /* … */],
  ],
  metadata: [
    {
      text: 'doc1',
      genre: 'documentary',
      year: 2023,
      createdAt: new Date('2024-01-01'),
    },
    { text: 'doc2', genre: 'comedy', year: 2021 },
  ],
})

// Query with metadata filters (implicit AND is canonicalized)
const results = await store.query({
  indexName: 'my-index',
  queryVector: [0.1, 0.2 /* … */],
  topK: 10, // Service-side limits may apply (commonly 30)
  filter: { genre: { $in: ['documentary', 'comedy'] }, year: { $gte: 2020 } },
  includeVector: false, // set true to include raw vectors (may trigger a secondary fetch)
})

// Clean up resources (closes the underlying HTTP handler)
await store.disconnect()

Options du constructeur

vectorBucketName:

string

Nom du bucket de vecteurs S3 Vectors cible.

clientConfig?:

S3VectorsClientConfig

Options du client AWS SDK v3 (par exemple, region, credentials).

nonFilterableMetadataKeys?:

string[]

Clés de métadonnées qui ne doivent PAS être filtrables (appliquées à l’index lors de sa création). Utilisez-les pour les champs de texte volumineux comme content.

Méthodes

createIndex()

Crée un nouvel index vectoriel dans le bucket de vecteurs configuré. Si l’index existe déjà, l’appel valide le schéma et n’a aucun effet (la métrique et la dimension existantes sont conservées).

indexName:

string

Nom logique de l’index. Normalisé en interne : les traits de soulignement sont remplacés par des traits d’union et le nom est converti en minuscules.

dimension:

number

Dimension du vecteur (doit correspondre à votre modèle d’embedding)

metric?:

'cosine' | 'euclidean'

= cosine

Métrique de distance pour la recherche de similarité. dotproduct n’est pas pris en charge par S3 Vectors.

upsert()

Ajoute ou remplace des vecteurs (écriture d’enregistrements complets). Si ids n’est pas fourni, des UUID sont générés.

indexName:

string

Nom de l’index dans lequel effectuer l’upsert

vectors:

number[][]

Tableau de vecteurs d’embedding

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()

Recherche les voisins les plus proches avec un filtrage facultatif des métadonnées.

indexName:

string

Nom de l’index à interroger

queryVector:

number[]

Vecteur de requête pour trouver des vecteurs similaires

topK?:

number

= 10

Nombre de résultats à renvoyer

filter?:

S3VectorsFilter

Filtre de métadonnées fondé sur JSON prenant en charge $and, $or, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists.

includeVector?:

boolean

= false

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

remarque

Les résultats incluent score = 1/(1 + distance) afin qu’un score plus élevé soit préférable tout en préservant le classement de distance sous-jacent.

describeIndex()

Renvoie des informations sur l’index.

indexName:

string

Nom de l’index à décrire.

Renvoie :

interface IndexStats {
  dimension: number
  count: number // computed via ListVectors pagination (O(n))
  metric: 'cosine' | 'euclidean'
}

deleteIndex()

Supprime un index et ses données.

indexName:

string

Index à supprimer.

listIndexes()

Répertorie tous les index du bucket de vecteurs configuré.

Renvoie : Promise<string[]>

updateVector()

Met à jour un vecteur ou des métadonnées pour un ID précis dans un index.

indexName:

string

Index contenant le vecteur.

id:

string

ID à mettre à jour.

update:

object

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

update.vector?:

number[]

Nouvelles données vectorielles à mettre à jour

update.metadata?:

Record<string, any>

Nouvelles métadonnées à mettre à jour

deleteVector()

Supprime un vecteur spécifique par ID.

indexName:

string

Index contenant le vecteur.

id:

string

ID à supprimer.

disconnect()

Ferme le gestionnaire HTTP AWS SDK sous-jacent afin de libérer les sockets.

Types de réponse

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

interface QueryResult {
  id: string
  score: number // 1/(1 + distance)
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

Syntaxe des filtres

S3 Vectors prend en charge un sous-ensemble strict d’opérateurs et de types de valeurs. Le traducteur de filtres Mastra :

• Canonicalise les ET implicites : {a:1,b:2} → { $and: [{a:1},{b:2}] }.
• Normalise les valeurs Date en ms depuis l’époque pour les comparaisons numériques et les éléments de tableau.
• Interdit Date dans les positions d’égalité (field: value ou $eq/$ne). Les valeurs d’égalité doivent être de type string | number | boolean.
• Rejette null/undefined pour l’égalité. L’égalité de tableaux n’est pas prise en charge (utilisez $in/$nin).
• Seuls $and / $or sont autorisés comme opérateurs logiques de premier niveau.
• Les opérateurs logiques doivent contenir des conditions de champ (et non des opérateurs directs).

Opérateurs pris en charge :

• Logiques : $and, $or (tableaux non vides)
• De base : $eq, $ne (string | number | boolean)
• Numériques : $gt, $gte, $lt, $lte (number ou Date → ms depuis l’époque)
• Tableau : $in, $nin (tableaux non vides de string | number | boolean ; Date → ms depuis l’époque)
• Élément : $exists (boolean)

Non pris en charge / interdits (rejetés) : $not, $nor, $regex, $all, $elemMatch, $size, $text, etc.

Exemples :

// Implicit AND
{ genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } }

// Explicit logicals and ranges
{
  $and: [
    { price: { $gte: 100, $lte: 1000 } },
    { $or: [{ stock: { $gt: 0 } }, { preorder: true }] }
  ]
}

// Dates in range (converted to epoch ms)
{ timestamp: { $gt: new Date("2024-01-01T00:00:00Z") } }

remarque

Si vous définissez nonFilterableMetadataKeys lors de la création de l’index, ces clés sont stockées mais ne peuvent pas être utilisées dans les filtres.

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 typiques lors de la configuration de votre application :

• S3_VECTORS_BUCKET_NAME : nom de votre bucket de vecteurs S3 (utilisé pour renseigner vectorBucketName).
• AWS_REGION : région AWS du bucket S3 Vectors.
• Informations d’identification AWS : via la chaîne de fournisseurs AWS SDK standard (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE, etc.).

Bonnes pratiques

• Choisissez la métrique (cosine ou euclidean) qui correspond à votre modèle d’embedding. dotproduct n’est pas pris en charge.
• Gardez les métadonnées filtrables petites et structurées (string/number/boolean). Stockez les textes volumineux (par exemple, content) comme non filtrables.
• Utilisez des chemins avec des points pour les métadonnées imbriquées et des $and/$or explicites pour la logique complexe.
• Évitez d’appeler describeIndex() sur les chemins critiques. count est calculé avec ListVectors paginé (O(n)).
• Utilisez includeVector: true seulement lorsque vous avez besoin des vecteurs bruts.

Pages associées

• Filtres de métadonnées