maze-agent/Maze

Maze：面向 LLM Agent 的分布式框架

它是什么 – Maze 是一个开源的 Python 框架，可让您将 LLM-agent 程序转变为可在集群上运行的持久、可观测的工作流。它构建在 Ray 之上，增加了统一的运行 API、异构资源队列（GPU、CPU、I/O）、内置的模型服务管理，以及用于设计和检查 DAG 的可视化 Workbench。

为什么重要 – 大语言模型 agent 通常需要许多异构步骤（提示、检索、微调、数据 I/O），并且必须在许多用户之间共享 GPU。Maze 协调这些步骤，在重启后保持状态，并提供一种统一的方式来提交工作流，无论您是用纯 Python、通过 LangGraph SDK 编写，还是以静态的 maze.yaml 规范编写。

核心概念

概念	作用
Run	工作流执行的不可变标识符。所有事件、日志、工件和放置信息都附加到 Run 上。
Task	使用 `@task` 注解的 Python 函数。您可以声明所需资源（`cpu_num`、`gpu_mem`、`io_num`）。
Workflow	使用 `@workflow` 构建的静态 DAG（或作为 JSON 契约提交）。
DynamicRun	一种可变的运行，可以在运行时向其追加任务，适用于实时决定下一步的 agent。
Workbench	一个 Web UI（React），提供拖放式 DAG 编辑器、运行时画布和集群资源监视器。
Scheduler	处理三个独立的队列（GPU、CPU、I/O）。支持简单的 FIFO（`FCFS`）或研究级的 HACS 算法，该算法会根据历史运行时间重新确定任务的优先级。
模型路由	Maze 发现本地检查点（vLLM 或 Transformers），按需启动模型服务器，并将需要模型的任务置于 Model Wait 状态，以便它们不会阻塞 GPU 队列。

主要特性

可视化工作流编写 – 拖放式 DAG 编辑器、可复用的任务目录、验证和一键提交。
异构调度 – 独立的 GPU、CPU 和 I/O 队列；可插拔的 FCFS 或与论文一致的 HACS 算法，带有可调参数。
静态 + 动态 DAG – 使用 @workflow 编写固定的 DAG，或通过 DynamicRun.append_task 在运行时扩展运行。
分布式模型服务 – 自动发现和部署本地检查点（vLLM/Transformers）、显式的 model-wait 状态、LRU 缩减空闲实例。
持久状态 – 运行在进程崩溃后仍能存活；任务状态、重试、超时和内容寻址工件都会被持久化。
统一 API 表面 – 相同的 Python SDK、LangGraph 适配器和 Workbench UI 都通过 maze.workflow/v1 契约与 Core 通信。
可观测性 – 结构化事件、日志、工件 URL（maze://artifacts/sha256/<hash>）以及显示实时任务状态的画布视图。
集群管理 – 用于列出资源、队列、加入 worker 和协调节点注册的 CLI 命令。

典型使用场景

LLM-agent 流水线 – 结合需要 CPU 和 GPU 资源的提示、检索、工具调用和微调步骤。
带有辅助 I/O 的训练作业 – 在 I/O 队列上运行数据预处理任务，同时 GPU 训练模型，防止 I/O 阻塞 GPU 调度。
研究可复现性 – 将每次运行的输入、代码和工件存储在内容寻址存储中；之后使用相同的工作区重放运行。
多租户集群 – 独立的队列可确保长时间运行的 CPU 作业不会饿死短时间的 GPU 推理请求。
动态 agent 推理 – 使用 DynamicRun 让 LLM 在运行时决定下一步操作，动态追加新任务。

快速开始（来自 README）

# 安装
pip install maze-agent

# 启动头节点和 Web UI（Workbench）
maze start --head --port 8000 --playground --detach
# UI → http://localhost:5173   API → http://localhost:8000

# 添加一个向头节点注册的 worker
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>

所有执行元数据都会出现在统一的 Run 历史记录中。

架构概览

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 拥有 Run ID；worker 仅执行任务并报告结果。

社区与引用

如果您在研究中使用 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}
}

该项目由来自华中科技大学、华为和其他机构的贡献者维护。

了解更多

网站： https://mazeagent.net/
文档： https://maze-doc-new.readthedocs.io/en/latest/
GitHub： https://github.com/maze-agent/Maze

总结 – Maze 为 LLM-agent 流水线提供了一个生产级的运行时：它处理跨异构资源的调度、保持运行持久性、按需提供模型服务，并通过一个统一的 Python 友好 API 提供用于设计和调试的可视化 UI。