[Liu-KM]

What does this PR do?

Users moving between mainline OPD and verl-recipe/gkd can select similarly named losses with different token support and normalization. Add a source-backed comparison to the OPD guide covering sampled-token estimators, teacher top-k objectives, config namespaces, migration choices, and the recipe's JSD beta clamping. Reuse the existing GKD/PG examples and distinguish raw loss/gradient scaling from optimizer updates.

Fixes #7975. This changes documentation only; the comparison is pinned to recipe commit 5451026758c3f1dc3ebc2a46a0e52b14406f0f72.

Checklist Before Starting

• Searched PRs referencing #7975 and GKD PRs, plus OPD/JSD keywords and the issue timeline, on 2026-09-22. No overlapping comparison PR was found: test(distillation): add value-level CPU tests for forward_kl_topk OPD loss #6822 adds numerical tests, while [trainer] feat: add reverse KL top-k distillation loss #7590 and [algo, fsdp, megatron, veomni] feat: add tail-aware top-k KL for on-policy distillation #7855 document new objectives rather than mapping existing mainline and recipe modes.
• Title uses the required [doc] fix: format.

Test

The following checks were run with AI assistance.

• git diff --check — passed.
• pre-commit run check-docs-time-info --files docs/algo/opd.md --show-diff-on-failure — passed.
• sphinx-build -E -a -b html docs /tmp/verl-7975-docs-html — succeeded with 323 warnings in an isolated documentation environment. An unmodified-mainline build in the same environment produced the same 323 warnings; normalized warning contents matched exactly. Checked the generated comparison table, math markup, and source links.
• No runtime tests were added or run because no code or formulas change. Full pre-commit across unrelated Python/config files was not run.

API and Usage Example

No API changes. The new section links the existing GKD and PG OPD examples to the corresponding loss/config choices.

Design & Code Changes

One comparison subsection in docs/algo/opd.md, plus its last-updated date.

Checklist Before Submitting

• Read CONTRIBUTING.md and AGENTS.md.
• Updated the documentation.
• Human submitter reviewed every changed line, verified the source interpretation, and ran the relevant checks as required by AGENTS.md.
• Request CI according to the repository contribution process when ready.

AI assistance was used to inspect both implementations, prepare the patch, run the listed checks, and perform an independent source review. This PR is a draft pending the human submitter's line-by-line review and execution of relevant checks required by AGENTS.md.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}