Stockage vectoriel libSQL
L'implémentation de stockage libSQL fournit une recherche vectorielle compatible avec SQLite au moyen de libSQL, un fork de SQLite doté d'extensions vectorielles, et de Turso avec des extensions vectorielles, offrant ainsi une solution de base de données vectorielle légère et efficace.
Elle fait partie du package @mastra/libsql et offre une recherche efficace par similarité vectorielle avec filtrage des métadonnées.
InstallationLien direct vers Installation
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/libsql@latest
pnpm add @mastra/libsql@latest
yarn add @mastra/libsql@latest
bun add @mastra/libsql@latest
UtilisationLien direct vers Utilisation
import { LibSQLVector } from "@mastra/libsql";
// Create a new vector store instance
const store = new LibSQLVector({
id: 'libsql-vector',
url: process.env.DATABASE_URL,
// Optional: for Turso cloud databases
authToken: process.env.DATABASE_AUTH_TOKEN,
});
// Create an index
await store.createIndex({
indexName: "myCollection",
dimension: 1536,
});
// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
{ text: "first document", category: "A" },
{ text: "second document", category: "B" }
];
await store.upsert({
indexName: "myCollection",
vectors,
metadata,
});
// Query similar vectors
const queryVector = [0.1, 0.2, ...];
const results = await store.query({
indexName: "myCollection",
queryVector,
topK: 10, // top K results
filter: { category: "A" } // optional metadata filter
});
Options du constructeurLien direct vers Options du constructeur
url:
authToken?:
syncUrl?:
syncInterval?:
MéthodesLien direct vers Méthodes
createIndex()Lien direct vers createindex
Crée une nouvelle collection vectorielle. Le nom de l'index doit commencer par une lettre ou un trait de soulignement et ne peut contenir que des lettres, des chiffres et des traits de soulignement. La dimension doit être un entier positif.
indexName:
dimension:
metric?:
upsert()Lien direct vers upsert
Ajoute ou met à jour les vecteurs et leurs métadonnées dans l'index. Utilise une transaction pour garantir l'insertion atomique de tous les vecteurs : si une insertion échoue, l'ensemble de l'opération est annulé.
indexName:
vectors:
metadata?:
ids?:
query()Lien direct vers query
Recherche des vecteurs similaires avec un filtrage facultatif des métadonnées.
indexName:
queryVector:
topK?:
filter?:
includeVector?:
minScore?:
describeIndex()Lien direct vers describeindex
Récupère des informations sur un index.
indexName:
Renvoie :
interface IndexStats {
dimension: number
count: number
metric: 'cosine' | 'euclidean' | 'dotproduct'
}
deleteIndex()Lien direct vers deleteindex
Supprime un index et toutes ses données.
indexName:
listIndexes()Lien direct vers listindexes
Répertorie tous les index vectoriels de la base de données.
Renvoie : Promise<string[]>
truncateIndex()Lien direct vers truncateindex
Supprime tous les vecteurs d'un index tout en conservant sa structure.
indexName:
updateVector()Lien direct vers updatevector
Met à jour un seul vecteur à partir de son identifiant ou d'un filtre de métadonnées. Vous devez fournir soit id, soit filter, mais pas les deux.
indexName:
id?:
filter?:
update:
update.vector?:
update.metadata?:
deleteVector()Lien direct vers deletevector
Supprime d'un index une entrée vectorielle précise à partir de son identifiant.
indexName:
id:
deleteVectors()Lien direct vers deletevectors
Supprime plusieurs vecteurs à partir de leurs identifiants ou d'un filtre de métadonnées. Vous devez fournir soit ids, soit filter, mais pas les deux.
indexName:
ids?:
filter?:
Types de réponseLien direct vers Types de réponse
Les résultats de la requête sont renvoyés au format suivant :
interface QueryResult {
id: string
score: number
metadata: Record<string, any>
vector?: number[] // Only included if includeVector is true
}
Gestion des erreursLien direct vers Gestion des erreurs
Le stockage lève des erreurs propres aux différents cas d'échec :
try {
await store.query({
indexName: 'my-collection',
queryVector: queryVector,
})
} catch (error) {
// Handle specific error cases
if (error.message.includes('Invalid index name format')) {
console.error(
'Index name must start with a letter/underscore and contain only alphanumeric characters',
)
} else if (error.message.includes('Table not found')) {
console.error('The specified index does not exist')
} else {
console.error('Vector store error:', error.message)
}
}
Les cas d'erreur courants comprennent :
- Format de nom d'index non valide
- Dimensions vectorielles non valides
- Table ou index introuvable
- Problèmes de connexion à la base de données
- Échecs de transaction pendant l'upsert
Exemple d'utilisationLien direct vers Exemple d'utilisation
Embeddings locaux avec fastembedLien direct vers Embeddings locaux avec fastembed
Les embeddings sont des vecteurs numériques utilisés par semanticRecall de la mémoire pour récupérer les messages associés en fonction de leur sens, et non de mots-clés. Cette configuration utilise @mastra/fastembed pour générer des embeddings vectoriels.
Pour commencer, installez fastembed :
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/fastembed@latest
pnpm add @mastra/fastembed@latest
yarn add @mastra/fastembed@latest
bun add @mastra/fastembed@latest
Ajoutez ce qui suit à votre Agent :
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
import { fastembed } from '@mastra/fastembed'
export const libsqlAgent = new Agent({
id: 'libsql-agent',
name: 'libSQL 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 LibSQLStore({
id: 'libsql-agent-storage',
url: 'file:libsql-agent.db',
}),
vector: new LibSQLVector({
id: 'libsql-agent-vector',
url: 'file:libsql-agent.db',
}),
embedder: fastembed,
options: {
lastMessages: 10,
semanticRecall: {
topK: 3,
messageRange: 2,
},
generateTitle: true, // Explicitly enable automatic title generation
},
}),
})