Maze 分布式 LLM Agent 框架
把 LLM Agent 程序变成跨 GPU/CPU/IO 异构资源的分布式可观测工作流，统一调度、恢复、模型服务与产物管理。
工作流说明只提及任务沙箱与相对路径，未描述代理任务的最小权限模型，故 least_privilege 仅得 1；取消/重试需用户显式发起但无危险操作确认机制，user_confirmation 得 1；工件寻址、工作区文件到任务沙箱的路径规则、模型路由状态说明较清楚，data_flow_transparency 得 2；使用 OpenAI 兼容端点但完全未提及密钥与敏感数据处理，sensitive_data_handling 得 1；依赖已锁定版本但含可疑项（zmq==0.0.0 是占位包、transformers>=5.12.1 与公开版本序列不符），dependency_security 得 1；系统会自动部署/缩容模型实例并占用 GPU，文档未描述防护或限制，external_effects 得 1；有重试、取消、重启安全的 Run 发现，但未描述回滚语义，rollback 得 1；引用条目与致谢齐全，但作者邮箱为 [email protected] 占位符且仓库 URL 相互矛盾，source_attribution 得 2。
README 声称多项 GA 能力而 pyproject 标注 Development Status: 4 - Beta，且 News 日期为 2026 年（未来），自述相互不一致，self_consistency 得 1；PyPI 安装、可选 vllm extra、锁定 ray 版本使依赖可用性尚可，dependency_availability 得 2；结构化错误字段（error_type、retryable、origin、node_id、attempt、traceback 等）描述详尽，failure_messages 得 2。
面向分布式 LLM 代理开发与科研场景，示例覆盖静态/动态工作流、应用规格与 Workbench，audience_and_scenarios 得 2；明确声明 GAIA 模板仅为集成练习而非基准复现、missing_model 与未部署检查点的区分，capability_boundaries 得 2；代理任务的触发/调度入口语义描述有限，trigger_precision 得 1；端口、环境变量、Python 版本、模型目录配置有说明，但 OS Independent 声明与 GPU 集群现实存在张力，environment_fit 得 2。
README 结构清晰（架构、快速开始、工作流、运维、Workbench 分节），information_architecture 得 2；pip 安装、源码安装、启动与 worker 命令均有，install_notes 得 2；包名 maze-agent 与仓库 Maze 混用，pyproject 中 Homepage 指向 QinbinLi/Maze 而 README 指向 maze-agent/Maze，naming_stability 得 1；代码与 YAML 示例丰富但无 FAQ，examples_and_faq 得 2；无已知限制章节，仅有零散边界说明，known_limitations 得 1；MIT 许可证全文在 LICENSE 且与 pyproject 一致，license 得 3；有版本号与 News 时间线但无正式 CHANGELOG，versioning_changelog 得 2；维护者为占位邮箱 '[email protected]'，无真实维护者联系或治理说明，maintenance_responsibility 得 1。
统一 Run API、CLI 与 Workbench 输出（结果摘要、日志、工件引用）描述可用，output_usability 得 2；在 Ray 之上提供工作流契约、异构调度与持久 Run，具有一定边际价值，但未与现有方案对比，marginal_value 得 2；GPU 部署与预留成本显著，无任何成本/收益指引，cost_benefit 得 1。
多数性能与稳定性断言（确定性 GPU 清理、restart-safe、DCT EMA 调度收益）无随附测试或数据可静态追溯，claim_traceability 得 1；README、pyproject、LICENSE 之间存在矛盾（2026 年日期、两个不同仓库 URL、占位邮箱），跨源一致性差，cross_source_corroboration 得 1；但明确将 GAIA 模板与基准精度声明分离，事实与推断区分做得较好，fact_inference_separation 得 2。
- pyproject.toml 中作者/维护者邮箱为占位符 '[email protected]'，无法核实维护者身份。
- 依赖中存在可疑条目：zmq==0.0.0 是占位包而非真正的 pyzmq；transformers>=5.12.1 与公开版本序列不符，安装前请核实依赖解析结果。
- README 与 pyproject 指向不同的仓库 URL（maze-agent/Maze 与 QinbinLi/Maze），且 News 与引用日期为 2026 年（未来），供应链来源需谨慎核实。
- 系统会自动部署与缩容 vLLM/Transformers 模型实例并占用 GPU，请在生产环境前审查其资源与外部影响控制。
- README 未提供任何 API 密钥或敏感数据处理指引，接入 OpenAI 兼容端点时请自行管理凭据。
- 包声明 Development Status: Beta，但 README 宣称多项 GA 能力；本文为静态评审，所有运行时断言均未经执行验证。
这个 Agent 能做什么，适合哪些场景？
Maze（GitHub: maze-agent/Maze，MIT 许可）是一个把 Agent 程序转化为分布式、可观测工作流的开源框架。它由 Maze Core（Run 状态、事件、日志、产物）、调度器（基于 Ray，含 gpu/cpu/io 独立队列与 FCFS/HACS 算法）、Python SDK、LangGraph 适配器和可视化 Workbench 组成。所有客户端通过统一的 maze.workflow/v1 契约提交 DAG，静态 @workflow、动态 DynamicRun 和 maze.yaml 应用任务共享同一执行面。框架还负责本地模型检查点发现、按需部署 vLLM 或 Transformers 实例、GPU 租约管理和 LRU 缩容。任务失败带有结构化错误字段，支持重试、超时、取消和跨进程重启的状态恢复。该项目的研究论文被 SC26 接收，由华中科技大学、华为等机构贡献者支持。
用户用 @task/@workflow 装饰器定义带资源声明的任务 DAG，或编写 maze.yaml 应用规格，通过 MaClient（如 client.create_workflow_from、client.create_dynamic_run）或 POST /workflows/submit 提交到 Maze Core。Core 生成 run_id，调度器按 gpu/cpu/io 队列以 FCFS 或 HACS 排序就绪任务，再由节点放置策略（如 least-loaded）选择注册节点，最终由 Ray 在 head/worker 节点上执行。模型任务声明 model_anchor 后，Maze 在 model_cache 中发现检查点，自动部署 vLLM/Transformers 实例并注入 OpenAI 兼容端点。运行期间产生事件、日志、放置信息和内容寻址产物（maze://artifacts/sha256/<hash>），可通过 CLI（maze runs/c cluster 命令）、SDK 或 Workbench 查询、取消、重试。
- ML 平台工程师需要在多 GPU 集群上跑带模型推理步骤的 Agent 工作流，希望 GPU/CPU/IO 任务互不阻塞排队
- 研究团队想以可视化 DAG 编辑器（Maze Workbench）搭建并复用任务目录，同时保留服务端工作区和文件管理
- 需要在运行时根据中间结果动态追加任务（DynamicRun）而非预先写死 DAG 的流水线开发者
- 用 LangGraph 编写 Agent 但需要持久化执行、重启恢复和跨节点调度的团队，可经 LangGraph 适配器接入
- 运维人员希望以 maze.yaml 声明应用式作业（命令、conda 环境、产物、超时、重试策略）并统一纳入 Run 历史
- 需要在生产中热备待命 worker、崩溃后重注册、并对模型实例做 GPU 租约与 LRU 缩容管理的集群管理者
这个 Agent 有哪些优点和局限？
- gpu/cpu/io 独立队列避免一类资源阻塞另一类，且支持论文对齐的 HACS 调度算法（可调 MAZE_HACS_* 参数）
- Run 状态跨进程重启持久化，保留任务状态、结构化错误、事件、日志、重试和内容寻址产物
- 调度器托管本地模型执行：自动部署 vLLM/Transformers 实例、显式 Model Wait 状态、GPU 租约复用与 LRU 缩容
- SDK、LangGraph、Workbench 和应用规格统一走 maze.workflow/v1 契约与同一套 Core Run API，避免多套执行路径
- 核心分布式执行建立在 Ray 之上，Ray 节点必须额外注册为 Maze worker 才可调度，引入双层运行时运维成本
- 分布式无共享存储时需启用 Head 端内容寻址产物存储，且任务代码必须用相对路径访问工作区文件
- 模型执行依赖节点本地检查点：missing_model 表示没有任何节点报告该本地模型，需自行准备 model_cache 目录
- GAIA 模板（reason/file/speech/vision）仅为工作流集成示例，README 明确不构成 GAIA 基准准确率复现声明
- 较新的 SC26 论文与 2026 年时间线的更新记录，社区生产案例证据尚有限
如何安装或部署这个 Agent？
从 PyPI 安装：pip install maze-agent
或从源码：
git clone https://github.com/maze-agent/Maze.git
cd Mazepip install -e .
需 Python 环境与 Ray 运行时；分布式部署还需可访问 head 节点的网络。
如何使用这个 Agent？
- 启动 head 与 Workbench：maze start --head --port 8000 --playground --detach（Workbench 在 http://localhost:5173，Core API 在 http://localhost:8000）。
- 添加 worker：maze start --worker --addr HEAD_IP:8000 --agent --heartbeat-interval 20；Ray 节点须同时注册为 Maze worker 才能被调度。
- 查看集群：maze cluster resources --server-url http://HEAD_IP:8000。
- 用 Python SDK 定义 @workflow 并通过 MaClient 提交运行，或 maze run maze.yaml --wait 运行应用规格。
- 查询与运维：maze runs list / show / logs / retry <run_id>，或 SDK 的 client.get_run、client.cancel_run 等接口。
- 管理服务：maze status、maze doctor、maze stop。