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

# PG 벡터 스토어

PgVector 클래스는 다음을 사용하여 벡터 검색을 제공합니다.[PostgreSQL](https://www.postgresql.org/)\~와 함께[pg벡터](https://github.com/pgvector/pgvector)확대. 기존 PostgreSQL 데이터베이스 내에서 안정적인 벡터 유사성 검색 기능을 제공합니다.

## 생성자 옵션

**connectionString** (`string`): PostgreSQL 연결 URL

**host** (`string`): PostgreSQL 서버 호스트

**port** (`number`): PostgreSQL 서버 포트

**database** (`string`): PostgreSQL 데이터베이스 이름

**user** (`string`): PostgreSQL 사용자

**password** (`string`): PostgreSQL 비밀번호

**ssl** (`boolean | ConnectionOptions`): SSL을 활성화하거나 사용자 지정 SSL 구성 제공

**schemaName** (`string`): 벡터 저장소에서 사용할 스키마의 이름입니다. 제공하지 않으면 기본 스키마를 사용합니다.

**max** (`number`): 최대 풀 연결 수(기본값: 20)

**idleTimeoutMillis** (`number`): 유휴 연결 제한 시간(밀리초, 기본값: 30000)

**pgPoolOptions** (`PoolConfig`): 추가 pg 풀 구성 옵션

**disableInit** (`boolean`): true이면 createIndex 내부의 자동 DDL(스키마, 확장, 테이블 및 인덱스 생성)을 건너뜁니다. 스키마와 인덱스를 별도로 관리하고 런타임 데이터베이스 역할에 DDL 권한이 없는 CI/CD 파이프라인에 유용합니다. MASTRA\_DISABLE\_STORAGE\_INIT 환경 변수로도 활성화할 수 있습니다. (Default: `false`)

## 생성자 예

### 연결 문자열

```ts
import { PgVector } from '@mastra/pg'

const vectorStore = new PgVector({
  id: 'pg-vector',
  connectionString: 'postgresql://user:password@localhost:5432/mydb',
})
```

### 호스트/포트/데이터베이스 구성

```ts
const vectorStore = new PgVector({
  id: 'pg-vector',
  host: 'localhost',
  port: 5432,
  database: 'mydb',
  user: 'postgres',
  password: 'password',
})
```

### 고급 구성

```ts
const vectorStore = new PgVector({
  id: 'pg-vector',
  connectionString: 'postgresql://user:password@localhost:5432/mydb',
  schemaName: 'custom_schema',
  max: 30,
  idleTimeoutMillis: 60000,
  pgPoolOptions: {
    connectionTimeoutMillis: 5000,
    allowExitOnIdle: true,
  },
})
```

## 행동 양식

### `createIndex()`

**indexName** (`string`): 생성할 인덱스의 이름

**dimension** (`number`): 벡터 차원(임베딩 Model과 일치해야 함)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색에 사용할 거리 측정 방식 (Default: `cosine`)

**indexConfig** (`IndexConfig`): 인덱스 구성 (Default: `{ type: 'ivfflat' }`)

**buildIndex** (`boolean`): 인덱스를 빌드할지 여부 (Default: `true`)

**metadataIndexes** (`string[]`): btree 인덱스를 생성할 메타데이터 필드 이름의 배열입니다. 이러한 메타데이터 필드로 필터링할 때 쿼리 성능을 향상합니다.

#### `IndexConfig`

**type** (`'flat' | 'hnsw' | 'ivfflat'`): 인덱스 유형 (Default: `ivfflat`)

**type.flat** (`flat`): 전체 검색을 수행하는 순차 스캔(인덱스 없음)입니다.

**type.ivfflat** (`ivfflat`): 근사 검색을 위해 벡터를 목록으로 클러스터링합니다.

**type.hnsw** (`hnsw`): 빠른 검색 시간과 높은 재현율을 제공하는 그래프 기반 인덱스입니다.

**ivf** (`IVFConfig`): IVF 구성

**ivf.lists** (`number`): 목록 수입니다. 지정하지 않으면 데이터 세트 크기에 따라 자동으로 계산됩니다. (최소 100, 최대 4000)

**hnsw** (`HNSWConfig`): HNSW 구성

**hnsw\.m** (`number`): 노드당 최대 연결 수(기본값: 8)

**hnsw\.efConstruction** (`number`): 빌드 시 복잡도(기본값: 32)

#### Memory 요구 사항

HNSW 인덱스는 생성 중에 상당한 공유 Memory가 필요합니다. 100,000개 벡터의 경우:

- 작은 크기(64d): 기본 설정으로 \~60MB
- 중간 크기(256d): 기본 설정에서 \~180MB
- 큰 크기(384d+): 기본 설정에서 \~250MB+

M 값이나 efConstruction 값이 높을수록 Memory 요구 사항이 크게 늘어납니다. 필요한 경우 시스템의 공유 Memory 제한을 조정하십시오.

### `upsert()`

**indexName** (`string`): 벡터를 upsert할 인덱스의 이름

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

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

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

### `query()`

**indexName** (`string`): 쿼리할 인덱스의 이름

**queryVector** (`number[]`): 쿼리 벡터

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

**filter** (`Record<string, any>`): 메타데이터 필터

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

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

**options** (`{ ef?: number; probes?: number }`): HNSW 및 IVF 인덱스의 추가 옵션

**options.ef** (`number`): HNSW 검색 매개변수

**options.probes** (`number`): IVF 검색 매개변수

### `listIndexes()`

인덱스 이름의 배열을 문자열로 반환합니다.

### `describeIndex()`

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

보고:

```typescript
interface PGIndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
  type: 'flat' | 'hnsw' | 'ivfflat'
  config: {
    m?: number
    efConstruction?: number
    lists?: number
    probes?: number
  }
}
```

### `deleteIndex()`

**indexName** (`string`): 삭제할 인덱스의 이름

### `updateVector()`

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

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

**id** (`string`): 업데이트할 벡터의 ID(filter와 함께 사용할 수 없음)

**filter** (`Record<string, any>`): 업데이트할 벡터를 식별하는 메타데이터 필터(id와 함께 사용할 수 없음)

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 업데이트할 벡터 및/또는 메타데이터가 포함된 객체

ID 또는 필터로 기존 벡터를 업데이트합니다. 업데이트 객체에는 벡터 또는 메타데이터 중 하나 이상이 제공되어야 합니다.

```typescript
// Update by ID
await pgVector.updateVector({
  indexName: 'my_vectors',
  id: 'vector123',
  update: {
    vector: [0.1, 0.2, 0.3],
    metadata: { label: 'updated' },
  },
})

// Update by filter
await pgVector.updateVector({
  indexName: 'my_vectors',
  filter: { category: 'product' },
  update: {
    metadata: { status: 'reviewed' },
  },
})
```

### `deleteVector()`

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

**id** (`string`): 삭제할 벡터의 ID

지정된 인덱스에서 ID별로 단일 벡터를 삭제합니다.

```typescript
await pgVector.deleteVector({ indexName: 'my_vectors', id: 'vector123' })
```

### `deleteVectors()`

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

**indexName** (`string`): 삭제할 벡터가 포함된 인덱스의 이름

**ids** (`string[]`): 삭제할 벡터 ID 배열(filter와 함께 사용할 수 없음)

**filter** (`Record<string, any>`): 삭제할 벡터를 식별하는 메타데이터 필터(ids와 함께 사용할 수 없음)

### `disconnect()`

데이터베이스 연결 풀을 닫습니다. 매장 이용이 끝나면 전화해야 합니다.

### `buildIndex()`

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

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색에 사용할 거리 측정 방식 (Default: `cosine`)

**indexConfig** (`IndexConfig`): 인덱스 유형 및 매개변수 구성

지정된 지표 및 구성을 사용하여 인덱스를 빌드하거나 다시 작성합니다. 새 인덱스를 생성하기 전에 기존 인덱스를 삭제합니다.

```typescript
// Define HNSW index
await pgVector.buildIndex('my_vectors', 'cosine', {
  type: 'hnsw',
  hnsw: {
    m: 8,
    efConstruction: 32,
  },
})

// Define IVF index
await pgVector.buildIndex('my_vectors', 'cosine', {
  type: 'ivfflat',
  ivf: {
    lists: 100,
  },
})

// Define flat index
await pgVector.buildIndex('my_vectors', 'cosine', {
  type: 'flat',
})
```

## 응답 유형

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

```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: '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
  }
}
```

## 인덱스 구성 가이드

### 성능 최적화

#### IVFF플랫 튜닝

- **목록 매개변수**: n이 벡터 수일 때 `sqrt(n) * 2`로 설정합니다.
- 목록이 많을수록 정확도는 높아지지만 빌드 시간은 느려집니다.
- 목록이 적을수록 빌드 속도는 빨라지지만 정확도가 낮아질 수 있습니다.

#### HNSW 튜닝

- **m 매개변수**:

  - 8-16: 보통 정확도, 낮은 Memory
  - 16-32: 높은 정확도, 중간 정도의 Memory
  - 32-64: 매우 높은 정확도, 높은 Memory

- **ef건설**:

  - 32-64: 빠른 빌드, 좋은 품질
  - 64-128: 느린 빌드, 더 나은 품질
  - 128-256: 가장 느린 빌드, 최고의 품질

### 인덱스 재생성 동작

시스템은 구성 변경 사항을 자동으로 감지하고 필요한 경우에만 인덱스를 다시 작성합니다.

- 동일한 구성: 인덱스가 유지됩니다(재구성 없음).
- 변경된 구성: 인덱스가 삭제되고 다시 작성됩니다.
- 이는 불필요한 인덱스 재생성으로 인한 성능 문제를 방지합니다.

## 모범 사례

- 최적의 성능을 보장하려면 인덱스 구성을 정기적으로 평가하세요.
- 데이터 세트 크기와 쿼리 요구 사항에 따라 `lists`와 `m` 같은 매개변수를 조정하세요.
- **인덱스 성능 모니터링**: 사용량을 추적하려면 `describeIndex()`를 사용하세요.
- 특히 데이터가 크게 변경된 후에는 효율성을 유지할 수 있도록 인덱스를 주기적으로 재구축하세요.

## 수영장 직접 이용 가능

`PgVector` 클래스는 기반 PostgreSQL 연결 풀을 public 필드로 노출합니다.

```typescript
pgVector.pool // instance of pg.Pool
```

이를 통해 직접 SQL 쿼리 실행, 트랜잭션 관리 또는 풀 상태 모니터링과 같은 고급 사용법이 가능해집니다. 수영장을 직접 사용하는 경우:

- 사용 후 클라이언트를 해제(`client.release()`)할 책임은 사용자에게 있습니다.
- `disconnect()`를 호출한 후에도 풀에는 접근할 수 있지만 새 쿼리는 실패합니다.
- 직접 접근하면 PgVector 메서드가 제공하는 유효성 검사 또는 트랜잭션 로직을 우회합니다. 이 디자인은 고급 사용 사례를 지원하지만 사용자의 신중한 리소스 관리가 필요합니다.

## 사용예

### 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 { PostgresStore, PgVector } from '@mastra/pg'
import { fastembed } from '@mastra/fastembed'

export const pgAgent = new Agent({
  id: 'pg-agent',
  name: 'PG 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 PostgresStore({
      id: 'pg-agent-storage',
      connectionString: process.env.DATABASE_URL!,
    }),
    vector: new PgVector({
      id: 'pg-agent-vector',
      connectionString: process.env.DATABASE_URL!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
    },
  }),
})
```

## 관련된

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