Skip to content

Enhance remote checkpoint loading with parallel mmap chunk downloading (#21868) - #21869

Open
yuxin00j wants to merge 10 commits into
Lightning-AI:masterfrom
yuxin00j:mmap-remote-checkpoint-load
Open

Enhance remote checkpoint loading with parallel mmap chunk downloading (#21868)#21869
yuxin00j wants to merge 10 commits into
Lightning-AI:masterfrom
yuxin00j:mmap-remote-checkpoint-load

Conversation

@yuxin00j

@yuxin00j yuxin00j commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Fixes #21868

This PR optimizes lightning.fabric.utilities.cloud_io._load() for monolithic, multi-gigabyte checkpoints stored on remote object stores by replacing sequential streaming reads with multiprocess parallel chunk downloads and zero-copy memory mapping (mmap=True).

Motivation and Context

Currently, loading large remote checkpoints via _load() streams bytes sequentially. This underutilizes network bandwidth and forces Python to allocate heap buffers for incoming data while simultaneously constructing unpickled model tensors in memory, causing severe restore bottlenecks and high transient heap RAM spikes.

Summary of Changes

  • _download_chunk_mmap() helper: Implements parallel chunk writes into a pre-allocated file using mmap.mmap() and explicit mm.flush().
  • Parallel Chunk Fetching in _load(): Remote files $\ge 128\text{ MB}$ are partitioned into 1 GB chunks and downloaded concurrently using concurrent.futures.ProcessPoolExecutor (spawn context, up to 16 workers).
  • Intelligent Node-Local Cache (/dev/shm / disk): Checkpoints are cached in /dev/shm if free space exceeds $1.5\times \text{filesize}$, falling back to tempfile.gettempdir().
  • Process Synchronization via FileLock: Eliminates redundant downloads by synchronizing processes across multi-GPU/multi-node setups; only one process downloads the file while others reuse the cache.
  • Zero-Copy Deserialization: Leverages torch.load(..., mmap=True) for both local paths and downloaded remote caches, significantly cutting peak heap RAM requirements.
  • Exception & Cleanup Safeguards: Enforces automatic cache cleanup (os.remove) if chunk downloading fails or is interrupted.
  • Documentation & Changelog: Updated docs/source-pytorch/common/remote_fs.rst and src/lightning/fabric/CHANGELOG.md.
Before submitting
  • Was this discussed/agreed via a GitHub issue? (not for typos and docs)
  • Did you read the contributor guideline, Pull Request section?
  • Did you make sure your PR does only one thing, instead of bundling different changes together?
  • Did you make sure to update the documentation with your changes? (if necessary)
  • Did you write any new necessary tests? (not for typos and docs)
  • Did you verify new and existing tests pass locally with your changes?
  • Did you list all the breaking changes introduced by this pull request?
  • Did you update the CHANGELOG? (not for typos, docs, test updates, or minor internal changes/refactors)

PR review

Anyone in the community is welcome to review the PR.
Before you start reviewing, make sure you have read the review guidelines. In short, see the following bullet-list:

Reviewer checklist
  • Is this pull request ready for review? (if not, please submit in draft mode)
  • Check that all items from Before submitting are resolved
  • Make sure the title is self-explanatory and the description concisely explains the PR
  • Add labels and milestones (and optionally projects) to the PR so it can be classified

@codecov-commenter

codecov-commenter commented Jul 30, 2026

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 96.38554% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 87%. Comparing base (7f0c343) to head (77449f8).
⚠️ Report is 2 commits behind head on master.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files
@@           Coverage Diff           @@
##           master   #21869   +/-   ##
=======================================
- Coverage      87%      87%   -0%     
=======================================
  Files         270      270           
  Lines       24069    24153   +84     
=======================================
+ Hits        20904    20972   +68     
- Misses       3165     3181   +16     

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Optimize remote checkpoint loading with parallel multiprocess downloads and zero-copy mmap

2 participants