Skip to Content
リファレンスツールcreateVectorQueryTool()

createVectorQueryTool()

createVectorQueryTool() 関数は、ベクトルストアに対するセマンティック検索のためのツールを作成します。フィルタリング、リランキング、データベース固有の設定をサポートし、さまざまなベクトルストアバックエンドと統合できます。

基本的な使い方

import { openai } from "@ai-sdk/openai";
import { createVectorQueryTool } from "@mastra/rag";
 
const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding("text-embedding-3-small"),
});

Parameters

💡

パラメータ要件: ほとんどのフィールドは作成時にデフォルトとして設定できます。 一部のフィールドは、ランタイムコンテキストまたは入力を介してランタイム時にオーバーライドできます。必須フィールドが作成時とランタイム時の両方で欠落している場合、エラーがスローされます。なお、model、id、descriptionは作成時にのみ設定できます。

id?:

string
ツールのカスタムID。デフォルト: 'VectorQuery {vectorStoreName} {indexName} Tool'。（作成時のみ設定可能。）

description?:

string
ツールのカスタム説明。デフォルト: 'Access the knowledge base to find information needed to answer user questions'（作成時のみ設定可能。）

model:

EmbeddingModel
ベクトル検索に使用する埋め込みモデル。（作成時のみ設定可能。）

vectorStoreName:

string
クエリするベクトルストアの名前。（作成時に設定するか、ランタイム時にオーバーライド可能。）

indexName:

string
ベクトルストア内のインデックスの名前。（作成時に設定するか、ランタイム時にオーバーライド可能。）

enableFilter?:

boolean
= false
メタデータに基づく結果のフィルタリングを有効にします。（作成時のみ設定可能ですが、ランタイムコンテキストでフィルターが提供された場合は自動的に有効になります。）

includeVectors?:

boolean
= false
結果に埋め込みベクトルを含めます。（作成時に設定するか、ランタイム時にオーバーライド可能。）

includeSources?:

boolean
= true
結果に完全な検索オブジェクトを含めます。（作成時に設定するか、ランタイム時にオーバーライド可能。）

reranker?:

RerankConfig
結果の再ランキングのオプション。（作成時に設定するか、ランタイム時にオーバーライド可能。）

databaseConfig?:

DatabaseConfig
クエリを最適化するためのデータベース固有の設定オプション。（作成時に設定するか、ランタイム時にオーバーライド可能。）

DatabaseConfig

DatabaseConfigタイプを使用すると、クエリ操作に自動的に適用されるデータベース固有の設定を指定できます。これにより、異なるベクトルストアが提供する独自の機能と最適化を活用できます。

pinecone?:

PineconeConfig
Pineconeベクトルストア固有の設定
object

namespace?:

string
ベクトルを整理するためのPinecone名前空間

sparseVector?:

{ indices: number[]; values: number[]; }
ハイブリッド検索用のスパースベクトル

pgvector?:

PgVectorConfig
pgvector拡張を使用したPostgreSQL固有の設定
object

minScore?:

number
結果の最小類似度スコア閾値

ef?:

number
HNSW検索パラメータ - 精度と速度のトレードオフを制御

probes?:

number
IVFFlatプローブパラメータ - 検索中に訪問するセルの数

chroma?:

ChromaConfig
Chromaベクトルストア固有の設定
object

where?:

Record<string, any>
メタデータフィルタリング条件

whereDocument?:

Record<string, any>
ドキュメントコンテンツフィルタリング条件

RerankConfig

model:

MastraLanguageModel
リランキングに使用する言語モデル

options?:

RerankerOptions
リランキングプロセスのオプション
object

weights?:

WeightConfig
スコアリングコンポーネントの重み (semantic: 0.4, vector: 0.4, position: 0.2)

topK?:

number
返すトップ結果の数

戻り値

このツールは以下のオブジェクトを返します：

relevantContext:

string
最も関連性の高いドキュメントチャンクから結合されたテキスト

sources:

QueryResult[]
完全な検索結果オブジェクトの配列。各オブジェクトには、元のドキュメント、チャンク、および類似度スコアを参照するために必要なすべての情報が含まれています。

QueryResult オブジェクトの構造

{
  id: string;         // Unique chunk/document identifier
  metadata: any;      // All metadata fields (document ID, etc.)
  vector: number[];   // Embedding vector (if available)
  score: number;      // Similarity score for this retrieval
  document: string;   // Full chunk/document text (if available)
}

デフォルトツールの説明

デフォルトの説明は以下に重点を置いています：

  • 保存された知識から関連情報を見つけること
  • ユーザーの質問に答えること
  • 事実に基づく内容を取得すること

結果の処理

このツールは、ユーザーのクエリに基づいて返す結果の数を決定し、デフォルトでは10件の結果を返します。これはクエリの要件に応じて調整することができます。

フィルター付きの例

const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding("text-embedding-3-small"),
  enableFilter: true,
});

フィルタリングが有効になっている場合、このツールはクエリを処理し、セマンティック検索と組み合わせるメタデータフィルターを構築します。プロセスは次のように動作します：

  1. ユーザーが「‘version’ フィールドが2.0より大きいコンテンツを探す」など、特定のフィルター条件を含むクエリを行います。
  2. エージェントがクエリを解析し、適切なフィルターを構築します： 
    {
   "version": { "$gt": 2.0 }
}

このエージェント駆動型のアプローチは以下のことを行います：

  • 自然言語のクエリをフィルター仕様に変換
  • ベクトルストア固有のフィルター構文を実装
  • クエリ用語をフィルター演算子に変換

詳細なフィルター構文やストア固有の機能については、Metadata Filters のドキュメントをご覧ください。

エージェント駆動型フィルタリングの動作例については、Agent-Driven Metadata Filtering の例をご参照ください。

リランキング付きの例

const queryTool = createVectorQueryTool({
  vectorStoreName: "milvus",
  indexName: "documentation",
  model: openai.embedding("text-embedding-3-small"),
  reranker: {
    model: openai("gpt-4o-mini"),
    options: {
      weights: {
        semantic: 0.5, // Semantic relevance weight
        vector: 0.3, // Vector similarity weight
        position: 0.2, // Original position weight
      },
      topK: 5,
    },
  },
});

リランキングは、以下を組み合わせることで結果の品質を向上させます：

  • セマンティック関連性：LLMベースのテキスト類似度スコアを使用
  • ベクトル類似度：元のベクトル距離スコア
  • ポジションバイアス：元の結果の順序を考慮
  • クエリ分析：クエリの特徴に基づく調整

リランカーは初期のベクトル検索結果を処理し、関連性を最適化した順序でリストを返します。

カスタム説明付きの例

const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding("text-embedding-3-small"),
  description:
    "Search through document archives to find relevant information for answering questions about company policies and procedures",
});

この例では、情報検索という基本的な目的を維持しつつ、特定のユースケースに合わせてツールの説明をカスタマイズする方法を示しています。

データベース固有の設定例

databaseConfigパラメータを使用すると、各ベクトルデータベース固有の機能と最適化を活用できます。これらの設定は、クエリ実行時に自動的に適用されます。

Pinecone設定

const pineconeQueryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding("text-embedding-3-small"),
  databaseConfig: {
    pinecone: {
      namespace: "production",  // 環境別にベクトルを整理
      sparseVector: {          // ハイブリッド検索を有効化
        indices: [0, 1, 2, 3],
        values: [0.1, 0.2, 0.15, 0.05]
      }
    }
  }
});

Pineconeの機能:

  • Namespace: 同一インデックス内で異なるデータセットを分離
  • Sparse Vector: 密ベクトルと疎ベクトルを組み合わせて検索品質を向上
  • 使用例: マルチテナントアプリケーション、ハイブリッドセマンティック検索

実行時設定のオーバーライド

異なるシナリオに適応するために、実行時にデータベース設定をオーバーライドできます：

import { RuntimeContext } from '@mastra/core/runtime-context';
 
const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding("text-embedding-3-small"),
  databaseConfig: {
    pinecone: {
      namespace: "development"
    }
  }
});
 
// 実行時にオーバーライド
const runtimeContext = new RuntimeContext();
runtimeContext.set('databaseConfig', {
  pinecone: {
    namespace: 'production'  // 本番環境のネームスペースに切り替え
  }
});
 
const response = await agent.generate(
  "デプロイメントに関する情報を検索",
  { runtimeContext }
);

このアプローチにより、以下が可能になります：

  • 環境間の切り替え（開発/ステージング/本番）
  • 負荷に基づくパフォーマンスパラメータの調整
  • リクエストごとの異なるフィルタリング戦略の適用

例: ランタイムコンテキストの使用

const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding("text-embedding-3-small"),
});

ランタイムコンテキストを使用する場合、実行時にランタイムコンテキスト経由で必要なパラメータを提供します：

const runtimeContext = new RuntimeContext<{
  vectorStoreName: string;
  indexName: string;
  topK: number;
  filter: VectorFilter;
  databaseConfig: DatabaseConfig;
}>();
runtimeContext.set("vectorStoreName", "my-store");
runtimeContext.set("indexName", "my-index");
runtimeContext.set("topK", 5);
runtimeContext.set("filter", { category: "docs" });
runtimeContext.set("databaseConfig", {
  pinecone: { namespace: "runtime-namespace" }
});
runtimeContext.set("model", openai.embedding("text-embedding-3-small"));
 
const response = await agent.generate(
  "Find documentation from the knowledge base.",
  {
    runtimeContext,
  },
);

ランタイムコンテキストの詳細については、以下を参照してください：

ツールの詳細

このツールは以下のように作成されています：

  • ID: VectorQuery {vectorStoreName} {indexName} Tool
  • 入力スキーマ: queryText と filter オブジェクトが必要
  • 出力スキーマ: relevantContext 文字列を返す

関連

createGraphRAGTool()リファレンス: MCPClient | ツール管理 | Mastra ドキュメント