PG 向量儲存

PgVector 類別使用配備 pgvector 擴充功能的 PostgreSQL 提供向量搜尋。 它在你現有的 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

你希望向量儲存使用的 schema 名稱。如未提供，將使用預設 schema。

max?:

number

連線池的連線數目上限（預設：20）

idleTimeoutMillis?:

number

閒置連線逾時（毫秒）（預設：30000）

pgPoolOptions?:

PoolConfig

其他 pg 連線池配置選項

disableInit?:

boolean

= false

設為 true 時，會略過 createIndex 內的自動 DDL（建立 schema、擴充功能、資料表及索引）。這適用於分開管理 schema 和索引，而且執行階段資料庫角色沒有 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

向量維度（必須與你的嵌入模型相符）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜尋的距離度量

indexConfig?:

IndexConfig

= { type: 'ivfflat' }

索引配置

buildIndex?:

boolean

= true

是否建立索引

metadataIndexes?:

string[]

要建立 btree 索引的 metadata 欄位名稱陣列。按這些 metadata 欄位篩選時，可改善查詢效能。

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）

記憶體需求

建立 HNSW 索引時需要大量共享記憶體。以 10 萬個向量為例：

• 小維度（64d）：使用預設設定時約為 ~60MB
• 中等維度（256d）：使用預設設定時約為 ~180MB
• 大維度（384d+）：使用預設設定時約為 ~250MB+

較高的 M 或 efConstruction 值會大幅增加記憶體需求。如有需要，請調整系統的共享記憶體上限。

upsert()

indexName:

string

要向其中 upsert 向量的索引名稱

vectors:

number[][]

嵌入向量陣列

metadata?:

Record<string, any>[]

每個向量的 metadata

ids?:

string[]

可選的向量 ID（如未提供則自動產生）

query()

indexName:

string

要查詢的索引名稱

queryVector:

number[]

查詢向量

topK?:

number

= 10

要傳回的結果數目

filter?:

Record<string, any>

Metadata 篩選條件

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 或 metadata 篩選條件更新單一向量。必須提供 id 或 filter，但不可同時提供兩者。

indexName:

string

包含該向量的索引名稱

id?:

string

要更新的向量 ID（與 filter 互斥）

filter?:

Record<string, any>

用於識別要更新向量的 metadata 篩選條件（與 id 互斥）

update:

{ vector?: number[]; metadata?: Record<string, any>; }

包含要更新向量及／或 metadata 的物件

按 ID 或篩選條件更新現有向量。update 物件中必須提供 vector 或 metadata，至少提供其中一項。

// 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 或 metadata 篩選條件刪除多個向量。必須提供 ids 或 filter，但不可同時提供兩者。

indexName:

string

包含要刪除向量的索引名稱

ids?:

string[]

要刪除的向量 ID 陣列（與 filter 互斥）

filter?:

Record<string, any>

用於識別要刪除向量的 metadata 篩選條件（與 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
  }
}

索引配置指南

效能最佳化

IVFFlat 調整

• lists 參數：設為 sqrt(n) * 2，其中 n 是向量數目
• 清單越多，準確度越高，但建立時間越長
• 清單越少，建立速度越快，但準確度可能較低

HNSW 調整

• m 參數：
  • 8-16：中等準確度，較低記憶體用量
  • 16-32：高準確度，中等記憶體用量
  • 32-64：極高準確度，高記憶體用量
• efConstruction：
  • 32-64：建立速度快，品質良好
  • 64-128：建立速度較慢，品質較佳
  • 128-256：建立速度最慢，品質最佳

索引重建行為

系統會自動偵測配置變更，並只在有需要時重建索引：

• 配置相同：保留索引（不會重建）
• 配置已變更：移除並重建索引
• 這可避免不必要的索引重建所造成的效能問題

最佳做法

• 定期評估索引配置，確保效能最佳。
• 根據資料集大小及查詢需求調整 lists 和 m 等參數。
• 使用 describeIndex() 監察索引效能，追蹤使用情況
• 定期重建索引以維持效率，尤其是在資料大幅變更後

直接存取連線池

PgVector 類別會將底層 PostgreSQL 連線池公開為 public 欄位：

pgVector.pool // instance of pg.Pool

這讓你可以執行直接 SQL 查詢、管理交易或監察連線池狀態等進階操作。直接使用連線池時：

• 你有責任在用完後釋放 client（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,
      },
    },
  }),
})

相關內容

• Metadata 篩選條件