JavaScript - Elasticsearch Labs

JavaScript、Mastra、Elasticsearch を使用したエージェント型 RAG アシスタントの構築

JD Armada — Tue, 01 Jul 2025 00:00:00 GMT

このアイデアは、白熱したハイリスクなファンタジーバスケットボールリーグの最中に思いつきました。私はこう考えました。 「毎週の対戦で優位に立つのに役立つ AI エージェントを構築できるだろうか？」もちろんです!

この記事では、 Mastraとそれと対話するための軽量 JavaScript Web アプリケーションを使用して、エージェント RAG アシスタントを構築する方法について説明します。このエージェントを Elasticsearch に接続することで、構造化されたプレイヤーデータへのアクセスとリアルタイムの統計集計の実行が可能になり、プレイヤー統計に基づいた推奨事項を提供できるようになります。GitHubリポジトリにアクセスして手順を確認してください。READMEには、アプリケーションを独自に複製して実行する方法が記載されています。

すべてをまとめると次のようになります。

注: このブログ投稿は、「 AI SDK と Elastic を使用した AI エージェントの構築」に基づいています。AI エージェント全般とその用途についてよく知らない場合は、まずそこから始めてください。

アーキテクチャの概要

システムの中核となるのは、エージェントの推論エンジン（脳）として機能する大規模言語モデル（LLM）です。ユーザー入力を解釈し、呼び出すツールを決定し、関連する応答を生成するために必要な手順を調整します。

エージェント自体は、JavaScript エコシステムのエージェントフレームワークである Mastra によって構築されます。Mastra は、LLM をバックエンドインフラストラクチャでラップし、それを API エンドポイントとして公開し、ツール、システムプロンプト、エージェントの動作を定義するためのインターフェイスを提供します。

フロントエンドでは、 Viteを使用して、エージェントにクエリを送信してその応答を受信するためのチャットインターフェイスを提供する React Web アプリケーションを迅速に構築します。

最後に、エージェントがクエリして集計できるプレーヤーの統計情報と対戦データを保存する Elasticsearch があります。

背景

いくつかの基本的な概念を確認してみましょう。

エージェントRAGとは何ですか？

AI エージェントは他のシステムと対話し、独立して動作し、定義されたパラメータに基づいてアクションを実行できます。Agentic RAG は、AI エージェントの自律性と検索拡張生成の原理を組み合わせ、LLM が応答を生成するために呼び出すツールとコンテキストとして使用するデータを選択できるようにします。RAG の詳細については、こちらをご覧ください。

フレームワークを選択する場合、なぜ AI-SDK を超えるのでしょうか?

利用可能な AI エージェントフレームワークは数多くあり、 CrewAI 、 AutoGen 、 LangGraphなどの人気のフレームワークについてはおそらく聞いたことがあるでしょう。これらのフレームワークのほとんどは、さまざまなモデルのサポート、ツールの使用、メモリ管理など、共通の機能セットを共有しています。

こちらは、Harrison Chase (LangChain CEO) によるフレームワーク比較シートです。

私が Mastra に興味を持ったのは、フルスタック開発者がエージェントをエコシステムに簡単に統合できるように構築された JavaScript ファーストのフレームワークであるという点です。Vercel の AI-SDK もこのほとんどを実行しますが、プロジェクトにさらに複雑なエージェントワークフローが含まれている場合は、Mastra が真価を発揮します。Mastra は AI-SDK によって設定された基本パターンを強化しており、このプロジェクトではそれらを連携して使用します。

フレームワークとモデル選択の考慮事項

これらのフレームワークは AI エージェントを迅速に構築するのに役立ちますが、考慮すべき欠点もいくつかあります。たとえば、AI エージェントや一般的な抽象化レイヤー以外のフレームワークを使用する場合、制御が少し失われます。LLM がツールを正しく使用しなかったり、望ましくないことを実行したりする場合、抽象化によってデバッグが難しくなります。それでも、私の意見では、特にこれらのフレームワークは勢いを増しており、継続的に反復されているため、このトレードオフは、構築時に得られる容易さとスピードの価値があります。

繰り返しになりますが、これらのフレームワークはモデルに依存しません。つまり、さまざまなモデルをプラグアンドプレイできます。モデルはトレーニングに使用されたデータセットによって異なり、その結果、モデルが提供する応答も異なることに注意してください。一部のモデルではツールの呼び出しすらサポートされていません。したがって、さまざまなモデルを切り替えてテストし、どのモデルが最適な応答を返すかを確認することは可能ですが、それぞれのシステムプロンプトを書き換える必要がある可能性が高いことに注意してください。例えば、Llama3.3を使用する場合GPT-4o よりも、必要な応答を得るために、より多くのプロンプトと具体的な指示が必要になります。

NBAファンタジーバスケットボール

ファンタジーバスケットボールでは、友達のグループでリーグを開始し (グループの競争力に応じて、友情のステータスに影響する可能性があります)、通常はいくらかのお金が賭けられます。その後、各自が 10 人のプレイヤーでチームを編成し、毎週交互に他の友達の 10 人のプレイヤーと対戦します。全体のスコアに加算されるポイントは、特定の週に各プレイヤーが対戦相手に対して行ったパフォーマンスです。

チームの選手が負傷したり、出場停止になったりした場合は、チームに追加できるフリーエージェント選手のリストが表示されます。ファンタジースポーツでは、選べる選手の数が限られており、誰もが常に最高の選手を選ぶために奔走しているため、ここで多くの難しい思考が生まれます。

これは、どの選手を選択するかをすぐに決定しなければならない状況で特に役立つ、NBA AI アシスタントの出番です。特定の対戦相手に対するプレーヤーのパフォーマンスを手動で調べる代わりに、アシスタントがそのデータをすばやく見つけて平均を比較し、情報に基づいた推奨事項を提供します。

エージェント RAG と NBA ファンタジーバスケットボールの基本がわかったので、実際に見てみましょう。

プロジェクトの構築

途中で行き詰まったり、最初から構築したくない場合は、リポジトリを参照してください。

取り上げる内容

プロジェクトの足場作り:
1. バックエンド (Mastra): npx create mastra@latest を使用してバックエンドをスキャフォールディングし、エージェントロジックを定義します。
2. フロントエンド (Vite + React): npm create vite@latest を使用して、エージェントと対話するためのフロントエンドチャットインターフェイスを構築します。
環境変数の設定
1. 環境変数を管理するには、dotenv をインストールします。
2. .envを作成するファイルを開き、必要な変数を指定します。
Elasticsearchの設定
1. Elasticsearch クラスターを起動します (ローカルまたはクラウド上)。
2. 公式 Elasticsearch クライアントをインストールします。
3. 環境変数にアクセスできることを確認します。
4. クライアントへの接続を確立します。
NBA データを Elasticsearch に一括取り込み
1. 集計を有効にするには、適切なマッピングを使用してインデックスを作成します。
2. プレイヤーのゲーム統計を CSV ファイルから Elasticsearch インデックスに一括取り込みます。
Elasticsearchの集計を定義する
1. 特定の対戦相手に対する過去の平均を計算するクエリ。
2. 特定の対戦相手に対するシーズン平均を計算するクエリ。
プレーヤー比較ユーティリティファイル
1. ヘルパー関数と Elasticsearch 集計を統合します。
エージェントの構築
1. エージェント定義とシステムプロンプトを追加します。
2. zod をインストールし、ツールを定義します。
3. CORS を処理するためのミドルウェア設定を追加します。
フロントエンドの統合
1. AI-SDK の useChat を使用してエージェントと対話します。
2. 適切にフォーマットされた会話を保持するための UI を作成します。
アプリケーションの実行
1. バックエンド (Mastra サーバー) とフロントエンド (React アプリ) の両方を起動します。
2. サンプルクエリと使用方法。
次はエージェントのさらなるインテリジェント化
1. セマンティック検索機能を追加して、より洞察力のある推奨を可能にします。
2. 検索ロジックを Elasticsearch MCP (Model Context Protocol) サーバーに移動することで、動的クエリを有効にします。

要件

Node.js と npm : バックエンドとフロントエンドの両方が Node 上で実行されます。Node 18+ と npm v9+ (Node 18+ にバンドルされています) がインストールされていることを確認してください。
Elasticsearch クラスター:ローカルまたはクラウド上のアクティブな Elasticsearch クラスター。
OpenAI API キー: OpenAI 開発者ポータルのAPI キーページで生成します。

プロジェクト構造

ステップ1：プロジェクトの足場作り

まず、nba-ai-assistant-js ディレクトリを作成し、次のコマンドを使用して内部に移動します。

mkdir nba-ai-assistant-js && cd nba-ai-assistant-js

バックエンド:

次のコマンドで Mastra 作成ツールを使用します。

npx create-mastra@latest

2. ターミナルにいくつかのプロンプトが表示されます。最初のプロンプトでは、プロジェクトに backend という名前を付けます。

3. 次に、Mastra ファイルを保存するためのデフォルトの構造を維持するため、 src/を入力します。

4. 次に、デフォルトの LLM プロバイダーとして OpenAI を選択します。

5. 最後に、OpenAI API キーの入力が求められます。ここでは、スキップするオプションを選択し、後で .envファイルで提供します。

フロントエンド：

ルートディレクトリに戻り、次のコマンドを使用してVite 作成ツールを実行します。 npm create vite@latest frontend -- --template react

これにより、React 専用のテンプレートを使用して、 frontendという名前の軽量 React アプリが作成されます。

すべてがうまくいけば、プロジェクトディレクトリ内に、Mastra コードを保持するバックエンドディレクトリと、React アプリを含むfrontendディレクトリが表示されるはずです。

ステップ2: 環境変数の設定

機密キーを管理するために、 dotenvパッケージを使用して.envから環境変数を読み込みます。ファイル。バックエンドディレクトリに移動してdotenvをインストールします。

cd backend npm install dotenv --save

2. バックエンドディレクトリでは、適切な変数を入力するための example.env ファイルが提供されます。独自に作成する場合は、次の変数を必ず含めてください。

# OpenAI Configuration OPENAI_API_KEY=your_openai_api_key_here # Elasticsearch Configuration ELASTIC_ENDPOINT=your_elasticsearch_endpoint_here ELASTIC_API_KEY=your_elasticsearch_api_key_here

注意: .env .gitignoreに追加して、このファイルがバージョン管理から除外されていることを確認してください。

ステップ3: Elasticsearchの設定

まず、アクティブな Elasticsearch クラスターが必要です。次の 2 つのオプションがあります。

オプションA: Elasticsearch Cloudを使用する
- Elastic Cloudにサインアップ
- 新しいデプロイメントを作成する
- エンドポイント URL と API キー（エンコード済み）を取得します
オプションB: Elasticsearchをローカルで実行する
- Elasticsearchをローカルにインストールして実行する
- エンドポイントとして http://localhost:9200 を使用します
- APIキーを生成する

バックエンドに Elasticsearch クライアントをインストールする:

まず、バックエンドディレクトリに公式 Elasticsearch クライアントをインストールします。

npm install @elastic/elasticsearch

2. 次に、再利用可能な関数を保持するディレクトリ lib を作成し、そこに移動します。

mkdir lib && cd lib

3. 内部にelasticClient.jsという新しいファイルを作成します。このファイルは Elasticsearch クライアントを初期化し、プロジェクト全体で使用できるように公開します。

4. ECMAScript モジュール (ESM) を使用しているため、 __dirname and __ファイル名は使用できません。環境変数が.envから正しく読み込まれていることを確認するにはバックエンドフォルダー内のファイルで、ファイルの先頭に次の設定を追加します。

import { config } from 'dotenv'; import { fileURLToPath } from 'url'; import { dirname, join } from 'path'; import { Client } from '@elastic/elasticsearch'; // Grab current directory and load .env from backend folder const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); const envPath = join(__dirname, '../.env'); // Load environment variables from the correct path config({ path: envPath });

5. 次に、環境変数を使用して Elasticsearch クライアントを初期化し、接続を確認します。

//Elastic client Initialization, make sure environment variables are being loaded in correctly const config= { node: `${process.env.ELASTIC_ENDPOINT}`, auth: { apiKey: `${process.env.ELASTIC_API_KEY}`, }, }; export const elasticClient = new Client(config); //Check if the client is connected async function checkConnection() { try { const info = await elasticClient.info(); console.log('Elasticsearch is connected:', info); } catch (error) { console.error('Elasticsearch connection error:', error); } } checkConnection();

これで、このクライアントインスタンスを、Elasticsearch クラスターと対話する必要がある任意のファイルにインポートできます。

ステップ4: NBAデータをElasticsearchに一括取り込み

データセット:

このプロジェクトでは、リポジトリのbackend/dataディレクトリにあるデータセットを参照します。当社の NBA アシスタントは、このデータを知識ベースとして使用し、統計的な比較を実行し、推奨事項を生成します。

sample_player_game_stats.csv - サンプルプレーヤーのゲーム統計 (例: NBA キャリア全体におけるプレーヤーごとのゲームごとのポイント、リバウンド、スティールなど)。このデータセットを使用して集計を実行します。(注: これはデモ用に事前に生成された模擬データであり、公式 NBA ソースから取得されたものではありません。)
playerAndTeamInfo.js - 通常は API 呼び出しによって提供されるプレーヤーとチームのメタデータを置き換え、エージェントがプレーヤーとチームの名前を ID に一致できるようにします。サンプルデータを使用しているため、外部 API から取得する際のオーバーヘッドを避け、エージェントが参照できるいくつかの値をハードコードしました。

実装：

backend/libディレクトリで、 playerDataIngestion.jsという名前のファイルを作成します。
インポートを設定し、CSV ファイルパスを解決し、解析を設定します。ここでも、ESM を使用しているため、サンプル CSV へのパスを解決するには__dirnameを再構築する必要があります。また、 Node.jsの組み込みモジュールfsとreadlineを使用して、指定された CSV ファイルを行ごとに解析します。

import fs from 'fs'; import readline from 'readline'; import path from 'path'; import { fileURLToPath } from 'url'; import { elasticClient } from './elasticClient.js'; const indexName = 'sample-nba-player-data'; //Replace with your preferred index name //Since we are using ES modules __dirname and __filename don't exist, so this is a workaround that allows us to use the absolute file path for our sample data. const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const filePath = path.resolve(__dirname, '../data/sample_nba_data.csv');

これにより、一括取り込み手順で CSV を効率的に読み取って解析できるようになります。

3. 適切なマッピングを使用してインデックスを作成します。Elasticsearch は動的マッピングを使用してフィールドタイプを自動的に推測できますが、ここでは各統計が数値フィールドとして扱われるように明示的に指定します。これらのフィールドは後で集計に使用するため、これは重要です。また、ポイントやリバウンドなどの統計情報には、小数値が含まれるようにするために、タイプfloat を使用します。最後に、Elasticsearch が認識されないフィールドを動的にマッピングしないように、マッピングプロパティdynamic: 'strict'を追加します。

// Function to create an index with mappings async function createIndex() { try { // Check if the index already exists const exists = await elasticClient.indices.exists({ index: indexName }); if (exists) { console.log(`Index "${indexName}" already exists, deleting it now.`); await elasticClient.indices.delete({ index: indexName }); console.log(`Deleted index "${indexName}".`); } // Create the index with mappings const response = await elasticClient.indices.create({ index: indexName, body: { mappings: { dynamic: 'strict', // Prevent dynamic mapping properties: { game_id: { type: 'integer' }, game_date: { type: 'date' }, player_id: { type: 'integer' }, player_full_name: { type: 'text' }, player_team_id: { type: 'integer' }, player_team_name: { type: 'text' }, home_team: { type: 'boolean' }, opponent_team_id: { type: 'integer' }, opponent_team_name: { type: 'text' }, points: { type: 'float' }, rebounds: { type: 'float' }, assists: { type: 'float' }, steals: { type: 'float' }, blocks: { type: 'float' }, fg_percentage: { type: 'float' }, minutes_played: { type: 'float' }, }, }, }, }); console.log('Index created:', response); return true; } catch (error) { console.error('Error creating index:', error); return false; } }

4. CSV データを Elasticsearch インデックスに一括で取り込む機能を追加します。コードブロック内では、ヘッダー行をスキップします。次に、各行項目をコンマで分割し、ドキュメントオブジェクトにプッシュします。このステップでは、それらをクリーンアップし、適切なタイプであることを確認します。次に、ドキュメントをインデックス情報とともに bulkBody 配列にプッシュします。これは、Elasticsearch への一括取り込みのペイロードとして機能します。

async function bulkIngestCsv(filePath) { const readStream = fs.createReadStream(filePath); const rl = readline.createInterface({ input: readStream, crlfDelay: Infinity, }); const bulkBody = []; let lineNum = 0; //Skip the header line let headerLine = true; for await (const line of rl) { if (headerLine) { headerLine = false; continue; } lineNum++; // Split the line by comma and remove whitespace const [ game_id, game_date, player_id, player_full_name, player_team_id, player_team_name, home_team, opponent_team_id, opponent_team_name, points, rebounds, assists, steals, blocks, fg_percentage, minutes_played, ] = line.split(','); // Create a document object const document = { game_id: parseInt(game_id), game_date: game_date.trim(), player_id: parseInt(player_id), player_full_name: player_full_name.trim(), player_team_id: parseInt(player_team_id), player_team_name: player_team_name.trim(), home_team: home_team.trim() === 'True', // Converts True/False into a boolean opponent_team_id: parseInt(opponent_team_id), opponent_team_name: opponent_team_name.trim(), points: parseFloat(points), rebounds: parseFloat(rebounds), assists: parseFloat(assists), steals: parseFloat(steals), blocks: parseFloat(blocks), fg_percentage: parseFloat(fg_percentage), minutes_played: parseFloat(minutes_played), }; // Prepare the bulk operation format bulkBody.push({ index: { _index: indexName } }); bulkBody.push(document); } console.log(`Parsed ${lineNum} lines from CSV`);

5.次に、 elasticClient.bulk()で Elasticsearch のBulk API を使用して、1 回のリクエストで複数のドキュメントを取り込むことができます。以下のエラー処理は、取り込みに失敗したドキュメントの数と、取り込みに成功したドキュメントの数を示すように構成されています。

try { // Perform the bulk request const response = await elasticClient.bulk({ body: bulkBody }); if (response.errors) { console.log('Bulk Ingestion had some hiccups:'); // Count successful vs failed operations let successCount = 0; let errorCount = 0; const errorDetails = []; response.items.forEach((item, index) => { const operation = item.index || item.create || item.update || item.delete; if (operation.error) { errorCount++; errorDetails.push({ document: index + 1, error: operation.error, }); } else { successCount++; } }); console.log(`Successfully indexed: ${successCount} documents`); console.log(`Failed to index: ${errorCount} documents, here are the details`, errorDetails); } else { console.log(`Bulk Ingestion fully successful!`); } } catch (error) { console.error('Error performing bulk ingestion:', error); } }

6. 以下のmain()関数を実行して、 createIndex()関数とbulkIngestCsv()関数を順番に実行します。

// Run this function async function main() { const result = await createIndex(); if (!result) { console.error('Index setup failed. Aborting.'); return; } await bulkIngestCsv(filePath); console.log('Bulk ingestion completed!'); } main();

一括取り込みが成功したことを示すコンソールログが表示された場合は、Elasticsearch インデックスを簡単にチェックして、ドキュメントが実際に正常に取り込まれたかどうかを確認します。

ステップ5: Elasticsearchの集計の定義と統合

これらは、プレイヤーの統計を相互に比較するために AI エージェントのツールを定義するときに使用される主な関数になります。

1. backend/libディレクトリに移動し、 elasticAggs.jsというファイルを作成します。

2. 特定の対戦相手に対するプレイヤーの過去の平均を計算するには、以下のクエリを追加します。このクエリでは、2 つの条件（1 つはplayer_idに一致し、もう 1 つはopponent_team_idに一致する）を持つboolフィルターを使用して、関連するゲームのみを取得します。ドキュメントを返す必要はなく、集計のみを対象とするため、 size:0を設定します。aggsブロックでは、 points, rebounds, assists, steals, blocksやfg_percentageなどのフィールドに対して複数のメトリック集計を並行して実行し、平均値を計算します。LLM は計算で成功するか失敗するかのどちらかですが、このプロセスは Elasticsearch にオフロードされ、NBA AI アシスタントが正確なデータにアクセスできるようになります。

export async function getHistoricalAveragesAgainstOpponent(player_id, opponent_team_id) { try { //Query for Historical Averages const historicalQuery = await elasticClient.search({ index: 'sample-nba-player-data', size: 0, query: { bool: { must: [ { term: { player_id: { value: player_id, }, }, }, { term: { opponent_team_id: { value: opponent_team_id, }, }, }, ], }, }, aggs: { avg_points: { avg: { field: 'points' } }, avg_rebounds: { avg: { field: 'rebounds' } }, avg_assists: { avg: { field: 'assists' } }, avg_steals: { avg: { field: 'steals' } }, avg_blocks: { avg: { field: 'blocks' } }, avg_fg_percentage: { avg: { field: 'fg_percentage' } }, }, }); return { points: historicalQuery.aggregations.avg_points.value || 0, rebounds: historicalQuery.aggregations.avg_rebounds.value || 0, assists: historicalQuery.aggregations.avg_assists.value || 0, steals: historicalQuery.aggregations.avg_steals.value || 0, blocks: historicalQuery.aggregations.avg_blocks.value || 0, fgPercentage: historicalQuery.aggregations.avg_fg_percentage.value || 0, }; } catch (error) { console.error('Query error from getHistoricalAveragesAgainstOpponent function:', error); return { error: 'Queries failed in getting historical averages against opponent.' }; } }

3. 特定の対戦相手に対するプレーヤーのシーズン平均を計算するには、履歴クエリとほぼ同じクエリを使用します。このクエリの唯一の違いは、 boolフィルターにgame_dateの追加条件があることです。フィールドgame_dateは、現在の NBA シーズンの範囲内に収まる必要があります。この場合、範囲は2024-10-01から2025-06-30の間になります。以下の追加条件により、後続の集計で今シーズンのゲームのみが分離されることが保証されます。

{ range: { //Range for this season, change to match current season game_date: { gte: '2024-10-01', lte: '2025-06-30', }, },

ステップ6: プレーヤー比較ユーティリティ

コードをモジュール化して保守しやすい状態に保つために、メタデータヘルパー関数と Elasticsearch 集計を統合するユーティリティファイルを作成します。これにより、エージェントが使用するメインツールが強化されます。詳細は後述します。

1. backend/libディレクトリに新しいファイルcomparePlayers.jsを作成します。

2. 以下の関数を追加して、メタデータヘルパーと Elasticsearch 集約ロジックを、エージェントが使用するメインツールを強化する単一の関数に統合します。

import { playersByName } from '../data/playerAndTeamInfo.js'; import { teamsByName } from '../data/playerAndTeamInfo.js'; import { upcomingMatchups } from '../data/playerAndTeamInfo.js'; import { getHistoricalAveragesAgainstOpponent } from './elasticAggs.js'; import { getSeasonAveragesAgainstOpponent } from './elasticAggs.js'; //Simple helper functions to simulate API calls for player and team metadata. These reference the hardcoded values from playerAndTeamInfo.js in the data directory export function getPlayerInfo(playerFullName) { return playersByName[playerFullName]; } export function getTeamID(teamFullName) { return teamsByName[teamFullName]; } export function getUpcomingMatchups(teamId) { return upcomingMatchups[teamId]; } //Main function used by the 'playerComparisonTool' agent tool export async function comparePlayersForNextMatchup(player1Name, player2Name) { //Get Player Info const player1Info = getPlayerInfo(player1Name); const player2Info = getPlayerInfo(player2Name); //Get upcoming matchups const player1NextGame = getUpcomingMatchups(player1Info.team_id)[0]; const player2NextGame = getUpcomingMatchups(player2Info.team_id)[0]; //Get season and historical averages against next opponent for player 1 const player1SeasonAverages = await getSeasonAveragesAgainstOpponent( player1Info.player_id, player1NextGame.opponent_team_id ); const player1HistoricalAverages = await getHistoricalAveragesAgainstOpponent( player1Info.player_id, player1NextGame.opponent_team_id ); //Get season and historical averages against next opponent for player 2 const player2SeasonAverages = await getSeasonAveragesAgainstOpponent( player2Info.player_id, player2NextGame.opponent_team_id ); const player2HistoricalAverages = await getHistoricalAveragesAgainstOpponent( player2Info.player_id, player2NextGame.opponent_team_id ); const player1 = { name: player1Name, playerId: player1Info.player_id, teamId: player1Info.team_id, nextOpponent: { teamId: player1NextGame.opponent_team_id, teamName: player1NextGame.opponent_team_name, home: player1NextGame.home, }, stats: { seasonAverages: player1SeasonAverages, historicalAverages: player1HistoricalAverages, }, }; const player2 = { name: player2Name, playerId: player2Info.player_id, teamId: player2Info.team_id, nextOpponent: { teamId: player2NextGame.opponent_team_id, teamName: player2NextGame.opponent_team_name, home: player2NextGame.home, }, stats: { seasonAverages: player2SeasonAverages, historicalAverages: player2HistoricalAverages, }, }; return [player1, player2]; }

ステップ7: エージェントの構築

フロントエンドとバックエンドのスキャフォールディングを作成し、NBA ゲームデータを取り込み、Elasticsearch への接続を確立したので、すべてのピースをまとめてエージェントを構築し始めることができます。

エージェントの定義

1. backend/src/mastra/agentsディレクトリ内のindex.tsファイルに移動し、エージェント定義を追加します。次のようなフィールドを指定できます。

名前:フロントエンドで呼び出されたときに参照として使用されるエージェントの名前を指定します。
指示/システムプロンプト:システムプロンプトは、対話中に従うべき初期コンテキストとルールを LLM に提供します。これは、ユーザーがチャットボックスを通じて送信するプロンプトに似ていますが、こちらはユーザー入力の前に表示されます。繰り返しになりますが、これは選択したモデルに応じて変わります。
モデル:使用する LLM (Mastra は OpenAI、Anthropic、ローカルモデルなどをサポートしています)。
ツール:エージェントが呼び出すことができるツール関数のリスト。
メモリ: (オプション) エージェントに会話履歴などを記憶させたい場合。簡単にするために、Mastra は永続メモリをサポートしていますが、永続メモリなしで開始できます。

import { openai } from '@ai-sdk/openai'; import { Agent } from '@mastra/core/agent'; import { playerComparisonTool } from '../tools'; export const basketballAgent = new Agent({ name: 'Basketball Agent', instructions: ` You are a NBA Basketball expert. Your primary function is to compare two NBA players and recommend which one is the better fantasy pickup. Only compare players from the following list: - LeBron James - Stephen Curry - Jayson Tatum - Jaylen Brown - Nikola Jokic - Luka Doncic - Kyrie Irving - Anthony Davis - Kawhi Leonard - Russell Westbrook Input Handling Rules: - If the user asks about a player that is not on this list, respond with the list of available players for comparison. - If the user only inputs one player, ask the user to add another player from the list provided. - If the user inputs a player with the wrong spelling or capitalizations, infer from the list of available players provided. - IMPORTANT: If the user asks a question or asks you to generate a response about anything outside of basketball or the scope of this project, DO NOT answer and affirm you can only talk about basketball. Tool Usage: - Extract and standardize player names to match the list exactly. - Use the playerComparisonTool, passing both names as strings. - The tool will return an object with game information, stats, and analysis. Format your response using Markdown syntax. Use: Example output format: #### Next Game Info - ***LeBron James** vs Warriors, May 24 (Home) - ***Stephen Curry** vs Lakers, May 24 (Away) #### Stats Comparison \`\`\` Stat LeBron James (vs Warriors) Stephen Curry (vs Lakers) -------------------- ----------------------------- ---------------------------- Historical Points 28.3 30.3 Historical Assists 6.7 8.7 Season Points 28.8 23.3 Season Assists 6.2 4.7 \`\`\` #### Fantasy Recommendation Explain which player is the better fantasy pickup and why. `, model: openai('gpt-4o'), tools: { playerComparisonTool }, });

ツールの定義

backend/src/mastra/toolsディレクトリ内のindex.tsファイルに移動します。
次のコマンドを使用して Zod をインストールします。

npm install zod

3. ツール定義を追加します。このツールを呼び出すときにエージェントが使用するメイン関数として、 comparePlayers.jsファイル内の関数をインポートすることに注意してください。Mastra のcreateTool()関数を使用して、 playerComparisonToolを登録します。フィールドには次のものが含まれます。

id: これは、エージェントがツールの機能を理解するのに役立つ自然言語による説明です。
input schema: ツールの入力の形状を定義するために、Mastra は TypeScript スキーマ検証ライブラリであるZodスキーマを使用します。Zod は、エージェントが正しく構造化された入力を入力したことを確認し、入力構造が一致しない場合はツールが実行されないようにすることで役立ちます。
description: これは、エージェントがいつ電話をかけてツールを使用するかを理解するのに役立つ自然言語による説明です。
execute: ツールが呼び出されたときに実行されるロジック。私たちの場合、インポートしたヘルパー関数を使用してパフォーマンス統計を返します。

import { comparePlayersForNextMatchup } from '../../../lib/comparePlayers.js' import { createTool } from "@mastra/core/tools"; import { z } from "zod"; export const playerComparisonTool = createTool({ id: "Compare two NBA players", inputSchema: z.object({ player1:z.string(), player2:z.string() }), description: "Use this tool to compare two players given in the user prompt.", execute: async ({ context: { player1, player2 } }) => { return await comparePlayersForNextMatchup(player1, player2); }, })

CORSを処理するミドルウェアの追加

CORS を処理するために、Mastra サーバーにミドルウェアを追加します。人生には避けられないことが 3 つあると言われています。死、税金、そして Web 開発者にとっては CORS です。簡単に言うと、クロスオリジンリソース共有は、フロントエンドが別のドメインまたはポートで実行されているバックエンドにリクエストを送信するのをブロックするブラウザのセキュリティ機能です。バックエンドとフロントエンドの両方をローカルホストで実行しているにもかかわらず、それらは異なるポートを使用するため、CORS ポリシーがトリガーされます。バックエンドがフロントエンドからのリクエストを許可するように、 Mastra ドキュメントで指定されているミドルウェアを追加する必要があります。

1. backend/src/mastraディレクトリ内のindex.tsファイルに移動し、CORS の設定を追加します。

origin: ['http://localhost:5173']
- このアドレス（Vite のデフォルトアドレス）からのリクエストのみを許可します
allowMethods: ["GET", "POST"]
- 許可される HTTP メソッド。ほとんどの場合、POST が使用されます。
allowHeaders: ["Content-Type", "Authorization", "x-mastra-client-type, "x-highlight-request", "traceparent"],
- これらはリクエストで使用できるカスタムヘッダーを決定します

import { Mastra } from '@mastra/core/mastra'; import { basketballAgent } from './agents'; console.log('Starting Mastra server...'); export const mastra = new Mastra({ agents: { basketballAgent }, server:{ timeout: 10 * 60 * 1000, // 10 minutes cors: { origin: ['http://localhost:5173'], allowMethods: ["GET", "POST"], allowHeaders: [ "Content-Type", "Authorization", "x-mastra-client-type", "x-highlight-request", "traceparent", ], exposeHeaders: ["Content-Length", "X-Requested-With"], credentials: false, }, }, }); console.log('Mastra server configured.'); // Log after server configuration

ステップ8: フロントエンドの統合

この React コンポーネントは、 @ai-sdk/reactのuseChat()フックを使用して Mastra AI エージェントに接続するシンプルなチャットインターフェースを提供します。このフックを使用して、トークンの使用状況やツールの呼び出しを表示したり、会話をレンダリングしたりします。上記のシステムプロンプトでは、エージェントに応答をマークダウンで出力するように要求しているため、 react-markdownを使用して応答を適切にフォーマットします。

1.フロントエンドディレクトリにいる間に、useChat() フックを使用するために @ai-sdk/react パッケージをインストールします。

npm install @ai-sdk/react

2. 同じディレクトリで、React Markdown をインストールして、エージェントが生成する応答を適切にフォーマットできるようにします。

npm install react-markdown

3. useChat()を実装します。このフックは、フロントエンドと AI エージェントのバックエンド間のやり取りを管理します。メッセージの状態、ユーザー入力、ステータスを処理し、監視の目的でライフサイクルフックを提供します。渡すオプションは次のとおりです。

api: これは、Mastra AI エージェントのエンドポイントを定義します。デフォルトではポート 4111 に設定されており、ストリーミング応答をサポートするルートも追加する必要があります。
onToolCall: これは、エージェントがツールを呼び出すたびに実行されます。エージェントがどのツールを呼び出しているかを追跡するために使用します。
onFinish: エージェントが完全な応答を完了した後に実行されます。ストリーミングを有効にしても、 onFinish各チャンクの後ではなく、完全なメッセージが受信された後に実行されます。ここでは、トークンの使用状況を追跡するためにこれを使用しています。これは、LLM コストを監視して最適化するときに役立ちます。

4. 最後に、 frontend/componentsディレクトリのChatUI.jsxコンポーネントに移動して、会話を行うための UI を作成します。次に、エージェントからの応答を適切にフォーマットするために、応答をReactMarkdownコンポーネントでラップします。

import React, { useState } from 'react'; import { useChat } from '@ai-sdk/react'; import ReactMarkdown from 'react-markdown'; export default function ChatUI() { const [totalTokenUsage, setTotalTokenUsage] = useState(0); const [promptTokenUsage, setPromptTokenUsage] = useState(0); const [completionTokenUsage, setCompletionTokenUsage] = useState(0); const [toolsCalled, setToolsCalled] = useState([]); const { messages, input, handleInputChange, handleSubmit, status } = useChat({ api: 'http://localhost:4111/api/agents/basketballAgent/stream', //Replace with your own endpoint for your agent id: 'my-chat-session', //Optional parameter to check agent tool calls onToolCall: ({ toolCall }) => { setToolsCalled((prev) => [...prev, toolCall.toolName]); }, //Optional parameter to check token usages onFinish: (message, { usage }) => { setTotalTokenUsage((prev) => prev + usage.totalTokens); setPromptTokenUsage((prev) => prev + usage.promptTokens); setCompletionTokenUsage((prev) => prev + usage.completionTokens); }, //Optional parameter for error handling onError: (error) => { console.error('Agent error:', error); }, }); return (

What's My Agent Doing?

Tools Called:

{tool}
No tools called yet.

Prompt Token Usage: {promptTokenUsage}

Completion Token Usage: {completionTokenUsage}

Total Token Usage: {totalTokenUsage}

Conversation:

{messages.map((msg) => (

{msg.role === 'assistant' ? 'Basketbot' : 'You'}: {msg.content}

))}

); }

ステップ9: アプリケーションの実行

おめでとうございます！これでアプリケーションを実行する準備が整いました。バックエンドとフロントエンドの両方を起動するには、次の手順に従います。

ターミナルウィンドウで、ルートディレクトリからバックエンドディレクトリに移動し、Mastra サーバーを起動します。

cd backend npm run dev

2. 別のターミナルウィンドウで、ルートディレクトリからフロントエンドディレクトリに移動し、React アプリを起動します。

cd frontend npm run dev

3. ブラウザで次の場所に移動します。

http://localhost:5173

チャットインターフェースが表示されるはずです。次のサンプルプロンプトを試してみてください。

「レブロン・ジェームズとステフィン・カリーを比較」
「ジェイソン・テイタムとルカ・ドンチッチのどちらを選ぶべきでしょうか？」

次はエージェントのさらなるインテリジェント化

アシスタントをよりエージェント的にし、推奨事項をより洞察力のあるものにするために、次のイテレーションでいくつかの重要なアップグレードを追加する予定です。

NBAニュースのセマンティック検索

プレーヤーのパフォーマンスに影響を与える要因は数多くありますが、その多くは生の統計には表示されません。負傷報告、ラインナップの変更、さらには試合後の分析などは、ニュース記事でしか見つけることができません。この追加のコンテキストを捉えるために、エージェントが関連する NBA の記事を取得し、その内容を推奨事項に組み込めるよう、セマンティック検索機能を追加します。

Elasticsearch MCPサーバーによる動的検索

MCP (モデルコンテキストプロトコル) は、エージェントがデータソースに接続する方法の標準として急速に普及しつつあります。検索ロジックを Elasticsearch MCP サーバーに移行します。これにより、エージェントは、私たちが提供する定義済みの検索機能に頼るのではなく、動的にクエリを構築できるようになります。これにより、より自然な言語ワークフローを使用できるようになり、すべての検索クエリを手動で記述する必要性が軽減されます。Elasticsearch MCP サーバーとエコシステムの現在の状態の詳細については、こちらをご覧ください。

これらの変更はすでに進行中ですので、お楽しみに!

まとめ

このブログでは、JavaScript、Mastra、Elasticsearch を使用して、ファンタジーバスケットボールチームに合わせた推奨事項を提供するエージェント RAG アシスタントを構築しました。取り上げた内容:

エージェント RAG の基礎と、AI エージェントの自律性と RAG を効果的に使用するツールを組み合わせることで、より繊細で動的なエージェントを実現できる方法について説明します。
Elasticsearchとそのデータストレージ機能および強力なネイティブ集約により、それが LLM のナレッジベースとして優れたパートナーとなる理由について説明します。
Mastraフレームワークと、それが JavaScript エコシステムの開発者にとってこれらのエージェントの構築をどのように簡素化するかについて説明します。

あなたがバスケットボールの熱狂的なファンであっても、AI エージェントの構築方法を検討している方であっても、あるいは私のようにその両方であっても、このブログが、始めるための基礎を提供できれば幸いです。完全なリポジトリはGitHubで入手できます。自由にクローンして改良してください。さあ、ファンタジーリーグで優勝しましょう!

JavaScript で Elasticsearch を正しく使う方法、パート II

Jeffrey Rengifo — Mon, 19 May 2025 00:00:00 GMT

これは、JavaScript での Elasticsearch シリーズの第 2 部です。最初の部分では、環境を正しくセットアップし、Node.js クライアントを構成し、データをインデックスして検索する方法を学びました。この第 2 部では、実稼働のベストプラクティスを実装し、サーバーレス環境で Elasticsearch Node.jsクライアントを実行する方法を学習します。

以下を確認します:

ここで 例付きのソースコードを確認できます 。

制作のベストプラクティス

Elasticsearchにおけるエラー処理。

Node.js の Elasticsearch クライアントの便利な機能は、Elasticsearch で発生する可能性のあるエラーのオブジェクトを公開し、さまざまな方法で検証して処理できることです。

すべてを表示するには、次のコマンドを実行します。

const { errors } = require('@elastic/elasticsearch') console.log(errors)

検索の例に戻り、起こりうるエラーのいくつかを処理してみましょう。

app.get("/search/lexic", async (req, res) => { .... } catch (error) { if (error instanceof errors.ResponseError) { let errorMessage = "Response error!, query malformed or server down, contact the administrator!"; if (error.body.error.type === "parsing_exception") { errorMessage = "Query malformed, make sure mappings are set correctly"; } res.status(error.meta.statusCode).json({ erroStatus: error.meta.statusCode, success: false, results: null, error: errorMessage, }); } res.status(500).json({ success: false, results: null, error: error.message, }); } });

ResponseError 特に、回答が4xxまたは5xx場合に発生します。これは、要求が正しくないか、サーバーが利用できないことを意味します。

このタイプのエラーは、テキストタイプのフィールドで用語クエリを実行するなど、間違ったクエリを生成することでテストできます。

デフォルトエラー:

{ "success": false, "results": null, "error": "parsing_exception\n\tRoot causes:\n\t\tparsing_exception: [terms] query does not support [visit_details]" }

カスタマイズされたエラー:

{ "erroStatus": 400, "success": false, "results": null, "error": "Response error!, query malformed or server down; contact the administrator!" }

各タイプのエラーを特定の方法でキャプチャして処理することもできます。たとえば、 TimeoutErrorに再試行ロジックを追加できます。

app.get("/search/semantic", async (req, res) => { try { ... } catch (error) { if (error instanceof errors.TimeoutError) { // Retry logic... res.status(error.meta.statusCode).json({ erroStatus: error.meta.statusCode, success: false, results: null, error: "The request took more than 10s after 3 retries. Try again later.", }); } } });

テスト

テストはアプリの安定性を保証する上で重要です。Elasticsearch から分離された方法でコードをテストするには、クラスターを作成するときにライブラリelasticsearch-js-mock を使用できます。

このライブラリを使用すると、実際のクライアントと非常によく似たクライアントをインスタンス化できますが、クライアントの HTTP レイヤーのみをモックのレイヤーに置き換え、残りは元のレイヤーと同じにすることで、構成に応答します。

自動テスト用に、モックライブラリとAVAをインストールします。

npm install @elastic/elasticsearch-mock

npm install --save-dev ava

テストを実行するためにpackage.jsonファイルを構成します。次のようになっていることを確認してください:

"type": "module", "scripts": { "test": "ava" }, "devDependencies": { "ava": "^5.0.0" }

それでは、 test.jsファイルを作成し、モッククライアントをインストールしましょう。

const { Client } = require('@elastic/elasticsearch') const Mock = require('@elastic/elasticsearch-mock') const mock = new Mock() const client = new Client({ node: 'http://localhost:9200', Connection: mock.getConnection() })

次に、セマンティック検索のモックを追加します。

function createSemanticSearchMock(query, indexName) { mock.add( { method: "POST", path: `/${indexName}/_search`, body: { query: { semantic: { field: "semantic_field", query: query, }, }, }, }, () => { return { hits: { total: { value: 2, relation: "eq" }, hits: [ { _id: "1", _score: 0.9, _source: { owner_name: "Alice Johnson", pet_name: "Buddy", species: "Dog", breed: "Golden Retriever", vaccination_history: ["Rabies", "Parvovirus", "Distemper"], visit_details: "Annual check-up and nail trimming. Healthy and active.", }, }, { _id: "2", _score: 0.7, _source: { owner_name: "Daniel Kim", pet_name: "Mochi", species: "Rabbit", breed: "Mixed", vaccination_history: [], visit_details: "Nail trimming and general health check. No issues.", }, }, ], }, }; } ); }

これで、コードのテストを作成し、Elasticsearch 部分が常に同じ結果を返すことを確認できるようになりました。

import test from 'ava'; test("performSemanticSearch must return formatted results correctly", async (t) => { const indexName = "vet-visits"; const query = "Which pets had nail trimming?"; createSemanticSearchMock(query, indexName); async function performSemanticSearch(esClient, q, indexName = "vet-visits") { try { const result = await esClient.search({ index: indexName, body: { query: { semantic: { field: "semantic_field", query: q, }, }, }, }); return { success: true, results: result.hits.hits, }; } catch (error) { if (error instanceof errors.TimeoutError) { return { success: false, results: null, error: error.body.error.reason, }; } return { success: false, results: null, error: error.message, }; } } const result = await performSemanticSearch(esClient, query, indexName); t.true(result.success, "The search must be successful"); t.true(Array.isArray(result.results), "The results must be an array"); if (result.results.length > 0) { t.true( "_source" in result.results[0], "Each result must have a _source property" ); t.true( "pet_name" in result.results[0]._source, "Results must include the pet_name field" ); t.true( "visit_details" in result.results[0]._source, "Results must include the visit_details field" ); } });

テストを実行してみましょう。

npm run test

完了です！これからは、外部要因ではなくコードに100%重点を置いてアプリをテストできます。

サーバーレス環境

Elastic Serverlessでクライアントを実行する方法

クラウドまたはオンプレミスでの Elasticsearch の実行について説明しましたが、Node.js クライアントはElastic Cloud Serverlessへの接続もサポートしています。

Elastic Cloud Serverless を使用すると、Elastic がインフラストラクチャを内部で処理するためインフラストラクチャについて心配する必要がないプロジェクトを作成でき、インデックスを作成するデータとそのデータにアクセスする期間のみを考慮すれば済みます。

使用の観点から見ると、Serverless はコンピューティングとストレージを切り離し、検索とインデックス作成の両方に自動スケーリング機能を提供します。これにより、実際に必要なリソースのみを増やすことができます。

クライアントは、Serverless に接続するために次の調整を行います。

スニッフィングをオフにし、スニッフィング関連のオプションを無視します
最初のノードを除いて、config で渡されたすべてのノードを無視し、ノードのフィルタリングと選択のオプションも無視します。
圧縮と `TLSv1_2_method` を有効にします（Elastic Cloud 用に構成した場合と同じ）
すべてのリクエストに `elastic-api-version` HTTP ヘッダーを追加します
デフォルトでは `WeightedConnectionPool` ではなく `CloudConnectionPool` を使用します
標準の MIME タイプを優先して、ベンダーの `content-type` および `accept` ヘッダーをオフにします。

サーバーレスプロジェクトを接続するには、パラメーター serverMode: serverless を使用する必要があります。

const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'ELASTICSEARCH_ENDPOINT', auth: { apiKey: 'ELASTICSEARCH_API_KEY' }, serverMode: "serverless", });

Function-as-a-Service環境でクライアントを実行する方法

この例では Node.js サーバーを使用しましたが、AWS lambda、GCP Run などの機能を備えた Function-as-a-Service 環境を使用して接続することもできます。

'use strict' const { Client } = require('@elastic/elasticsearch') const client = new Client({ // client initialisation }) exports.handler = async function (event, context) { // use the client }

もう 1 つの例は、同じくサーバーレスである Vercel などのサービスに接続することです。これを実行する方法の完全な例を確認できますが、検索エンドポイントの最も重要な部分は次のようになります。

const response = await client.search( { index: INDEX, // You could directly send from the browser // the Elasticsearch's query DSL, but it will // expose you to the risk that a malicious user // could overload your cluster by crafting // expensive queries. query: { match: { field: req.body.text }, }, }, { headers: { Authorization: `ApiKey ${token}`, }, } );

このエンドポイントは /api フォルダーにあり、サーバー側から実行されるため、クライアントは検索用語に対応する「テキスト」パラメータのみを制御できます。

Function-as-a-Service を使用する意味は、24 時間 365 日稼働するサーバーとは異なり、関数は関数を実行するマシンのみを起動し、関数が終了するとマシンは休止モードになり、消費するリソースが少なくなることです。

この構成は、アプリケーションがあまり多くのリクエストを受け取らない場合には便利ですが、そうでない場合はコストが高くなる可能性があります。また、関数のライフサイクルと実行時間 (場合によっては数秒しかないこともあります) も考慮する必要があります。

まとめ

この記事では、実稼働環境で非常に重要なエラーの処理方法を学びました。また、Elasticsearch サービスをモックしながらアプリケーションをテストする方法についても説明しました。これにより、クラスターの状態に関係なく信頼性の高いテストが提供され、コードに集中できるようになります。

最後に、Elastic Cloud Serverless と Vercel アプリケーションの両方をプロビジョニングして、完全にサーバーレスなスタックを立ち上げる方法を示しました。

JavaScript で Elasticsearch を正しく使う方法、パート 1

Jeffrey Rengifo — Thu, 15 May 2025 00:00:00 GMT

これは、JavaScript で Elasticsearch を使用する方法を説明するシリーズの最初の記事です。このシリーズでは、JavaScript 環境で Elasticsearch を使用する方法の基本を学習し、検索アプリを作成するための最も関連性の高い機能とベストプラクティスを確認します。最後には、JavaScript を使用して Elasticsearch を実行するために必要なすべてのことを理解できるようになります。

この最初の部分では、次の点を確認します。

ここで 例付きのソースコードを確認できます 。

Elasticsearch Node.js クライアントとは何ですか?

Elasticsearch Node.js クライアントは、Elasticsearch API からの HTTP REST 呼び出しを JavaScript に配置する JavaScript ライブラリです。これにより、処理が容易になり、ドキュメントのインデックス作成などのタスクを一括で簡素化するヘルパーが利用できるようになります。

環境

フロントエンド、バックエンド、それともサーバーレス？

JavaScript クライアントを使用して検索アプリを作成するには、Elasticsearch クラスターとクライアントを実行する JavaScript ランタイムという少なくとも 2 つのコンポーネントが必要です。

JavaScript クライアントはすべての Elasticsearch ソリューション (クラウド、オンプレミス、サーバーレス) をサポートしており、クライアントがすべてのバリエーションを内部で処理するため、ソリューション間に大きな違いはありません。そのため、どれを使用するかについて心配する必要はありません。

ただし、JavaScript ランタイムはブラウザから直接ではなく、サーバーから実行する必要があります。

これは、ブラウザから Elasticsearch を呼び出すと、ユーザーがクラスター API キー、ホスト、クエリ自体などの機密情報を取得する可能性があるためです。Elasticsearch では、クラスターをインターネットに直接公開せず、このすべての情報を抽象化する中間層を使用して、ユーザーがパラメータのみを確認できるようにすることを推奨しています。このトピックの詳細については、ここをご覧ください。

次のようなスキーマを使用することをお勧めします。

この場合、クライアントは検索用語とサーバーの認証キーのみを送信し、サーバーはクエリと Elasticsearch との通信を完全に制御します。

クライアントの接続

まず、次の手順に従って API キーを作成します。

前の例に従って、シンプルな Express サーバーを作成し、Node.JS サーバーからのクライアントを使用してそのサーバーに接続します。

NPM を使用してプロジェクトを初期化し、Elasticsearch クライアントとExpress をインストールします。後者は、Node.js でサーバーを起動するためのライブラリです。Express を使用すると、HTTP 経由でバックエンドと対話できます。

プロジェクトを初期化しましょう:

npm init -y

依存関係をインストールします:

npm install @elastic/elasticsearch express split2 dotenv

詳しく説明しましょう:

@elastic/elasticsearch : 公式Node.jsクライアントです
express : 軽量なNode.jsサーバーを立ち上げてElasticsearchを公開できるようになります
split2 : テキスト行をストリームに分割します。ndjsonファイルを1行ずつ処理するのに便利です
dotenv : .env を使用して環境変数を管理できるようにしますファイル

.envを作成するプロジェクトのルートにあるファイルを作成し、次の行を追加します。

ELASTICSEARCH_ENDPOINT="Your Elasticsearch endpoint" ELASTICSEARCH_API_KEY="Your Elasticssearch API"

この方法では、 dotenvパッケージを使用してこれらの変数をインポートできます。

server.jsファイルを作成します:

このコードは、ポート 3000 をリッスンし、認証用の API キーを使用して Elasticsearch クラスターに接続する基本的な Express.js サーバーをセットアップします。これには、GET リクエストを介してアクセスすると、Elasticsearch クライアントの.info()メソッドを使用して Elasticsearch クラスターに基本情報を照会する /ping エンドポイントが含まれています。

クエリが成功した場合は、クラスター情報が JSON 形式で返され、それ以外の場合はエラーメッセージが返されます。サーバーは、JSON リクエスト本体を処理するために body-parser ミドルウェアも使用します。

ファイルを実行してサーバーを起動します。

node server.js

答えは次のようになるはずです:

Server running on port 3000

それでは、エンドポイント/pingを参照して、Elasticsearch クラスターのステータスを確認しましょう。

curl http://localhost:3000/ping { "success": true, "clusterInfo": { "name": "instance-0000000000", "cluster_name": "61b7e19eec204d59855f5e019acd2689", "cluster_uuid": "BIfvfLM0RJWRK_bDCY5ldg", "version": { "number": "9.0.0", "build_flavor": "default", "build_type": "docker", "build_hash": "112859b85d50de2a7e63f73c8fc70b99eea24291", "build_date": "2025-04-08T15:13:46.049795831Z", "build_snapshot": false, "lucene_version": "10.1.0", "minimum_wire_compatibility_version": "8.18.0", "minimum_index_compatibility_version": "8.0.0" }, "tagline": "You Know, for Search" } }

文書のインデックス作成

接続すると、セマンティック検索用のsemantic_textやフルテキストクエリ用の text などのマッピングを使用してドキュメントのインデックスを作成できます。これら 2 つのフィールドタイプを使用すると、ハイブリッド検索も実行できます。

マッピングを生成し、ドキュメントをアップロードするために、新しいload.jsファイルを作成します。

Elasticsearchクライアント

まずクライアントをインスタンス化して認証する必要があります。

const { Client } = require("@elastic/elasticsearch"); const ELASTICSEARCH_ENDPOINT = "cluster/project_endpoint"; const ELASTICSEARCH_API_KEY = "apiKey"; const esClient = new Client({ node: ELASTICSEARCH_ENDPOINT, auth: { apiKey: ELASTICSEARCH_API_KEY }, });

セマンティックマッピング

動物病院に関するデータを含むインデックスを作成します。飼い主様、ペット様、訪問の詳細に関する情報を保存します。

名前や説明など、全文検索を実行するデータはテキストとして保存されます。動物の種や品種などのカテゴリのデータは、キーワードとして保存されます。

さらに、すべてのフィールドの値を semantic_text フィールドにコピーして、その情報に対してもセマンティック検索を実行できるようにします。

バルクヘルパー

クライアントのもう 1 つの利点は、一括ヘルパーを使用してインデックスを一括で作成できることです。バルクヘルパーを使用すると、同時実行、再試行、関数を通過して成功または失敗した各ドキュメントの処理などを簡単に処理できます。

このヘルパーの魅力的な機能は、ストリームを操作できることです。この機能を使用すると、ファイル全体をメモリに保存して Elasticsearch に一度に送信するのではなく、ファイルを 1 行ずつ送信できます。

Elasticsearch にデータをアップロードするには、プロジェクトのルートに data.ndjson というファイルを作成し、以下の情報を追加します (または、ここからデータセットを含むファイルをダウンロードすることもできます)。

{"owner_name":"Alice Johnson","pet_name":"Buddy","species":"Dog","breed":"Golden Retriever","vaccination_history":["Rabies","Parvovirus","Distemper"],"visit_details":"Annual check-up and nail trimming. Healthy and active."} {"owner_name":"Marco Rivera","pet_name":"Milo","species":"Cat","breed":"Siamese","vaccination_history":["Rabies","Feline Leukemia"],"visit_details":"Slight eye irritation, prescribed eye drops."} {"owner_name":"Sandra Lee","pet_name":"Pickles","species":"Guinea Pig","breed":"Mixed","vaccination_history":[],"visit_details":"Loss of appetite, recommended dietary changes."} {"owner_name":"Jake Thompson","pet_name":"Luna","species":"Dog","breed":"Labrador Mix","vaccination_history":["Rabies","Bordetella"],"visit_details":"Mild ear infection, cleaning and antibiotics given."} {"owner_name":"Emily Chen","pet_name":"Ziggy","species":"Cat","breed":"Mixed","vaccination_history":["Rabies","Feline Calicivirus"],"visit_details":"Vaccination update and routine physical."} {"owner_name":"Tomás Herrera","pet_name":"Rex","species":"Dog","breed":"German Shepherd","vaccination_history":["Rabies","Parvovirus","Leptospirosis"],"visit_details":"Follow-up for previous leg strain, improving well."} {"owner_name":"Nina Park","pet_name":"Coco","species":"Ferret","breed":"Mixed","vaccination_history":["Rabies"],"visit_details":"Slight weight loss; advised new diet."} {"owner_name":"Leo Martínez","pet_name":"Simba","species":"Cat","breed":"Maine Coon","vaccination_history":["Rabies","Feline Panleukopenia"],"visit_details":"Dental cleaning. Minor tartar buildup removed."} {"owner_name":"Rachel Green","pet_name":"Rocky","species":"Dog","breed":"Bulldog Mix","vaccination_history":["Rabies","Parvovirus"],"visit_details":"Skin rash, antihistamines prescribed."} {"owner_name":"Daniel Kim","pet_name":"Mochi","species":"Rabbit","breed":"Mixed","vaccination_history":[],"visit_details":"Nail trimming and general health check. No issues."}

バルクヘルパーがファイル行を Elasticsearch に送信する間、split2 を使用してファイル行をストリーミングします。

const { createReadStream } = require("fs"); const split = require("split2"); const indexData = async (filePath, indexName) => { try { console.log(`Indexing data from ${filePath} into ${indexName}...`); const result = await esClient.helpers.bulk({ datasource: createReadStream(filePath).pipe(split()), onDocument: () => { return { index: { _index: indexName }, }; }, onDrop(doc) { console.error("Error processing document:", doc); }, }); console.log("Bulk indexing successful elements:", result.items.length); } catch (error) { console.error("Error indexing data:", error); throw error; } }; await indexData("./data.ndjson", INDEX_NAME);

上記のコードは.ndjsonを読み取りますファイルを 1 行ずつ読み込み、 helpers.bulkメソッドを使用して各 JSON オブジェクトを指定された Elasticsearch インデックスに一括インデックスします。createReadStreamとsplit2を使用してファイルをストリーミングし、各ドキュメントのインデックスメタデータを設定し、処理に失敗したドキュメントをログに記録します。完了すると、正常にインデックスが作成されたアイテムの数を記録します。

indexData関数を使用する代わりに、Kibana を使用して UI 経由でファイルを直接アップロードし、データファイルのアップロード UI を使用することもできます。

ファイルを実行して、ドキュメントを Elasticsearch クラスターにアップロードします。

node load.js

Creating mappings for index vet-visits... Index created successfully: { acknowledged: true, shards_acknowledged: true, index: 'vet-visits' } Indexing data from ./data.ndjson into vet-visits... Bulk indexing completed. Total documents: 10, Failed: 0

Elasticsearchでのデータ検索

server.jsファイルに戻って、語彙検索、セマンティック検索、ハイブリッド検索を実行するためのさまざまなエンドポイントを作成します。

簡単に言えば、これらのタイプの検索は相互に排他的ではありませんが、回答する必要がある質問の種類によって異なります。

クエリタイプ

使用事例

例題

語彙クエリ

質問内の単語または語根は、索引文書に表示される可能性があります。質問とドキュメント間のトークンの類似性。

青いスポーツTシャツを探しています。

セマンティッククエリ

質問内の単語は文書には表示されない可能性があります。質問とドキュメント間の概念的な類似性。

寒い季節用の服を探しています。

ハイブリッド検索

質問には語彙や意味の要素が含まれています。質問とドキュメント間のトークンと意味の類似性。

ビーチでの結婚式用にSサイズのドレスを探しています。

質問の語彙部分はタイトルや説明、またはカテゴリ名の一部である可能性が高く、意味部分はそれらの分野に関連する概念です。青はおそらくカテゴリ名または説明の一部であり、ビーチウェディングはそうではないかもしれませんが、意味的にはリネンの衣服に関連している可能性があります。

語彙クエリ (/search/lexic?q=)

語彙検索 (フルテキスト検索とも呼ばれる) とは、トークンの類似性に基づいて検索することを意味します。つまり、分析後、検索内のトークンを含むドキュメントが返されます。

語彙検索の実践チュートリアルは、こちらでご覧いただけます。

app.get("/search/lexic", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, size: 5, body: { query: { multi_match: { query: q, fields: ["owner_name", "pet_name", "visit_details"], }, }, }, }); res.status(200).json({ success: true, results: result.hits.hits }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

爪切りでテストする

curl http://localhost:3000/search/lexic?q=nail%20trimming

答え：

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 2.7075968, "_source": { "pet_name": "Mochi", "owner_name": "Daniel Kim", "species": "Rabbit", "visit_details": "Nail trimming and general health check. No issues.", "breed": "Mixed", "vaccination_history": [] } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 2.560356, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } } ] }

セマンティッククエリ (/search/semantic?q=)

セマンティック検索は、語彙検索とは異なり、ベクトル検索を通じて検索用語の意味に類似した結果を見つけます。

セマンティック検索の実践チュートリアルは、こちらでご覧いただけます。

app.get("/search/semantic", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, size: 5, body: { query: { semantic: { field: "semantic_field", query: q }, }, }, }); res.status(200).json({ success: true, results: result.hits.hits, }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

テスト対象:誰がペディキュアをしましたか?

curl http://localhost:3000/search/semantic?q=Who%20got%20a%20pedicure?

答え：

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 4.861466, "_source": { "owner_name": "Daniel Kim", "pet_name": "Mochi", "species": "Rabbit", "breed": "Mixed", "vaccination_history": [], "visit_details": "Nail trimming and general health check. No issues." } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 4.7152824, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } }, { "_index": "vet-visits", "_id": "9RY6RJYBLe2GoFQ6-9n9", "_score": 1.6717153, "_source": { "pet_name": "Rex", "owner_name": "Tomás Herrera", "species": "Dog", "visit_details": "Follow-up for previous leg strain, improving well.", "breed": "German Shepherd", "vaccination_history": [ "Rabies", "Parvovirus", "Leptospirosis" ] } }, { "_index": "vet-visits", "_id": "9xY6RJYBLe2GoFQ6-9n9", "_score": 1.5600781, "_source": { "pet_name": "Simba", "owner_name": "Leo Martínez", "species": "Cat", "visit_details": "Dental cleaning. Minor tartar buildup removed.", "breed": "Maine Coon", "vaccination_history": [ "Rabies", "Feline Panleukopenia" ] } }, { "_index": "vet-visits", "_id": "-BY6RJYBLe2GoFQ6-9n9", "_score": 1.2696637, "_source": { "pet_name": "Rocky", "owner_name": "Rachel Green", "species": "Dog", "visit_details": "Skin rash, antihistamines prescribed.", "breed": "Bulldog Mix", "vaccination_history": [ "Rabies", "Parvovirus" ] } } ] }

ハイブリッドクエリ (/search/hybrid?q=)

ハイブリッド検索により、セマンティック検索と語彙検索を組み合わせることができるため、両方の長所を活用できます。つまり、トークンによる検索の精度と、セマンティック検索の意味の近似性の両方が得られます。

app.get("/search/hybrid", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, body: { retriever: { rrf: { retrievers: [ { standard: { query: { bool: { must: { multi_match: { query: q, fields: ["owner_name", "pet_name", "visit_details"], }, }, }, }, }, }, { standard: { query: { bool: { must: { semantic: { field: "semantic_field", query: q, }, }, }, }, }, }, ], }, }, size: 5, }, }); res.status(200).json({ success: true, results: result.hits.hits, }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

「ペディキュアや歯科治療を受けた人はいますか？」という質問をしてテストします。

curl http://localhost:3000/search/hybrid?q=who%20got%20a%20pedicure%20or%20dental%20treatment

対応：

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "9xY6RJYBLe2GoFQ6-9n9", "_score": 0.032522473, "_source": { "pet_name": "Simba", "owner_name": "Leo Martínez", "species": "Cat", "visit_details": "Dental cleaning. Minor tartar buildup removed.", "breed": "Maine Coon", "vaccination_history": [ "Rabies", "Feline Panleukopenia" ] } }, { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 0.016393442, "_source": { "pet_name": "Mochi", "owner_name": "Daniel Kim", "species": "Rabbit", "visit_details": "Nail trimming and general health check. No issues.", "breed": "Mixed", "vaccination_history": [] } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 0.015873017, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } }, { "_index": "vet-visits", "_id": "9RY6RJYBLe2GoFQ6-9n9", "_score": 0.015625, "_source": { "pet_name": "Rex", "owner_name": "Tomás Herrera", "species": "Dog", "visit_details": "Follow-up for previous leg strain, improving well.", "breed": "German Shepherd", "vaccination_history": [ "Rabies", "Parvovirus", "Leptospirosis" ] } }, { "_index": "vet-visits", "_id": "8xY6RJYBLe2GoFQ6-9n9", "_score": 0.015384615, "_source": { "pet_name": "Luna", "owner_name": "Jake Thompson", "species": "Dog", "visit_details": "Mild ear infection, cleaning and antibiotics given.", "breed": "Labrador Mix", "vaccination_history": [ "Rabies", "Bordetella" ] } } ] }

まとめ

このシリーズの最初の部分では、クライアント/サーバーのベストプラクティスに従って、環境を設定し、さまざまな検索エンドポイントを持つサーバーを作成し、Elasticsearch ドキュメントをクエリする方法を説明しました。シリーズのパート 2では、本番環境のベストプラクティスと、サーバーレス環境で Elasticsearch Node.js クライアントを実行する方法について学習します。