IntraIntel.ai - Multi-LLM Agent Coding Challenge

CliniSearch - 医療検索向けマルチLLMエージェント

このプロジェクトは、医療に関する質問に回答するために設計された、Python 製のマルチLLMエージェントシステムを実装しています。独自の Model Context Protocol（MCP）を活用し、情報検索（Web 検索と PubMed 検索）を行う個別のツールサーバーと連携します。中核となるエージェントは、Hugging Face Inference API から利用できる複数の無料 LLM を統括し、検索クエリの調整、コンテキストのスニペットの要約、検索拡張生成（RAG）による最終回答の統合などのタスクを実行します。このシステムは、Web 検索と PubMed から取得したコンテキストに基づいて、それぞれ個別に回答を統合し、元の資料へのリンクを含めて提示するように設計されています。

動画デモへのリンク

https://youtu.be/JvFvCYFYpzU?si=Vho8MM5Dy7YQk53E

システムアーキテクチャ

Hugging Face API の無料プランで使用する2つのLLMモデル：distillbart と mistral instruct

中核となるアプローチと設計

このシステムは、複数のステップで構成されるエージェント型 RAG パイプラインに従います。

1. ユーザー入力： エージェントはユーザーから医療に関する質問を受け取ります。
2. （任意）クエリの調整（LLM1）： ユーザーの質問を最初の LLM（例：mistralai/Mistral-7B-Instruct-v0.3）に渡し、重要な医療用語に焦点を当てた、より簡潔で効果的な検索クエリを生成できます。
3. 情報検索（MCP ツール）：
   • 調整された（または元の）検索クエリを、一方または両方の MCP ツールサーバーに送信します。
     • Web 検索 MCP サーバー： duckduckgo-search を使用して一般の Web を検索します。
     • PubMed MCP サーバー： BioPython の Entrez ユーティリティを使用して PubMed データベースを検索します。
   • これらのサーバーは、構造化された検索結果（タイトル、スニペット、URL／ID）を返します。
4. コンテキストの処理：
   • （任意）スニペットの要約（LLM2）： 検索結果ごとに、スニペットが長い場合は、専用の要約用 LLM（例：sshleifer/distilbart-cnn-6-6）に渡して、より簡潔な内容にできます。
   • コンテキストの整形： 各ソース（Web 検索、PubMed）のスニペット（要約済みまたは元の内容）を、個別に構造化されたコンテキスト文字列に整形します。コンテキスト内の各項目にはラベル（例：「項目 1」）を付け、タイトル、内容、参照先（URL または PubMed ID）を含めます。
5. 回答の統合（LLM3 - RAG）：
   • 各情報ソース（Web 検索、PubMed）について、エージェントは高性能な指示調整済み LLM（例：mistralai/Mistral-7B-Instruct-v0.3）を個別に呼び出します。
   • この LLM へのプロンプトには、次の内容を含めます。
     • 元のユーザーの質問。
     • その特定のソースから取得した整形済みコンテキスト。
     • 提供されたコンテキストのみに基づいて回答し、可能であれば項目番号を引用するよう指示する内容。
   • この LLM は、そのソースに対する回答を統合して生成します。
6. 出力： システムは、元の質問に続いて、Web 検索から得られた統合回答（ソースへのリンク付き）、次に PubMed から得られた統合回答（ソースへのリンク付き）を提示します。

主要なテクノロジー：

• Python 3.9+ と、並行処理のための asyncio。
• FastAPI と Uvicorn： 非同期 MCP ツールサーバーの構築に使用します。
• httpx： エージェントから MCP サーバーおよび Hugging Face API への非同期 HTTP リクエストに使用します。
• Hugging Face Inference API： 調整、要約、統合に無料の LLM を利用します。
• duckduckgo-search： API キー不要の Web 検索に使用します。
• BioPython： NCBI の PubMed データベースの検索に使用します。
• python-dotenv： API キーと環境変数の管理に使用します。

Model Context Protocol（MCP）の定義

このプロジェクトで使用する MCP は、メインエージェントとツールサーバー間の通信に使用する、シンプルな HTTP ベースの JSON プロトコルです。

• MCP サーバーへのリクエスト：
  • エンドポイント： POST /execute
  • JSON ボディ： {"query": "user's search query string"}
• MCP サーバーからのレスポンス：
  • JSON ボディ（成功時）：

    {
      "source": "server_name_string (e.g., WebSearchServer, PubMedServer)",
      "status": "success",
      "results": [
        {
          "title": "string",
          "snippet": "string",
          "url": "string_url_if_web_search", // or missing
          "id": "string_pubmed_id_if_pubmed" // or missing
        }
        // ... more results
      ]
    }
    

  • JSON ボディ（エラー時）：

    {
      "source": "server_name_string",
      "status": "error",
      "error_message": "string_describing_the_error"
    }
    

セットアップ手順

1. クローン／ダウンロード：

   • プロジェクトファイルを取得し、intra_intel_multi_llm_challenge という名前のディレクトリに配置します。

2. Python 仮想環境の作成と有効化：

   • プロジェクトのルートディレクトリ（intra_intel_multi_llm_challenge）に移動します。
   • 環境を作成します：

     python -m venv venv
     

   • 有効化します：
     • macOS/Linux の場合：source venv/bin/activate
     • Windows の場合：venv\Scripts\activate

3. 依存関係のインストール：

   pip install -r requirements.txt
   

4. 環境変数の設定：

   • プロジェクトのルートで、.env.example ファイルを .env という名前の新しいファイルにコピーします。
   • .env ファイルを開き、必要な情報を入力します：

     # .env
     HF_API_TOKEN="your_huggingface_api_token_here"
     NCBI_EMAIL="[email protected]"
     

     • HF_API_TOKEN： Hugging Face アカウント設定（https://huggingface.co/settings/tokens）から取得します。read 権限を持つトークンで十分です。
     • NCBI_EMAIL： Entrez 経由で NCBI の PubMed データベースにプログラムから適切にアクセスするためのメールアドレスを指定します。このプロジェクトでは、事前にこのメールアドレスを NCBI に登録する必要はありません。

5. ゲート付きモデルの利用規約への同意（Mistral では必須）：

   • デフォルトで使用されるテキスト生成 LLM は mistralai/Mistral-7B-Instruct-v0.3 です。これはゲート付きモデルです。
   • Hugging Face のウェブサイトでアカウントにログインします。
   • モデルカードのページに移動します：https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.3
   • このモデルへのアクセス権を得るため、ライセンス条項を確認して同意します。これにより、HF_API_TOKEN を使ってモデルを利用できるようになります。この手順を省略すると、このモデルへの API 呼び出しは失敗します。

システムの実行

メインエージェントが MCP サーバーにクエリを送信する前に、MCP サーバーを起動しておく必要があります。

1. ターミナル 1：Web Search MCP Server を起動します：

   • プロジェクトのルート（intra_intel_multi_llm_challenge）に移動します。
   • 仮想環境が有効になっていることを確認します。
   • 次を実行します：

     python -m uvicorn mcp_servers.web_search_server:app --reload --port 8001
     

   • Uvicorn が実行中であることを示すメッセージが表示されるまで待ちます（例：Uvicorn running on http://0.0.0.0:8001）。

2. ターミナル 2：PubMed MCP Server を起動します（ボーナス機能用）：

   • プロジェクトのルートに移動します。
   • 仮想環境が有効になっていることを確認します。
   • 次を実行します：

     python -m uvicorn mcp_servers.pubmed_search_server:app --reload --port 8002
     

   • Uvicorn の起動確認メッセージが表示されるまで待ちます。

3. ターミナル 3：メインエージェントを実行します：

   • プロジェクトのルートに移動します。
   • 仮想環境が有効になっていることを確認します。
   • 次を実行します：

     python agent/main_agent.py
     

   • エージェントは、あらかじめ定義された5つの医学的な質問を処理します。各質問について、次の処理を行います：
     • 必要に応じて、LLM1 を使用してクエリを改善します。
     • Web Search MCP サーバーにクエリを送信します。
     • 必要に応じて、LLM2 を使用してウェブ検索のスニペットを要約します。
     • LLM3 を使用して、ウェブ検索のコンテキストに基づく回答を作成します。
     • ウェブ検索に基づく回答とそのソースリンクを出力します。
     • PubMed MCP サーバーにクエリを送信します（例では、デフォルトで use_pubmed_for_this_question が True に設定されています）。
     • 必要に応じて、LLM2 を使用して PubMed のスニペットを要約します。
     • LLM3 を使用して、PubMed のコンテキストに基づく回答を作成します。
     • PubMed に基づく回答とそのソースリンクを出力します。
   • Hugging Face API のレート制限に配慮するため、各質問の処理の間に一時停止します。

   Hugging Face API でのモデル読み込みに関する注意： Inference API 経由で初めて LLM を呼び出すときは、Hugging Face によるモデルの読み込みが必要になる場合があり、20～90秒（Mistral-7B のような大規模モデルではさらに長くなることがあります）かかることがあります。2回目以降の呼び出しは通常、より速くなります。このスクリプトにはタイムアウトが設定されており、モデル読み込みメッセージへの対応も試みます。

カスタマイズとデバッグ

• LLM の選択： Hugging Face の無料 Inference API で、より適切に動作するモデルや、より安定して利用できるモデルが見つかった場合は、agent/main_agent.py の VERIFIED_INSTRUCT_MODEL_ID と SUMMARIZATION_MODEL_ID を変更できます（必ず最初にモデルのカードページにあるウィジェットで確認してください！）。
• 機能の切り替え： agent/main_agent.py の if __name__ == "__main__": ブロックで、main_agent_workflow に渡される refine_queries と summarize_snippets のブール値フラグを変更すると、これらのステップを有効または無効にしてパイプラインをテストできます。呼び出しごとに use_pubmed_for_this_question を変更することもできます。
• 詳細なログ出力： 詳細なデバッグ情報（API ペイロード、完全なコンテキストなど）を表示するには：
  1. agent/main_agent.py を開きます。
  2. LOG_LEVEL = logging.INFO を LOG_LEVEL = logging.DEBUG に変更します。
  3. 保存してエージェントを再実行します。

依存関係

主な依存関係は requirements.txt に記載されています：

• fastapi：MCP サーバーの構築に使用します。
• uvicorn[standard]：FastAPI 用の ASGI サーバーです。
• httpx：非同期 HTTP リクエストの送信に使用します。
• duckduckgo-search：ウェブ検索機能に使用します。
• biopython：NCBI Entrez 経由で PubMed にクエリを送信するために使用します。
• python-dotenv：環境変数の管理に使用します。

この README では、プロジェクトの理解、セットアップ、実行に必要な情報を網羅しています。

医学的な質問の出力例のスクリーンショット

ウェブ検索

Pubmed 検索