# alibaba/chatlearn architecture

> Architecture diagram of the GitHub repository alibaba/chatlearn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alibaba/chatlearn
- Repository: https://github.com/alibaba/chatlearn

## Overview

##### Project type and purpose
- ChatLearn is neither a web app nor a GUI tool but a Python-based, large-scale alignment training framework (RLHF, DPO, OnlineDPO, GRPO) developed by Alibaba Cloud PAI.
- It orchestrates distributed training/inference workflows over backends such as Megatron-LM, vLLM (and plans for DeepSpeed), managing data flow, resource scheduling, parallel strategies, and checkpointing.

##### High-level file-structure analysis
- Top-level directories:
- chatlearn/            ← core framework code
- examples/             ← end-to-end usage examples (HuggingFace, Megatron)
- docs/                 ← user/developer documentation
- tests/                ← unit/integration tests
- docker/               ← container definitions
- .github/              ← CI/CD workflows
- Key submodules under chatlearn/:
- checkpoint/          ← checkpoint manager
- data/                ← data ingestion, sampling, ranking, storage
- launcher/            ← CLI or programmatic entrypoint, configuration parsing
- runtime/             ← engine, trainer, executor, environment, decorators
- schedule/            ← resource, port, and model manager for distributed scheduling
- synchronizer/        ← inter-model parameter synchronization
- models/              ← adapters for Megatron-LM, DeepSpeed, vLLM, plus base modules
- tools/               ← conversion utilities (Megatron ↔ HF)
- utils/               ← logging, timing, argument parsing, distributed helpers

##### Readme insights
- It emphasizes a separation of concerns: model definition vs. system scheduling vs. execution backends.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface / Launcher
    subgraph "User Interface / Launcher"
        UI["Launcher"]:::core
    end

    %% Scheduler Layer
    subgraph "Scheduler Layer"
        RM["ResourceManager"]:::core
        PM["PortManager"]:::core
        MMg["ModelManager"]:::core
    end

    %% Runtime Engine
    subgraph "Runtime Engine"
        Eng["Engine"]:::core
        Tr["Trainer"]:::core
        Exe["Executor"]:::core
        Env["Environment"]:::core
        Dec["Decorator"]:::core
        Ev["Evaluator"]:::core
        MF["ModelFlow"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        DS["DataSampler"]:::core
        RK["Ranking"]:::core
        ST["Storage"]:::core
        DI["Data I/O"]:::core
    end

    %% Synchronization Layer
    subgraph "Synchronization Layer"
        PS["ParameterSync"]:::core
        BS["BaseSync"]:::core
        MMsync["Megatron↔Megatron Sync"]:::core
        MVsync["Megatron↔vLLM Sync"]:::core
    end

    %% Model Backends
    subgraph "Model Backends"
        MMo["Megatron-LM Adapter"]:::backend
        VLM["vLLM Adapter"]:::backend
        DSP["DeepSpeed Adapter"]:::backend
    end

    %% Checkpoint Manager
    subgraph "Checkpoint Manager"
        CP["CheckpointManager"]:::core
    end

    %% Conversion Tools
    subgraph "Conversion Tools"
        CT["Megatron↔HF Tools"]:::core
    end

    %% External Infrastructure
    subgraph "External Infrastructure"
        Infra["GPU Cluster / Docker / Storage"]:::infra
    end

    %% Connections
    UI -->|"submit configs"| RM
    UI -->|"submit configs"| PM
    UI -->|"submit configs"| MMg

    RM -->|"allocate resources"| Eng
    PM -->|"assign ports"| Eng
    MMg -->|"instantiate models"| Eng

    Eng -->|"fetch data"| DS
    Eng -->|"fetch data"| RK
    Eng -->|"fetch data"| ST
    Eng -->|"fetch data"| DI

    Eng -->|"forward/backward"| MMo
    MMo -->|"results"| Eng
    Eng -->|"forward/backward"| VLM
    VLM -->|"results"| Eng
    Eng -->|"forward/backward"| DSP
    DSP -->|"results"| Eng

    Eng -->|"sync params"| PS
    Eng -->|"sync base"| BS
    Eng -->|"sync M-M"| MMsync
    Eng -->|"sync M-V"| MVsync

    Eng -->|"save/load state"| CP
    Eng -->|"convert checkpoints"| CT
    Eng -->|"use GPU / network"| Infra

    %% Click Events
    click UI "https://github.com/alibaba/chatlearn/tree/main/chatlearn/launcher"
    click RM "https://github.com/alibaba/chatlearn/blob/main/chatlearn/schedule/resource_manager.py"
    click PM "https://github.com/alibaba/chatlearn/blob/main/chatlearn/schedule/port_manager.py"
    click MMg "https://github.com/alibaba/chatlearn/blob/main/chatlearn/schedule/model_manager.py"
    click Eng "https://github.com/alibaba/chatlearn/blob/main/chatlearn/runtime/engine.py"
    click Tr "https://github.com/alibaba/chatlearn/blob/main/chatlearn/runtime/trainer.py"
    click Exe "https://github.com/alibaba/chatlearn/blob/main/chatlearn/runtime/executor.py"
    click Env "https://github.com/alibaba/chatlearn/blob/main/chatlearn/runtime/environment.py"
    click Dec "https://github.com/alibaba/chatlearn/blob/main/chatlearn/runtime/decorator.py"
    click Ev "https://github.com/alibaba/chatlearn/blob/main/chatlearn/runtime/evaluator.py"
    click MF "https://github.com/alibaba/chatlearn/blob/main/chatlearn/runtime/model_flow.py"
    click DS "https://github.com/alibaba/chatlearn/blob/main/chatlearn/data/sampler.py"
    click RK "https://github.com/alibaba/chatlearn/blob/main/chatlearn/data/ranking.py"
    click ST "https://github.com/alibaba/chatlearn/blob/main/chatlearn/data/storage.py"
    click DI "https://github.com/alibaba/chatlearn/blob/main/chatlearn/data/data.py"
    click PS "https://github.com/alibaba/chatlearn/blob/main/chatlearn/synchronizer/parameter_sync.py"
    click BS "https://github.com/alibaba/chatlearn/blob/main/chatlearn/synchronizer/base.py"
    click MMsync "https://github.com/alibaba/chatlearn/blob/main/chatlearn/synchronizer/megatron_megatron.py"
    click MVsync "https://github.com/alibaba/chatlearn/blob/main/chatlearn/synchronizer/megatron_vllm.py"
    click MMo "https://github.com/alibaba/chatlearn/blob/main/chatlearn/models/megatron_module.py"
    click VLM "https://github.com/alibaba/chatlearn/blob/main/chatlearn/models/vllm_module.py"
    click DSP "https://github.com/alibaba/chatlearn/blob/main/chatlearn/models/deepspeed_module.py"
    click CP "https://github.com/alibaba/chatlearn/blob/main/chatlearn/checkpoint/checkpoint_manager.py"
    click CT "https://github.com/alibaba/chatlearn/blob/main/chatlearn/tools/megatron_to_hf.py"
    click Infra "https://github.com/alibaba/chatlearn/tree/main/docker/torch"

    %% Styles
    classDef core fill:#cce5ff,stroke:#2b6cb0,color:#1a365d;
    classDef backend fill:#ffe5b4,stroke:#c05621,color:#7b341e;
    classDef infra fill:#e6ffed,stroke:#2f855a,color:#22543d;
```
