Add transformers-xpu-helper for Intel XPU / Core Ultra 7 255H training #1

Merged

thesimonharms merged 1 commit from cursor/transformers-xpu-helper-255h-743d into main

2026-08-01 11:54:38 -04:00

thesimonharms commented

2026-08-01 11:52:05 -04:00

(Migrated from github.com)

Summary

Adds transformers-xpu-helper, a Python library meant to sit alongside Hugging Face Transformers and speed up / stabilize training on Intel XPUs. Defaults are tuned for the Intel Core Ultra 7 255H (Arrow Lake-H + Arc Graphics 140T).

Uses native PyTorch XPU (2.5+). IPEX is treated as EOL.

What’s included

Hardware profiles for 255H / 265H / 285H and generic client Arc
ultra_255h_config() — BF16 (no GradScaler), torch.compile, gradient checkpointing, shared-DRAM memory fraction, hybrid-CPU thread / DataLoader knobs
prepare_for_training / training_step / finalize_step for custom loops
build_training_arguments for Hugging Face Trainer
Memory budget + batch-size heuristic for shared system RAM
xpu-helper-info CLI
Examples + unit tests (12 passing)

Usage sketch

from transformers_xpu_helper import prepare_for_training, ultra_255h_config

cfg = ultra_255h_config()
prepared = prepare_for_training(model, optimizer, config=cfg)

Test plan

pytest — 12 passed
ruff check clean
examples/train_tiny_classifier.py runs on CPU fallback
On a 255H machine: install PyTorch XPU wheels + drivers, confirm xpu-helper-info reports XPU and a short Trainer/finetune run completes

## Summary Adds `transformers-xpu-helper`, a Python library meant to sit alongside Hugging Face Transformers and speed up / stabilize training on Intel XPUs. Defaults are tuned for the **Intel Core Ultra 7 255H** (Arrow Lake-H + **Arc Graphics 140T**). Uses **native PyTorch XPU** (2.5+). IPEX is treated as EOL. ## What’s included - Hardware profiles for 255H / 265H / 285H and generic client Arc - `ultra_255h_config()` — BF16 (no GradScaler), `torch.compile`, gradient checkpointing, shared-DRAM memory fraction, hybrid-CPU thread / DataLoader knobs - `prepare_for_training` / `training_step` / `finalize_step` for custom loops - `build_training_arguments` for Hugging Face `Trainer` - Memory budget + batch-size heuristic for shared system RAM - `xpu-helper-info` CLI - Examples + unit tests (12 passing) ## Usage sketch ```python from transformers_xpu_helper import prepare_for_training, ultra_255h_config cfg = ultra_255h_config() prepared = prepare_for_training(model, optimizer, config=cfg) ``` ## Test plan - [x] `pytest` — 12 passed - [x] `ruff check` clean - [x] `examples/train_tiny_classifier.py` runs on CPU fallback - [ ] On a 255H machine: install PyTorch XPU wheels + drivers, confirm `xpu-helper-info` reports XPU and a short Trainer/finetune run completes  <div><a href="https://cursor.com/agents/bc-019fbe01-c40c-762c-9166-fdc72f51743d?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-019fbe01-c40c-762c-9166-fdc72f51743d&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div>