 |
VOOZH | about |
|
VOOZH | about |
This document describes AReaL's dependency management system, package installation workflows, and versioning strategy. It covers the use of uv as the package manager, dependency specifications in pyproject.toml, optional extras for different backends, and the dual-lockfile system used to support conflicting inference backends.
AReaL uses uv as its primary package manager pyproject.toml2-3 The choice of uv provides significantly faster dependency resolution, reproducible builds via lock files, and automated virtual environment management compared to traditional pip or poetry.
The build system is configured in pyproject.toml using uv_build as the backend pyproject.toml1-3:
The package is configured with a flat layout where the module root is the project directory, allowing for direct imports of top-level modules pyproject.toml216-218
Sources: pyproject.toml1-3 pyproject.toml216-218
The project metadata defines the package identity and requirements in pyproject.toml pyproject.toml5-11:
| Field | Value |
|---|---|
| Name | areal |
| Version | 1.0.4 |
| Python Requirement | >=3.11,<3.13 |
| License | Apache-2.0 |
| Description | A Large-Scale Asynchronous Reinforcement Learning System |
Platform support is restricted to environments where CUDA packages have pre-built wheels or where development is supported. This is configured in the [tool.uv] section pyproject.toml220-228:
This ensures uv only resolves dependencies for supported platforms, preventing failures on macOS when CUDA-only packages (like megatron-core) lack compatible wheels pyproject.toml221-228
Sources: pyproject.toml5-11 pyproject.toml220-228
AReaL's core dependencies are organized into functional categories in pyproject.toml pyproject.toml43-138:
"Natural Language Space to Code Entity Space: Core Dependency Mapping"
Most dependencies use minimum version constraints, but several are pinned to exact versions or specific ranges due to tight coupling pyproject.toml52-118:
transformers>=5.0.0,<=5.3.0: Specific model architecture compatibility pyproject.toml52omegaconf==2.4.0.dev2 & hydra-core==1.4.0.dev1: Required for the hierarchical dataclass-based configuration system pyproject.toml82-83math-verify==0.8.0: Specific version for math reasoning reward parsing and verification pyproject.toml89swanlab[dashboard]==0.6.12: Precise version for integrated experiment tracking pyproject.toml119Sources: pyproject.toml43-138
CUDA packages are separated into optional extras because they require specific hardware and drivers. Platform markers ensure they're only installed on compatible Linux systems pyproject.toml141-143
"Natural Language Space to Code Entity Space: Optional Extras Hierarchy"
The extras are defined in pyproject.toml pyproject.toml141-186:
| Extra | Contents | Platform Requirement | Purpose |
|---|---|---|---|
| sglang | sglang[tracing]==0.5.10.post1 | Linux x86_64 | SGLang inference backend |
| megatron | megatron-core==0.17.0 | Linux x86_64 | Megatron training backend |
| tms | torch_memory_saver==0.0.9 | Linux | Memory optimization (Checkpointing) |
| kernels | kernels==0.12.2 | N/A | HF Kernels runtime |
| cuda-train | tms + megatron + kernels + tilelang | Linux x86_64 | Training-only bundle |
| cuda | cuda-train + sglang | Linux x86_64 | Full stack bundle (SGLang) |
Sources: pyproject.toml141-186
SGLang and vLLM pin mutually-incompatible versions of torch and torchao. To manage this, AReaL uses two separate configuration files: pyproject.toml (defaulting to SGLang/torch 2.9) and pyproject.vllm.toml (vLLM/torch 2.10) pyproject.vllm.toml3-5
The areal/tools/check_pyproject_consistency.py script enforces that all non-backend-specific packages (defined in ESCAPABLE_PACKAGES) remain identical between the two files areal/tools/check_pyproject_consistency.py32-46
Users switch variants by swapping the files and lock files docs/en/tutorial/installation.md114-118:
The script scripts/uv_lock.sh automates the generation of both uv.lock and uv.vllm.lock by temporarily swapping the project files scripts/uv_lock.sh42-47
Sources: pyproject.vllm.toml3-5 scripts/uv_lock.sh36-51 areal/tools/check_pyproject_consistency.py32-46
The lock file uv.lock ensures reproducible builds across environments. It contains resolution markers for different Python and platform combinations uv.lock4-13 A separate uv.vllm.lock is maintained for the vLLM variant uv.vllm.lock1-13
AReaL uses manifest overrides to resolve version conflicts between transitive dependencies in uv.lock uv.lock21-37:
This ensures consistent versions are used even when sub-dependencies (like litellm or sglang) request conflicting versions pyproject.toml229-238
Sources: uv.lock1-37 pyproject.toml229-238 uv.vllm.lock1-33
Development tools are specified as a dependency group in pyproject.toml pyproject.toml193-210:
The project enforces code quality through pre-commit hooks. These include:
ruff: Python linting and formatting pyproject.toml198clang-format: Formatting for C++/CUDA files pyproject.toml199mdformat: Markdown formatting pyproject.toml201-204Sources: pyproject.toml193-210
The Dockerfile implements a multi-stage installation strategy to handle heavy C++ dependencies and backend variants.
The VARIANT build argument determines the torch version and the inference backend Dockerfile1-15
sglang (default): Installs torch==2.9.1 Dockerfile62vllm: Installs torch==2.10.0 Dockerfile62Heavy C++ dependencies are compiled early in the Dockerfile to leverage layer caching Dockerfile75-159:
torch_memory_saver: Built with TMS_CUDA_MAJOR=12 Dockerfile76-77grouped_gemm: v1.1.4 for MoE support Dockerfile80-81apex: Built with APEX_PARALLEL_BUILD=8 Dockerfile84-86TransformerEngine: Required for FP8 training Dockerfile89-90FlashMLA, DeepGEMM, and DeepEP are installed from source Dockerfile92-112Refresh this wiki