PG 向量存储
🌐 PG Vector Store
PgVector 类提供使用 PostgreSQL 和 pgvector 扩展的向量搜索功能。它在你现有的 PostgreSQL 数据库中提供强大的向量相似性搜索能力。
🌐 The PgVector class provides vector search using PostgreSQL with pgvector extension. It provides robust vector similarity search capabilities within your existing PostgreSQL database.
构造函数选项Direct link to 构造函数选项
🌐 Constructor Options
connectionString?:
host?:
port?:
database?:
user?:
password?:
ssl?:
schemaName?:
max?:
idleTimeoutMillis?:
pgPoolOptions?:
构造函数示例Direct link to 构造函数示例
🌐 Constructor Examples
连接字符串Direct link to 连接字符串
🌐 Connection String
import { PgVector } from "@mastra/pg";
const vectorStore = new PgVector({
id: 'pg-vector',
connectionString: "postgresql://user:password@localhost:5432/mydb",
});
主机/端口/数据库配置Direct link to 主机/端口/数据库配置
🌐 Host/Port/Database Configuration
const vectorStore = new PgVector({
id: 'pg-vector',
host: "localhost",
port: 5432,
database: "mydb",
user: "postgres",
password: "password",
});
高级配置Direct link to 高级配置
🌐 Advanced Configuration
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,
},
});
方法Direct link to 方法
🌐 Methods
createIndex()Direct link to createIndex()
indexName:
dimension:
metric?:
indexConfig?:
buildIndex?:
IndexConfigDirect link to IndexConfig
type:
flat:
ivfflat:
hnsw:
ivf?:
lists?:
hnsw?:
m?:
efConstruction?:
内存要求Direct link to 内存要求
🌐 Memory Requirements
HNSW 索引在构建过程中需要大量共享内存。对于 10 万个向量：
🌐 HNSW indexes require significant shared memory during construction. For 100K vectors:
- 小尺寸（64d）：默认设置下约为60MB
- 中等维度（256d）：在默认设置下约为180MB
- 大尺寸（384d+）：使用默认设置约250MB以上
较高的 M 值或 efConstruction 值将显著增加内存需求。如有必要，请调整系统的共享内存限制。
🌐 Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system's shared memory limits if needed.
upsert()Direct link to upsert()
indexName:
vectors:
metadata?:
ids?:
query()Direct link to query()
indexName:
vector:
topK?:
filter?:
includeVector?:
minScore?:
options?:
ef?:
probes?:
listIndexes()Direct link to listIndexes()
返回一个由索引名称组成的字符串数组。
🌐 Returns an array of index names as strings.
describeIndex()Direct link to describeIndex()
indexName:
返回：
🌐 Returns:
interface PGIndexStats {
dimension: number;
count: number;
metric: "cosine" | "euclidean" | "dotproduct";
type: "flat" | "hnsw" | "ivfflat";
config: {
m?: number;
efConstruction?: number;
lists?: number;
probes?: number;
};
}
deleteIndex()Direct link to deleteIndex()
indexName:
updateVector()Direct link to updateVector()
通过 ID 或元数据过滤器更新单个向量。必须提供 id 或 filter 中的一个，但不能同时提供两者。
🌐 Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.
indexName:
id?:
filter?:
update:
通过 ID 或筛选条件更新现有向量。更新对象中必须至少提供向量或元数据中的一项。
🌐 Updates an existing vector by ID or filter. At least one of vector or metadata must be provided in the update object.
// 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()Direct link to deleteVector()
indexName:
id:
根据指定索引通过 ID 删除单个向量。
🌐 Deletes a single vector by ID from the specified index.
await pgVector.deleteVector({ indexName: "my_vectors", id: "vector123" });
deleteVectors()Direct link to deleteVectors()
通过 ID 或元数据过滤器删除多个向量。必须提供 ids 或 filter 中的一个，但不能同时提供两者。
🌐 Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.
indexName:
ids?:
filter?:
disconnect()Direct link to disconnect()
关闭数据库连接池。使用存储完成后应调用此方法。
🌐 Closes the database connection pool. Should be called when done using the store.
buildIndex()Direct link to buildIndex()
indexName:
metric?:
indexConfig:
使用指定的度量和配置构建或重建索引。创建新索引之前会删除任何已有索引。
🌐 Builds or rebuilds an index with specified metric and configuration. Will drop any existing index before creating the new one.
// 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",
});
响应类型Direct link to 响应类型
🌐 Response Types
查询结果以此格式返回：
🌐 Query results are returned in this format:
interface QueryResult {
id: string;
score: number;
metadata: Record<string, any>;
vector?: number[]; // Only included if includeVector is true
}
错误处理Direct link to 错误处理
🌐 Error Handling
该存储会抛出可以被捕获的类型化错误：
🌐 The store throws typed errors that can be caught:
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
}
}
索引配置指南Direct link to 索引配置指南
🌐 Index Configuration Guide
性能优化Direct link to 性能优化
🌐 Performance Optimization
IVF平面调谐Direct link to IVF平面调谐
🌐 IVFFlat Tuning
- lists 参数：设置为
sqrt(n) * 2，其中 n 是向量的数量 - 更多列表 = 更高精度但构建时间更慢
- 列表越少 = 构建越快，但可能准确性较低
HNSW 调优Direct link to HNSW 调优
🌐 HNSW Tuning
- m 参数：
- 8-16：准确度中等，内存力较低
- 16-32：高精度，中等内存
- 32-64：极高精度，高内存
- efConstruction：
- 32-64：构建快，质量好
- 64-128：构建较慢，但质量更好
- 128-256：最慢的构建，最佳质量
索引重建行为Direct link to 索引重建行为
🌐 Index Recreation Behavior
系统会自动检测配置更改，并且仅在必要时重建索引：
🌐 The system automatically detects configuration changes and only rebuilds indexes when necessary:
- 相同配置：索引保持不变（不重新创建）
- 配置已更改：索引已被删除并重建
- 这可以防止因不必要的索引重建而导致的性能问题
最佳实践Direct link to 最佳实践
🌐 Best Practices
- 定期评估你的索引配置以确保最佳性能。
- 根据数据集大小和查询要求调整参数，如
lists和m。 - 使用
describeIndex()监控索引性能 以跟踪使用情况 - 定期重建索引以保持效率，尤其是在数据发生重大变化后
直接访问池Direct link to 直接访问池
🌐 Direct Pool Access
PgVector 类将其底层的 PostgreSQL 连接池作为公共字段公开：
🌐 The PgVector class exposes its underlying PostgreSQL connection pool as a public field:
pgVector.pool; // instance of pg.Pool
这可以实现高级用法，例如运行直接的 SQL 查询、管理事务或监控连接池状态。直接使用连接池时：
🌐 This enables advanced usage such as running direct SQL queries, managing transactions, or monitoring pool state. When using the pool directly:
- 你有责任在使用后释放客户端（
client.release()）。 - 在调用
disconnect()之后，连接池仍然可访问，但新的查询将会失败。 - 直接访问会绕过 PgVector 方法提供的任何验证或事务逻辑。
这个设计支持高级用例，但需要用户仔细管理资源。
🌐 This design supports advanced use cases but requires careful resource management by the user.
使用示例Direct link to 使用示例
🌐 Usage Example
使用 fastembed 的本地嵌入Direct link to 使用 fastembed 的本地嵌入
🌐 Local embeddings with fastembed
嵌入是由内存的 semanticRecall 用来按意义（而非关键词）检索相关信息的数字向量。这一设置使用 @mastra/fastembed 来生成向量嵌入。
🌐 Embeddings are numeric vectors used by memory's semanticRecall to retrieve related messages by meaning (not keywords). This setup uses @mastra/fastembed to generate vector embeddings.
安装 fastembed 以开始：
🌐 Install fastembed to get started:
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/fastembed@latest
pnpm add @mastra/fastembed@latest
yarn add @mastra/fastembed@latest
bun add @mastra/fastembed@latest
将以下内容添加到你的代理中：
🌐 Add the following to your agent:
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.1",
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,
},
},
}),
});
相关Direct link to 相关
🌐 Related