libSQL 벡터 저장소

libSQL 저장소 구현은 SQLite 호환 벡터 검색을 제공합니다.libSQL, 벡터 확장이 포함된 SQLite 포크,투르소벡터 확장을 통해 가볍고 효율적인 벡터 데이터베이스 솔루션을 제공합니다. 그것은의 일부입니다@mastra/libsql패키지화하고 메타데이터 필터링을 통해 효율적인 벡터 유사성 검색을 제공합니다.

설치

npm

npm install @mastra/libsql@latest

pnpm

pnpm add @mastra/libsql@latest

Yarn

yarn add @mastra/libsql@latest

Bun

bun add @mastra/libsql@latest

용법

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

생성자 옵션

url:

string

libSQL 데이터베이스 URL. 인메모리 데이터베이스에는 ':memory:'를, 로컬 파일에는 'file:dbname.db'를, 원격 연결에는 'libsql://your-database.turso.io'와 같은 libSQL 호환 연결 문자열을 사용합니다.

authToken?:

string

Turso 클라우드 데이터베이스의 인증 토큰

syncUrl?:

string

데이터베이스 복제용 URL(Turso 전용)

syncInterval?:

number

데이터베이스 동기화 간격(밀리초, Turso 전용)

행동 양식

createIndex()

새로운 벡터 컬렉션을 만듭니다. 인덱스 이름은 문자나 밑줄로 시작해야 하며 문자, 숫자, 밑줄 문자만 포함할 수 있습니다. 측정기준은 양의 정수여야 합니다.

indexName:

string

생성할 인덱스의 이름

dimension:

number

벡터 차원 크기(임베딩 Model과 일치해야 함)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

유사도 검색에 사용할 거리 측정 방식. 참고: 현재 libSQL에서는 코사인 유사도만 지원합니다.

upsert()

인덱스에 벡터와 해당 메타데이터를 추가하거나 업데이트합니다. 트랜잭션을 사용하여 모든 벡터가 원자적으로 삽입되도록 합니다. 삽입이 실패하면 전체 작업이 롤백됩니다.

indexName:

string

데이터를 삽입할 인덱스의 이름

vectors:

number[][]

임베딩 벡터 배열

metadata?:

Record<string, any>[]

각 벡터의 메타데이터

ids?:

string[]

선택적 벡터 ID(제공하지 않으면 자동 생성)

query()

선택적 메타데이터 필터링을 사용하여 유사한 벡터를 검색합니다.

indexName:

string

검색할 인덱스의 이름

queryVector:

number[]

유사한 벡터를 찾는 데 사용할 쿼리 벡터

topK?:

number

= 10

반환할 결과 수

filter?:

Filter

메타데이터 필터

includeVector?:

boolean

= false

결과에 벡터 데이터를 포함할지 여부

minScore?:

number

= 0

최소 유사도 점수 임계값

describeIndex()

인덱스에 대한 정보를 가져옵니다.

indexName:

string

설명할 인덱스의 이름

보고:

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

deleteIndex()

인덱스와 해당 데이터를 모두 삭제합니다.

indexName:

string

삭제할 인덱스의 이름

listIndexes()

데이터베이스의 모든 벡터 인덱스를 나열합니다.

보고:Promise<string[]>

truncateIndex()

인덱스 구조를 유지하면서 인덱스에서 모든 벡터를 제거합니다.

indexName:

string

비울 인덱스의 이름

updateVector()

ID 또는 메타데이터 필터를 기준으로 단일 벡터를 업데이트합니다. id 또는 filter 중 하나만 제공해야 하며, 둘 다 제공해서는 안 됩니다.

indexName:

string

벡터가 포함된 인덱스의 이름

id?:

string

업데이트할 벡터 항목의 ID(filter와 함께 사용할 수 없음)

filter?:

Record<string, any>

업데이트할 벡터를 식별하는 메타데이터 필터(id와 함께 사용할 수 없음)

update:

object

벡터 및/또는 메타데이터가 포함된 업데이트 데이터

update.vector?:

number[]

업데이트할 새 벡터 데이터

update.metadata?:

Record<string, any>

업데이트할 새 메타데이터

deleteVector()

ID별로 인덱스에서 특정 벡터 항목을 삭제합니다.

indexName:

string

벡터가 포함된 인덱스의 이름

id:

string

삭제할 벡터 항목의 ID

deleteVectors()

ID 또는 메타데이터 필터를 기준으로 여러 벡터를 삭제합니다. ids 또는 filter 중 하나만 제공해야 합니다.

indexName:

string

삭제할 벡터가 포함된 인덱스의 이름

ids?:

string[]

삭제할 벡터 ID 배열(filter와 함께 사용할 수 없음)

filter?:

Record<string, any>

삭제할 벡터를 식별하는 메타데이터 필터(ids와 함께 사용할 수 없음)

응답 유형

쿼리 결과는 다음 형식으로 반환됩니다.

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

오류 처리

저장소는 다양한 실패 사례에 대해 특정 오류를 발생시킵니다.

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

일반적인 오류 사례는 다음과 같습니다.

• 잘못된 인덱스 이름 형식
• 잘못된 벡터 차원
• 테이블/인덱스를 찾을 수 없습니다
• 데이터베이스 연결 문제
• Upsert 중 트랜잭션 실패

사용예

Fastembed를 사용한 로컬 임베딩

임베딩은 Memory의 semanticRecall에서 키워드가 아닌 의미를 기준으로 관련 메시지를 검색하는 데 사용하는 숫자 벡터입니다. 이 설정은 @mastra/fastembed를 사용하여 벡터 임베딩을 생성합니다. 시작하려면 fastembed를 설치하세요.

npm

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

Agent에 다음을 추가합니다.

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

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

관련된

• 메타데이터 필터