Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat(trainer): emergency checkpointing on crashes & SIGTERM/SIGINT#39140

Open
AyushSharma173 wants to merge 4 commits into
huggingface:mainfrom
AyushSharma173:feature/add-emergency-checkpointing
Open

feat(trainer): emergency checkpointing on crashes & SIGTERM/SIGINT#39140
AyushSharma173 wants to merge 4 commits into
huggingface:mainfrom
AyushSharma173:feature/add-emergency-checkpointing

Conversation

@AyushSharma173

@AyushSharma173 AyushSharma173 commented Jul 1, 2025

Copy link
Copy Markdown

What does this PR do?

Adds failure-safe training to the 🤗 Trainer.

  • New flag enable_emergency_checkpoint in TrainingArguments
    • default: False (opt-in)
  • Automatic emergency save when training ends unexpectedly
    • un-handled exception inside Trainer.train
    • external SIGTERM/SIGINT (e.g. job pre-emption, Ctrl-C)
  • Checkpoint is written to
    <output_dir>/checkpoint-emergency
    and contains model weights, optimizer, scheduler, scaler, RNG state
    plus a minimal trainer_state.json.
  • Resume works transparently via
    TrainingArguments(..., resume_from_checkpoint=".../checkpoint-emergency").

Motivation

Issue #38961 requests a robust way to avoid losing progress when a run is killed mid-epoch or by OOM/infra errors.
Current work-arounds (very frequent save_steps or a user-level try/except) are slow or brittle.
This PR makes the feature one-line (enable_emergency_checkpoint=True) and cost-free when disabled.

Implementation details

  • training_args.py – new dataclass field enable_emergency_checkpoint.
  • trainer.py
    • registers signal & atexit handlers when the flag is on
    • wraps train() loop in try/except and calls _common_emergency_save
    • _common_emergency_save is idempotent & rank-safe (_emergency_save_running / _completed flags).
  • Tests
    • tests/trainer/test_emergency_ckpt.py
      • verifies flag round-trip
      • asserts emergency folder is created on crash and training can resume
      • checks that opting-out leaves no folder

Fixes # (issue)
Closes #38961.

Before submitting

Who can review?

Trainer reviewers: @zach-huggingface, @SunMarc, @qgallouedec

* new flag
* save model/optimizer/scheduler/RNG on crash or signal
* tests:
Comment thread src/transformers/trainer.py Outdated

try:
if args.push_to_hub:
try:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Wrapping the whole training loop into a try/expect would make the use of debugger quite challenging, no?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Good point. I’ve adjusted the implementation so the try except now only surrounds the call to inner_training_loop (via a small _run_inner_training_loop_with_emergency_ckpt helper).
Everything that happens earlier in train is executed outside a try so debuggers will still break exactly at the offending line. The emergency checkpoint logic is therefore triggered only for failures that occur after training has actually started, which is where we have state worth saving.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks for narrowing the scope of the try/epxect, although I think that the remark remains for everything inside the training loop.
Not saying that's it's a major issue for this feature, but I feel like it could make the development work a lot more annoying

@ArthurZucker ArthurZucker added the Feature request Request for a new feature label Jul 1, 2025
@ArthurZucker

Copy link
Copy Markdown
Collaborator

cc @SunMarc as well

@yaswanth19

Copy link
Copy Markdown
Contributor

CC: @SunMarc for your attn here

@SunMarc SunMarc self-requested a review July 11, 2025 16:38
@yaswanth19

yaswanth19 commented Jul 18, 2025

Copy link
Copy Markdown
Contributor

hey @AyushSharma173 I don't think saving it in <output_dir>/checkpoint-emergency folder makes sense. When we retrigger the training run then it should pickup the last saved checkpoint/emergency checkpoint from the output dir itself. So the checkpoint should be saved in output dir with the last step number before it crashed like output_dir/checkpoint-123

@yaswanth19

Copy link
Copy Markdown
Contributor

@SunMarc A gentle ping here for review. Also @AyushSharma173 LMK if you don't have the bandwidth to continue as I have some time now and can it pick up.

@AyushSharma173

Copy link
Copy Markdown
Author

@yaswanth19 Hey sure. You can pickup this issue and try to address the concerns raised so far. I dont have time for next week, so feel free.

@efazal

efazal commented Sep 23, 2025

Copy link
Copy Markdown
Contributor

Hi @AyushSharma173, This is great work! I've been working on a similar feature and only now came across your PR.
We wanted to solve a problem common faced by many people on a shared cluster, where their training jobs get preempted by high priority jobs and they lose progress, or for any reasons users would like to pause their training jobs and be able to resume without loosing progress up until the point of resume.

I took a proactive approach as opposed to your reactive approach to solve this and named it Just-in-Time (JIT) checkpointing. And I also wanted to ensure the trainer code was not disrupted a lot. For that reason I took a modular approach. I'm also leveraging SIGTERM signals for this implementation, and the key difference would we that I'm doing the checkpoint asynchronously. Please have a look at my approach implemented in my fork and let me know your thoughts as I would love to contribute these changes as part of this PR or even a fresh PR if you think that would be wise:
main...efazal:transformers:main

cc: @qgallouedec @yaswanth19

@qgallouedec

Copy link
Copy Markdown
Member

what about just:

try:
    trainer.train()
except:
    trainer.save_model()

@efazal

efazal commented Oct 6, 2025

Copy link
Copy Markdown
Contributor

Hi @AyushSharma173 @qgallouedec @SunMarc, I was wondering if I could pickup this issue and continue working on the feature. In my previous comment I've added a link to my fork with the approach I took to implement emergency checkpoint. It addresses all the review comments here so far. Please have a look and let me know if I can go ahead and submit a new revision to this PR. Thank you.

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

Labels

Feature request Request for a new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

🛠️ Add Failure-Safe Training with Emergency Checkpointing

5 participants