Add tools/prepare_cache.py for offline GPT dataset cache preparation

[asolergi-nv]

What does this PR do ?

This PR adds a new offline cache-preparation entrypoint for GPTDataset-based training so dataset caches can be built ahead of time on a CPU-only node instead of forcing rank 0 to build them during training startup.

What this introduces

• Adds tools/prepare_cache.py
  • Reuses Megatron’s normal argument parsing/validation path so the tool can be launched with the same dataset-related training args
  • Computes train/valid/test sample targets via get_train_valid_test_num_samples() so cache keys match training behavior
  • Builds caches through the same GPTDataset + BlendedMegatronDatasetBuilder path used by training
  • Supports both:
    • --data-path + --split
    • per-split dataset definitions (--train-data-path, --valid-data-path, --test-data-path, --per-split-data-args-path)
  • Adds optional --prepare-cache-world-size to let a single-node prep run match the future training topology when sample counts depend on world size / DP size
• Entry point parity changes
  • Updates pretrain_mamba.py so its GPTDatasetConfig construction matches GPT-relevant fields already present in pretrain_gpt.py, specifically:
    • multiple_validation_sets
    • full_validation
  • Includes a small formatting cleanup in pretrain_gpt.py

Tests

Adds tests/unit_tests/data/test_prepare_cache.py covering:

• cache preparation for blended datasets
• cache preparation for per-split datasets
• --prepare-cache-world-size normalization
• unsupported-mode rejection
• cache-hit rebuilds using:
  • dataloader_fast_cache_load=True
  • dataloader_defer_npy_index_mmap=True
• verification that deferred/lazy-loaded cached datasets still return the same samples as the normal cache-hit path

Contribution process

Pre-checks

• 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

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!

All PRs start as draft. If you open a non-draft PR, it will be automatically converted to draft.

Step 1: Mark PR as "Ready for Review"

1. When your PR is ready, click Ready for Review.
2. An oncall reviewer is auto-assigned and expert reviewers are notified based on your changes.
   • Some PRs may jump straight to step 2. This is determined by .github/CODEOWNERS.

⚠️ Only mark as ready once merge-conflicts are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

Step 2: Final Review

For PRs that change megatron/core, once all expert reviewers have approved, the Final Review label is applied automatically and final reviewers are assigned.

For PRs outside megatron/core, this step is skipped.

Step 3: Approved

Once all required reviewers have approved, the Approved label is applied automatically.

Merge

Any member of mcore-engineers will be able to merge your PR.

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.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

This PR has been automatically converted to draft because all PRs must start as drafts.

When you are ready for review, click Ready for Review to begin the review process. This will:

1. Add the oncall reviewer (optional reviewer)
2. Add required review teams based on your changes

See the contribution guide for more details.

[asolergi-nv]

/ok to test d72afb6

[asolergi-nv]

/ok to test c87feda

[asolergi-nv]

/ok to test 2cd79f9