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

💡

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

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
結果の再ランキングのオプション。(作成時に設定するか、実行時にオーバーライド可能。)

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; // ユニークなチャンク/ドキュメント識別子 metadata: any; // すべてのメタデータフィールド(ドキュメントIDなど) vector: number[]; // 埋め込みベクトル(利用可能な場合) score: number; // この検索の類似度スコア document: string; // 完全なチャンク/ドキュメントテキスト(利用可能な場合) }

デフォルトツールの説明

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

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

結果の処理

このツールは、ユーザーのクエリに基づいて返す結果の数を決定し、デフォルトでは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", });

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

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

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: any }>(); runtimeContext.set("vectorStoreName", "my-store"); runtimeContext.set("indexName", "my-index"); runtimeContext.set("topK", 5); runtimeContext.set("filter", { "category": "docs" }); const response = await agent.generate("Find documentation from the knowledge base.", { runtimeContext, });

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

ツールの詳細

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

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

関連