Jeffrey Rengifo - Elasticsearch Labs

Elasticsearchの検索再現率を測定・改善する方法：ハイブリッド検索で0.43から0.75へ

Jeffrey Rengifo — Mon, 04 May 2026 00:00:00 GMT

BM25ランキングアルゴリズムを用いた語彙検索は、低コストで高速であり、幅広いクエリに対して非常に効果的です。しかし盲点があります。それは、ドキュメントとトークンを共有しないクエリです。この記事では、BM25が足りないところを正確に測定します。Elasticsearchのランキング評価API（rank_eval）を使用し、Elastic Inference Service（EIS）を介してJina AIの埋め込みを追加することでそのギャップを埋めます。再現率スコアが 0.43 から 0.75 に上がるのを見て、その理由がわかるでしょう。

リコールとは何ですか？

再現率は、0から1のスケールで、ユーザーが実際に欲しいドキュメントが検索結果にどれだけ含まれているかを測定します。クエリで3点の製品が表示されるはずなのに、検索結果の上位10位に2つしか表示されない場合は、そのクエリの再現率はrecall@10 = 0.67となります。これは集合ベースの指標であり、そのk件の結果内の関連ドキュメントの位置は考慮されません。10番目の位置にある関連ドキュメントは、1番目の位置にある関連ドキュメントと同じものとして扱われます。再現率が高いということは、関連性の高い検索結果を見逃さないということです。

この図は2つの集合を示しています。1つは関連するすべてのドキュメント（左側）、もう1つはBM25が実際に取得したドキュメント（上位10件、右側）です。再現率に影響する交差部分、prod_1とprod_2が見つかり、prod_3、prod_4、prod_6は完全に見落とされました。結果：Recall@10 = 2/5 = 0.40。

要件

再現率がどのように機能するのかをよりよく理解するために、本題に入りましょう。このデモンストレーションではPythonを使用します。付属のノートブック（notebook.ipynb）で一緒に進めることができます。すべてのコードブロックは、実行準備が整ったセルです。

提供されたコードでは、以下を使用しています。

Elasticsearch 9.3以降
Python 3.10+

pip install elasticsearch pandas plotly python-dotenv

Elasticsearchの認証情報が含まれる.envファイル

ELASTICSEARCH_URL=https://your-cluster-url ELASTICSEARCH_API_KEY=your-api-key

データセット

靴、電子機器、工具など、さまざまなカテゴリーにわたる1,000点の製品を掲載した製品カタログを使用します。

各ドキュメントには4つのフィールドがあります。

フィールド

タイプ

`タイトル`

テキスト

`description`

テキスト

`ブランド`

キーワード

`category`

キーワード

データセットは dataset.csvから読み込まれます。

語彙検索の力と限界

BM25は、Elasticsearchおよびほとんどの検索エンジンのデフォルトのランキングアルゴリズムです。ドキュメントは、クエリ用語がどれだけ頻繁に出現するかによってスコアリングされます。これは、ドキュメントの長さと、インデックス全体でのそれらの用語の頻度に合わせて調整されます。さらに、小文字への正規化、語幹抽出、ストップワード除去といったアナライザーも搭載されています。「running shoes」というクエリは、「Running Shoes」と一致し、おそらく「run」とも一致します。

これは、多くの種類のクエリに対して有効です。

「running shoes」はタイトルにこれらのトークンを含む商品を即座にマッチングします。
「Bluetoothスピーカー」は、トークンが逐語的に表示されるため、携帯オーディオ製品として表示されます。

結果は決定論的で説明可能です。つまり、検索クエリに含まれる用語がドキュメント中に含まれているからこそ、そのドキュメントは上位にランク付けされるのです。関連性のデバッグは単純明快です。

問題が発生する箇所

では、同じカタログに対してこれらのクエリを試してみましょう。

「スキンケアルーティン」：どの製品名にも「ルーティン」という単語は含まれません。BM25は、「スキンケア」で部分一致することができますが、フェイス美容液、ボディオイル、モイスチャライザーは、「ビタミンC」、「レチノール」、または「ブライトニング」のような用語を使用して説明されており、いずれもクエリと重複しません。完全なスキンケアルーティンを形成する製品は、共通のトークンを持たずにインデックス全体に散らばっています。

ID: B06XX6DS3P, Score: 9.0552, Title: Replenix Retinol Smooth + Tighten Body Lotion - Collagen-Boosting, Regenerating Anti-Aging Body Cream, Reduces Appearance of Stretch Marks, 6.7 oz. ID: B08XMPKJ1L, Score: 5.2699, Title: Bio-Oil Skincare Body Oil (Natural) Serum for Scars and Stretchmarks, Face and Body Moisturizer Hydrates Skin, with Organic Jojoba Oil and Vitamin E, For All Skin Types, 6.7 oz ID: B01CY764KQ, Score: 5.0057, Title: Nike Up Or Down Men Deodorant - Pack of 2 | Long-Lasting Fragrance, Body Spray Combo for Men | Deodorant for Active Living | Nike Men's Deo Set | Ultimate Odor Protection | Grooming Essentials | Signature Nike Scent | High-Performance Men's Deodorant

「ペット用旅行用品」：これはユースケースのグループ分けであり、製品カテゴリではありません。犬用スリングキャリア、ペット用カーシート、旅行用クレートはどれも関連性のあるアイテムですが、それらの説明文は「旅行用品」というよりは、携帯性、安全性、快適性について述べています。BM25は「ペット」と大まかに一致しますが、旅行固有の商品を他のペットカタログと区別するシグナルはありません。

ID: B0BVV7BKTW, Score: 7.4371, Title: Large Foldable Travel Duffel Bag with Shoes Compartment ID: B07TNPHYNV, Score: 6.6455, Title: 40 Pieces Christmas Bronze Jingle Bells Craft Small Bells ID: B08R8FRW53, Score: 6.6335, Title: CUBY Dog and Cat Sling Carrier ID: B08QMCQYGM, Score: 6.5259, Title: YTFGGY Whiteboard Pinstripe Tape 6 Rolls 1/8" ID: B0CP3LQSWM, Score: 6.2994, Title: Portable Dog Water Bottle 32 Oz

これは 再現率の問題です。関連するドキュメントはインデックスに存在しますが、ユーザーの言葉と文書の単語が十分に一致しないため、BM25はそれらを見つけることができません。

同義語を追加することは、既知の事例に役立ちますが、ユーザーが意図を表現するすべての方法を列挙することはできません。そこでベクトルが役立ちます。

リコールを測定すべき理由

問題を解決する前に、まずそれを定量化する必要があります。

Recall@kは、ユーザーが実際に求めているドキュメントのうち、検索結果に表示されるドキュメントの数を測定します。正式には：

Recall@k = (relevant documents found in top k) / (total relevant documents)

Precision@kは、上位k件の結果のうち、実際にどれだけ関連性があるかを測定します。

Precision@k = (relevant documents in top k) / k

高精度とは、得られる結果が良好であることを意味します。電子商取引においては、関連商品を見落とすこと（再現率の低さ）は、多少不完全な結果を表示すること（精度の低さ）よりも深刻です。なぜなら、商品が表示されないということは、販売機会の損失を意味するからです。

Elasticsearchのrank_eval APIは、両方を体系的に測定できます。それぞれに評価されたドキュメントを含むクエリのリストを提供すると、Elasticsearchがすべてのクエリのメトリックを計算します。

評価の設定

rank_eval APIには評価データセットが必要です。これは、クエリとそれに関連するドキュメントのマッピング、および関連性グレード（0 = 関連性なし、1 = 関連性あり、2 = 非常に関連性あり）で構成されます。

ノートブックでは、これは判断リストです。

judgments = [ # Query 1: "running shoes" BM25 handles well (tokens appear in product titles) {"query_id": "q1", "doc_id": "B09NQJFRW6", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B08JMD4LMM", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B08VRJ6F2Q", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B07S8NRRWR", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B01HD620I8", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B07DX86321", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B0968YVLQ8", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B093QJ39ZS", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B096FGSC39", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B01GVQWVV2", "grade": 1, "query": "running shoes"}, # Query 2: "skincare routine" intent-based, "routine" never appears in product titles {"query_id": "q2", "doc_id": "B08XMPKJ1L", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B0BN3WQB92", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B0BT7B7P5T", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B00NPA2WEY", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B06XX6DS3P", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B07PDRD1KT", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B074J7869B", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B08JV31QW4", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B00K3TVJMQ", "grade": 1, "query": "skincare routine"}, # Query 3: "study desk setup" intent-based, products are desks/stands/organizers {"query_id": "q3", "doc_id": "B08CS35J2T", "grade": 2, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B09B3LFDXJ", "grade": 2, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B07W58LMND", "grade": 1, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B0CHYDX91L", "grade": 1, "query": "study desk setup"}, # Query 4: "pet travel accessories" use-case grouping, products are carriers/crates/seats {"query_id": "q4", "doc_id": "B08R8FRW53", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B01MYUYX33", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B003C5RKE4", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B09GF8GBF6", "grade": 1, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B0CP3LQSWM", "grade": 1, "query": "pet travel accessories"}, ]

この組み合わせは意図的なものです。 q1はBM25が適切に処理するクエリ（製品タイトル内の正確なトークン）であり、 q2 、 q3 、 q4はユーザーの意図が特定の製品キーワードではなく概念として表現されるインテントベースのクエリです。

BM25ベースライン再現率の測定

まず、Elasticsearchクライアントを設定し、生のテキストデータをインデックス化します。

import os import json import pandas as pd import plotly.graph_objects as go from elasticsearch import Elasticsearch, helpers from dotenv import load_dotenv load_dotenv() es = Elasticsearch( os.getenv("ELASTICSEARCH_URL"), api_key=os.getenv("ELASTICSEARCH_API_KEY") ) INDEX_NAME = "ecommerce-products"

次にBM25のrank_evalリクエストを作成しましょう。リスト内の各リクエストは、クエリとその評価を組み合わせたものです。

judgments_df = pd.DataFrame(judgments) bm25_requests = [] for query_id, query_text in ( judgments_df[["query_id", "query"]].drop_duplicates().values ): relevant_docs = judgments_df[judgments_df["query_id"] == query_id] ratings = [ {"_index": INDEX_NAME, "_id": row["doc_id"], "rating": row["grade"]} for _, row in relevant_docs.iterrows() ] bm25_requests.append({ "id": query_id, "request": { "query": { "multi_match": { "query": query_text, "fields": ["title", "description"] } } }, "ratings": ratings, }) bm25_eval = { "requests": bm25_requests, "metric": {"recall": {"k": 10, "relevant_rating_threshold": 1}}, } bm25_result = es.rank_eval(index=INDEX_NAME, body=bm25_eval) print("BM25 Recall@10:", bm25_result.body["metric_score"])

次の結果が得られます。

BM25 Recall@10: 0.43

0.43 は、4つのクエリすべてで、BM25が見つけるべきドキュメントの43%しか見つけられないということです。不足している点は、意図に基づくクエリに集中している。「スキンケアルーティン」という検索では、「ルーティン」が製品タイトルに含まれていないため、フェイス美容液やボディオイルが見つかりません。また、「ペット用旅行用品」という検索では、旅行用品ではなく携帯性や安全性の観点から説明されているキャリーケースやクレートが見つからない一方で、関連性のないペット用品が検索結果に表示されます。

これがベースラインです。これで、破るべき数値ができました。

Jina埋め込みを用いたベクトル検索機能の追加

Vector search はドキュメントとクエリを高次元ベクトルとしてエンコードします。高次元ベクトルとは、数百または数千の数値から構成されるベクトルの一種で、各数値はそれが表すデータの特定の特徴をエンコードします。意味が似ているドキュメントは、たとえ共通の単語が一つもなくても、ベクトル空間上では互いに近い位置に配置されます。「ジム器具」と「ダンベルセット」は、概念が関連しているため、近くに配置されるでしょう。私がベクトルデータベースとしてElasticsearchを選んだ理由は、ハイブリッド検索をサポートしており、セマンティックな理解とキーワードの精度をすぐに実現できるからです。

EISには、推論APIを通じてモデル埋め込みを標準でサポートする機能が含まれています。

ステップ1：Jina埋め込みv5を推論エンドポイントとして使用する

INFERENCE_ENDPOINT_ID = ".jina-embeddings-v5-text-small"

クラスターにGPUリソースがある場合（Elastic CloudおよびElasticsearch 9.3以降で利用可能）、埋め込みはGPU上で生成されます。これはCPU推論よりも大幅に高速であり、従来、大規模な環境でベクトル処理を高価にしていたパフォーマンスのトレードオフを解消します。

なぜJina埋め込みが特に重要なのでしょうか。JINA-embeddings-v5-textは、32,000トークンのコンテキストウィンドウを持ち、タスク固有の Low-Rank Adaptation (LoRA) アダプターをサポートする多言語モデル（119言語以上に対応）です。短い商品説明であれば、そのままでも十分に機能します。jina-embeddings-v5-textモデルの詳細についてはこちらをご覧ください。

ステップ2：セマンティックフィールドを持つインデックスを作成

index_mappings = { "mappings": { "properties": { "title": {"type": "text", "copy_to": "semantic_field"}, "description": {"type": "text", "copy_to": "semantic_field"}, "brand": {"type": "keyword"}, "category": {"type": "keyword"}, "semantic_field": { "type": "semantic_text", "inference_id": INFERENCE_ENDPOINT_ID, }, } } } if not es.indices.exists(index=INDEX_NAME): es.indices.create(index=INDEX_NAME, body=index_mappings) print(f"Created index: {INDEX_NAME}")

ここで重要なのは semantic_text フィールドタイプです。これはdense_vectorよりも高レベルの抽象化です。推論エンドポイントを指定すると、Elasticsearchが埋め込みの生成を自動的に行います。

copy_toプロパティがtitleとdescriptionにある場合、両方のフィールドのコンテンツがsemantic_fieldに流れ込んで埋め込まれるため、単一のベクトルで製品の完全な表現を捉えることができます。

ステップ3：製品をインデックス化する

def bulk_index(products, index_name): actions = [] for product in products: doc_id = product.get("_id") source = {k: v for k, v in product.items() if k != "_id"} action = {"_index": index_name, "_source": source} if doc_id: action["_id"] = doc_id actions.append(action) success, failed = helpers.bulk(es, actions, raise_on_error=False) if failed: for error in failed: print(f"Error: {error}") else: print(f"Successfully indexed {success} documents") bulk_index(products, INDEX_NAME)

インデックス時には、Elasticsearchは各文書の推論エンドポイントを呼び出し、その結果得られた埋め込みをsemantic_fieldに保存します。余計なコードは必要ありません。

ハイブリッド検索：BM25とベクトルおよびRRFの組み合わせ

ベクトルを追加すると再現率は向上しますが、ベクトルのみを使用すると、完全一致クエリの精度が低下するリスクがあります。「ランニングシューズ」は、依然として逐語的に一致するものを最優先にランク付けするべきです。ハイブリッド検索は、その精度を維持するために、語彙要素を意図的に保持します。

ハイブリッド逆順位融合（RRF）検索は、両方の長所を保持します。

BM25は正確およびほぼ正確なクエリを高精度で処理します。
セマンティック検索は、意図に基づく多言語クエリを高い再現率で処理します。
RRFは2つのランキングリストを1つのランキングに統合します。

RRF式は、各結果リストのランクに基づいて各文書にスコアを割り当てます。

score = sum(1 / (rank_constant + rank))

両方のリストで上位に表示されるドキュメントほど、統合スコアは高くなります。rank_constantは、より低いランクの文書に与えられる重みを制御します。

hybrid_requests = [] for query_id, query_text in ( judgments_df[["query_id", "query"]].drop_duplicates().values ): relevant_docs = judgments_df[judgments_df["query_id"] == query_id] ratings = [ {"_index": INDEX_NAME, "_id": row["doc_id"], "rating": row["grade"]} for _, row in relevant_docs.iterrows() ] hybrid_requests.append({ "id": query_id, "request": { "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "multi_match": { "query": query_text, "fields": ["title", "description"], } } } }, { "standard": { "query": { "match": { "semantic_field": {"query": query_text} } } } }, ], "rank_window_size": 50, "rank_constant": 5, } } }, "ratings": ratings, }) hybrid_eval = { "requests": hybrid_requests, "metric": {"recall": {"k": 10, "relevant_rating_threshold": 1}}, } hybrid_result = es.rank_eval(index=INDEX_NAME, body=hybrid_eval) print("Hybrid Recall@10:", hybrid_result.body["metric_score"])

次の結果が得られます。

Hybrid Recall@10: 0.75

ハイブリッドはBM25（0.43）よりも大幅に改善されており、「ランニングシューズ」のような完全一致クエリに対しても精度を維持します。

結果：ビフォーアフター

3つのアプローチの完全な比較は次のとおりです。

methods = { "BM25 (Lexical)": bm25_requests, "Hybrid (BM25 + Vectors)": hybrid_requests, } recall_metric = {"recall": {"k": 10, "relevant_rating_threshold": 1}} comparison_data = [] for method_name, requests in methods.items(): result = es.rank_eval( index=INDEX_NAME, body={"requests": requests, "metric": recall_metric} ) comparison_data.append({ "method": method_name, "recall@10": result.body["metric_score"] }) comparison_df = pd.DataFrame(comparison_data) print(comparison_df.to_string(index=False))

次の結果が得られます。

メソッド

Recall@10

BM25（語彙）

0.43

ハイブリッド（BM25 + ベクター）

0.75

クエリごとに分解すると次のようになります。

まとめ

この記事を通して、BM25の語彙検索は、ユーザーが正確なクエリを入力する場合には信頼性が高いものの、キーワードではなく意図に基づいて検索する場合は再現率が低下することがわかりました。rank_evalを用いて、そのギャップを実数で測定するための再現可能な基準を確立しました。そこから、Jina埋め込みを利用したsemantic_textフィールドを追加し、評価を再度実行しました。結果：ハイブリッド検索により、0.43から0.75への再現率が向上し、正確な一致クエリでの精度を維持しました。ただし、実際の差はクエリの組み合わせによって異なります。

このパターンは、この例を超えてスケールします。ユーザーの実際のクエリから判断を収集し、rank_evalをベースラインとして実行し、semantic_textを追加して再度測定します。何がどれだけ改善したかが正確にわかるでしょう。

今後の見通し

再現率とベクトル検索についてさらに詳しく：再現率とベクトル検索の量子化（Jeff Vestal著）
上位結果の精度をさらに向上させるために再ランキング機能を追加
Elasticsearchハイブリッド検索のドキュメントをご覧ください。
rank_eval APIについて詳しくはこちら

TypeScriptを使用したElasticsearch MCPサーバーの作成

Jeffrey Rengifo — Fri, 27 Mar 2026 00:00:00 GMT

Elasticsearchで大規模なナレッジベースを扱う場合、情報を見つけるだけでは片手落ちです。エンジニアは複数の文書から結果を統合し、要約を作成し、回答を情報源にたどる必要があることが多いです。モデルコンテキストプロトコル（MCP）は、Elasticsearchと大規模言語モデル（LLM）アプリケーションを接続するための標準化された方法を提供します。ElasticはElastic Agent Builder（MCPエンドポイントを機能の一つに含む）のような公式ソリューションを提供していますが、カスタムMCPサーバーを構築することで、検索ロジック、結果のフォーマット、取得したコンテンツをLLMに渡して合成、要約、引用を行う方法などを完全に制御できます。

この記事では、カスタムElasticsearch MCPサーバーを構築するメリットを探り、ElasticsearchをLLM対応アプリケーションに接続するサーバーをTypeScriptで作成する方法を紹介します。

カスタムのElasticsearch MCPサーバーを構築する理由

ElasticはMCPサーバーのいくつかの代替手段を提供しています。

MCPサーバーとElasticsearchの連携方法をより細かく制御したい場合は、独自のカスタムサーバーを構築することで、ニーズに合わせて柔軟にカスタマイズできます。例えば、Agent BuilderのMCPエンドポイントはElasticsearchクエリ言語（ES|QL）クエリに限定されていますが、カスタムサーバーでは完全なクエリDSLを使用できます。また、LLMに渡される前に結果をどのようにフォーマットするかを制御でき、このチュートリアルで実装するOpenAIを利用した要約など、追加の処理ステップを統合することもできます。

この記事を読み終える頃には、Elasticsearchインデックスに保存されている情報を検索し、要約し、引用を提供するTypeScriptで記述されたMCPサーバーが完成しているでしょう。Elasticsearchを使用して情報を検索し、OpenAIのgpt-4o-miniモデルを用いて要約と引用を生成し、Claude DesktopをMCPクライアントおよびUIとして活用してユーザーのクエリを受け取り、応答を提供します。最終的には、エンジニアが組織内の技術文書全体からベストプラクティスを発見し、統合するのに役立つ内部ナレッジアシスタントが完成します。

要件：

Node.js 20 +
Elasticsearch
OpenAI APIキー
Claude Desktop

MCPとは何ですか？

MCPはAnthropicによって作成されたオープンスタンダードで、LLMとElasticsearchのような外部システムとの間で安全かつ双方向の接続を提供します。MCP の現状についてはこの記事で詳しく読むことができます。

MCPの環境は日々進化しており、多様なユースケースに対応したサーバーが利用可能です。さらに、この記事でご紹介するように、独自のカスタムMCPサーバーを簡単に構築することもできます。

MCPクライアント

利用可能なMCPクライアントは多数あり、それぞれに特徴や制限があります。簡便性と普及度を考慮し、今回はMCPクライアントとしてClaude Desktopを使用します。これは、ユーザーが自然言語で質問できるチャットインターフェースとして機能し、MCPサーバーが公開しているツールを自動的に呼び出して、文書を検索し、要約を生成します。

Elasticsearch MCPサーバーの作成

TypeScript SDKを使えば、ユーザーのクエリ入力に基づいてElasticsearchデータのクエリ方法を理解するサーバーを簡単に作成できます。

この記事では、Elasticsearch MCPサーバーとClaude Desktopクライアントを統合するための手順を説明します。

Elasticsearch MCPサーバーを設定してください

まず、Nodeアプリケーションを初期化します。

npm init -y

これで package.jsonファイルが作成され、このアプリケーションに必要な依存関係のインストールを開始できます。

npm install @elastic/elasticsearch @modelcontextprotocol/sdk openai zod && npm install --save-dev ts-node @types/node typescript

@elastic/elasticsearch はElasticsearchのNode.jsライブラリにアクセスするためのものです。
@modelcontextprotocol/sdkは、MCPサーバーの作成と管理、ツールの登録、MCPクライアントとの通信処理を行うためのコアツールを提供します。
openaiは、OpenAIのモデルと対話し、要約や自然言語による対応を生成することができます。
zodは、各ツールの入出力データの構造化スキーマの定義と検証に役立ちます。

ts-node、@types/node、 typescriptは開発中にコードの入力やスクリプトのコンパイルに使用されます。

データセットを設定

Claude DesktopがMCPサーバーを使用してクエリできるデータを提供するために、内部の模擬ナレッジベースデータセットを使用します。このデータセットから作成される文書は以下のような形式になります。

{ "id": 5, "title": "Logging Standards for Microservices", "content": "Consistent logging across microservices helps with debugging and tracing. Use structured JSON logs and include request IDs and timestamps. Avoid logging sensitive information. Centralize logs in Elasticsearch or a similar system. Configure log rotation to prevent storage issues and ensure logs are searchable for at least 30 days.", "tags": ["logging", "microservices", "standards"] }

データを取り込むために、Elasticsearchにインデックスを作成し、そこにデータセットをロードするスクリプトを用意しました。こちらでご覧いただけます。

MCPサーバー

index.tsというファイルを作成し、依存関係をインポートして環境変数を処理するための以下のコードを追加します。

// index.ts import { z } from "zod"; import { Client } from "@elastic/elasticsearch"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import OpenAI from "openai"; const ELASTICSEARCH_ENDPOINT = process.env.ELASTICSEARCH_ENDPOINT ?? "http://localhost:9200"; const ELASTICSEARCH_API_KEY = process.env.ELASTICSEARCH_API_KEY ?? ""; const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? ""; const INDEX = "documents";

また、ElasticsearchとOpenAIの呼び出しを処理するようにクライアントを初期化します。

const openai = new OpenAI({ apiKey: OPENAI_API_KEY, }); const _client = new Client({ node: ELASTICSEARCH_ENDPOINT, auth: { apiKey: ELASTICSEARCH_API_KEY, }, });

実装をより堅牢にし、構造化された入出力を保証するために、 zodを使用してスキーマを定義します。これにより、ランタイムでデータを検証し、エラーを早期に捕捉し、ツールの対応をプログラムで処理しやすくすることができます。

const DocumentSchema = z.object({ id: z.number(), title: z.string(), content: z.string(), tags: z.array(z.string()), }); const SearchResultSchema = z.object({ id: z.number(), title: z.string(), content: z.string(), tags: z.array(z.string()), score: z.number(), }); type Document = z.infer; type SearchResult = z.infer;

構造化出力の詳細については、こちらをご覧ください。

それでは、MCPサーバーを初期化しましょう。

const server = new McpServer({ name: "Elasticsearch RAG MCP", description: "A RAG server using Elasticsearch. Provides tools for document search, result summarization, and source citation.", version: "1.0.0", });

MCPツールの定義

すべての設定が完了したので、MCPサーバーによって公開されるツールの作成を開始できます。このサーバーは2つのツールを公開します。

search_docs：Elasticsearchで文書を全文検索で検索します。
summarize_and_cite：以前に取得した文書から情報を要約・統合し、ユーザーの質問に答えます。このツールは、出典となる文書を参照する引用も追加します。

これらのツールを組み合わせることで、シンプルな「検索してから要約」ワークフローが構築されます。一方のツールが関連文書を取得し、もう一方のツールがその文書を使用して要約と引用を含む回答を生成します。

ツールの応答形式

各ツールは任意の入力パラメータを受け入れることができますが、以下の構造で応答する必要があります。

Content： これは非構造化形式でのツールの応答です。このフィールドは通常、テキスト、画像、音声、リンク、または埋め込みを返すために使用されます。この用途では、ツールによって生成された情報を含む整形済みテキストを返すために使用されます。
structuredContent：これは、各ツールの結果を構造化された形式で提供するために使用されるオプションの戻り値です。これはプログラム上の目的に役立ちます。このMCPサーバーでは使用されていませんが、他のツールを開発したり、結果をプログラムで処理したりする場合に便利です。

その構造を念頭に置いて、各ツールについて詳しく見ていきましょう。

Search_docsツール

このツールは、Elasticsearchインデックスで全文検索を実行し、ユーザークエリに基づいて最も関連性の高いドキュメントを取得します。主要な一致をハイライトし、関連性スコアを素早くまとめてくれます。

server.registerTool( "search_docs", { title: "Search Documents", description: "Search for documents in Elasticsearch using full-text search. Returns the most relevant documents with their content, title, tags, and relevance score.", inputSchema: { query: z .string() .describe("The search query terms to find relevant documents"), max_results: z .number() .optional() .default(5) .describe("Maximum number of results to return"), }, outputSchema: { results: z.array(SearchResultSchema), total: z.number(), }, }, async ({ query, max_results }) => { if (!query) { return { content: [ { type: "text", text: "Query parameter is required", }, ], isError: true, }; } try { const response = await _client.search({ index: INDEX, size: max_results, query: { bool: { must: [ { multi_match: { query: query, fields: ["title^2", "content", "tags"], fuzziness: "AUTO", }, }, ], should: [ { match_phrase: { title: { query: query, boost: 2, }, }, }, ], }, }, highlight: { fields: { title: {}, content: {}, }, }, }); const results: SearchResult[] = response.hits.hits.map((hit: any) => { const source = hit._source as Document; return { id: source.id, title: source.title, content: source.content, tags: source.tags, score: hit._score ?? 0, }; }); const contentText = results .map( (r, i) => `[${i + 1}] ${r.title} (score: ${r.score.toFixed( 2, )})\n${r.content.substring(0, 200)}...`, ) .join("\n\n"); const totalHits = typeof response.hits.total === "number" ? response.hits.total : (response.hits.total?.value ?? 0); return { content: [ { type: "text", text: `Found ${results.length} relevant documents:\n\n${contentText}`, }, ], structuredContent: { results: results, total: totalHits, }, }; } catch (error: any) { console.log("Error during search:", error); return { content: [ { type: "text", text: `Error searching documents: ${error.message}`, }, ], isError: true, }; } } );

fuzziness: “AUTO” は 分析対象のトークンの長さに応じて誤字許容度を調整するように設定しています。また 、 タイトルフィールドで一致が発生したドキュメントのスコアを上げるtitle^2も設定しました。。

summarize_and_citeツール

このツールは、前回の検索で取得したドキュメントに基づいて要約を生成します。OpenAIの gpt-4o-miniモデルを使用して、ユーザーの質問に答えるために最も関連性の高い情報を統合し、検索結果に直接基づく回答を提供します。要約に加えて、使用したソースドキュメントの引用情報（メタデータ）も返します。

server.registerTool( "summarize_and_cite", { title: "Summarize and Cite", description: "Summarize the provided search results to answer a question and return citation metadata for the sources used.", inputSchema: { results: z .array(SearchResultSchema) .describe("Array of search results from search_docs"), question: z.string().describe("The question to answer"), max_length: z .number() .optional() .default(500) .describe("Maximum length of the summary in characters"), max_docs: z .number() .optional() .default(5) .describe("Maximum number of documents to include in the context"), }, outputSchema: { summary: z.string(), sources_used: z.number(), citations: z.array( z.object({ id: z.number(), title: z.string(), tags: z.array(z.string()), relevance_score: z.number(), }) ), }, }, async ({ results, question, max_length, max_docs }) => { if (!results || results.length === 0 || !question) { return { content: [ { type: "text", text: "Both results and question parameters are required, and results must not be empty", }, ], isError: true, }; } try { const used = results.slice(0, max_docs); const context = used .map( (r: SearchResult, i: number) => `[Document ${i + 1}: ${r.title}]\\n${r.content}` ) .join("\n\n---\n\n"); // Generate summary with OpenAI const completion = await openai.chat.completions.create({ model: "gpt-4o-mini", messages: [ { role: "system", content: "You are a helpful assistant that answers questions based on provided documents. Synthesize information from the documents to answer the user's question accurately and concisely. If the documents don't contain relevant information, say so.", }, { role: "user", content: `Question: ${question}\\n\\nRelevant Documents:\\n${context}`, }, ], max_tokens: Math.min(Math.ceil(max_length / 4), 1000), temperature: 0.3, }); const summaryText = completion.choices[0]?.message?.content ?? "No summary generated."; const citations = used.map((r: SearchResult) => ({ id: r.id, title: r.title, tags: r.tags, relevance_score: r.score, })); const citationText = citations .map( (c: any, i: number) => `[${i + 1}] ID: ${c.id}, Title: "${c.title}", Tags: ${c.tags.join( ", ", )}, Score: ${c.relevance_score.toFixed(2)}`, ) .join("\n"); const combinedText = `Summary:\\n\\n${summaryText}\\n\\nSources used (${citations.length}):\\n\\n${citationText}`; return { content: [ { type: "text", text: combinedText, }, ], structuredContent: { summary: summaryText, sources_used: citations.length, citations: citations, }, }; } catch (error: any) { return { content: [ { type: "text", text: `Error generating summary and citations: ${error.message}`, }, ], isError: true, }; } } );

最後に、stdioを使用してサーバーを起動する必要があります。つまり、MCPクライアントは、標準の入出力ストリームを読み書きすることでサーバーと通信します。stdioは最もシンプルな転送オプションで、クライアントによってサブプロセスとして立ち上げられるローカルMCPサーバーに適しています。ファイルの最後に以下のコードを追加します。

const transport = new StdioServerTransport(); server.connect(transport);

次に、以下のコマンドを使用してプロジェクトをコンパイルします。

npx tsc index.ts --target ES2022 --module node16 --moduleResolution node16 --outDir ./dist --strict --esModuleInterop

これによりdistフォルダが作成され、その中にindex.jsファイルが作成されます。

MCPサーバーをClaude Desktopにロード

Claude DesktopでMCPサーバーを設定するには、このガイドに従ってください。Claudeの設定ファイルでは、以下の値を設定する必要があります:

{ "mcpServers": { "elasticsearch-rag-mcp": { "command": "node", "args": [ "/Users/user-name/app-dir/dist/index.js" ], "env": { "ELASTICSEARCH_ENDPOINT": "your-endpoint-here", "ELASTICSEARCH_API_KEY": "your-api-key-here", "OPENAI_API_KEY": "your-openai-key-here" } } } }

args値は、 distフォルダ内のコンパイル済みファイルを指す必要があります。また、設定ファイル内の環境変数も、コード内で定義されているものと全く同じ名前で設定する必要があります。

試してみる

各ツールを実行する前に、「検索とツール」をクリックして、ツールが有効になっていることを確認します。ここでは、それぞれを有効または無効にすることもできます。

最後に、Claude DesktopのチャットからMCPサーバーをテストして、質問を始めましょう。

「認証方法とRBACに関する文書を検索する」という質問に対して、search_docs ツールが実行され、以下の結果が返されます。

Most Relevant Documents: Access Control and Role Management (highest relevance) - This document covers role-based access control (RBAC) principles, including ensuring users only have necessary permissions, regular auditing of user roles, revoking inactive accounts, and implementing just-in-time access for sensitive operations. User Authentication with OAuth 2.0 - This document explains OAuth 2.0 authentication, which enables secure delegated access without credential sharing. It covers configuring identity providers, token management with limited scope and lifetime, and secure storage of refresh tokens. Container Security Guidelines - While primarily about container security, this document touches on access control aspects like running containers as non-root users and avoiding embedded credentials. Incident Response Playbook - This mentions role assignment during incidents (incident commander, communications lead, etc.), which relates to access control in emergency scenarios. Logging Standards for Microservices - This document includes guidance on avoiding logging sensitive information, which is relevant to authentication security.

回答は「素晴らしい！認証方法とロールベースのアクセス制御に関する関連文書を5件見つけました。見つかった内容は以下のとおりです。」

ツール呼び出しは、対応ペイロードの一部としてソース文書を返します。これらの文書は、後に引用を生成するために使用されます。

また、複数のツールを一度のインタラクションで連結することも可能です。この場合、Claude Desktopはユーザーの質問を分析し、まずsearch_docsを呼び出して関連文書を取得し、次にその結果をsummarize_and_citeに渡して最終的な回答を生成する必要があると判断します。これらすべては、ユーザーからの個別のプロンプトを必要とせずに実行されます。

この場合、「システム全体の認証とアクセス制御を改善するための主な推奨事項は何ですか？参考文献を含めてください。」というクエリに対して、以下の結果が得られました。

Based on the documentation, here are the main recommendations to improve authentication and access control across your systems: Key Recommendations 1. Implement Role-Based Access Control (RBAC) Ensure users have only the permissions necessary for their job functions. This principle of least privilege minimizes security risks by limiting access to what's truly needed. [1] 2. Regular Access Audits Conduct regular audits of user roles and promptly revoke access for inactive accounts. This helps prevent unauthorized access from dormant or compromised accounts. [1] 3. Just-in-Time (JIT) Access Implement just-in-time access for sensitive operations, where permissions are granted only when needed and for a limited duration. This reduces the attack surface by minimizing standing privileges. [1] 4. OAuth 2.0 for Secure Authentication Use OAuth 2.0 to enable secure delegated access without sharing user credentials. This protocol allows third-party applications to access resources on behalf of users without exposing passwords. [2] 5. Token Security and Management Configure your identity provider to issue tokens with limited scope and lifetime Store refresh tokens securely Validate access tokens consistently to maintain security [2] References Access Control and Role Management (Tags: security, access-control) User Authentication with OAuth 2.0 (Tags: authentication, oauth) These recommendations work together to create a defense-in-depth approach, where multiple security layers protect your systems from unauthorized access.

前のステップと同様に、この質問に対する各ツールの回答を確認できます。

注：各ツールの使用を承認するかを確認するサブメニューが表示された場合は、「常に許可」または「一度だけ許可」を選択します。

まとめ

MCPサーバーは、ローカルとリモートの両方のアプリケーションのLLMツールの標準化に向けた重要な一歩です。完全な互換性の実現にはまだ取り組んでいますが、その方向へ急速に進んでいます。

この記事では、ElasticsearchをLLM搭載アプリケーションに接続するカスタムMCPサーバーをTypeScriptで構築する方法を学びました。当サーバーは2つのツールを提供しています。1つはQuery DSLを使用して関連文書を取得するためのツールsearch_docs、もう1つはOpenAIモデルとクライアントUIとしてのClaude Desktopを使用して引用付きの要約を生成するためのツールsummarize_and_citeです。

異なるクライアントとサーバープロバイダー間の互換性の将来は有望に見えます。次のステップは、エージェントにより多くの機能と柔軟性を加えることです。実用的な記事で、検索テンプレートを使用してクエリをパラメーター化し、精度と柔軟性を得る方法を学ぶことができます。

Elasticsearch Inference APIとHugging Faceモデルを組み合わせて使用

Jeffrey Rengifo — Mon, 23 Mar 2026 00:00:00 GMT

最近のアップデートで、ElasticsearchはHugging Face Inference Serviceでホストされているモデルに接続するためのネイティブ統合機能を導入しました。この記事では、この統合を構成し、大規模言語モデル（LLM）を使用して簡単なAPI呼び出しを通じて推論を実行する方法を探ります。リソース使用量と解答品質のバランスが取れた軽量汎用モデルであるSmolLM3-3Bを使用します。

要件

Elasticsearch 9.3またはElastic Cloud Serverless：これらの指示に従ってクラウド導入を作成することもできますし、start-localクイックスタートを使うこともできます。
Python 3.12：Pythonはこちらからダウンロードしてください。
Hugging Faceアクセストークン。

Hugging Face推論エンドポイントを使用したチャットの完了

まず、ElasticsearchをHugging Faceの推論エンドポイントに接続し、ブログ記事のコレクションからAIを活用したレコメンデーションを生成する実践的な例を作成します。アプリのナレッジベースには、会社のブログ記事のデータセットを使用します。これには価値のある情報が含まれていますが、多くの場合、見つけるのが困難です。

このエンドポイントでは、セマンティック検索が指定されたクエリに対して最も関連性の高い記事を取得し、Hugging Face LLMがそれらの結果に基づいて短いコンテキスト推奨を生成します。

これから構築する情報フローの概要を見ていきましょう。

この記事では、コンパクトなサイズと強力な多言語推論能力・ツール呼び出し能力を組み合わせたSmolLM3-3Bの性能を検証します。検索クエリに基づいて、一致するすべてのコンテンツ（英語とスペイン語）をLLMに送信し、検索クエリと結果に基づいたカスタムメイドの説明を含むおすすめ記事のリストを生成します。

AIによる推奨生成システムを備えた記事サイトのUIは次のようになります。

このアプリケーションの完全な実装は、リンク先のノートブックで確認できます。

Elasticsearch推論エンドポイントの構成

Elasticsearch Hugging Face推論エンドポイントを使用するには、2つの重要な要素（Hugging Face APIキーと実行中のHugging FaceエンドポイントURL）が必要です。下の画像のように表示されるはずです。

PUT _inference/chat_completions/hugging-face-smollm3-3b { "service": "hugging_face", "service_settings": { "api_key": "hugging-face-access-token", "url": "url-endpoint" } }

Hugging FaceのElasticsearchにおける推論エンドポイントは、 text_embedding, completion, chat_completion, と rerankの異なるタスクタイプをサポートしています。このブログ記事では、検索結果とシステムプロンプトに基づいて会話形式のレコメンデーションをモデルに生成させる必要があるため、chat_completion を使用します。このエンドポイントを使用すると、Elasticsearch APIを使用してElasticsearchから直接チャットの完了を簡単に実行できます。

POST _inference/chat_completion/hugging-face-smollm3-3b/_stream { "messages": [ { "role": "user", "content": "" } ] }

これはアプリケーションのコアとして機能し、モデルを通過するプロンプトと検索結果を受け取ります。理論について説明したので、アプリケーションの実装を始めましょう。

Hugging Faceでの推論エンドポイントの設定

Hugging Faceモデルをデプロイするために、モデルのエンドポイントをデプロイするための簡単で高速なサービスHugging Faceワンクリック導入を使用します。これは有料サービスであり、利用には追加料金が発生する可能性があることにご注意ください。このステップでは、記事の推奨を生成するために使うモデルインスタンスが作成されます。

ワンクリックカタログからモデルを選択できます。

SmolLM3-3Bモデルを選択します。

ここから、Hugging FaceのエンドポイントURLを取得します。

Elasticsearch Hugging Faceの推論エンドポイントのドキュメントで述べられているように、テキスト生成にはOpenAI APIと互換性のあるモデルが必要です。そのため、/v1/chat/completionsのサブパスをHugging FaceのエンドポイントURLに追加する必要があります。最終的な結果は次のようになります。

https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions

これで準備が整いましたので、Pythonノートブックでコーディングを開始できます。

Hugging Face APIキーの生成

Hugging Faceアカウントを作成し、以下の指示に従ってAPIトークンを取得してください。トークンの種類は、fine-grained（本番環境に推奨。特定のリソースへのアクセスのみを提供）、read（読み取り専用アクセス用）、write（読み取りおよび書き込みアクセス用）の3つから選択できます。このチュートリアルでは、推論エンドポイントを呼び出すだけでよいので、readトークンで十分です。次のステップのために、このキーを保存しておいてください。

Elasticsearch推論エンドポイントの設定

まず、Elasticsearch Pythonクライアントを宣言します。

os.environ["ELASTICSEARCH_API_KEY"] = "your-elasticsearch-api-key" os.environ["ELASTICSEARCH_URL"] = "https://xxxx.us-central1.gcp.cloud.es.io:443" es_client = Elasticsearch( os.environ["ELASTICSEARCH_URL"], api_key=os.environ["ELASTICSEARCH_API_KEY"] )

次に、Hugging Faceモデルを使用するElasticsearch推論エンドポイントを作成します。このエンドポイントを使用すると、ブログ記事とモデルに渡されたプロンプトに基づいて応答を生成できます。

INFERENCE_ENDPOINT_ID = "smollm3-3b-pnz" os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"] = ( "https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions" ) os.environ["HUGGING_FACE_API_KEY"] = "hf_xxxxx" resp = es_client.inference.put( task_type="chat_completion", inference_id=INFERENCE_ENDPOINT_ID, body={ "service": "hugging_face", "service_settings": { "api_key": os.environ["HUGGING_FACE_API_KEY"], "url": os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"], }, }, )

データセット

このデータセットには、クエリの対象となるブログ記事が含まれており、ワークフロー全体で使用される多言語コンテンツセットを表しています。

// Articles dataset document example: { "id": "6", "title": "Complete guide to the new API: Endpoints and examples", "author": "Tomas Hernandez", "date": "2025-11-06", "category": "tutorial", "content": "This guide describes in detail all endpoints of the new API v2. It includes code examples in Python, JavaScript, and cURL for each endpoint. We cover authentication, resource creation, queries, updates, and deletion. We also explain error handling, rate limiting, and best practices. Complete documentation is available on our developer portal." }

Elasticsearch マッピング

データセットが定義されたので、ブログ記事の構造に適切にフィットするデータスキーマを作成する必要があります。Elasticsearchにデータを格納するために以下のインデックスマッピングが使用されます。

INDEX_NAME = "blog-posts" mapping = { "mappings": { "properties": { "id": {"type": "keyword"}, "title": { "type": "object", "properties": { "original": { "type": "text", "copy_to": "semantic_field", "fields": {"keyword": {"type": "keyword"}}, }, "translated_title": { "type": "text", "fields": {"keyword": {"type": "keyword"}}, }, }, }, "author": {"type": "keyword", "copy_to": "semantic_field"}, "category": {"type": "keyword", "copy_to": "semantic_field"}, "content": {"type": "text", "copy_to": "semantic_field"}, "date": {"type": "date"}, "semantic_field": {"type": "semantic_text"}, } } } es_client.indices.create(index=INDEX_NAME, body=mapping)

ここで、データがどのように構造化されているかをより明確に見ることができます。セマンティック検索を使用して自然言語に基づいて結果を取得し、copy_toプロパティを使用してフィールドの内容をsemantic_textフィールドにコピーします。さらに、titleフィールドには2つのサブフィールドが含まれています。originalサブフィールドは、記事の元の言語に応じて英語またはスペイン語でタイトルを格納し、translated_titleサブフィールドはスペイン語の記事にのみ存在し、元のタイトルの英語訳が含まれています。

データの取り込み

以下のコードスニペットはbulk APIを使用してブログ投稿データセットをElasticsearchに取り込みます。

def build_data(json_file, index_name): with open(json_file, "r") as f: data = json.load(f) for doc in data: action = {"_index": index_name, "_source": doc} yield action try: success, failed = helpers.bulk( es_client, build_data("dataset.json", INDEX_NAME), ) print(f"{success} documents indexed successfully") if failed: print(f"Errors: {failed}") except Exception as e: print(f"Error: {str(e)}")

Elasticsearchに記事を取り込んだので、次にsemantic_textフィールドに対して検索できる関数を作成する必要があります:

def perform_semantic_search(query_text, index_name=INDEX_NAME, size=5): try: query = { "query": { "match": { "semantic_field": { "query": query_text, } } }, "size": size, } response = es_client.search(index=index_name, body=query) hits = response["hits"]["hits"] return hits except Exception as e: print(f"Semantic search error: {str(e)}") return []

推論エンドポイントを呼び出す関数も必要です。この場合、chat_completionタスクタイプを使用してエンドポイントを呼び出し、ストリーミング応答を取得します。

def stream_chat_completion(messages: list, inference_id: str = INFERENCE_ENDPOINT_ID): url = f"{ELASTICSEARCH_URL}/_inference/chat_completion/{inference_id}/_stream" payload = {"messages": messages} headers = { "Authorization": f"ApiKey {ELASTICSEARCH_API_KEY}", "Content-Type": "application/json", } try: response = requests.post(url, json=payload, headers=headers, stream=True) response.raise_for_status() for line in response.iter_lines(decode_unicode=True): if line: line = line.strip() if line.startswith("event:"): continue if line.startswith("data: "): data_content = line[6:] if not data_content.strip() or data_content.strip() == "[DONE]": continue try: chunk_data = json.loads(data_content) if "choices" in chunk_data and len(chunk_data["choices"]) > 0: choice = chunk_data["choices"][0] if "delta" in choice and "content" in choice["delta"]: content = choice["delta"]["content"] if content: yield content except json.JSONDecodeError as json_err: print(f"\nJSON decode error: {json_err}") print(f"Problematic data: {data_content}") continue except requests.exceptions.RequestException as e: yield f"Error: {str(e)}"

ここで、 chat_completions 推論エンドポイントと推薦エンドポイントを合わせてセマンティック検索関数を呼び出し、カードに割り当てられるデータを生成する関数を書くことができます。

def recommend_articles(search_query, index_name=INDEX_NAME, max_articles=5): print(f"\n{'='*80}") print(f"🔍 Search Query: {search_query}") print(f"{'='*80}\n") articles = perform_semantic_search(search_query, index_name, size=max_articles) if not articles: print("❌ No relevant articles found.") return None, None print(f"✅ Found {len(articles)} relevant articles\n") # Build context with found articles context = "Available blog articles:\n\n" for i, article in enumerate(articles, 1): source = article.get("_source", article) context += f"Article {i}:\n" context += f"- Title: {source.get('title', 'N/A')}\n" context += f"- Author: {source.get('author', 'N/A')}\n" context += f"- Category: {source.get('category', 'N/A')}\n" context += f"- Date: {source.get('date', 'N/A')}\n" context += f"- Content: {source.get('content', 'N/A')}\n\n" system_prompt = """You are an expert content curator that recommends blog articles. Write recommendations in a conversational style starting with phrases like: - "If you're interested in [topic], this article..." - "This post complements your search with..." - "For those looking into [topic], this article provides..." FORMAT REQUIREMENTS: - Return ONLY a JSON array - Each element must have EXACTLY these three fields: "article_number", "title", "recommendation" - If the original title is in spanish, use the "translated_title" subfield in the "title" field Keep each recommendation concise (2-3 sentences max) and focused on VALUE to the reader. EXAMPLE OF CORRECT FORMAT: [ {"article_number": 1, "title": "Article title in english", "recommendation": "If you are interested in [topic], this article provides..."}, {"article_number": 2, "title": "Article title in english", "recommendation": " for those looking into [topic], this article provides..."} ] Return ONLY the JSON array following this exact structure.""" user_prompt = f"""Search query: "{search_query}" Generate recommendations for the following articles: {context} """ messages = [ {"role": "system", "content": "/no_think"}, {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}, ] # LLM generation print(f"{'='*80}") print("🤖 Generating personalized recommendations...\n") full_response = "" for chunk in stream_chat_completion(messages): print(chunk, end="", flush=True) full_response += chunk return context, articles, full_response

最後に、情報を抽出して出力できるようにフォーマットする必要があります。

def display_recommendation_cards(articles, recommendations_text): print("\n" + "=" * 100) print("📇 RECOMMENDED ARTICLES".center(100)) print("=" * 100 + "\n") # Parse JSON recommendations - clean tags and extract JSON recommendations_list = [] try: # Clean up tags cleaned_text = re.sub( r".*?", "", recommendations_text, flags=re.DOTALL ) # Remove markdown code blocks ( ... ``` or ``` ... ```) cleaned_text = re.sub(r"```(?:json)?", "", cleaned_text) cleaned_text = cleaned_text.strip() parsed = json.loads(cleaned_text) # Extract recommendations from list format for item in parsed: article_number = item.get("article_number") title = item.get("title", "") rec_text = item.get("recommendation", "") if article_number and rec_text: recommendations_list.append( { "article_number": article_number, "title": title, "recommendation": rec_text, } ) except json.JSONDecodeError as e: print(f"⚠️ Could not parse recommendations as JSON: {e}") return for i, article in enumerate(articles, 1): source = article.get("_source", article) # Card border print("┌" + "─" * 98 + "┐") # Find recommendation and title for this article number recommendation = None title = None for rec in recommendations_list: if rec.get("article_number") == i: recommendation = rec.get("recommendation") title = rec.get("title") break # Print title title_lines = textwrap.wrap(f"📌 {title}", width=94) for line in title_lines: print(f"│ {line}".ljust(99) + "│") # Card border print("├" + "─" * 98 + "┤") # Print recommendation if recommendation: recommendation_lines = textwrap.wrap(recommendation, width=94) for line in recommendation_lines: print(f"│ {line}".ljust(99) + "│") # Card bottom print("└" + "─" * 98 + "┘")

セキュリティブログの投稿について質問して、これをテストしてみましょう。

search_query = "Security and vulnerabilities" context, articles, recommendations = recommend_articles(search_query) print("\nElasticsearch context:\n", context) # Display visual cards display_recommendation_cards(articles, recommendations)

ここでは、ワークフローによって生成されたコンソール内のカードを確認できます。

すべてのヒットとLLMの対応を含む完全な結果をこのファイルでご覧いただけます。

「Security and vulnerabilities」に関連する記事をクエリしています。この質問は、Elasticsearchに保存されているドキュメントに対する検索クエリとして使用されます。取得された結果はモデルに渡され、モデルはその内容に基づいてレコメンデーションを生成します。ご覧の通り、このモデルは読者がクリックする動機付けとなる魅力的な短いテキストを非常にうまく生成しています。

まとめ

この例では、ElasticsearchとHugging Faceを組み合わせて、AIアプリケーション向けの高速で効率的な集中型システムを構築する方法を示します。Hugging Faceの豊富なモデルカタログにより、このアプローチでは手作業を削減し、柔軟性を確保できます。特にSmolLM3-3Bを使用すると、コンパクトな多言語モデルでも、セマンティック検索と組み合わせることで有意義な推論とコンテンツ生成を実現できることがわかります。これらのツールを組み合わせることで、インテリジェントなコンテンツ分析と多言語アプリケーションを構築するための、拡張性が高く効果的な基盤を提供できます。

LangGraph.jsとElasticsearchを使用して金融AI検索ワークフローを構築

Jeffrey Rengifo — Fri, 05 Dec 2025 00:00:00 GMT

AI検索アプリケーションの構築では、多くの場合、複数のタスク、データ取得、データ抽出をシームレスなワークフローに調整する必要があります。LangGraphは、開発者がnodeベースの構造を使用してAIエージェントを管理することで、このプロセスを簡素化します。この記事では、LangGraph.jsを使用して金融ソリューションを構築します。

LangGraphの概要

LangGraphは、AIエージェントを構築し、ワークフロー内で管理してAI支援アプリケーションを作成するためのフレームワークです。LangGraphには、タスクを表す関数を宣言し、それらをワークフローのノードとして割り当てることができるノードアーキテクチャがあります。複数のノードが相互作用した結果がグラフになります。LangGraphは、モジュール式かつ構成可能なAIシステムを構築するためのツールを提供する、より広範なLangChainエコシステムの一部です。

LangGraphが有用である理由をより深く理解するために、LangGraphを使用して問題のある状況を解決してみましょう。

ソリューションの概要

ベンチャーキャピタル企業では、投資家は多くのフィルタリングオプションを備えた大規模なデータベースにアクセスできますが、基準を組み合わせたい場合には困難で時間がかかります。これにより、関連するスタートアップの一部が投資対象として見つからない可能性があります。その結果、最適な候補を見つけるために多くの時間を費やしたり、機会を逃したりすることになります。

LangGraphとElasticsearchを使用することで、自然言語を用いてフィルターで検索することが可能となり、ユーザーが手動で複雑なリクエストを何十ものフィルターで構築する必要がなくなります。柔軟性を高めるために、ワークフローはユーザーの入力に基づいて2つのクエリタイプを自動的に決定します。

投資に焦点を当てたクエリ：スタートアップ企業の財務および資金調達の側面を対象としており、資金調達ラウンド、バリュエーション、収益を含みます。例：「シリーズAまたはシリーズBの資金調達額が800万ドル～2,500万ドルで、月間収益が50万ドルを超えるスタートアップを探してください。」
市場重視のクエリ：業界分野、地理的市場、ビジネスモデルに重点を置き、特定のセクターまたは地域での機会の特定に役立ちます。例：「サンフランシスコ、ニューヨーク、ボストンのフィンテックおよびヘルスケアのスタートアップ企業を探してください」

クエリを強固に保つため、LLMに検索テンプレートを構築させ、完全なDSLクエリの代わりとします。このようにすれば、必要なクエリを常に取得でき、LLMは空白を埋めるだけで済み、毎回必要なクエリを構築する責任を負う必要がなくなります。

始めるために必要なもの

Elasticsearch APIキー
OpenAPI APIキー
Node 18以降

ステップ別のガイド

このセクションでは、アプリがどのように見えるかを見てみましょう。TypeScriptはJavaScriptのスーパーセットで、静的な型を追加することでコードの信頼性を高め、保守性を向上させ、エラーを早期に発見して安全性を高めます。既存のJavaScriptとの完全な互換性を保ちながら、これを実現します。

ノードのフローは次のようになります。

上記の画像はLangGraphによって生成されたもので、ノード間の実行順序と条件付きロジックを定義するワークフローを表しています。

decideStrategy：LLMを用いてユーザーのクエリを分析し、投資重視か市場重視の2つの専門的な検索戦略のどちらかを判断します。
prepareInvestmentSearch：クエリからフィルター値を抽出し、財務および資金調達関連のパラメータを強調した定義済みテンプレートを構築します。
prepareMarketSearch : フィルター値も抽出しますが、市場、業界、地理的コンテキストを重視したパラメータを動的に構築します。
executeSearch：検索テンプレートを使用して構築されたクエリをElasticsearchに送信し、一致するスタートアップドキュメントを取得します。
visualizeResults：最終結果を、資金、業界、収益などの主要なスタートアップ属性を示す明確で読みやすい要約にフォーマットします。

このフローには「if」ステートメントとして機能する条件分岐が含まれており、ユーザーの入力に基づいて投資検索パスを使用するか、市場検索パスを使用するかを決定します。LLMにより駆動されるこの意思決定ロジックにより、ワークフローは適応的でコンテキストに応じたものになります。このメカニズムについては次のセクションで詳しく説明します。

LangGraphの状態

各ノードを個別に見る前に、ノードがどのように通信し、データを共有するかを理解する必要があります。そのために、LangGraphではワークフローの状態を定義することができます。これはノード間で共有される状態を定義します。

状態は、ワークフロー全体の中間データを保存する共有コンテナとして機能します。ユーザーの自然言語クエリから始まり、選択された検索戦略、Elasticsearch用に準備されたパラメータ、取得された検索結果、最後にフォーマットされた出力が保持されます。

この構造により、すべてのノードが状態を読み取って更新できるようになり、ユーザー入力から最終的な視覚化までの一貫した情報の流れが保証されます。

const VCState = Annotation.Root({ input: Annotation(), // User's natural language query searchStrategy: Annotation(), // Search strategy chosen by LLM searchParams: Annotation(), // Prepared search parameters results: Annotation(), // Search results final: Annotation(), // Final formatted response });

アプリケーションをセットアップする

このセクションのすべてのコードはelasticsearch-labsリポジトリで見つけることができます。

アプリが置かれるフォルダーでターミナルを開き、以下のコマンドで Node.js アプリケーションを初期化します。

npm init -y

これで、このプロジェクトに必要な依存関係をインストールできます。

npm install @elastic/elasticsearch @langchain/langgraph @langchain/openai @langchain/core dotenv zod && npm install --save-dev @types/node tsx typescript

@elastic/elasticsearch: Elasticsearchのデータインジェストや検索などのリクエストを処理するのに役立ちます。
@langchain/langgraph: すべてのLangGraphツールを提供するためのJS依存関係。
@langchain/openai: LangChain用のOpenAI LLMクライアント。
@langchain/core：プロンプトテンプレートなど、LangChainアプリのコアとなる基本的な構成要素を提供します。
dotenv:JavaScriptで環境変数を使用するために必要な依存関係。
zod：型データへの依存関係。

@types/node tsx typescript により、TypeScriptコードを記述して実行できるようになります。

次に、以下のファイルを作成します。

elasticsearchSetup.ts: Elasticsearchのマッピングを作成し、JSONファイルからデータを取り込み、Elasticsearchにデータを取り込みます。
main.ts: LangGraphアプリケーションが含まれます。
.env：環境変数を格納するファイル

.envファイルに以下の環境変数を追加します。

ELASTICSEARCH_ENDPOINT="your-endpoint-here" ELASTICSEARCH_API_KEY="your-key-here" OPENAI_API_KEY="your-key-here"

OpenAPI APIKeyはコード上で直接使用されることはなく、ライブラリ@langchain/openaiによって内部的に使用されます。

マッピングの作成、検索テンプレートの作成、データセットのインジェストに関するすべてのロジックは、elasticsearchSetup.tsファイルにあります。次のステップでは、main.tsファイルに焦点を当てていきます。また、データセットをチェックして、 dataset.jsonでデータがどのように表示されるかをよりよく理解することもできます。

LangGraphアプリ

main.tsファイルで、LangGraphアプリを統合するために必要な依存関係をいくつかインポートしましょう。このファイルには、ノード関数と状態宣言も含める必要があります。グラフの宣言は、次のステップで main メソッドで行われます。elasticsearchSetup.tsファイルには、以降のステップでノード内で使用する Elasticsearch ヘルパーが含まれます。

import { writeFileSync } from "node:fs"; import { StateGraph, Annotation, START, END } from "@langchain/langgraph"; import { ChatOpenAI } from "@langchain/openai"; import { z } from "zod"; import { esClient, ingestDocuments, createSearchTemplates, INDEX_NAME, INVESTMENT_FOCUSED_TEMPLATE, MARKET_FOCUSED_TEMPLATE, createIndex, } from "./elasticsearchSetup.js"; const llm = new ChatOpenAI({ model: "gpt-4o-mini" });

前述のように、LLMクライアントは、ユーザーの質問に基づいてElasticsearch検索テンプレートパラメーターを生成するために使用されます。

async function saveGraphImage(app: any): Promise { try { const drawableGraph = app.getGraph(); const image = await drawableGraph.drawMermaidPng(); const arrayBuffer = await image.arrayBuffer(); const filePath = "./workflow_graph.png"; writeFileSync(filePath, new Uint8Array(arrayBuffer)); console.log(`📊 Workflow graph saved as: ${filePath}`); } catch (error: any) { console.log("⚠️ Could not save graph image:", error.message); } }

上記の方法はグラフ画像をpng形式で生成し、裏でMermaid.INK APIを利用しています。これは、スタイル設定された視覚化を使用してアプリノードがどのように相互作用するかを確認する場合に便利です。

LangGraphノード

次に、各ノードの詳細を見てみましょう。

decideSearchStrategyノード

decideSearchStrategyノードはユーザー入力を分析し、投資重視の検索を実行するか、市場重視の検索を実行するかを決定します。構造化された出力スキーマ（Zodで定義）を持つLLMを使用してクエリタイプを分類します。決定を下す前に、集計を使用してインデックスから利用可能なフィルターを取得し、モデルが業界、場所、資金調達データに関する最新のコンテキストを持っていることを確認します。

フィルタの可能な値を抽出してLLMに送信するために、集計クエリを使ってElasticsearchインデックスから直接値を取得してみましょう。このロジックはgetAvailableFiltersというメソッドに割り当てられます。

async function getAvailableFilters() { try { const response = await esClient.search({ index: INDEX_NAME, size: 0, aggs: { industries: { terms: { field: "industry", size: 100 }, }, locations: { terms: { field: "location", size: 100 }, }, funding_stages: { terms: { field: "funding_stage", size: 20 }, }, business_models: { terms: { field: "business_model", size: 10 }, }, lead_investors: { terms: { field: "lead_investor", size: 100 }, }, funding_amount_stats: { stats: { field: "funding_amount" }, }, }, }); return response.aggregations; } catch (error) { console.error("❌ Error getting available filters:", error); return {}; } }

上記の集約クエリを用いると、以下の結果が得られます。

{ "industries": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "logistics", "doc_count": 5 }, ... ] }, "locations": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "San Francisco, CA", "doc_count": 4 }, { "key": "New York, NY", "doc_count": 3 }, ... ] }, "funding_stages": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "Series A", "doc_count": 8 }, ... ] }, "business_models": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "B2B", "doc_count": 13 }, ... ] }, "lead_investors": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "Battery Ventures", "doc_count": 1 }, { "key": "Benchmark Capital", "doc_count": 1 }, ... ] }, "funding_amount_stats": { "count": 20, "min": 4500000, "max": 35000000, "avg": 14075000, "sum": 281500000 } }

すべての結果はこちらでご覧いただけます。

両方の戦略において、ハイブリッド検索を行うことにより、質問の構造化された部分（フィルター）とより主観的な部分（セマンティック）の両方を検出します。以下は検索テンプレートを使用した両方のクエリの例です。

await esClient.putScript({ id: INVESTMENT_FOCUSED_TEMPLATE, script: { lang: "mustache", source: `{ "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "{{query_text}}" } } } }, { "standard": { "query": { "bool": { "filter": [ {"terms": {"funding_stage": {{#join}}{{#toJson}}funding_stage{{/toJson}}{{/join}}}}, {"range": {"funding_amount": {"gte": {{funding_amount_gte}}{{#funding_amount_lte}},"lte": {{funding_amount_lte}}{{/funding_amount_lte}}}}}, {"terms": {"lead_investor": {{#join}}{{#toJson}}lead_investor{{/toJson}}{{/join}}}}, {"range": {"monthly_revenue": {"gte": {{monthly_revenue_gte}}{{#monthly_revenue_lte}},"lte": {{monthly_revenue_lte}}{{/monthly_revenue_lte}}}}} ] } } } } ], "rank_window_size": 100, "rank_constant": 20 } } }`, }, });

elasticsearchSetup.tsファイルに詳細が記載されているクエリを確認します。次のノードでは、2つのクエリのどちらを使用するかが決定されます。

// Node 1: Decide search strategy using LLM async function decideSearchStrategy(state: typeof VCState.State) { // Zod schema for specialized search strategy decision const SearchDecisionSchema = z.object({ search_type: z .enum(["investment_focused", "market_focused"]) .describe("Type of specialized search strategy to use"), reasoning: z .string() .describe("Brief explanation of why this search strategy was chosen"), }); const decisionLLM = llm.withStructuredOutput(SearchDecisionSchema); // Get dynamic filters from Elasticsearch const availableFilters = await getAvailableFilters(); const prompt = `Query: "${state.input}" Available filters: ${JSON.stringify(availableFilters, null, 2)} Choose between two specialized search strategies: - investment_focused: For queries about funding stages, funding amounts, monthly revenue, lead investors, financial performance - market_focused: For queries about industries, locations, business models, market segments, geographic markets Analyze the query intent and choose the most appropriate strategy. `; try { const result = await decisionLLM.invoke(prompt); console.log( `🤔 Search strategy: ${result.search_type} - ${result.reasoning}` ); return { searchStrategy: result.search_type, }; } catch (error: any) { console.error("❌ Error in decideSearchStrategy:", error.message); return { searchStrategy: "investment_focused", }; } }

prepareInvestmentSearchノードとprepareMarketSearchノード

どちらのノードも共有ヘルパー関数extractFilterValuesを使用します。この関数はLLMを活用して、業界、場所、資金調達段階、ビジネスモデルなど、ユーザーの入力に記載されている関連フィルターを識別します。このスキーマを使用して検索テンプレートを構築します。

// Extract all possible filter values from user input async function extractFilterValues(input: string) { const FilterValuesSchema = z.object({ // Investment-focused filters funding_stage: z .array(z.string()) .default([]) .describe("Funding stage values mentioned in query"), funding_amount_gte: z .number() .default(0) .describe("Minimum funding amount in USD"), funding_amount_lte: z .number() .default(100000000) .describe("Maximum funding amount in USD"), lead_investor: z .array(z.string()) .default([]) .describe("Lead investor values mentioned in query"), monthly_revenue_gte: z .number() .default(0) .describe("Minimum monthly revenue in USD"), monthly_revenue_lte: z .number() .default(10000000) .describe("Maximum monthly revenue in USD"), industry: z .array(z.string()) .default([]) .describe("Industry values mentioned in query"), location: z .array(z.string()) .default([]) .describe("Location values mentioned in query"), business_model: z .array(z.string()) .default([]) .describe("Business model values mentioned in query"), }); const extractorLLM = llm.withStructuredOutput(FilterValuesSchema); const availableFilters = await getAvailableFilters(); const extractPrompt = `Extract ALL relevant filter values from: "${input}" Available options: ${JSON.stringify(availableFilters, null, 2)} Extract only values explicitly mentioned in the query. Leave fields empty if not mentioned.`; return await extractorLLM.invoke(extractPrompt); }

検出された意図に応じて、ワークフローは2つのパスのいずれかを選択します。

prepareInvestmentSearch：資金調達段階、資金調達額、投資家、更新情報などの財務指向の検索パラメータを構築します。クエリテンプレート全体はelasticsearchSetup.tsファイルで確認できます。

// Node 2A: Prepare Investment-Focused Search Parameters async function prepareInvestmentSearch(state: typeof VCState.State) { console.log( "💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis..." ); try { // Extract all filter values from input const values = await extractFilterValues(state.input); let searchParams: any = { template_id: INVESTMENT_FOCUSED_TEMPLATE, query_text: state.input, ...values, }; return { searchParams }; } catch (error) { console.error("❌ Error preparing investment-focused params:", error); return { searchParams: {}, }; } }

prepareMarketSearch：業界、地域、ビジネスモデルに重点を置いた市場主導のパラメータを作成します。クエリ全文はelasticsearchSetup.tsファイルをご覧ください。

// Node 2B: Prepare Market-Focused Search Parameters async function prepareMarketSearch(state: typeof VCState.State) { console.log( "🔍 Preparing MARKET-FOCUSED search parameters with market emphasis..." ); try { // Extract all filter values from input const values = await extractFilterValues(state.input); let searchParams: any = { template_id: MARKET_FOCUSED_TEMPLATE, query_text: state.input, ...values, }; return { searchParams }; } catch (error) { console.error("❌ Error preparing market-focused params:", error); return {}; } }

executeSearchノード

このノードは、生成された検索パラメータを状態から取得し、最初にElasticsearchに送信します。次に、_render APIを使用してデバッグの目的でクエリを視覚化し、次に結果を取得するためのリクエストを送信します。

// Node 3: Execute Search async function executeSearch(state: typeof VCState.State) { const { searchParams } = state; try { // getting formed query from template for debugging const renderedTemplate = await esClient.renderSearchTemplate({ id: searchParams.template_id, params: searchParams, }); console.log( "📋 Complete query:", JSON.stringify(renderedTemplate.template_output, null, 2) ); const results = await esClient.searchTemplate({ index: INDEX_NAME, id: searchParams.template_id, params: searchParams, }); return { results: results.hits.hits.map((hit: any) => hit._source), }; } catch (error: any) { console.error(`❌ ${state.searchParams.search_type} search error:`, error); return { results: [] }; } }

visualizeResultsノード

最後に、このnodeはElasticsearchの結果を表示します。

// Node 4: Visualize results async function visualizeResults(state: typeof VCState.State) { const results = state.results || []; let formattedResults = `🎯 Found ${results.length} startups matching your criteria:\n\n`; results.forEach((startup: any, index: number) => { formattedResults += `${index + 1}. **${startup.company_name}**\n`; formattedResults += ` 📍 ${startup.location} | 🏢 ${startup.industry} | 💼 ${startup.business_model}\n`; formattedResults += ` 💰 ${startup.funding_stage} - $${( startup.funding_amount / 1000000 ).toFixed(1)}M\n`; formattedResults += ` 👥 ${startup.employee_count} employees | 📈 $${( startup.monthly_revenue / 1000 ).toFixed(0)}K MRR\n`; formattedResults += ` 🏦 Lead: ${startup.lead_investor}\n`; formattedResults += ` 📝 ${startup.description}\n\n`; }); return { final: formattedResults, }; }

プログラム的には、グラフ全体は次のようになります。

const workflow = new StateGraph(VCState) // Register nodes - these are the processing functions .addNode("decideStrategy", decideSearchStrategy) .addNode("prepareInvestment", prepareInvestmentSearch) .addNode("prepareMarket", prepareMarketSearch) .addNode("executeSearch", executeSearch) .addNode("visualizeResults", visualizeResults) // Define execution flow with conditional branching .addEdge(START, "decideStrategy") // Start with strategy decision .addConditionalEdges( "decideStrategy", (state: typeof VCState.State) => state.searchStrategy, // Conditional function { investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation market_focused: "prepareMarket", // If market focused -> dynamic query preparation } ) .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute .addEdge("prepareMarket", "executeSearch") // Market prep -> execute .addEdge("executeSearch", "visualizeResults") // Execute -> visualize .addEdge("visualizeResults", END); // End workflow

ご覧のとおり、アプリが次にどの「パス」またはノードを実行するかを決定する条件付きエッジがあります。この特徴は、ワークフローに分岐ロジックが必要な場合、例えば複数のツールから選択する場合や、人間が関与するステップを含む場合に有用です。

LangGraph のコア機能を理解したら、コードが実行されるアプリケーションをセットアップできます。

すべてをmainメソッドで組み合わせ、ここではすべての要素をワークフロー変数下のグラフとして宣言します。

async function main() { await createIndex(); await createSearchTemplates(); await ingestDocuments(); // Create the workflow graph with shared state const workflow = new StateGraph(VCState) // Register nodes - these are the processing functions .addNode("decideStrategy", decideSearchStrategy) .addNode("prepareInvestment", prepareInvestmentSearch) .addNode("prepareMarket", prepareMarketSearch) .addNode("executeSearch", executeSearch) .addNode("visualizeResults", visualizeResults) // Define execution flow with conditional branching .addEdge(START, "decideStrategy") // Start with strategy decision .addConditionalEdges( "decideStrategy", (state: typeof VCState.State) => state.searchStrategy, // Conditional function { investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation market_focused: "prepareMarket", // If market focused -> dynamic query preparation } ) .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute .addEdge("prepareMarket", "executeSearch") // Market prep -> execute .addEdge("executeSearch", "visualizeResults") // Execute -> visualize .addEdge("visualizeResults", END); // End workflow const app = workflow.compile(); await saveGraphImage(app); const query = "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"; const marketResult = await app.invoke({ input: query }); console.log(marketResult.final); }

クエリ変数は、仮想の検索バーに入力されたユーザー入力をシミュレートします。

「シリーズAまたはシリーズBの資金調達額が800万ドル～2,500万ドルで、月間収益が50万ドルを超えるスタートアップを探してください。」という自然言語フレーズから、すべてのフィルターが抽出されます。

最後にmainメソッドを呼び出します。

main().catch(console.error);

成果

🔍 Checking if index exists... 🏗️ Creating index... ✅ Index created successfully! Ingesting documents... ✅ Documents ingested successfully! ✅ Investment-focused template created successfully! ✅ Market-focused template created successfully! 📊 Workflow graph saved as: ./workflow_graph.png 🔍 Query: "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K" 🤔 Search strategy: investment_focused - The query specifically seeks profitable fintech startups with defined funding amounts and high monthly revenue, which aligns closely with financial performance metrics and investment-related criteria. 💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis... 📋 Complete query: { "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K" } } } }, { "standard": { "query": { "bool": { "filter": [ { "terms": { "funding_stage": [ "Series A", "Series B" ] } }, { "range": { "funding_amount": { "gte": 8000000, "lte": 25000000 } } }, { "terms": { "lead_investor": [] } }, { "range": { "monthly_revenue": { "gte": 500000, "lte": 0 } } } ] } } } } ], "rank_window_size": 100, "rank_constant": 20 } } } 🎯 Found 5 startups matching your criteria: 1. **TechFlow** 📍 San Francisco, CA | 🏢 logistics | 💼 B2B 💰 Series A - $8.0M 👥 45 employees | 📈 $500K MRR 🏦 Lead: Sequoia Capital 📝 TechFlow optimizes supply chain operations using AI-powered route optimization and real-time tracking. Founded in 2023, shows remarkable growth with $500K monthly revenue. 2. **DataViz** 📍 New York, NY | 🏢 enterprise software | 💼 B2B 💰 Series A - $10.0M 👥 42 employees | 📈 $450K MRR 🏦 Lead: Battery Ventures 📝 DataViz creates intuitive data visualization tools for enterprise customers. No-code platform allows business users to create dashboards without technical expertise. 3. **FinanceAI** 📍 San Francisco, CA | 🏢 fintech | 💼 B2C 💰 Series C - $25.0M 👥 120 employees | 📈 $1200K MRR 🏦 Lead: Tiger Global Management 📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users. 4. **UrbanMobility** 📍 New York, NY | 🏢 logistics | 💼 B2B2C 💰 Series B - $15.0M 👥 78 employees | 📈 $750K MRR 🏦 Lead: Kleiner Perkins 📝 UrbanMobility revolutionizes urban transportation through autonomous delivery drones and smart logistics hubs. Partners with major retailers for same-day delivery across Manhattan and Brooklyn. 5. **HealthTech Solutions** 📍 Boston, MA | 🏢 healthcare | 💼 B2B 💰 Series B - $18.0M 👥 95 employees | 📈 $900K MRR 🏦 Lead: General Catalyst 📝 HealthTech Solutions develops medical devices and software for remote patient monitoring. Comprehensive telehealth platform reducing hospital readmissions by 30%. ✨ Done in 18.80s.

送信された入力に対して、アプリケーションは投資に重点を置いたパスを選択し、その結果、ユーザー入力から値と範囲を抽出するLangGraphワークフローによって生成されたElasticsearchクエリを確認できます。また、抽出された値が適用された状態でElasticsearchに送信されたクエリと、最後にvisualizeResultsノードによって結果がフォーマットされた結果も確認できます。

次に、市場重視のノードを、クエリ「サンフランシスコ、ニューヨーク、ボストンのフィンテックおよびヘルスケアのスタートアップ企業を探してください」を使用してテストしてみましょう。

... 🔍 Query: Find fintech and healthcare startups in San Francisco, New York, or Boston 🤔 Search strategy: market_focused - The query is focused on finding fintech startups in San Francisco that are disrupting traditional banking and payment systems, which pertains to specific industries (fintech) and locations (San Francisco). Thus, a market-focused strategy is more appropriate. 🔍 Preparing MARKET-FOCUSED search parameters with market emphasis... 📋 Complete query: { "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "Find fintech and healthcare startups in San Francisco, New York, or Boston" } } } }, { "standard": { "query": { "bool": { "filter": [ { "terms": { "industry": [ "fintech", "healthcare" ] } }, { "terms": { "location": [ "San Francisco, CA", "New York, NY", "Boston, MA" ] } }, { "terms": { "business_model": [] } } ] } } } } ], "rank_window_size": 50, "rank_constant": 10 } } } 🎯 Found 5 startups matching your criteria: 1. **FinanceAI** 📍 San Francisco, CA | 🏢 fintech | 💼 B2C 💰 Series C - $25.0M 👥 120 employees | 📈 $1200K MRR 🏦 Lead: Tiger Global Management 📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users. 2. **CryptoWallet** 📍 Miami, FL | 🏢 fintech | 💼 B2C 💰 Series B - $16.0M 👥 73 employees | 📈 $820K MRR 🏦 Lead: Coinbase Ventures 📝 CryptoWallet provides secure digital wallet solutions for cryptocurrency trading and storage. Multi-chain support with enterprise-grade security features. ... ✨ Done in 7.41s.

学び

執筆の過程で次のことを学びました。

LLMにフィルターの正確な値を表示する必要があります。そうしないと、ユーザーが正確な値を入力することになります。カーディナリティが低い場合はこのアプローチで問題ありませんが、カーディナリティが高い場合は結果をフィルタリングする何らかのメカニズムが必要です。
検索テンプレートを使用すると、LLMにElasticsearchクエリを記述させるよりも結果の一貫性が大幅に向上し、速度も速くなります。
条件付きエッジは、複数のバリアントと分岐パスを持つアプリケーションを構築するための強力なメカニズムです。
構造化された出力は、予測可能でタイプセーフな応答を強制するため、LLMを使用して情報を生成する場合に非常に役立ちます。これにより、信頼性が向上し、プロンプトの誤解が減少します。

ハイブリッド検索を通じてセマンティック検索と構造化検索を組み合わせることで、精度とコンテキスト理解のバランスを保ちながら、より適切で関連性の高い結果が生成されます。

まとめ

この例では、LangGraph.jsとElasticsearchを組み合わせて、自然言語クエリをElasticsearchで検索し、金融と市場のいずれかワークフローを焦点を当てた検索戦略をワークフローで決定できる動的なワークフローを作成します。このアプローチにより、手動クエリ作成の複雑さが軽減され、ベンチャーキャピタルアナリストの柔軟性と精度が向上します。

AI搭載ダッシュボード：ビジョンからKibanaへ

Jeffrey Rengifo,Tomás Murúa — Wed, 16 Jul 2025 00:00:00 GMT

Kibana Lens を使用するとダッシュボードのドラッグアンドドロップが非常に簡単になりますが、数十個のパネルが必要な場合はクリック回数が増えてしまいます。ダッシュボードをスケッチし、スクリーンショットを撮り、LLM にプロセス全体を任せることができたらどうでしょうか?

この記事では、それを実現します。ダッシュボードのイメージを取得し、マッピングを分析し、Kibana にまったく触れることなくダッシュボードを生成するアプリケーションを作成します。

手順:

背景とアプリケーションのワークフロー

最初に思いついたのは、LLM に NDJSON 形式の Kibana保存オブジェクト全体を生成させて、それを Kibana にインポートさせることでした。

私たちはいくつかのモデルを試しました:

ジェミニ 2.5 プロ
GPT o3 / o4-ミニハイ / 4.1
クロード 4つのソネット
グロク3
ディープシーク（ディープシンク R1）

プロンプトについては、次のように単純なものから始めました。

You are an Elasticsearch Saved-Object generator (Kibana 9.0). INPUTS ===== 1. PNG screenshot of a 4-panel dashboard (attached). 2. Index mapping (below) – trimmed down to only the fields present in the screenshot. 3. Example NDJSON of *one* metric visualization (below) for reference. TASK ==== Return **only** a valid NDJSON array that recreates the dashboard exactly: * 2 metric panels (Visits, Unique Visitors) * 1 pie chart (Most used OS) * 1 vertical bar chart (State Geo Dest) * Use index pattern `kibana_sample_data_logs`. * Preserve roughly the same layout (2×2 grid). * Use `panelIndex` values 1-4 and random `id` strings. * Kibana version: 9.0

いくつかのショットの例と、各視覚化の構築方法に関する詳細な説明を確認したにもかかわらず、うまくいきませんでした。この実験に興味がある方は、こちらで詳細をご覧ください。

このアプローチの結果、LLM によって生成されたファイルを Kibana にアップロードしようとしたときに、次のメッセージが表示されました。

これは、生成された JSON が無効であるか、形式が間違っていることを意味します。最も一般的な問題は、LLM が不完全な NDJSON を生成したり、パラメータを幻覚させたり、あるいは、どれだけ強制しようとしても NDJSON ではなく通常の JSON を返したりすることでした。

この記事（検索テンプレートがLLM フリースタイルよりもうまく機能した）に触発され、完全な NDJSON ファイルを生成するように要求するのではなく、テンプレートを LLM に提供し、コード内で LLM によって提供されたパラメータを使用して適切な視覚化を作成することにしました。このアプローチは期待を裏切らず、予測可能で拡張可能です。LLM ではなくコードが重い処理を実行するようになったためです。

アプリケーションのワークフローは次のようになります。

簡潔にするために一部のコードは省略しますが、完全なアプリケーションの動作コードはこのノートブックに記載されています。

要件

開発を始める前に、次のものが必要です。

Python 3.8以上
Venv Python環境
実行中のElasticsearchインスタンス、そのエンドポイント、APIキー
環境変数名 OPENAI_API_KEY に保存された OpenAI API キー:

export OPENAI_API_KEY="your-openai-api-key"

データを準備する

データについては、シンプルさを保ち、Elastic のサンプル Web ログを使用します。ここで、そのデータをクラスターにインポートする方法を学習できます。

各ドキュメントには、アプリケーションにリクエストを発行したホストの詳細と、リクエスト自体とその応答ステータスに関する情報が含まれています。以下にサンプル文書を示します。

{ "agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24", "bytes": 8509, "clientip": "70.133.115.149", "extension": "css", "geo": { "srcdest": "US:IT", "src": "US", "dest": "IT", "coordinates": { "lat": 38.05134111, "lon": -103.5106908 } }, "host": "cdn.elastic-elastic-elastic.org", "index": "kibana_sample_data_logs", "ip": "70.133.115.149", "machine": { "ram": 5368709120, "os": "osx" }, "memory": null, "message": "70.133.115.149 - - [2018-08-30T23:35:31.492Z] \"GET /styles/semantic-ui.css HTTP/1.1\" 200 8509 \"-\" \"Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24\"", "phpmemory": null, "referer": "http://twitter.com/error/john-phillips", "request": "/styles/semantic-ui.css", "response": 200, "tags": [ "success", "info" ], "@timestamp": "2025-07-03T23:35:31.492Z", "url": "https://cdn.elastic-elastic-elastic.org/styles/semantic-ui.css", "utc_time": "2025-07-03T23:35:31.492Z", "event": { "dataset": "sample_web_logs" }, "bytes_gauge": 8509, "bytes_counter": 51201128 }

ここで、先ほどロードしたインデックスkibana_sample_data_logsのマッピングを取得しましょう。

INDEX_NAME = "kibana_sample_data_logs" es_client = Elasticsearch( [os.getenv("ELASTICSEARCH_URL")], api_key=os.getenv("ELASTICSEARCH_API_KEY"), ) result = es_client.indices.get_mapping(index=INDEX_NAME) index_mappings = result[list(result.keys())[0]]["mappings"]["properties"]

後で読み込むイメージと一緒にマッピングを渡します。

LLM構成

構造化出力を使用して画像を入力し、JSON オブジェクトを生成するために関数に渡す必要がある情報を含む JSON を受け取るように LLM を構成しましょう。

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

pip install elasticsearch pydantic langchain langchain-openai -q

Elasticsearch はインデックスマッピングの取得に役立ちます。Pydantic を使用すると、Python でスキーマを定義して LLM に従うように要求することができ、 LangChain はLLM と AI ツールの呼び出しを容易にするフレームワークです。

LLM から必要な出力を定義するために、Pydantic スキーマを作成します。画像からわかる必要があるのは、グラフの種類、フィールド、視覚化タイトル、ダッシュボードタイトルです。

class Visualization(BaseModel): title: str = Field(description="The dashboard title") type: List[Literal["pie", "bar", "metric"]] field: str = Field( description="The field that this visualization use based on the provided mappings" ) class Dashboard(BaseModel): title: str = Field(description="The dashboard title") visualizations: List[Visualization]

画像入力には、先ほど描いたダッシュボードを送信します。

ここで、LLM モデルの呼び出しとイメージの読み込みを宣言します。この関数は、Elasticsearch インデックスのマッピングと、生成するダッシュボードの画像を受け取ります。

with_structured_outputを使用すると、Pydantic Dashboardスキーマを LLM が生成する応答オブジェクトとして使用できます。Pydanticを使用すると、検証付きのデータモデルを定義できるため、LLM 出力が期待される構造と一致することが保証されます。

画像を base64 に変換して入力として送信するには、オンラインコンバーターを使用するか、コードで実行します。

prompt = f""" You are an expert in analyzing Kibana dashboards from images for the version 9.0.0 of Kibana. You will be given a dashboard image and an Elasticsearch index mapping. Below are the index mappings for the index that the dashboard is based on. Use this to help you understand the data and the fields that are available. Index Mappings: {index_mappings} Only include the fields that are relevant for each visualization, based on what is visible in the image. """ message = [ { "role": "user", "content": [ {"type": "text", "text": prompt}, { "type": "image", "source_type": "base64", "data": image_base64, "mime_type": "image/png", }, ], } ] try: llm = init_chat_model("gpt-4.1-mini") llm = llm.with_structured_output(Dashboard) dashboard_values = llm.invoke(message) print("Dashboard values generated by the LLM successfully") print(dashboard_values) except Exception as e: print(f"Failed to analyze image and match fields: {str(e)}")

LLM にはすでに Kibana ダッシュボードに関するコンテキストがあるため、プロンプトですべてを説明する必要はなく、Elasticsearch と Kibana で動作していることを忘れないようにするための詳細のみを説明します。

プロンプトを分解してみましょう:

セクション

理由

あなたは、Kibana バージョン 9.0.0 の画像から Kibana ダッシュボードを分析するエキスパートです。

これを Elasticsearch と Elasticsearch バージョンで強化することで、LLM が古い/無効なパラメータを幻覚する可能性を減らします。

ダッシュボードイメージと Elasticsearch インデックスマッピングが提供されます。

LLM による誤った解釈を避けるために、この画像はダッシュボードに関するものであることを説明します。

以下は、ダッシュボードのベースとなるインデックスのインデックスマッピングです。これを使用すると、使用可能なデータとフィールドを理解するのに役立ちます。インデックスマッピング: {index_mappings}

LLM が有効なフィールドを動的に選択できるようにマッピングを提供することが重要です。そうしないと、ここでのマッピングをハードコードすることになり、厳しすぎることになります。あるいは、正しいフィールド名を含むイメージに依存することになりますが、これは信頼できません。

画像に表示されている内容に基づいて、各視覚化に関連するフィールドのみを含めます。

画像に関係のないフィールドを追加しようとすることがあるため、この強化を追加する必要がありました。

これにより、表示する視覚化の配列を含むオブジェクトが返されます。

"Dashboard values generated by the LLM successfully title=""Client, Extension, OS, and Response Keyword Analysis""visualizations="[ "Visualization(title=""Count of Client IP", "type="[ "metric" ], "field=""clientip"")", "Visualization(title=""Extension Keyword Distribution", "type="[ "pie" ], "field=""extension.keyword"")", "Visualization(title=""Most Used OS", "type="[ "bar" ], "field=""machine.os.keyword"")", "Visualization(title=""Response Keyword Distribution", "type="[ "bar" ], "field=""response.keyword"")" ]

LLM応答の処理

私たちはサンプルの 2x2 パネルダッシュボードを作成し、 Get a dashboard API を使用して JSON 形式でエクスポートしました。その後、パネルを視覚化テンプレート (円グラフ、棒グラフ、メトリック) として保存し、いくつかのパラメータを置き換えて、質問に応じて異なるフィールドを持つ新しい視覚化を作成できます。

テンプレート JSON ファイルはここで確認できます。後で置き換えたいオブジェクトの値を {variable_name} に変更したことに注意してください。

LLM が提供した情報を使用して、どのテンプレートを使用し、どの値を置き換えるかを決定できます。

fill_template_with_analysis 視覚化の JSON テンプレート、タイトル、フィールド、グリッド上の視覚化の座標など、単一のパネルのパラメータを受け取ります。

次に、テンプレートの値を置き換えて、最終的な JSON 視覚化を返します。

def fill_template_with_analysis( template: Dict[str, Any], visualization: Visualization, grid_data: Dict[str, Any], ): template_str = json.dumps(template) replacements = { "{visualization_id}": str(uuid.uuid4()), "{title}": visualization.title, "{x}": grid_data["x"], "{y}": grid_data["y"], } if visualization.field: replacements["{field}"] = visualization.field for placeholder, value in replacements.items(): template_str = template_str.replace(placeholder, str(value)) return json.loads(template_str)

簡単にするために、LLM が作成することを決定したパネルに割り当てる静的座標があり、上の画像のように 2x2 グリッドダッシュボードが生成されます。

# Filling templates fields panels = [] grid_data = [ {"x": 0, "y": 0}, {"x": 12, "y": 0}, {"x": 0, "y": 12}, {"x": 12, "y": 12}, ] i = 0 for vis in dashboard_values.visualizations: for vis_type in vis.type: template = templates.get(vis_type, templates.get("bar", {})) filled_panel = fill_template_with_analysis(template, vis, grid_data[i]) panels.append(filled_panel) i += 1

LLM によって決定された視覚化タイプに応じて、JSON ファイルテンプレートを選択し、 fill_template_with_analysisを使用して関連情報を置き換え、後でダッシュボードを作成するために使用する配列に新しいパネルを追加します。

ダッシュボードの準備ができたら、ダッシュボードの作成 APIを使用して新しい JSON ファイルを Kibana にプッシュし、ダッシュボードを生成します。

try: dashboard_id = str(uuid.uuid4()) # post request to create the dashboard endpoint url = f"{os.getenv('KIBANA_URL')}/api/dashboards/dashboard/{dashboard_id}" dashboard_config = { "attributes": { "title": dashboard_values.title, "description": "Generated by AI", "timeRestore": True, "panels": panels, # Visualizations with the values generated by the LLM "timeFrom": "now-7d/d", "timeTo": "now", }, } headers = { "Content-Type": "application/json", "kbn-xsrf": "true", "Authorization": f"ApiKey {os.getenv('ELASTICSEARCH_API_KEY')}", } requests.post( url, headers=headers, json=dashboard_config, ) # Url to the generated dashboard dashboard_url = f"{os.getenv('KIBANA_URL')}/app/dashboards#/view/{dashboard_id}" print("Dashboard URL: ", dashboard_url) print("Dashboard ID: ", dashboard_id) except Exception as e: print(f"Failed to create dashboard: {str(e)}")

スクリプトを実行してダッシュボードを生成するには、コンソールで次のコマンドを実行します。

python .py

最終結果は次のようになります。

まとめ

LLM は、テキストをコード化したり、画像をコード化したりするときに、強力な視覚機能を発揮します。ダッシュボード API を使用すると、JSON ファイルをダッシュボードに変換することも可能で、LLM といくつかのコードを使用して、画像を Kibana ダッシュボードに変換することもできます。

次のステップは、さまざまなグリッド設定、ダッシュボードのサイズ、位置を使用して、ダッシュボードのビジュアルの柔軟性を向上させることです。また、より複雑な視覚化と視覚化タイプのサポートを提供することも、このアプリケーションにとって便利な追加機能となるでしょう。

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 クライアントを実行する方法について学習します。

Ollama を推論 API と共に使用する

Jeffrey Rengifo — Fri, 14 Feb 2025 00:00:00 GMT

この記事では、Ollama を使用してローカルモデルを Elasticsearch 推論モデルに接続し、Playground を使用してドキュメントに質問する方法を学習します。

Elasticsearch を使用すると、ユーザーは Open Inference APIを使用して LLM に接続でき、Amazon Bedrock、Cohere、Google AI、Azure AI Studio、HuggingFace などのプロバイダーをサービスとしてサポートします。

Ollama は、独自のインフラストラクチャ (ローカルマシン/サーバー) を使用して LLM モデルをダウンロードおよび実行できるツールです。ここでは、Ollama と互換性のある利用可能なモデルのリストを見つけることができます。

Ollama は、各モデルをセットアップする方法の違いや、モデル関数にアクセスするための API の作成方法について心配することなく、さまざまなオープンソースモデルをホストしてテストしたい場合に最適なオプションです。Ollama がすべてを処理します。

Ollama API は OpenAI API と互換性があるため、推論モデルを簡単に統合し、Playground を使用して RAG アプリケーションを作成できます。

要件

エラスティックサーチ 8.17
キバナ 8.17
Python

ステップ

Ollama LLMサーバーのセットアップ

Ollama を使用して、LLM サーバーを設定し、Playground インスタンスに接続します。以下のことが必要です:

Ollamaをダウンロードして実行します。
ngrokを使用して、インターネット経由でOllamaをホストするローカルWebサーバーにアクセスします。

Ollamaをダウンロードして実行する

Ollama を使用するには、まずダウンロードする必要があります。Ollama は Linux、Windows、macOS をサポートしているので、ここからお使いの OS と互換性のある Ollama バージョンをダウンロードしてください。Ollama がインストールされると、サポートされている LLM のリストからモデルを選択できます。この例では、汎用多言語モデルであるllama3.2モデルを使用します。セットアッププロセスでは、Ollama のコマンドラインツールを有効にします。ダウンロードが完了したら、次の行を実行できます。

ollama pull llama3.2

出力は次のようになります:

pulling manifest pulling dde5aa3fc5ff... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 2.0 GB pulling 966de95ca8a6... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 1.4 KB pulling fcc5a6bec9da... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 7.7 KB pulling a70ff7e570d9... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 6.0 KB pulling 56bb8bd477a5... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 96 B pulling 34bb5ab01051... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 561 B verifying sha256 digest writing manifest success

インストールしたら、次のコマンドでテストできます。

ollama run llama3.2

質問してみましょう:

モデルを実行すると、Ollama はポート「11434」でデフォルトで実行される API を有効にします。公式ドキュメントに従って、その API にリクエストを送信してみましょう。

curl http://localhost:11434/api/generate -d '{ "model": "llama3.2", "prompt": "What is the capital of France?" }'

私たちが受け取った回答は次のとおりです。

{"model":"llama3.2","created_at":"2024-11-28T21:48:42.152817532Z","response":"The","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.251884485Z","response":" capital","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.347365913Z","response":" of","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.446837322Z","response":" France","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.542367394Z","response":" is","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.644580384Z","response":" Paris","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.739865362Z","response":".","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.834347518Z","response":"","done":true,"done_reason":"stop","context":[128006,9125,128007,271,38766,1303,33025,2696,25,6790,220,2366,18,271,128009,128006,882,128007,271,3923,374,279,6864,315,9822,30,128009,128006,78191,128007,271,791,6864,315,9822,374,12366,13],"total_duration":6948567145,"load_duration":4386106503,"prompt_eval_count":32,"prompt_eval_duration":1872000000,"eval_count":8,"eval_duration":684000000}

このエンドポイントの特定の応答はストリーミングであることに注意してください。

ngrokを使用してエンドポイントをインターネットに公開する

エンドポイントはローカル環境で動作するため、Elastic Cloud インスタンスなどの別のポイントからインターネット経由でアクセスすることはできません。ngrok を使用すると、パブリック IP を提供するポートを公開できます。ngrok でアカウントを作成し、公式のセットアップガイドに従ってください。

ngrok エージェントをインストールして構成したら、Ollama が使用しているポートを公開できます。

ngrok http 11434 --host-header="localhost:11434"

注: ヘッダー--host-header="localhost:11434"は、リクエスト内の「Host」ヘッダーが「localhost:11434」と一致することを保証します。

このコマンドを実行すると、ngrok と Ollama サーバーがローカルで実行されている限り機能するパブリックリンクが返されます。

Session Status online Account xxxx@yourEmailProvider.com (Plan: Free) Version 3.18.4 Region United States (us) Latency 561ms Web Interface http://127.0.0.1:4040 Forwarding https://your-ngrok-url.ngrok-free.app -> http://localhost:11434 Connections ttl opn rt1 rt5 p50 p90 0 0 0.00 0.00 0.00 0.00 ```

「転送」では、ngrok が URL を生成したことがわかります。後で使用するために保存します。

ngrok によって生成された URL を使用して、エンドポイントへの HTTP リクエストを再度実行してみましょう。

curl https://your-ngrok-endpoint.ngrok-free.app/api/generate -d '{ "model": "llama3.2", "prompt": "What is the capital of France?" }'

応答は前のものと同様になるはずです。

マッピングの作成

ELSERエンドポイント

この例では、 Elasticsearch 推論 API を使用して推論エンドポイントを作成します。さらに、 ELSERを使用して埋め込みを生成します。

PUT _inference/sparse_embedding/medicines-inference { "service": "elasticsearch", "service_settings": { "num_allocations": 1, "num_threads": 1, "model_id": ".elser_model_2_linux-x86_64" } }

この例では、2 種類の薬を販売する薬局があるとします。

処方箋が必要な医薬品。
処方箋を必要としない医薬品。

この情報は各薬剤の説明欄に含まれます。

LLM はこのフィールドを解釈する必要があるため、次のデータマッピングを使用します。

PUT medicines { "mappings": { "properties": { "name": { "type": "text", "copy_to": "semantic_field" }, "semantic_field": { "type": "semantic_text", "inference_id": "medicines-inference" }, "text_description": { "type": "text", "copy_to": "semantic_field" } } } }

フィールドtext_descriptionは説明のプレーンテキストが格納され、 semantic_textフィールドタイプであるsemantic_fieldには ELSER によって生成された埋め込みが格納されます。

プロパティcopy_to は、フィールド名とtext_descriptionの内容をセマンティックフィールドにコピーし、それらのフィールドの埋め込みが生成されます。

データのインデックス作成

ここで、 _bulk APIを使用してデータをインデックス化してみましょう。

POST _bulk {"index":{"_index":"medicines"}} {"id":1,"name":"Paracetamol","text_description":"An analgesic and antipyretic that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":2,"name":"Ibuprofen","text_description":"A nonsteroidal anti-inflammatory drug (NSAID) available WITHOUT a prescription."} {"index":{"_index":"medicines"}} {"id":3,"name":"Amoxicillin","text_description":"An antibiotic that requires a prescription."} {"index":{"_index":"medicines"}} {"id":4,"name":"Lorazepam","text_description":"An anxiolytic medication that strictly requires a prescription."} {"index":{"_index":"medicines"}} {"id":5,"name":"Omeprazole","text_description":"A medication for stomach acidity that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":6,"name":"Insulin","text_description":"A hormone used in diabetes treatment that requires a prescription."} {"index":{"_index":"medicines"}} {"id":7,"name":"Cold Medicine","text_description":"A compound formula to relieve flu symptoms available WITHOUT a prescription."} {"index":{"_index":"medicines"}} {"id":8,"name":"Clonazepam","text_description":"An antiepileptic medication that requires a prescription."} {"index":{"_index":"medicines"}} {"id":9,"name":"Vitamin C","text_description":"A dietary supplement that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":10,"name":"Metformin","text_description":"A medication used for type 2 diabetes that requires a prescription."}

対応：

{ "errors": false, "took": 34732020848, "items": [ { "index": { "_index": "medicines", "_id": "mYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 0, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "mooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 1, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "m4oeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 2, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nIoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 3, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 4, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 5, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "n4oeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 6, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oIoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 7, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 8, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 9, "_primary_term": 1, "status": 201 } } ] }

Playgroundを使って質問する

Playground は、Elasticsearch インデックスと LLM プロバイダーを使用して RAG システムをすばやく作成できる Kibana ツールです。詳細については、この記事をお読みください。

ローカルLLMをPlaygroundに接続する

まず、作成したパブリック URL を使用するコネクタを作成する必要があります。Kibana で、 「検索」>「プレイグラウンド」に移動し、「LLM に接続」をクリックします。

このアクションにより、Kibana インターフェースの左側にメニューが表示されます。そこで、「OpenAI」をクリックします。

これで、OpenAI コネクタの設定を開始できます。

「コネクタ設定」に移動し、OpenAI プロバイダーの場合は「その他 (OpenAI 互換サービス)」を選択します。

次に、他のフィールドを設定しましょう。この例では、モデル名を「medicines-llm」とします。URLフィールドには、ngrokによって生成されたURL（/v1/chat/completions）を入力します。「デフォルトモデル」フィールドで、「llama3.2」を選択します。API キーは使用しないので、任意のテキストを入力して続行します。

「保存」をクリックし、「データソースの追加」をクリックしてインデックス医薬品を追加します。

素晴らしい！これで、RAG エンジンとしてローカルで実行している LLM を使用して Playground にアクセスできるようになりました。

テストする前に、エージェントにさらに具体的な指示を追加し、モデルに送信されるドキュメントの数を 10 に増やして、回答にできるだけ多くのドキュメントが含まれるようにします。コンテキストフィールドはsemantic_fieldになり、copy_to プロパティにより、薬剤の名前と説明が含まれます。

さて、質問しましょう：処方箋なしでクロナゼパムを購入できますか？そして何が起こるか見てみましょう:

予想通り、正しい答えが得られました。

今後の見通し

次のステップは、独自のアプリケーションを作成することです。Playground は、マシン上で実行し、ニーズに合わせてカスタマイズできる Python のコードスクリプトを提供します。たとえば、 FastAPIサーバーの背後に配置して、UI で使用される QA 医薬品チャットボットを作成します。

このコードは、Playground の右上のセクションにある[コードの表示]ボタンをクリックすると見つかります。

また、エンドポイントと API キーを使用して、コードで必要なES_API_KEY環境変数を生成します。

この特定の例では、コードは次のようになります。

## Install the required packages ## pip install -qU elasticsearch openai import os from elasticsearch import Elasticsearch from openai import OpenAI es_client = Elasticsearch( "https://your-deployment.us-central1.gcp.cloud.es.io:443", api_key=os.environ["ES_API_KEY"] ) openai_client = OpenAI( api_key=os.environ["OPENAI_API_KEY"], ) index_source_fields = { "medicines": [ "semantic_field" ] } def get_elasticsearch_results(): es_query = { "retriever": { "standard": { "query": { "nested": { "path": "semantic_field.inference.chunks", "query": { "sparse_vector": { "inference_id": "medicines-inference", "field": "semantic_field.inference.chunks.embeddings", "query": query } }, "inner_hits": { "size": 2, "name": "medicines.semantic_field", "_source": [ "semantic_field.inference.chunks.text" ] } } } } }, "size": 3 } result = es_client.search(index="medicines", body=es_query) return result["hits"]["hits"] def create_openai_prompt(results): context = "" for hit in results: inner_hit_path = f"{hit['_index']}.{index_source_fields.get(hit['_index'])[0]}" ## For semantic_text matches, we need to extract the text from the inner_hits if 'inner_hits' in hit and inner_hit_path in hit['inner_hits']: context += '\n --- \n'.join(inner_hit['_source']['text'] for inner_hit in hit['inner_hits'][inner_hit_path]['hits']['hits']) else: source_field = index_source_fields.get(hit["_index"])[0] hit_context = hit["_source"][source_field] context += f"{hit_context}\n" prompt = f""" Instructions: - You are an assistant specializing in answering questions about the sale of medicines. - Answer questions truthfully and factually using only the context presented. - If you don't know the answer, just say that you don't know, don't make up an answer. - You must always cite the document where the answer was extracted using inline academic citation style [], using the position. - Use markdown format for code examples. - You are correct, factual, precise, and reliable. Context: {context} """ return prompt def generate_openai_completion(user_prompt, question): response = openai_client.chat.completions.create( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": user_prompt}, {"role": "user", "content": question}, ] ) return response.choices[0].message.content if __name__ == "__main__": question = "my question" elasticsearch_results = get_elasticsearch_results() context_prompt = create_openai_prompt(elasticsearch_results) openai_completion = generate_openai_completion(context_prompt, question) print(openai_completion)

Ollama で動作させるには、OpenAI クライアントを OpenAI サーバーではなく Ollama サーバーに接続するように変更する必要があります。OpenAI の例と互換性のあるエンドポイントの完全なリストについては、こちらをご覧ください。

openai_client = OpenAI( # you can use http://localhost:11434/v1/ if running this code locally. base_url='https://your-ngrok-url.ngrok-free.app/v1/', # required but ignored api_key='ollama', )

また、補完メソッドを呼び出すときにモデルを llama3.2 に変更します。

def generate_openai_completion(user_prompt, question): response = openai_client.chat.completions.create( model="llama3.2", messages=[ {"role": "system", "content": user_prompt}, {"role": "user", "content": question}, ] ) return response.choices[0].message.content

質問を追加しましょう:処方箋なしでクロナゼパムを購入できますか?Elasticsearch クエリへ:

def get_elasticsearch_results(): es_query = { "retriever": { "standard": { "query": { "nested": { "path": "semantic_field.inference.chunks", "query": { "sparse_vector": { "inference_id": "medicines-inference", "field": "semantic_field.inference.chunks.embeddings", "query": "Can I buy Clonazepam without a prescription?" } }, "inner_hits": { "size": 2, "name": "medicines.semantic_field", "_source": [ "semantic_field.inference.chunks.text" ] } } } } }, "size": 3 } result = es_client.search(index="medicines", body=es_query) return result["hits"]["hits"]

また、いくつかの出力を伴う完了呼び出しでは、質問のコンテキストの一部として Elasticsearch の結果が送信されていることを確認できます。

if __name__ == "__main__": question = "Can I buy Clonazepam without a prescription?" elasticsearch_results = get_elasticsearch_results() context_prompt = create_openai_prompt(elasticsearch_results) print("========== Context Prompt START ==========") print(context_prompt) print("========== Context Prompt END ==========") print("========== Ollama Completion START ==========") openai_completion = generate_openai_completion(context_prompt, question) print(openai_completion) print("========== Ollama Completion END ==========")

ではコマンドを実行してみましょう

pip install -qU elasticsearch openai

python main.py

次のような画面が表示されます。

========== Context Prompt START ========== Instructions: - You are an assistant specializing in answering questions about the sale of medicines. - Answer questions truthfully and factually using only the context presented. - If you don't know the answer, just say that you don't know, don't make up an answer. - You must always cite the document where the answer was extracted using inline academic citation style [], using the position. - Use markdown format for code examples. - You are correct, factual, precise, and reliable. Context: Clonazepam --- An antiepileptic medication that requires a prescription.A nonsteroidal anti-inflammatory drug (NSAID) available WITHOUT a prescription. --- IbuprofenAn anxiolytic medication that strictly requires a prescription. --- Lorazepam ========== Context Prompt END ========== ========== Ollama Completion START ========== No, you cannot buy Clonazepam over-the-counter (OTC) without a prescription [1]. It is classified as a controlled substance in the United States due to its potential for dependence and abuse. Therefore, it can only be obtained from a licensed healthcare provider who will issue a prescription for this medication. ========== Ollama Completion END ==========

まとめ

この記事では、Ollama などのツールを Elasticsearch 推論 API および Playground と組み合わせて使用した場合の、その強力さと汎用性について説明します。

いくつかの簡単な手順を実行するだけで、LLM を使用したチャット機能を備えた RAG アプリケーションが、コストゼロで独自のインフラストラクチャで稼働するようになりました。これにより、さまざまなタスクのさまざまなモデルにアクセスできるだけでなく、リソースと機密情報をより細かく制御できるようになります。