maze-agent/Maze

Maze: LLMエージェントのための分散フレームワーク

概要 – MazeはオープンソースのPythonフレームワークで、LLMエージェントプログラムを、クラスタ上で動作する永続的で観測可能なワークフローに変換します。Rayの上に構築され、統一された実行API、異種リソースキュー（GPU、CPU、I/O）、組み込みのモデルサービス管理、DAGの設計と検査のためのビジュアルなワークベンチを追加します。

重要性 – 大規模言語モデルエージェントは、多くの場合、多くの異種ステップ（プロンプティング、検索、ファインチューニング、データI/O）を必要とし、多くのユーザー間でGPUを共有する必要があります。Mazeはこれらのステップを調整し、再起動後も状態を保持し、純粋なPython、LangGraph SDK、または静的なmaze.yaml仕様のいずれで記述しても、ワークフローを送信する単一の方法を提供します。

中核となる概念

概念	機能
実行	ワークフロー実行の不変の識別子。すべてのイベント、ログ、アーティファクト、配置情報が実行に添付されます。
タスク	`@task`で注釈されたPython関数。必要なリソース（`cpu_num`、`gpu_mem`、`io_num`）を宣言します。
ワークフロー	`@workflow`で構築された静的DAG（またはJSONコントラクトとして送信）。
動的実行	実行時にタスクを追加できる可変の実行。次のステップをその場で決定するエージェントに役立ちます。
ワークベンチ	ドラッグ＆ドロップのDAGエディタ、実行時キャンバス、クラスタリソースモニタを提供するWeb UI（React）。
スケジューラ	3つの独立したキュー（GPU、CPU、I/O）を処理します。単純なFIFO（`FCFS`）または、履歴実行時間に基づいてタスクの優先順位を再設定する研究グレードのHACSアルゴリズムをサポートします。
モデルルーティング	Mazeはローカルチェックポイント（vLLMまたはTransformers）を発見し、オンデマンドでモデルサーバーを起動し、モデルを必要とするタスクをモデル待機状態にして、GPUキューをブロックしないようにします。

主な機能

ビジュアルなワークフロー作成 – ドラッグ＆ドロップのDAGエディタ、再利用可能なタスクカタログ、検証、ワンクリック送信。
異種スケジューリング – 個別のGPU、CPU、I/Oキュー。プラグ可能なFCFSまたはチューニング可能なパラメータを持つ論文準拠のHACSアルゴリズム。
静的+動的DAG – @workflowで固定DAGを記述するか、DynamicRun.append_taskを使用して実行時に実行を拡張します。
分散モデルサービス – ローカルチェックポイント（vLLM/Transformers）の自動発見とデプロイ、明示的なモデル待機状態、アイドルインスタンスのLRUスケールイン。
永続的な状態 – 実行はプロセスのクラッシュ後も生存します。タスク状態、再試行、タイムアウト、コンテンツアドレス指定されたアーティファクトが永続化されます。
統一APIサーフェス – 同じPython SDK、LangGraphアダプタ、ワークベンチUIがすべてmaze.workflow/v1コントラクトを通じてCoreと通信します。
可観測性 – 構造化イベント、ログ、アーティファクトURL（maze://artifacts/sha256/<ハッシュ>）、およびライブタスクステータスを表示するキャンバスビュー。
クラスタ管理 – リソース、キュー、ワーカーの参加、ノード登録の調整を一覧表示するCLIコマンド。

典型的なユースケース

LLMエージェントパイプライン – CPUとGPUの両方のリソースを必要とするプロンプティング、検索、ツール呼び出し、ファインチューニングのステップを組み合わせます。
補助I/Oを伴うトレーニングジョブ – GPUがモデルをトレーニングしている間にI/Oキューでデータ前処理タスクを実行し、I/OがGPUディスパッチをブロックしないようにします。
研究の再現性 – 各実行の入力、コード、アーティファクトをコンテンツアドレス指定されたストアに保存し、後で同じワークスペースで実行を再生します。
マルチテナントクラスタ – 分離されたキューにより、長時間実行されるCPUジョブが短いGPU推論要求を枯渇させないようにします。
動的エージェント推論 – DynamicRunを使用して、LLMが実行時に次のアクションを決定し、新しいタスクをその場で追加できるようにします。

クイックスタート（READMEから）

# インストール
pip install maze-agent

# ヘッドノードとWeb UI（ワークベンチ）を起動
maze start --head --port 8000 --playground --detach
# UI → http://localhost:5173   API → http://localhost:8000

# ヘッドに登録するワーカーを追加
maze start --worker \
  --addr HEAD_IP:8000 \
  --agent \
  --heartbeat-interval 20

単純な静的ワークフローを定義

from maze import MaClient, task, workflow

@task(resources={"cpu_num":1, "gpu_mem":0, "io_num":0})
def greet(text: str):
    return {"result": f"Hello {text}"}

@task(resources={"cpu_num":1, "gpu_mem":0, "io_num":0})
def uppercase(result: str):
    return {"upper": result.upper()}

@workflow
def hello(name: str):
    g = greet(name)
    return uppercase(g.result)

client = MaClient("http://localhost:8000")
run = client.create_workflow_from(hello, inputs={"name":"Maze"}).run()
print(client.wait_run(run)["result_summary"])

動的ワークフローの例

from maze import MaClient, task

@task(resources={"cpu_num":1})
def summarize(topic: str=""):
    return {"summary": f"Maze can build workflows dynamically for {topic}."}

client = MaClient("http://localhost:8000")
run = client.create_dynamic_run(max_tasks=10)
task_ref = run.append_task(summarize, inputs={"topic":"agent runtime"})
run.wait_for_task(task_ref)
run.finalize({"status":"done"})
print(run.status())

完全なアプリケーション仕様の実行

maze.yamlを作成：

name: gpu-demo
command: python train.py
workspace: .
resources:
  cpu_num: 4
  gpu_mem: 8192
  io_num: 0
env:
  conda: maze
  vars:
    DATASET: sample
artifacts:
  - outputs/
timeout_seconds: 1800
retries:
  max: 1
  backoff_seconds: 5
  on: [node_lost, resource_unavailable]

次に：

maze app validate maze.yaml
maze run maze.yaml --wait
maze runs logs <run_id>

すべての実行メタデータが統一された実行履歴に表示されます。

アーキテクチャ概要

Python SDK / LangGraph / Workbench / App Spec
        |
   maze.workflow/v1 (JSON contract)
        |
      Maze Core – runs, events, logs, artifacts
        |
   Scheduler + Ray – heterogeneous queues, placement
        |
   Head & Worker nodes – actual task execution, model services

Coreは実行IDを所有し、ワーカーはタスクを実行して報告するだけです。

コミュニティと引用

研究でMazeを使用する場合は、引用してください：

@inproceedings{gu2026maze,
  title={Maze: A Distributed Framework for Large Language Model Agents},
  author={Jing Gu and Zhuang Xing and Yiheng Yang and ...},
  booktitle={Proceedings of the International Conference for High Performance Computing, Networking, Storage and Analysis},
  year={2026}
}

このプロジェクトは、華中科技大学、Huawei、および他の機関の貢献者によって維持されています。

詳細情報

ウェブサイト: https://mazeagent.net/
ドキュメント: https://maze-doc-new.readthedocs.io/en/latest/
GitHub: https://github.com/maze-agent/Maze

結論 – Mazeは、LLMエージェントパイプラインのための本番グレードのランタイムを提供します。異種リソース間のスケジューリングを処理し、実行を永続化し、オンデマンドでモデルを提供し、設計とデバッグのためのビジュアルUIを提供します。これらすべてを単一のPythonフレンドリーなAPIで実現します。