セマンティック検索

友人に先週末何をしたかを聞くと、その人は記憶の中から「先週末」に関連する出来事を探し出して、何をしたかを話してくれます。これがMastraのセマンティック検索の仕組みとよく似ています。

📹 動画: セマンティック検索とは何か、どのように機能するか、Mastraでの設定方法について → YouTube（5分）

セマンティックリコールの仕組み

セマンティックリコールはRAGベースの検索であり、メッセージが最近の会話履歴に含まれなくなった場合でも、エージェントが長期間の対話にわたってコンテキストを維持するのに役立ちます。

メッセージのベクトル埋め込みを使用して類似性検索を行い、さまざまなベクトルストアと統合し、取得されたメッセージの周囲のコンテキストウィンドウを設定可能です。

有効にすると、新しいメッセージを使用してベクトルDBに意味的に類似したメッセージを問い合わせます。

LLMからの応答を受け取った後、すべての新しいメッセージ（ユーザー、アシスタント、ツールコール/結果）がベクトルDBに挿入され、後の対話で呼び出されるようになります。

クイックスタート

セマンティックリコールはデフォルトで有効になっているため、エージェントにメモリを与えると、それが含まれます：


import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
 
const agent = new Agent({
  name: "SupportAgent",
  instructions: "You are a helpful support agent.",
  model: openai("gpt-4o"),
  memory: new Memory(),
});

Recall設定

セマンティックリコールの動作を制御する3つの主要なパラメータは以下の通りです：

topK: セマンティックに類似したメッセージを何件取得するか
messageRange: 各マッチに含める周辺コンテキストの量
scope: 現在のスレッド内で検索するか、リソースが所有するすべてのスレッドを対象に検索するか。scope: 'resource'を使用すると、エージェントはユーザーの過去の会話すべてから情報を思い出すことができます。


const agent = new Agent({
  memory: new Memory({
    options: {
      semanticRecall: {
        topK: 3, // 最も類似した3つのメッセージを取得
        messageRange: 2, // 各マッチの前後2つのメッセージを含める
        scope: 'resource', // このユーザーのすべてのスレッドを検索
      },
    },
  }),
});

注意：現在、セマンティックリコールのscope: 'resource'は以下のストレージアダプターでサポートされています：LibSQL、Postgres、Upstash。

ストレージ設定

セマンティックリコールは、メッセージとその埋め込みを保存するためにストレージとベクターDBに依存しています。


import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
const agent = new Agent({
  memory: new Memory({
    // 省略した場合のデフォルトストレージDB
    storage: new LibSQLStore({
      url: "file:./local.db",
    }),
    // 省略した場合のデフォルトベクターDB
    vector: new LibSQLVector({
      connectionUrl: "file:./local.db",
    }),
  }),
});

ストレージ/ベクターコードの例：

埋め込み設定

セマンティックリコールは、メッセージを埋め込みに変換するために埋め込みモデルに依存しています。AI SDKと互換性のある任意の埋め込みモデルを指定できます。

FastEmbed（ローカル埋め込みモデル）を使用するには、@mastra/fastembedをインストールしてください：


npm install @mastra/fastembed


pnpm add @mastra/fastembed


yarn add @mastra/fastembed


bun add @mastra/fastembed

次に、メモリで設定します：


import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { fastembed } from "@mastra/fastembed";
 
const agent = new Agent({
  memory: new Memory({
    // ... その他のメモリオプション
    embedder: fastembed,
  }),
});

または、OpenAIなど別のプロバイダーを使用します：


import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
const agent = new Agent({
  memory: new Memory({
    // ... その他のメモリオプション
    embedder: openai.embedding("text-embedding-3-small"),
  }),
});

無効化

セマンティックリコールの使用にはパフォーマンスへの影響があります。新しいメッセージは埋め込みに変換され、新しいメッセージがLLMに送信される前にベクターデータベースのクエリに使用されます。

セマンティックリコールはデフォルトで有効になっていますが、不要な場合は無効にできます：


const agent = new Agent({
  memory: new Memory({
    options: {
      semanticRecall: false,
    },
  }),
});

以下のようなシナリオでセマンティックリコールを無効にすることを検討してください：

会話履歴が現在の会話に十分なコンテキストを提供している場合。
リアルタイム双方向音声のようなパフォーマンス重視のアプリケーションで、埋め込みの作成とベクタークエリの実行による追加の遅延が顕著な場合。

呼び出されたメッセージの表示

トレースが有効になっている場合、セマンティック呼び出しによって取得されたメッセージは、最近の会話履歴（設定されている場合）と併せて、エージェントのトレース出力に表示されます。

メッセージトレースの表示に関する詳細については、取得されたメッセージの表示を参照してください。