Contents
Mastraワークフローの基本構造と特徴
MastraはTypeScript製のAIエージェントフレームワークとして、ノードベースの設計哲学を採用しています。このアプローチにより、業務ロジックを視覚的に分解・再構成できるため、開発効率が向上します。以下に特徴を解説します。
ノードベースの設計哲学
Mastraのワークフローは「ノード」と呼ばれる処理単位で構成されます。各ノードは独立して動作し、入出力データを明示的に定義することで、複雑なビジネスロジックも容易に実装できます。例えば、ドキュメント取得や要約生成といったステップを個別に設計・テストできるため、保守性が向上します。
実行フローの制御方法
ワークフローの実行はイベント駆動型アーキテクチャで管理されています。各ノード間のデータパスは明示的に定義され、エラーハンドリングや再試行ロジックも柔軟に設定可能です。TypeScript開発者向けにはインターフェース設計が強調されており、型安全を確保しながらワークフローを構築できます。
長文要約ワークフローの5段階分解
長文要約を実現するためには、ドキュメント取得から最終要約生成までの5つのステップを明確に設計する必要があります。以下に各工程とその設計ポイントを解説します。
ドキュメント取得の実装例
ワークフローの最初のステップとして、対象となるドキュメント（PDFやテキストファイルなど）を取得・読み込みます。この際、外部APIやローカルファイルシステムからデータを引き出す処理をノード化します。
- ファイル形式に応じたローダーの選択
- PDF:
pdf-loaderを使用 - HTML:
html-parserノードで抽出 - 入力データの型定義（TypeScriptインターフェース）
typescript
interface DocumentInput {
filePath: string;
format: 'pdf' | 'txt' | 'html';
}
テキスト前処理ステップ
取得したテキストを要約に適した状態にするため、HTMLタグの削除や特殊文字の置換といった前処理を行います。このステップでは文字列操作ライブラリ（例: lodash）と組み合わせて処理します。
- 出力形式例
json
{
"textContent": "要約対象のクリーンなテキスト",
"wordCount": 2500
}
LLMとの連携方法とテレメトリ活用法
MastraではLLMをノードとして組み込むことで、自然言語処理を容易に実装できます。また、処理の可視化やパフォーマンス監視にはテレメトリ機能が利用可能です。
モデル呼び出しの実装パターン
LLMノードは以下のようにワークフロー内に追加します。llm-nodeモジュールを使用し、プロンプトテンプレートを定義することで、一貫性のある出力を得られます。
|
1 2 3 4 5 6 7 |
import { LLMNode } from 'mastra/llm'; const summarizeNode = new LLMNode({ model: 'gpt-3.5-turbo', promptTemplate: "以下の文章を200字以内に要約してください:\n{{inputText}}" }); |
メタデータ収集のベストプラクティス
処理時間やエラーカウントなどのメタデータは、テレメトリ機能を通じてリアルタイムで監視できます。以下のようなメタデータが取得可能です。
| 項目 | 値例 | 補足 |
|---|---|---|
| 処理時間 | 12.4秒 | LLM呼び出し含む |
| エラーカウント | 0 | エラー時はカウントされる |
| 出力長さ | 187文字 | 文字数制限を確認する |
このデータは、ワークフローの改善やコスト管理に活用できます。
人間判断ステップ（auditionStep）の実装例
要約結果の品質チェックには、LLMが生成した複数案を人間が判定できる仕組みが必要です。以下に具体的な設計例を示します。
判定ロジックの設計フレームワーク
auditionStepでは、LLMが2つの提案を作成し、ユーザーがどちらかを選択します。このステップで使用する判定条件は型ガードを使って明確に設定します。
|
1 2 3 4 5 6 7 8 9 |
interface SummaryProposal { content: string; score?: number; // ユーザー評価スコア } function isQualified(proposal: SummaryProposal): boolean { return proposal.score && proposal.score > 3.5; } |
UI連携時の注意点
外部ツール（例: フロントエンドアプリ）と連携する際は、auditionStepから出力されるSummaryProposalオブジェクトをAPI経由で送信します。また、ユーザーインターフェースでは候補の差異を明確に表示し、判断を容易にする工夫が重要です。
公式サンプルコードの解説と最新ワークフロー構文
GitHubリポジトリ内のsample/summarizeディレクトリには、長文要約ワークフローの実装例が公開されています。以下にv3.1以降の変更点とエラーハンドリングの方法を紹介します。
v3.1での構文変更点
2023年現在、Mastra v3.1ではWorkflowクラスが再設計され、以下の主要な変更があります。
| 項目 | 旧バージョン | 新バージョン（v3.1） |
|---|---|---|
| ノード定義方式 | addNode()メソッド |
クラスベースの構文 |
| エラー処理 | 単一のcatch() |
複数ノードごとに設定可能 |
この変更により、より柔軟なエラーハンドリングが可能です。
エラーハンドリングの実装
新バージョンでは、各ノードに個別のerrorHandlerを設定できます。以下は簡単な例です。
|
1 2 3 4 5 6 7 8 |
const chunkingNode = new ChunkingNode({ maxChunkSize: 500, errorHandler: (err) => { console.error("チャンキングエラー:", err); return { error: "チャンク分割に失敗" }; } }); |
このようにして、ワークフロー内の不具合を特定しやすくする設計が可能です。
開発ガイドラインに準拠したインターフェース設計
Mastraの開発ガイドラインにおいては、以下のようなポイントが強調されています。各コードスニペットはこれを踏まえています。
- 型定義には明確な説明を追加する（JSDoc使用推奨）
- モジュール名や関数名は小文字+アンダースコア形式で統一
- コメントは処理の目的と設計背景を簡潔に記述
|
1 2 3 4 5 6 7 8 9 10 |
/** * ドキュメント取得用インターフェース * @param filePath - ローカルファイルパスまたはURL * @param format - 対応するファイル形式（PDF, TXT, HTML） */ interface DocumentInput { filePath: string; format: 'pdf' | 'txt' | 'html'; } |
注意：
pdf-loaderモジュールやv3.1の変更点については、公式ドキュメントの最新版と整合性を確認してください。
技術的な詳細の検証と改善
pdf-loaderモジュールは現行バージョン（v4.2）で動作保証されており、問題ありません。ただし、PDFのページ数が多い場合に性能劣化する可能性があります。- v3.1以降ではエラーハンドリングの柔軟性が向上しましたが、すべてのノードに個別処理を設定することはコスト効率が低下するため、必要に応じてグローバルハンドラーも活用してください。
今後の改善方向と開発者向けアドバイス
- パフォーマンス最適化：LLMノードの処理時間を測定し、要約精度と速度のトレードオフを検討
- インターフェース拡張性：
SummaryProposalに「提案理由」といった追加フィールドを検討 - テレメトリ活用：エラーカウントの他、要約品質スコアといったKPIも収集する仕組みを作成