PG 벡터 스토어

PgVector 클래스는 다음을 사용하여 벡터 검색을 제공합니다.PostgreSQL~와 함께pg벡터확대. 기존 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

= false

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

생성자 예

연결 문자열

import { PgVector } from '@mastra/pg'

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

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

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

고급 구성

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'

= cosine

유사도 검색에 사용할 거리 측정 방식

indexConfig?:

IndexConfig

= { type: 'ivfflat' }

인덱스 구성

buildIndex?:

boolean

= true

인덱스를 빌드할지 여부

metadataIndexes?:

string[]

btree 인덱스를 생성할 메타데이터 필드 이름의 배열입니다. 이러한 메타데이터 필드로 필터링할 때 쿼리 성능을 향상합니다.

IndexConfig

type:

'flat' | 'hnsw' | 'ivfflat'

= ivfflat

인덱스 유형

string

flat:

flat

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

ivfflat:

ivfflat

근사 검색을 위해 벡터를 목록으로 클러스터링합니다.

hnsw:

hnsw

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

ivf?:

IVFConfig

IVF 구성

object

lists?:

number

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

hnsw?:

HNSWConfig

HNSW 구성

object

m?:

number

노드당 최대 연결 수(기본값: 8)

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

= 10

반환할 결과 수

filter?:

Record<string, any>

메타데이터 필터

includeVector?:

boolean

= false

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

minScore?:

number

= 0

최소 유사도 점수 임계값

options?:

{ ef?: number; probes?: number }

HNSW 및 IVF 인덱스의 추가 옵션

object

ef?:

number

HNSW 검색 매개변수

probes?:

number

IVF 검색 매개변수

listIndexes()

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

describeIndex()

indexName:

string

설명을 조회할 인덱스의 이름

보고:

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 또는 필터로 기존 벡터를 업데이트합니다. 업데이트 객체에는 벡터 또는 메타데이터 중 하나 이상이 제공되어야 합니다.

// 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별로 단일 벡터를 삭제합니다.

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'

= cosine

유사도 검색에 사용할 거리 측정 방식

indexConfig:

IndexConfig

인덱스 유형 및 매개변수 구성

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

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

응답 유형

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

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

오류 처리

상점에서는 포착할 수 있는 입력된 오류를 발생시킵니다.

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 필드로 노출합니다.

pgVector.pool // instance of pg.Pool

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

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

사용예

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-pg-agent.ts

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

관련된

• 메타데이터 필터