> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# libSQL 벡터 저장소

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

## 설치

**npm**:

```bash
npm install @mastra/libsql@latest
```

**pnpm**:

```bash
pnpm add @mastra/libsql@latest
```

**Yarn**:

```bash
yarn add @mastra/libsql@latest
```

**Bun**:

```bash
bun add @mastra/libsql@latest
```

## 용법

```typescript
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'`): 유사도 검색에 사용할 거리 측정 방식. 참고: 현재 libSQL에서는 코사인 유사도만 지원합니다. (Default: `cosine`)

### `upsert()`

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

**indexName** (`string`): 데이터를 삽입할 인덱스의 이름

**vectors** (`number[][]`): 임베딩 벡터 배열

**metadata** (`Record<string, any>[]`): 각 벡터의 메타데이터

**ids** (`string[]`): 선택적 벡터 ID(제공하지 않으면 자동 생성)

### `query()`

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

**indexName** (`string`): 검색할 인덱스의 이름

**queryVector** (`number[]`): 유사한 벡터를 찾는 데 사용할 쿼리 벡터

**topK** (`number`): 반환할 결과 수 (Default: `10`)

**filter** (`Filter`): 메타데이터 필터

**includeVector** (`boolean`): 결과에 벡터 데이터를 포함할지 여부 (Default: `false`)

**minScore** (`number`): 최소 유사도 점수 임계값 (Default: `0`)

### `describeIndex()`

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

**indexName** (`string`): 설명할 인덱스의 이름

보고:

```typescript
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와 함께 사용할 수 없음)

## 응답 유형

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

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

## 오류 처리

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

```typescript
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**:

```bash
npm install @mastra/fastembed@latest
```

**pnpm**:

```bash
pnpm add @mastra/fastembed@latest
```

**Yarn**:

```bash
yarn add @mastra/fastembed@latest
```

**Bun**:

```bash
bun add @mastra/fastembed@latest
```

Agent에 다음을 추가합니다.

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

## 관련된

- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)