Skip to content

feat: add checkpoint-engine refit interface and integrate NIXL#2608

Open
HollowMan6 wants to merge 6 commits into
NVIDIA-NeMo:mainfrom
HollowMan6:nixl
Open

feat: add checkpoint-engine refit interface and integrate NIXL#2608
HollowMan6 wants to merge 6 commits into
NVIDIA-NeMo:mainfrom
HollowMan6:nixl

Conversation

@HollowMan6

@HollowMan6 HollowMan6 commented May 28, 2026

Copy link
Copy Markdown
Member

What does this PR do ?

Adds checkpoint-engine based non-colocated GRPO refit with a NIXL backend for policy-to-vLLM weight transfer.

Issues

List issues that this PR closes (syntax):

Usage

Enable checkpoint-engine refit for non-colocated generation:

policy:                                                                                                                       
  generation:                                                                                                                 
    colocated:                                                                                                                
      enabled: false                                                                                                          
    checkpoint_engine:                                                                                                        
      enabled: true                                                                                                           
      backend: nixl                                                                                                           
      update_weights_bucket_megabytes: 2048                                                                                   
      engine_kwargs:                                                                                                          
        nixl:                                                                                                                 
          device: cpu                                                                                                         
          cleanup_after_load: false

Before your PR is "Ready for review"

Pre checks:

  • Make sure you read and followed Contributor guidelines
  • Did you write any new necessary tests?
  • Did you run the unit tests and functional tests locally? Visit our Testing Guide for how to run tests
  • Did you add or update any necessary documentation? Visit our Document Development Guide for how to write, build and test the docs.

Additional Information

@copy-pr-bot

copy-pr-bot Bot commented May 28, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@HollowMan6
HollowMan6 force-pushed the nixl branch 3 times, most recently from ebf023f to e5829e0 Compare May 30, 2026 20:42
@github-actions github-actions Bot added the Documentation Improvements or additions to documentation label May 30, 2026
@HollowMan6
HollowMan6 marked this pull request as ready for review May 30, 2026 21:02
Copilot AI review requested due to automatic review settings May 30, 2026 21:02
@HollowMan6
HollowMan6 requested review from a team as code owners May 30, 2026 21:02
@copy-pr-bot

copy-pr-bot Bot commented May 30, 2026

Copy link
Copy Markdown

Auto-sync is disabled for ready for review pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@HollowMan6
HollowMan6 force-pushed the nixl branch 4 times, most recently from 6aeadb6 to cad807c Compare June 5, 2026 05:55
@HollowMan6
HollowMan6 force-pushed the nixl branch 2 times, most recently from 6968a6c to cb745fa Compare June 8, 2026 00:36
@HollowMan6 HollowMan6 added CI:Lfast Runs a fast test suite and re-use nightly `main` container (but sync dependencies to PRs version) CI:L1 Run doctests, unit tests, and functional tests and removed CI:Lfast Runs a fast test suite and re-use nightly `main` container (but sync dependencies to PRs version) CI:L1 Run doctests, unit tests, and functional tests labels Jun 8, 2026
@HollowMan6
HollowMan6 force-pushed the nixl branch 2 times, most recently from bd5271d to c251ec6 Compare June 9, 2026 00:51
@HollowMan6 HollowMan6 added the CI:L1 Run doctests, unit tests, and functional tests label Jun 9, 2026
@NVIDIA-NeMo NVIDIA-NeMo deleted a comment from github-actions Bot Jun 9, 2026
Comment thread nemo_rl/models/generation/interfaces.py Outdated
@HollowMan6

Copy link
Copy Markdown
Member Author

/ok to test 4876676

@HollowMan6

Copy link
Copy Markdown
Member Author

/claude review

Comment thread nemo_rl/models/policy/workers/tokenizer_serialization.py Outdated
@HollowMan6

Copy link
Copy Markdown
Member Author

/claude review

@HollowMan6

Copy link
Copy Markdown
Member Author

/ok to test 1ffd083

Comment thread nemo_rl/models/generation/vllm/checkpoint_engine.py
@HollowMan6

Copy link
Copy Markdown
Member Author

/ok to test ed66052

@HollowMan6

Copy link
Copy Markdown
Member Author

/ok to test 7c66f90

Comment on lines +149 to +151
if self.checkpoint_engine.cleanup_after_load:
gc.collect()
torch.cuda.empty_cache()

@ZhiyuLi-Nvidia ZhiyuLi-Nvidia Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like cleanup_after_load is set false by default

Have we check how much memory reserved if without clean up?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The backend default is actually cleanup_after_load=true, I set it to false in the performance recipe explicitly just to get the possible best number for refit time.

I'll check how much memory reserved if without clean up.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

Looks like maybe we can just remove this option, this doesn't really clean up much memory

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

THis option is now removed, and release_after_refit is introduced for this #2608 (comment)

Comment thread nemo_rl/models/generation/vllm/vllm_backend.py Outdated
Comment thread nemo_rl/models/generation/vllm/vllm_worker.py Outdated
try:
for idx, logprob_dict in enumerate(generation.logprobs):
if logprob_dict:
if logprob_dict and idx < len(generated_tokens):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do you know why we need this change? Seems not quite relevant to refit.
Is this to fix something?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I think this is because I mixed up something when I rebased and resolve conflicts of this PR previously, will clean this up

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Comment thread nemo_rl/models/generation/vllm/worker_utils.py
Comment thread nemo_rl/models/policy/workers/base_policy_worker.py Outdated
Comment thread nemo_rl/models/generation/vllm/refit_loader.py Outdated
Comment thread nemo_rl/models/generation/vllm/vllm_backend.py Outdated
Comment thread nemo_rl/models/generation/vllm/vllm_backend.py Outdated
Comment thread nemo_rl/utils/checkpoint_engines/nixl.py Outdated
@HollowMan6

Copy link
Copy Markdown
Member Author

/ok to test 705af30

backend_name: UCX
backend_init_params:
engine_config: MAX_RMA_RAILS=8
device_list: "mlx5_0,mlx5_1,mlx5_2,mlx5_4,mlx5_5,mlx5_6,mlx5_7,mlx5_8"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need manually update the device_list when changing the scale, or the current default setting works for most of situation?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

device_list restricts local UCX devices, so node-count changes on homogeneous hardware do not require updating it, we only need to update the list when HCA names or node topology change. Without device_list, UCX discovers devices automatically. NIXL 1.3 defaults MAX_RMA_RAILS to 2, so auto-discovery works but will not match the validated eight-rail performance.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also we are skipping mlx5_3 for a reason and shall we add explanations?

@HollowMan6 HollowMan6 Jul 18, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes this is intentional, this topology is intended for the dfw cluster, mlx5_3 maps to ethernet, while all others map to IB RDMA data fabric. This is cluster specific so I guess we don't need to document cluster specific configs unless you think this is needed.

Comment thread docs/guides/checkpoint-engine-refit.md Outdated
checkpoint_engine:
enabled: true
backend: nixl
update_weights_bucket_megabytes: 2048

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Emm does this need to be static? can we derive it based on existing gpu memory?

like NRL_REFIT_BUFFER_MEMORY_RATIO. In previous exps the large update_weights_bucket_megabytes the better. If that helpful we can make it adaptive.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

replaced update_weights_bucket_megabytes for update_weights_bucket_memory_ratio

@ZhiyuLi-Nvidia

Copy link
Copy Markdown
Contributor

Awesome @HollowMan6. Generally looks great to me!

Signed-off-by: Hollow Man <hollowman@opensuse.org>
Signed-off-by: Hollow Man <hollowman@opensuse.org>
Signed-off-by: Hollow Man <hollowman@opensuse.org>
Signed-off-by: Hollow Man <hollowman@opensuse.org>
Signed-off-by: Hollow Man <hollowman@opensuse.org>
Signed-off-by: Hollow Man <hollowman@opensuse.org>
@HollowMan6

Copy link
Copy Markdown
Member Author

/ok to test ce460e5

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CI:L1 Run doctests, unit tests, and functional tests Documentation Improvements or additions to documentation Feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants