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 索引的中繼資料欄位名稱陣列。依這些中繼資料欄位篩選時，可提升查詢效能。

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>[]

每個向量的中繼資料

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 物件中必須至少提供 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 或中繼資料篩選條件刪除多個向量。必須提供 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
  }
}

索引設定指南

效能最佳化

IVFFlat 調校

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

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.release()）。
• 呼叫 disconnect() 後仍可存取連線池，但新查詢會失敗。
• 直接存取會略過 PgVector 方法提供的任何驗證或交易邏輯。

此設計支援進階使用情境，但需要使用者謹慎管理資源。

使用範例

使用 fastembed 的本機嵌入

嵌入是記憶體的 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,
      },
    },
  }),
})

相關內容

• 中繼資料篩選條件