Where On-Device and Cloud LLMs Meet

オンデバイス LLM とクラウド LLM が出会う場所

これは何ですか？ Minions は、オンデバイスの小型モデルがクラウド上の最先端モデルと協調できるようにする通信プロトコルです。長いコンテキストをローカルで読み取るだけで、品質をほとんど、またはまったく低下させずにクラウドコストを削減できます。このリポジトリでは、プロトコルのデモを提供しています。以下から始めるか、詳しくは下記の論文とブログ記事をご覧ください。

論文：Minions：オンデバイスモデルとクラウド言語モデルのコスト効率に優れた協調

Minions のブログ記事：https://hazyresearch.stanford.edu/blog/2025-02-24-minions

Secure Minions Chat のブログ記事：https://hazyresearch.stanford.edu/blog/2025-05-12-security

目次

Secure Minions Chat をお探しですか？ エンドツーエンド暗号化されたチャットシステムに関心がある場合は、詳しいセットアップ手順と使用方法について、Secure Minions Chat の READMEをご覧ください。

• セットアップ
  • ステップ 1：クローンとインストール
  • ステップ 2：ローカルモデルサーバーのインストール
  • ステップ 3：クラウド LLM API キーの設定
• Minions デモアプリケーション
• Minions WebGPU アプリ
• サンプルコード
  • Minion（単数形）
  • Minions（複数形）
• Python ノートブック
• Docker のサポート
• コマンドラインインターフェース
• Secure Minions ローカル・リモートプロトコル
• Secure Minions Chat
• アプリ
• 推論コスト見積もりツール
  • コマンドラインでの使用方法
  • Python API の使用方法
• その他のセットアップ
  • Azure OpenAI の使用
• メンテナー

セットアップ

Mac と Ubuntu で Python 3.10～3.11 を使用した以下のセットアップをテスト済みです（注：Python 3.13 はサポートされていません）

conda create -n minions python=3.11

ステップ 1： リポジトリをクローンして、Python パッケージをインストールします。

git clone https://github.com/HazyResearch/minions.git
cd minions
pip install -e .  # installs the minions package in editable mode

注： MLX-LM を任意でインストールする場合は、次のコマンドでパッケージをインストールします。

pip install -e ".[mlx]"

注： セキュアな minions チャットを使用する場合は、次のコマンドでパッケージをインストールします。

pip install -e ".[secure]"

注： Cartesia-MLX を任意でインストールする場合は、基本パッケージを pip install でインストールしてから、以下の手順に従ってください。

ステップ 2： ローカルモデルを実行するためのサーバーをインストールします。

ローカルモデルの実行には、lemonade、ollama、tokasaurus の 3 つのサーバーをサポートしています。これらのうち、少なくとも 1 つをインストールする必要があります。

• NVIDIA/AMD GPU を利用できない場合は、ollama を使用してください。こちらの手順に従って ollama をインストールします。Flash Attention を有効にするには、launchctl setenv OLLAMA_FLASH_ATTENTION 1 を実行し、Mac の場合は ollama アプリを再起動してください。
• ローカルの AMD CPU/GPU/NPU を利用できる場合は、lemonade を使用してください。こちらの手順に従って lemonade をインストールします。
  • サポートされている APU 構成については、次を参照してください：https://ryzenai.docs.amd.com/en/latest/llm/overview.html#supported-configurations
  • lemonade のインストール後、lemonade サーバーを起動してください。Lemonade Server をスタンドアロンツールとしてインストールするワンクリック Windows GUI インストーラーから起動できます。
  • 注：Lemonade は現時点で Minion-CUA プロトコルをサポートしていません。
• NVIDIA GPU を利用でき、tokasaurus の高スループットの恩恵を受ける Minions プロトコルを実行する場合は、tokasaurus を使用してください。次のコマンドで tokasaurus をインストールします。

pip install tokasaurus

pip install nanobind@git+https://github.com/wjakob/nanobind.git@2f04eac452a6d9142dedb957701bdb20125561e4

pip install git+https://github.com/cartesia-ai/edge.git#subdirectory=cartesia-metal

pip install git+https://github.com/cartesia-ai/edge.git#subdirectory=cartesia-mlx

# CPU-only installation
pip install llama-cpp-python

# For Metal on Mac (Apple Silicon/Intel)
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python

# For CUDA on NVIDIA GPUs
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python

# For OpenBLAS CPU optimizations
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python

from minions.clients import LlamaCppClient

# Initialize the client with a local model
client = LlamaCppClient(
    model_path="/path/to/model.gguf",
    chat_format="chatml",     # Most modern models use "chatml" format
    n_gpu_layers=35           # Set to 0 for CPU-only inference
)

# Run a chat completion
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the capital of France?"}
]

responses, usage, done_reasons = client.chat(messages)
print(responses[0])  # The generated response

client = LlamaCppClient(
    model_path="dummy",  # Will be replaced by downloaded model
    model_repo_id="TheBloke/Mistral-7B-Instruct-v0.2-GGUF",
    model_file_pattern="*Q4_K_M.gguf",  # Optional - specify quantization
    chat_format="chatml",
    n_gpu_layers=35     # Offload 35 layers to GPU
)

ステップ 3： 次のクラウド LLM プロバイダーから少なくとも 1 つの API キーを設定します。

必要に応じて、クラウドモデル用にOpenAI API キー、TogetherAI API キー、DeepSeek API キー、または MiniMax API キーを作成してください。

# OpenAI
export OPENAI_API_KEY=<your-openai-api-key>
export OPENAI_BASE_URL=<your-openai-base-url>  # Optional: Use a different OpenAI API endpoint

# Together AI
export TOGETHER_API_KEY=<your-together-api-key>

# OpenRouter
export OPENROUTER_API_KEY=<your-openrouter-api-key>
export OPENROUTER_BASE_URL=<your-openrouter-base-url>  # Optional: Use a different OpenRouter API endpoint

# Perplexity
export PERPLEXITY_API_KEY=<your-perplexity-api-key>
export PERPLEXITY_BASE_URL=<your-perplexity-base-url>  # Optional: Use a different Perplexity API endpoint

# Tokasaurus
export TOKASAURUS_BASE_URL=<your-tokasaurus-base-url>  # Optional: Use a different Tokasaurus API endpoint

# DeepSeek
export DEEPSEEK_API_KEY=<your-deepseek-api-key>

# Anthropic
export ANTHROPIC_API_KEY=<your-anthropic-api-key>

# Mistral AI
export MISTRAL_API_KEY=<your-mistral-api-key>

# MiniMax
export MINIMAX_API_KEY=<your-minimax-api-key>

# Gemini
export GEMINI_API_KEY=<your-gemini-api-key>

# Groq
export GROQ_API_KEY=<your-groq-api-key>

# Grok (xAI)
export XAI_API_KEY=<your-xai-api-key>

# Cohere
export COHERE_API_KEY=<your-cohere-api-key>

Minions デモアプリケーション

Minion または Minions プロトコルを試すには、次のコマンドを実行します：

pip install torch transformers

streamlit run app.py

ollama クライアントに関するエラーが表示された場合は、

An error occurred: Failed to connect to Ollama. Please check that Ollama is downloaded, running and accessible. https://ollama.com/download

次のコマンドを実行してみてください：

OLLAMA_FLASH_ATTENTION=1 ollama serve

Minions WebGPU アプリ

Minions WebGPU アプリでは、ローカルモデルの推論に WebGPU を、監督にクラウド API を使用して、Minions プロトコルをブラウザー内だけで実行する様子を確認できます。この方式では、使いやすいウェブインターフェースを提供しながら、ローカルサーバーのセットアップが不要になります。

特長

• ブラウザベース：ローカルサーバーは不要で、すべてウェブブラウザ内で動作します
• WebGPU による高速化：WebGPU を使用し、ローカルでのモデル推論を高速化します
• モデルの選択：MLC AI の最適化済みモデルから選択できます
• リアルタイムの進捗表示：モデルの読み込み状況や会話ログをリアルタイムで確認できます
• プライバシー重視：API キーとデータがブラウザの外部に送信されることはありません

クイックスタート

1. WebGPU アプリのディレクトリに移動します：

   cd apps/minions-webgpu
   

2. 依存関係をインストールします：

   npm install
   

3. 開発サーバーを起動します：

   npm start
   

4. ブラウザを開き、 ターミナルに表示された URL にアクセスします（通常は http://localhost:5173）

コード例：Minion（単数形）

次の例では、ollama ローカルクライアントと openai リモートクライアントを使用します。 プロトコルは minion です。

from minions.clients.ollama import OllamaClient
from minions.clients.openai import OpenAIClient
from minions.minion import Minion

local_client = OllamaClient(
        model_name="llama3.2",
    )

remote_client = OpenAIClient(
        model_name="gpt-4o",
    )

# Instantiate the Minion object with both clients
minion = Minion(local_client, remote_client)


context = """
Patient John Doe is a 60-year-old male with a history of hypertension. In his latest checkup, his blood pressure was recorded at 160/100 mmHg, and he reported occasional chest discomfort during physical activity.
Recent laboratory results show that his LDL cholesterol level is elevated at 170 mg/dL, while his HDL remains within the normal range at 45 mg/dL. Other metabolic indicators, including fasting glucose and renal function, are unremarkable.
"""

task = "Based on the patient's blood pressure and LDL cholesterol readings in the context, evaluate whether these factors together suggest an increased risk for cardiovascular complications."

# Execute the minion protocol for up to two communication rounds
output = minion(
    task=task,
    context=[context],
    max_rounds=2
)

コード例：Minions（複数形）

次の例では、ollama ローカルクライアントと openai リモートクライアントを使用します。 プロトコルは minions です。

from minions.clients.ollama import OllamaClient
from minions.clients.openai import OpenAIClient
from minions.minions import Minions
from pydantic import BaseModel

class StructuredLocalOutput(BaseModel):
    explanation: str
    citation: str | None
    answer: str | None

local_client = OllamaClient(
        model_name="llama3.2",
        temperature=0.0,
        structured_output_schema=StructuredLocalOutput
)

remote_client = OpenAIClient(
        model_name="gpt-4o",
)


# Instantiate the Minion object with both clients
minion = Minions(local_client, remote_client)


context = """
Patient John Doe is a 60-year-old male with a history of hypertension. In his latest checkup, his blood pressure was recorded at 160/100 mmHg, and he reported occasional chest discomfort during physical activity.
Recent laboratory results show that his LDL cholesterol level is elevated at 170 mg/dL, while his HDL remains within the normal range at 45 mg/dL. Other metabolic indicators, including fasting glucose and renal function, are unremarkable.
"""

task = "Based on the patient's blood pressure and LDL cholesterol readings in the context, evaluate whether these factors together suggest an increased risk for cardiovascular complications."

# Execute the minion protocol for up to two communication rounds
output = minion(
    task=task,
    doc_metadata="Medical Report",
    context=[context],
    max_rounds=2
)

Python ノートブック

ノートブックで Minion／Minions を実行するには、minions.ipynb を確認してください。

Docker のサポート

Docker イメージをビルドする

docker build -t minions-docker .

コンテナーを実行する

注： コンテナーは、ローカルモデル推論用の Ollama サービスをバックグラウンドで自動的に起動します。これにより、追加の設定なしで llama3.2:3b などのモデルを使用できます。

# Basic usage (includes Ollama service)
docker run -i minions-docker

# With Docker socket mounted (for Docker Model Runner)
docker run -i -v /var/run/docker.sock:/var/run/docker.sock minions-docker

# With API keys for remote models
docker run -i -e OPENAI_API_KEY=your_key -e ANTHROPIC_API_KEY=your_key minions-docker

# With custom Ollama host
docker run -i -e OLLAMA_HOST=0.0.0.0:11434 minions-docker

# For Streamlit app (legacy usage)
docker run -p 8501:8501 --env OPENAI_API_KEY=<your-openai-api-key> --env DEEPSEEK_API_KEY=<your-deepseek-api-key> minions-docker

Docker での Minion プロトコルの使用方法

Docker コンテナーは、各種 minion プロトコルを実行するための stdin／stdout インターフェースをサポートしています。次の構造の JSON 入力を受け取ります。

{
  "local_client": {
    "type": "ollama",
    "model_name": "llama3.2:3b",
    "port": 11434,
    "kwargs": {}
  },
  "remote_client": {
    "type": "openai",
    "model_name": "gpt-4o",
    "kwargs": {
      "api_key": "your_openai_key"
    }
  },
  "protocol": {
    "type": "minion",
    "max_rounds": 3,
    "log_dir": "minion_logs",
    "kwargs": {}
  },
  "call_params": {
    "task": "Your task here",
    "context": ["Context string 1", "Context string 2"],
    "max_rounds": 2
  }
}

使用例

基本的な Minion プロトコル：

echo '{
  "local_client": {
    "type": "ollama",
    "model_name": "llama3.2:3b"
  },
  "remote_client": {
    "type": "openai",
    "model_name": "gpt-4o"
  },
  "protocol": {
    "type": "minion",
    "max_rounds": 3
  },
  "call_params": {
    "task": "Analyze the patient data and provide a diagnosis",
    "context": ["Patient John Doe is a 60-year-old male with hypertension. Blood pressure: 160/100 mmHg. LDL cholesterol: 170 mg/dL."]
  }
}' | docker run -i -e OPENAI_API_KEY=$OPENAI_API_KEY minions-docker

Minions（並列）プロトコル：

echo '{
  "local_client": {
    "type": "ollama",
    "model_name": "llama3.2:3b"
  },
  "remote_client": {
    "type": "openai",
    "model_name": "gpt-4o"
  },
  "protocol": {
    "type": "minions"
  },
  "call_params": {
    "task": "Analyze the financial data and extract key insights",
    "doc_metadata": "Financial report",
    "context": ["Revenue increased by 15% year-over-year. Operating expenses rose by 8%. Net profit margin improved to 12%."]
  }
}' | docker run -i -e OPENAI_API_KEY=$OPENAI_API_KEY minions-docker

サポートされているクライアントの種類

ローカルクライアント：

• ollama：ローカル推論に Ollama を使用します（コンテナーに含まれています）
• docker_model_runner：ローカル推論に Docker Model Runner を使用します

リモートクライアント：

• openai：OpenAI API
• anthropic：Anthropic API

サポートされているプロトコルの種類

• minion：単一の会話プロトコル
• minions：並列処理プロトコル

出力形式

コンテナーは、次の構造の JSON を出力します。

{
  "success": true,
  "result": {
    "final_answer": "The analysis result...",
    "supervisor_messages": [...],
    "worker_messages": [...],
    "remote_usage": {...},
    "local_usage": {...}
  },
  "error": null
}

エラーが発生した場合：

{
  "success": false,
  "result": null,
  "error": "Error message"
}

環境変数

• OPENAI_API_KEY：OpenAI API キー
• ANTHROPIC_API_KEY：Anthropic API キー
• OLLAMA_HOST：Ollama サービスのホスト（デフォルトは 0.0.0.0:11434）
• PYTHONPATH：Python パス（デフォルトは /app）
• PYTHONUNBUFFERED：バッファーなし出力（デフォルトは 1）

ヒントと応用的な使い方

1. Ollama モデル：初回使用時に、コンテナーがモデル（例：llama3.2:3b）を自動的に取得します
2. Docker Model Runner：Docker が起動しており、コンテナー内からアクセスできることを確認してください
3. API キー：セキュリティのため、API キーは環境変数として渡してください
4. ボリューム：ワークスペースやログを永続化するには、ボリュームをマウントしてください
5. ネットワーク：ローカルサービスにアクセスする必要がある場合は、--network host を使用してください

カスタムボリュームを使用する場合：

docker run -i \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/logs:/app/minion_logs \
  -v $(pwd)/workspace:/app/workspace \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  minions-docker

対話モード：

docker run -it \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  minions-docker bash

その後、インターフェースを手動で実行できます：

python minion_stdin_interface.py 

コンテナーを永続的に使用する

コンテナーと Ollama サービスを毎回再起動せずに、複数のクエリを実行する場合：

1. 永続コンテナーを起動します：

docker run -d --name minions-container -e OPENAI_API_KEY="$OPENAI_API_KEY" minions-docker

2. 起動中のコンテナーにクエリを送信します：

echo '{
  "local_client": {"type": "ollama", "model_name": "llama3.2:3b"},
  "remote_client": {"type": "openai", "model_name": "gpt-4o"},
  "protocol": {"type": "minion", "max_rounds": 1},
  "call_params": {"task": "How many times did Roger Federer end the year as No.1?"}
}' | docker exec -i minions-container /app/start_minion.sh

3. 追加のクエリを送信します（再起動の待ち時間がなく高速です）：

echo '{
  "local_client": {"type": "ollama", "model_name": "llama3.2:3b"},
  "remote_client": {"type": "openai", "model_name": "gpt-4o"},
  "protocol": {"type": "minion", "max_rounds": 1},
  "call_params": {"task": "What is the capital of France?"}
}' | docker exec -i minions-container /app/start_minion.sh

4. 完了したら後片付けをします：

docker stop minions-container
docker rm minions-container

永続コンテナーの利点：

• ✅ Ollama が起動したままになります - クエリ間の再起動待ち時間がありません
• ✅ モデルが読み込まれたままになります - 2 回目以降のクエリが高速になります
• ✅ リソースを効率的に利用できます - 1 つのコンテナーで複数のクエリを処理します
• ✅ モデルを自動的に取得します - 初回使用時にモデルがダウンロードされます

CLI

CLI で Minion／Minions を実行するには、minions_cli.py を確認してください。

次のコマンドを実行して、使用するローカルモデルとリモートモデルを設定します。形式は <provider>/<model_name> です。プロバイダーには ollama、openai、anthropic、together、perplexity、openrouter、groq、deepseek、mlx を指定できます。

export MINIONS_LOCAL=ollama/llama3.2
export MINIONS_REMOTE=openai/gpt-4o

minions --help

minions --context <path_to_context> --protocol <minion|minions>

セキュア Minions ローカル・リモートプロトコル

セキュア Minions ローカル・リモートプロトコル（secure/minions_secure.py）は、ローカルワーカーモデルとリモートスーパーバイザーサーバー間の安全な通信を可能にする、Minions プロトコルのエンドツーエンド暗号化実装です。このプロトコルには、アテステーションの検証、完全前方秘匿性、リプレイ攻撃対策が含まれています。

前提条件

セキュアな依存関係をインストールします。

pip install -e ".[secure]"

基本的な使い方

Python API

from minions.clients import OllamaClient
from secure.minions_secure import SecureMinionProtocol

# Initialize local client
local_client = OllamaClient(model_name="llama3.2")

# Create secure protocol instance
protocol = SecureMinionProtocol(
    supervisor_url="https://your-supervisor-server.com",
    local_client=local_client,
    max_rounds=3,
    system_prompt="You are a helpful AI assistant."
)

# Run a secure task
result = protocol(
    task="Analyze this document for key insights",
    context=["Your document content here"],
    max_rounds=2
)

print(f"Final Answer: {result['final_answer']}")
print(f"Session ID: {result['session_id']}")
print(f"Log saved to: {result['log_file']}")

# Clean up the session
protocol.end_session()

コマンドラインインターフェース

python secure/minions_secure.py \
    --supervisor_url https://your-supervisor-server.com \
    --local_client_type ollama \
    --local_model llama3.2 \
    --max_rounds 3

セキュア Minions Chat

セキュア Minions Chat をインストールするには、次のコマンドでパッケージをインストールします。

pip install -e ".[secure]"

クライアントのセットアップ方法とセキュアチャットプロトコルの実行方法について詳しくは、Secure Minions Chat README をご覧ください。

アプリ

apps/ ディレクトリには、さまざまなユースケースを実演する専用アプリケーションが含まれています。

• 📊 A2A-Minions - エージェント間統合サーバー
• 🎭 Character Chat - AI ペルソナとのロールプレイ
• 🔍 Document Search - 複数方式によるドキュメント検索
• 🐳 Docker - HTTP サーバーを備えたコンテナ化 Minions
• 📚 Story Teller - イラスト付きの創作ストーリーテリング
• 🛠️ Tools Comparison - MCP ツールのパフォーマンス比較
• 🌐 WebGPU App - ブラウザベースの Minions プロトコル

推論速度推定ツール

Minions には、お使いのハードウェアでの LLM 推論速度を推定するユーティリティが用意されています。推論速度推定ツールでは、次のことができます。

1. ハードウェアの性能（GPU、MPS、CPU）を分析する
2. モデルのピーク性能を計算する
3. 1 秒あたりのトークン数と完了時間を推定する

コマンドラインでの使用方法

コマンドラインから推定ツールを直接実行して、モデルの実行速度を確認します。

python -m minions.utils.inference_estimator --model llama3.2 --tokens 1000 --describe

引数：

• --model：対応モデル一覧からモデル名を指定します（例：llama3.2、mistral7b）
• --tokens：生成時間を推定するトークン数を指定します
• --describe：ハードウェアとモデルのパフォーマンス統計の詳細を表示します
• --quantized：モデルが量子化されていることを指定します
• --quant-bits：量子化のビット幅（4、8、または 16）を指定します

Python API の使用方法

Python コードから推論速度推定ツールを使用することもできます。

from minions.utils.inference_estimator import InferenceEstimator

# Initialize the estimator for a specific model
estimator = InferenceEstimator(
    model_name="llama3.2",  # Model name
    is_quant=True,          # Is model quantized?
    quant_bits=4            # Quantization level (4, 8, 16)
)

# Estimate performance for 1000 tokens
tokens_per_second, estimated_time = estimator.estimate(1000)
print(f"Estimated speed: {tokens_per_second:.1f} tokens/sec")
print(f"Estimated time: {estimated_time:.2f} seconds")

# Get detailed stats
detailed_info = estimator.describe(1000)
print(detailed_info)

# Calibrate with your actual model client for better accuracy
# (requires a model client that implements a chat() method)
estimator.calibrate(my_model_client, sample_tokens=32, prompt="Hello")

この推定ツールは、計算能力とメモリ帯域幅の両方の制限を考慮するルーフラインモデルを使用し、精度を高めるために実測によるキャリブレーションを適用します。キャリブレーションデータは、次回以降の使用に備えて ~/.cache/ie_calib.json にキャッシュされます。

その他のセットアップ

Minions で Azure OpenAI を使用する

環境変数を設定する

export AZURE_OPENAI_API_KEY=your-api-key
export AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
export AZURE_OPENAI_API_VERSION=2024-02-15-preview

コード例

以下は、独自のコードで Minions プロトコルと Azure OpenAI を使用する例です。

from minions.clients.ollama import OllamaClient
from minions.clients.azure_openai import AzureOpenAIClient
from minions.minion import Minion

local_client = OllamaClient(
    model_name="llama3.2",
)

remote_client = AzureOpenAIClient(
    model_name="gpt-4o",  # This should match your deployment name
    api_key="your-api-key",
    azure_endpoint="https://your-resource-name.openai.azure.com/",
    api_version="2024-02-15-preview",
)

# Instantiate the Minion object with both clients
minion = Minion(local_client, remote_client)

メンテナー

• Avanika Narayan（連絡先：[email protected]）