[tdene]

What does this PR do ?

policy_staleness describes how many checkpoints off-policy a request's tokens are. kv_cache_staleness describes how many checkpoints off-policy a request's KV$ is. policy_staleness >= kv_cache_staleness. Both are tracked on a per-token basis.

When not using recompute, the two metrics are expected to overlap - with one exception. If the KV cache buffer is full and needs to evict paused requests to make room, this will null kv_cache_staleness while not affecting policy_staleness. num_evictions is a per-request metric that tracks such "natural" prefill recompute.

Request staleness is tracked inside the engine. Once a request finishes, it leaves the engine. Since a request may not be consumed until much later than it finishes, RL has to manually increment staleness. This is represented by completion_gap and is graphed as mean_completion_gap.

Contribution process

flowchart LR
    A[Pre-checks] --> B[PR Tests]
    subgraph Code Review/Approval
        C1[Expert Review] --> C2[Final Review]
    end
    B --> C1
    C2 --> D[Merge]

Loading

Pre-checks

• I want this PR in a versioned release and have added the appropriate Milestone (e.g., Core 0.8)
• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code Typing guidelines
• I have added relevant documentation
• I have run the autoformatter.sh on my PR

Code review

The following process is enforced via the CODEOWNERS file for changes into megatron/core. For changes outside of megatron/core, it is up to the PR author whether or not to tag the Final Reviewer team.

For MRs into `main` branch

Feel free to message or comment the @mcore-oncall to help accelerate your merge into main. The less complex your PR is, the faster it will be approved and merged!

(Step 1): Add PR label Expert Review

(Step 2): Collect the expert reviewers reviews

1. Attach the Expert Review label when your PR is ready for review.
2. GitHub auto-assigns expert reviewers based on your changes. They will get notified and pick up your PR soon.

⚠️ Only proceed to the next step once all reviewers have approved, merge-conflict are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

(Step 3): Final Review

1. Add Final Review label
2. GitHub auto-assigns final reviewers based on your changes. They will get notified and pick up your PR soon.

(Optional Step 4): Cherry-pick into release branch

If this PR also needs to be merged into core_r* release branches, after this PR has been merged, select Cherry-pick to open a new PR into the release branch.

For MRs into `dev` branch

The proposed review process for `dev` branch is under active discussion.

MRs are mergable after one approval by either eharper@nvidia.com or zijiey@nvidia.com.

Merging your PR

Any member of core-adlr and core-nemo will be able to merge your PR.

[yobibyte]

What if gap is 0?

[tdene]

Then we're doing a list comprehension with [x+0 for x in l], and that seemed uglier to me.

[yobibyte]

LGTM! Thanks for addressing my comments.

[svcnvidia-nemo-ci]

🔄 Merge queue validation started!

You can track the progress here: https://github.com/NVIDIA/Megatron-LM/actions/runs/22455951465

[svcnvidia-nemo-ci]

🔄 Merge queue validation started!

You can track the progress here: https://github.com/NVIDIA/Megatron-LM/actions/runs/22456323984