docs(weave): add VERL integration guide

[dbrian57]

Summary

• Adds a new Weave integration guide for VERL (Volcano Engine Reinforcement Learning) at weave/guides/integrations/verl.mdx.
• Documents enabling the Weave rollout trace backend via actor_rollout_ref.rollout.trace.backend=weave, tuning trace volume with max_samples_per_step_per_worker, viewing traces in the W&B project, and extending coverage with rollout_trace_op / rollout_trace_attr.
• Adds the new page to the Frameworks group in docs.json, next to other RL framework integrations (verifiers, verdict).

Jira: DOCS-2509

Test plan

• Mintlify preview renders the new page correctly
• Page appears in the sidebar under Integrate with your LLM provider and frameworks > Frameworks
• Code examples run end-to-end against a live VERL training job with WANDB_API_KEY set and async rollout enabled
• SME accuracy review (see PR comment)

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wandb	🟢 Ready	View Preview	May 14, 2026, 2:54 PM

[github-actions]

📚 Mintlify Preview Links

🔗 View Full Preview

✨ Added (1 total)

📄 Pages (1)

File	Preview
weave/guides/integrations/verl.mdx	Verl

📝 Changed (1 total)

⚙️ Other (1)

File
docs.json

---

🤖 Generated automatically when Mintlify deployment succeeds
📍 Deployment: c7d0f87 at 2026-05-14 14:54:59 UTC

[github-actions]

🔗 Link Checker Results

✅ All links are valid!

No broken links were detected.

Checked against: https://wb-21fd5541-dbrian-docs-2509-verl-integration.mintlify.app

[dbrian57]

Sources and decision log

Sources

• VERL upstream PR that added Weave tracing: volcengine/verl#2345 — "[misc] feat: trace rollout generation and tool calls using weave" by @chenhaiq, merged 2025-07-08. Established the config keys, the two helper APIs (rollout_trace_op, rollout_trace_attr), and the async-rollout limitation.
• VERL upstream docs: Trace Function Usage Instructions — canonical reference for the config flags, max_samples_per_step_per_worker semantics, the GRPO total-traces formula (max_samples_per_step_per_worker * num_workers * n), the filter keys (step, sample_index, rollout_n, experiment_name), and the 1 GB / "dozens of GB/day" data-volume note.
• Existing Weave integration patterns: weave/guides/integrations/verifiers.mdx — used as the structural model since Verifiers is the closest existing RL integration page.
• Internal context (Glean): WBDOCS-1357 / DOCS-2509 ticket, plus Slack threads where Samin Alnajafi (2025-11-07) and Deok Filho (2026-04-20) flagged customer interest in VERL on-prem and sandbox-based RL scenarios.

Decisions

• Trainer command example uses python -m verl.trainer.main_ppo. The upstream docs don't show a verbatim CLI invocation — they only list flags. I picked PPO as the most common entry point. See "Needs SME verification" below.
• Claim that VERL initializes Weave automatically. The upstream PR and RST docs strongly imply this (VERL passes the trainer.project_name through to Weave when the weave backend is selected) but neither states it verbatim. The page says: "Weave is initialized automatically from your W&B project and experiment name — you do not need to call weave.init() yourself." Flagged for SME verification.
• token2text default = False. Sourced from the PR description, which explicitly says "Defaults to False for better performance." The RST example uses True, but that's an illustrative override.
• No "How It Works" section. Per the established pattern for short Weave integration pages (bedrock, claude_agent, verifiers).
• Nav placement under Frameworks, next to verifiers and verdict. VERL is an RL post-training framework, matching the other RL pages in that group.
• No screenshot or GIF. Upstream docs reference two screenshots in eric-haibin-lin/verl-community (weave_trace_list.png, weave_trace_compare.png) but I did not pull them in — they should be hosted in the wandb/docs images/ tree before being included.

Intentionally omitted

• mlflow trace backend. The upstream docs cover both Weave and mlflow; this page intentionally only covers Weave.
• A working train_*.py script. The reader is expected to bring their own VERL training config; the integration is purely a flag/env-var addition. Including a full script would duplicate VERL's own tutorials and quickly go stale.
• weave.Model / @weave.op examples. VERL drives the trace decorators itself via rollout_trace_op and rollout_trace_attr, so generic Weave op wrapping is out of scope.

Needs SME verification

• Trainer entry-point. Confirm python -m verl.trainer.main_ppo is the right default in the CLI example, or whether to swap for a more generic [YOUR-TRAINER-COMMAND] placeholder. Multiple entry points exist (PPO, GRPO, etc.).
• Implicit weave.init(). Confirm that VERL initializes Weave for the user when actor_rollout_ref.rollout.trace.backend=weave is set, and the user does not need to call weave.init() themselves. If they do need to call it, the example should add an explicit weave.init() line and a note.
• Screenshots. Decide whether the page should include weave_trace_list.png and weave_trace_compare.png (with copies hosted in images/weave/) or stay text-only.
• VERL version requirement. PR docs(locadex): update translations on auto_translation_demo #2345 merged on 2025-07-08. Confirm the minimum VERL version readers need (a release-tag link would be more useful than a PR link in the Prerequisites bullet).
• async mode applies to both vLLM and SGLang. Upstream docs say "async mode for either vllm or sglang." Confirm there isn't an additional engine-specific flag readers need.

Related

• Jira: DOCS-2509 (originally WBDOCS-1357)
• VERL upstream PR: volcengine/verl#2345
• VERL rollout trace docs: https://verl.readthedocs.io/en/latest/advance/rollout_trace.html

Resume prompt

I'm picking up work on #2631 (Jira: DOCS-2509), a new Weave integration page for VERL (Volcano Engine Reinforcement Learning) at weave/guides/integrations/verl.mdx. The page documents enabling the Weave rollout trace backend in a VERL training command via actor_rollout_ref.rollout.trace.backend=weave, tuning trace volume with max_samples_per_step_per_worker, viewing traces in the W&B project sidebar, and extending coverage with rollout_trace_op / rollout_trace_attr. It's listed under the Frameworks group in docs.json, next to verifiers and verdict. Decisions made: used python -m verl.trainer.main_ppo as the example trainer command, claimed VERL handles weave.init() implicitly, set token2text default to False (from PR description), no "How It Works" section, no screenshots. Outstanding items for SME verification are listed under "Needs SME verification" in the PR comment. The canonical upstream reference is https://verl.readthedocs.io/en/latest/advance/rollout_trace.html and the source PR is verl-project/verl#2345.

{
  "skill": "docs",
  "version": "unknown",
  "depends_on": "unknown",
  "model": "claude-opus-4-7",
  "note": "versions.json not present in the skill folder at runtime"
}