Magasin vectoriel Turbopuffer

La classe TurbopufferVector fournit une recherche vectorielle avec Turbopuffer, une base de données vectorielle hautes performances optimisée pour les applications RAG. Turbopuffer offre une recherche de similarité vectorielle rapide, des capacités de filtrage avancées et une gestion efficace du stockage.

Options du constructeur

apiKey:

string

Clé API permettant de s’authentifier auprès de Turbopuffer

baseUrl?:

string

= https://api.turbopuffer.com

URL de base de l’API Turbopuffer

connectTimeout?:

number

= 10000

Délai d’expiration pour établir une connexion, en ms. S’applique uniquement à Node et Deno.

connectionIdleTimeout?:

number

= 60000

Délai d’inactivité du socket, en ms. S’applique uniquement à Node et Deno.

warmConnections?:

number

= 0

Nombre de connexions à ouvrir initialement lors de la création d’un client.

compression?:

boolean

= true

Indique s’il faut compresser les requêtes et accepter les réponses compressées.

consistency?:

'strong' | 'eventual'

= strong

Niveau de cohérence par défaut des requêtes. Peut être remplacé pour chaque requête. "strong" 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 encore être visibles.

schemaConfigForIndex?:

function

Fonction de rappel qui reçoit un nom d’index et renvoie un objet de configuration pour cet index. Vous pouvez définir des schémas explicites par index.

Méthodes

createIndex()

indexName:

string

Nom de l’index à créer

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Métrique de distance pour la recherche de similarité

upsert()

vectors:

number[][]

Tableau de vecteurs d’embeddings

metadata?:

Record<string, any>[]

Métadonnées de chaque vecteur

ids?:

string[]

ID de vecteurs 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

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

consistency?:

'strong' | 'eventual'

Niveau de cohérence de cette requête. Remplace le niveau de cohérence défini dans le constructeur. La valeur par défaut est "strong".

listIndexes()

Renvoie un tableau de noms d’index 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 à supprimer

updateVector()

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

indexName:

string

Nom de l’index contenant le vecteur

id?:

string

ID du vecteur à mettre à jour (mutuellement exclusif avec filter)

filter?:

Record<string, any>

Filtre de métadonnées pour identifier le ou les vecteurs à mettre à jour (mutuellement exclusif avec id)

update:

{ vector?: number[]; metadata?: Record<string, any>; }

Objet contenant le vecteur et/ou les métadonnées à mettre à jour

deleteVector()

indexName:

string

Nom de l’index contenant le vecteur

id:

string

ID du vecteur à supprimer

deleteVectors()

Supprime plusieurs vecteurs par leurs ID ou par filtre de métadonnées. Vous devez fournir ids ou filter, mais pas les deux.

indexName:

string

Nom de l’index contenant les vecteurs à supprimer

ids?:

string[]

Tableau d’ID de vecteurs à supprimer (mutuellement exclusif avec filter)

filter?:

Record<string, any>

Filtre de métadonnées pour identifier les vecteurs à supprimer (mutuellement exclusif avec ids)

Types de réponse

Les résultats de la 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
}

Configuration des schémas

L’option schemaConfigForIndex vous permet de définir des schémas explicites pour différents index :

schemaConfigForIndex: (indexName: string) => {
  // Mastra's default embedding model and index for memory messages:
  if (indexName === 'memory_messages_384') {
    return {
      dimensions: 384,
      schema: {
        thread_id: {
          type: 'string',
          filterable: true,
        },
      },
    }
  } else {
    throw new Error(`TODO: add schema for index: ${indexName}`)
  }
}

Gestion des erreurs

Le magasin lève des erreurs typées pouvant être interceptées :

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
  }
}

Ressources associées

• Filtres de métadonnées