PG Vector Store
PgVectorクラスは、PostgreSQL とpgvector 拡張機能を使用したベクトル検索を提供します。 既存のPostgreSQLデータベース内で堅牢なベクトル類似性検索機能を実現します。
コンストラクタオプション
connectionString:
string
PostgreSQL接続URL
schemaName?:
string
ベクトルストアが使用するスキーマの名前。提供されない場合はデフォルトのスキーマを使用します。
コンストラクタの例
PgVector
を2つの方法でインスタンス化できます:
import { PgVector } from "@mastra/pg";
// 接続文字列を使用する方法(文字列形式)
const vectorStore1 = new PgVector(
"postgresql://user:password@localhost:5432/mydb",
);
// 設定オブジェクトを使用する方法(オプションのschemaNameを含む)
const vectorStore2 = new PgVector({
connectionString: "postgresql://user:password@localhost:5432/mydb",
schemaName: "custom_schema", // オプション
});
メソッド
createIndex()
indexName:
string
作成するインデックスの名前
dimension:
number
ベクトルの次元数(埋め込みモデルと一致する必要があります)
metric?:
'cosine' | 'euclidean' | 'dotproduct'
= cosine
類似検索に使用する距離メトリック
indexConfig?:
IndexConfig
= { type: 'ivfflat' }
インデックスの設定
buildIndex?:
boolean
= true
インデックスを構築するかどうか
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インデックスの構築時には多くの共有メモリが必要です。100Kベクトルの場合:
- 小さい次元(64d):デフォルト設定で約60MB
- 中程度の次元(256d):デフォルト設定で約180MB
- 大きい次元(384d以上):デフォルト設定で約250MB以上
M値やefConstruction値を大きくすると、必要なメモリも大幅に増加します。必要に応じてシステムの共有メモリ上限を調整してください。
upsert()
indexName:
string
ベクトルをアップサートするインデックスの名前
vectors:
number[][]
埋め込みベクトルの配列
metadata?:
Record<string, any>[]
各ベクトルのメタデータ
ids?:
string[]
オプションのベクトルID(指定しない場合は自動生成)
query()
indexName:
string
クエリを実行するインデックスの名前
vector:
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()
indexName:
string
ベクトルを含むインデックスの名前
id:
string
更新するベクトルのID
update:
object
更新パラメータ
object
vector?:
number[]
新しいベクトル値
metadata?:
Record<string, any>
新しいメタデータ値
IDによって既存のベクトルを更新します。ベクトルまたはメタデータの少なくとも一方を提供する必要があります。
// ベクトルのみを更新
await pgVector.updateVector("my_vectors", "vector123", {
vector: [0.1, 0.2, 0.3],
});
// メタデータのみを更新
await pgVector.updateVector("my_vectors", "vector123", {
metadata: { label: "updated" },
});
// ベクトルとメタデータの両方を更新
await pgVector.updateVector("my_vectors", "vector123", {
vector: [0.1, 0.2, 0.3],
metadata: { label: "updated" },
});
deleteVector()
indexName:
string
ベクトルを含むインデックスの名前
id:
string
削除するベクトルのID
指定されたインデックスからIDによって単一のベクトルを削除します。
await pgVector.deleteVector("my_vectors", "vector123");
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
}
}
ベストプラクティス
- 最適なパフォーマンスを確保するために、インデックス設定を定期的に評価してください。
- データセットのサイズやクエリ要件に応じて、
lists
やm
などのパラメータを調整しましょう。 - 特に大きなデータ変更の後は、効率を維持するためにインデックスを定期的に再構築してください。