verl

Use this repo skill when a user asks how to install, configure, run, debug, or maintain verl, the Volcano Engine Reinforcement Learning library for LLM post-training.

Start Here

• Read references/repo-provenance.md before relying on this skill for a different checkout or after package metadata, config files, examples, or docs change.
• Read references/troubleshooting.md for cross-cutting failures that span setup, Hydra configs, data schema, rollout backends, checkpoint operations, and repo maintenance.
• Run scripts/check_skill_integrity.py when editing or importing this skill to check frontmatter, links, private-path leaks, and generated cache files.

Route By User Task

• Install or verify an environment: use sub-skills/setup-and-backends/ for base install choices, Docker-vs-custom setup, Python/CUDA requirements, optional extras, vLLM/SGLang/Megatron/TensorRT-LLM/NPU/ROCm caveats, and safe import/backend checks.
• Prepare or validate data and rewards: use sub-skills/data-and-rewards/ for parquet row schemas, chat prompt fields, reward_model.ground_truth, custom reward modules, and the bundled parquet validator.
• Build training commands and Hydra overrides: use sub-skills/training-and-configs/ for PPO, GRPO, SFT, on-policy distillation, backend strategy switches, batch/micro-batch sizing, generated config references, and the dry-run PPO command builder.
• Configure rollout, agent loops, and tools: use sub-skills/rollout-and-tools/ for rollout engines, async generation server flows, multi-turn agent loops, @function_tool, native BaseTool, tokenization sanity checks, traces, and tool schema validation.
• Operate checkpoints and model artifacts: use sub-skills/checkpoints-and-model-ops/ for checkpoint layout inspection, verl.model_merger, FSDP/Megatron/HuggingFace export decisions, LoRA merge implications, profiling, and performance diagnostics.
• Maintain the repository: use sub-skills/repo-development/ for contribution policy, duplicate-work checks, AGENTS.md editing rules, generated trainer config maintenance, focused test selection, and non-executing test suggestions.

Common Decision Points

• If the user says “training fails,” first classify the failure: installation/import (setup-and-backends), parquet/reward schema (data-and-rewards), Hydra override/resource sizing (training-and-configs), rollout backend/tooling (rollout-and-tools), or checkpoint/export (checkpoints-and-model-ops).
• If the user asks for a command, prefer the nearest bundled command builder or validator; never require the original source checkout examples to remain available.
• If the user asks for GPU execution, distinguish a base Python import check from real accelerator runtime validation. vLLM, SGLang, Megatron, flash-attn, TensorRT-LLM, ROCm, and NPU stacks need backend-specific environments.
• If the user is editing the repo, apply repo-development before changing files so duplicate-work, AGENTS.md scope, generated config, and focused-test rules are not missed.

Bundled Helpers

• sub-skills/setup-and-backends/scripts/check_verl_environment.py checks active Python package metadata, imports, optional CUDA state, and dependency consistency.
• sub-skills/data-and-rewards/scripts/validate_verl_parquet.py validates verl parquet rows without importing verl.
• sub-skills/training-and-configs/scripts/build_ppo_command.py prints a dry-run python -m verl.trainer.main_ppo command from common arguments.
• sub-skills/rollout-and-tools/scripts/validate_function_tool.py preflights trusted function-tool Python files for type hints and Google-style Args: docs.
• sub-skills/checkpoints-and-model-ops/scripts/inspect_checkpoint_path.py classifies checkpoint/run/role directories without loading tensors.
• sub-skills/repo-development/scripts/select_verl_tests.py maps changed paths to suggested tests and pre-commit hooks without running them.

Safety Rules

• Do not run training, dataset downloads, Docker builds, GPU/NPU jobs, checkpoint merges, or source-mutating maintenance scripts unless the user explicitly asks and the environment is appropriate.
• Treat original repo docs, examples, scripts, and tests as evidence only. Runtime guidance in this skill is self-contained and should use bundled references/scripts.
• Do not leak local checkout paths, private Python prefixes, cache paths, credentials, or machine-specific install commands into public skill content.
• For native verification, prefer CPU-safe tests and help/parser checks first; record GPU/NPU/e2e examples as skipped unless the user authorizes heavy hardware runs.