maze-agent/Maze

Maze: LLM 에이전트를 위한 분산 프레임워크

정의 – Maze는 LLM 에이전트 프로그램을 클러스터에서 실행되는 지속적이고 관찰 가능한 워크플로우로 변환하는 오픈소스 Python 프레임워크입니다. Ray 위에서 동작하며, 통합 실행 API, 이기종 리소스 큐(GPU, CPU, I/O), 내장 모델 서비스 관리, DAG 설계 및 검사를 위한 시각적 Workbench를 제공합니다.

중요성 – 대규모 언어 모델 에이전트는 종종 다양한 이기종 단계(프롬프팅, 검색, 파인튜닝, 데이터 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	런타임에 작업을 추가할 수 있는 가변 실행으로, 다음 단계를 즉흥적으로 결정하는 에이전트에 유용합니다.
Workbench	드래그 앤 드롭 DAG 편집기, 런타임 캔버스, 클러스터 리소스 모니터를 제공하는 웹 UI(React)입니다.
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)의 자동 발견 및 배포, 명시적 모델 대기 상태, 유휴 인스턴스의 LRU 축소.
지속적 상태 – Run은 프로세스 충돌에서도 생존합니다. 작업 상태, 재시도, 타임아웃, 콘텐츠 주소 지정 아티팩트가 영속화됩니다.
통합 API 표면 – 동일한 Python SDK, LangGraph 어댑터, Workbench UI가 모두 maze.workflow/v1 계약을 통해 Core와 통신합니다.
관찰 가능성 – 구조화된 이벤트, 로그, 아티팩트 URL(maze://artifacts/sha256/<hash>), 실시간 작업 상태를 보여주는 캔버스 뷰.
클러스터 관리 – 리소스, 큐, 워커 참여, 노드 등록 조정을 위한 CLI 명령.

일반적인 사용 사례

LLM 에이전트 파이프라인 – CPU와 GPU 리소스가 모두 필요한 프롬프팅, 검색, 도구 호출, 파인튜닝 단계를 결합합니다.
보조 I/O가 있는 학습 작업 – GPU가 모델을 학습하는 동안 I/O 큐에서 데이터 전처리 작업을 실행하여 I/O가 GPU 디스패치를 차단하지 않도록 합니다.
연구 재현성 – 모든 실행의 입력, 코드, 아티팩트를 콘텐츠 주소 지정 저장소에 저장하고, 동일한 작업 공간으로 나중에 실행을 재현합니다.
멀티 테넌트 클러스터 – 분리된 큐는 장기 실행 CPU 작업이 짧은 GPU 추론 요청을 굶기지 않도록 보장합니다.
동적 에이전트 추론 – DynamicRun을 사용하여 LLM이 런타임에 다음 행동을 결정하고 새 작업을 즉석에서 추가하도록 합니다.

빠른 시작 (README에서)

# 설치
pip install maze-agent

# 헤드 노드와 웹 UI(Workbench) 시작
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>

모든 실행 메타데이터가 통합 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를 소유하며, 워커는 작업을 실행하고 보고만 합니다.

커뮤니티 및 인용

연구에서 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 에이전트 파이프라인을 위한 프로덕션급 런타임을 제공합니다: 이기종 리소스 간 스케줄링, 실행 지속성, 주문형 모델 서빙, 설계 및 디버깅을 위한 시각적 UI를 모두 하나의 Python 친화적 API로 처리합니다.