miniverl 0.8.0

PyPI · Stable docs · Development docs · 中文

Run a documented subset of verl-style on-policy distillation on one consumer GPU. miniVERL accepts a typed verl v0.8 OPD profile and Parquet prompts, executes actor rollout → teacher scoring → actor update locally, and exports standard PEFT/Parquet/config artifacts for scale-out. Native SFT, DPO, KD and tool-agent recipes remain available.

PyPI v0.8.0 is stable; main is development. miniVERL is independent from verl. It does not claim arbitrary verl YAML execution, distributed execution, or full algorithmic compatibility.

Pip-only OPD quickstart

python -m pip install "miniverl[train]"
miniverl data sample --format verl-parquet --out prompts.parquet
miniverl plan --profile verl-opd-v0.8-single-gpu-v1 --config builtin:qwen3-0.6b-1.7b-opd \
  --set 'data.train_files=["prompts.parquet"]'
miniverl run --profile verl-opd-v0.8-single-gpu-v1 --config builtin:qwen3-0.6b-1.7b-opd \
  --set 'data.train_files=["prompts.parquet"]' --dry-run

The sample, plan and dry run need no Git checkout; planning loads no weights. Remove --dry-run on one CUDA GPU to execute the pinned Qwen3-0.6B/1.7B NF4 recipe and produce a loadable PEFT adapter. Follow the OPD quickstart.

Supported hardware and runtime boundary

miniVERL runs one local process on CPU or one NVIDIA CUDA GPU. The CUDA path is device-name agnostic, but fit depends on model pair, context, kernels and VRAM. Install the matching CUDA-enabled PyTorch build first, then miniverl[train,cuda]; that extra does not select a CUDA PyTorch wheel. Ray, FSDP, Megatron, PPO, GRPO and distributed launch are outside the runtime. See the single-GPU guide.

verl compatibility summary

The executable profile targets official verl v0.8.0 at commit 7aed6b23 and supports one actor, one teacher, n=1, pure GKD forward_kl_topk, token-mean aggregation, LoRA/QLoRA and no reward/KL penalty. PG OPD, task-reward mixtures, multi-teacher, multimodal and distributed fields fail closed.

Compatible OPD exports contain no reward scaffold. They preserve student and teacher identities, Parquet bytes and OPD overrides, but remain launchable: false until exact base snapshots are materialized. Parse status, artifact loadability, launchability and distributed execution are separate. Read the bridge contract.

Measured RTX 4080 runtime

The packaged Qwen3-0.6B/1.7B recipe completed two 16-token rollouts and one OPD update with 3.1758 GiB peak reserved VRAM; the first update completed in 12.0224 s and the standard PEFT adapter reloaded successfully. This proves one runtime/artifact path only—no alignment-quality endpoint or method comparison ran. Exact recipe, timings and hashes.

Three paths

Research notes and preserved negative evidence

v0.7 External Alignment Gate

The preregistered external study stopped before teacher or method training. Both declared starting-policy lineages scored 0/64 retained JSONNav utility for every candidate against the unchanged 20% floor.

miniverl pilot --builtin-study alignment-external-v1 --json

The result is do_not_continue_this_study and insufficient_evidence, not a recommendation among SFT/DPO/KD/OPD. Granite Guardian values are unqualified selection diagnostics; Granite, PairRM and teacher qualification and the reserved final test did not run. Study and limitations.

Earlier measured alignment case study

Alignment Lab v1 began from an SFT checkpoint already at 100% policy compliance and 100% retained tool utility in all three seeds. No continuation improved the ceiling; continued SFT and both OPD variants retained measured regressions. The two sandbox safety checks tied at zero while utility still regressed. IFEval, XSTest, HarmBench and RewardBench were not executed, and “preference win rate” is a deterministic Minipolicy paired outcome, not human preference. Seed-level evidence.

• RecoveryBench v1: frozen-student KD beat slower fresh-state OPD on the preregistered primary view; the verifier gate remained insufficient_evidence.
• Calculator benchmark: both negative controls completed normally at 0%; the ambiguous historical protocol-v1 prompt prevents attributing failure solely to intrinsic teacher behavior.
• Limitations, math, reproducibility and compatibility policy.

New runs establish tokenizer compatibility through structural identity. The legacy behavioral fingerprint is only a migration fallback, not identity proof.

Develop

git clone https://github.com/DaoyuanLi2816/mini-verl.git
cd mini-verl
python -m pip install -e ".[dev]"
pytest -q -m "not gpu and not network"

Apache-2.0 licensed. See CONTRIBUTING.md, SECURITY.md, the changelog and citation. Project records: default GPU recipe, frozen calculator result and license.