opd-tuning

Diagnoses and tunes Relax on-policy distillation teacher engine configurations and GPU splits.

585|144|Updated Apr 13, 2026
One-click install
npx skills add https://github.com/redai-infra/Relax --skill opd-tuning
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: opd-tuning
Source: https://github.com/redai-infra/Relax/tree/main/skills/opd-tuning
Command: npx skills add https://github.com/redai-infra/Relax --skill opd-tuning

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

On-policy distillation (OPD/MOPD) runs in Relax often suffer from teacher engine OOMs, teacher timeouts, and idle student or teacher GPUs caused by misconfigured SGLang flags, logits memory peaks, and unbalanced GPU partitioning. This Skill analyzes an OPD launch script and produces a cited diagnosis report with concrete, ordered fixes.

Core Features & Use Cases

  • Teacher knob auditing: Evaluates ten rules (R-T01 to R-T10) covering mem-fraction-static, logits chunking, chunked-prefill sizing, CUDA graph phases, TP vs replicas, timeouts, VLM cache, env propagation, and max-running-requests.
  • Balance analysis: Measures student/teacher capacity imbalance via GPU sampling, engine log windows, and wait-time metrics, then computes feasible GPU repartition points under divisibility constraints.
  • Baseline anchoring: Compares the script against snapshot configurations from working OPD examples to flag untuned settings.
  • Use Case: A user reports teacher OOM at logits[input_logprob_indices] on a multimodal MOPD run; the Skill computes the logits peak from vocab size and chunk size, recommends enabling logits chunking before raising prefill budgets, and emits an ordered fix list.

Quick Start

Run the opd-tuning skill on my OPD launch script examples/on_policy_distillation/mopd/run-mopd-qwen35-9b-8xgpu-colocate.sh and diagnose why the teacher engine is OOMing.

Frequently Asked Questions about opd-tuning

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix teacher engine OOM in Relax on-policy distillation?

Teacher OOM in OPD usually comes from the full-vocabulary logits tensor sized N_positions times vocab/TP times 4 bytes. Enable SGLang logits chunking first, then raise chunked-prefill-size, and only then consider raising teacher TP or repartitioning GPUs.

How do I balance student and teacher GPUs in colocate OPD?

Measure both sides with nvidia-smi sampling or engine log time windows, compute the work ratio r, then assign teacher GPUs approximately G*r/(1+r). The split must satisfy rollout plus teacher equals actor GPUs and both sides' per-engine divisibility constraints.

Why is my SGLang environment variable not taking effect in Relax?

Relax rebuilds each actor's runtime env and only copies variables explicitly listed in RELAX_PROPAGATE_ENV_VARS. Scripts submitted via ray job submit must also merge the variable into the runtime-env JSON, since the driver does not inherit the submitting shell.

Should I disable CUDA graphs for the OPD teacher engine?

The teacher is pure prefill, so decode CUDA graphs are never replayed and disabling them saves capture time and memory. Prefill graphs are actually used, so keep them unless measurement shows otherwise; newer SGLang versions split these into per-phase flags.

What are the limits of this OPD tuning approach?

It only covers OPD-specific teacher-side issues; general actor training performance, TP/PP/CP, recompute, and hang debugging belong to other skills. It also cannot rely on teacher-side metrics because none exist, so diagnosis depends on logs and GPU sampling.