Skip to content

Load the zoo Hub download helpers without unsloth_zoo's package init - #13849

Merged
danielhanchen merged 4 commits into
mainfrom
studio-light-download-helpers
Oct 15, 2026
Merged

danielhanchen merged 4 commits into
mainfrom
studio-light-download-helpers

Conversation

@danielhanchen

Copy link
Copy Markdown
Member

Companion to unslothai/unsloth-zoo#1752, which moves the Hub download helpers (hf_xet_fallback, hf_xet_health, hf_xet_tuning, hf_cache, hf_cache_state) into unsloth_zoo_downloads, a sibling package that imports without running unsloth_zoo/__init__ (no torch, transformers or temporary patches). This PR makes Unsloth use it when the installed zoo ships it, and keeps today's behaviour on an older zoo.

What changes

  • studio/backend/utils/hf_xet_fallback.py: _load_shared and _load_optional first try _import_light(name). It returns a module already in sys.modules under the unsloth_zoo.* name (keeps the identity of an earlier full import and of test doubles), else imports unsloth_zoo_downloads.<module>. On a zoo without that package it returns None and the existing path runs unchanged (torch gate, GPU-init retry, degrade).
  • unsloth/_gpu_init.py: the early read-only cache redirect imports redirect_hf_cache_if_readonly from unsloth_zoo_downloads.hf_cache, and falls back to executing unsloth_zoo/hf_cache.py by path as before.
  • Tests: the tests that simulate an older zoo (GPU-init retry, late init failure, degrade paths) now pin _import_light to None or also block unsloth_zoo_downloads, so they keep testing the path they were written for whichever zoo is installed. Three new tests cover the light route against a stand-in package: the shared backend and an optional module load without any unsloth_zoo import attempt, torch gate or UNSLOTH_ZOO_DISABLE_GPU_INIT, and an already loaded zoo module wins.

First download in a Studio process

Fresh process per run, torch already imported (as after the backend's startup warm), then import utils.hf_xet_fallback, xet_health() and hf_hub_download_with_xet_fallback of one small file. Colab T4-HM, 4 interleaved rounds per arm (ABCCBA x2):

arm median to first download load + Xet verdict added RSS unsloth_zoo init ran transformers loaded
this PR's base, zoo main 5.42 s (5.40 to 14.25) 4.87 s 298 MB yes yes
this PR's base, zoo#1752 5.36 s (5.34 to 5.83) 4.83 s 298 MB yes yes
this PR, zoo#1752 0.69 s (0.68 to 0.72) 0.039 s 25 MB no no

So the first Hub download in Studio starts about 4.8 s sooner and the backend process stays about 270 MB smaller until something else imports the zoo. With an older zoo nothing changes (row 1 is what this PR runs there).

Compatibility

  • Older zoo (no unsloth_zoo_downloads): _import_light returns None, every existing branch runs as before. The suite below passes against zoo main and zoo#1752 alike.
  • A process that only takes the light route skips unsloth_zoo/__init__'s environment steps. The download children size their own HF_XET_* (resize_for_cache_dir before the spawn, apply_xet_env in download_lifecycle), and training / inference workers import Unsloth, which runs the init there. Before this PR those steps reached the backend process only if a download happened to come first, so nothing could rely on them.
  • import unsloth with a read-only HF_HOME: the cache redirect result is identical with zoo main (by-path) and zoo#1752 (light import).

Tests

16 files (test_hf_xet_fallback, test_hub_download_transport_auto, test_gguf_xet_fallback_integration, test_training_xet_fallback, test_scoped_download_worker, test_training_worker_import_discipline, test_dynamo_import_race, test_gpu_init_crash_message, root test_cold_import_order, test_import_time_floors, test_hf_xet_broken_wheel, test_prefetch_snapshot_scope, ...): 524 passed, 1 skipped against zoo main and against zoo#1752. The one failure on both, test_startup_defers_torch::test_import_main_does_not_import_torch, fails the same way on main without this PR. Disabling _import_light makes the two new routing tests fail.

Prefer the init-free unsloth_zoo_downloads package (unslothai/unsloth-zoo#1752) for the
Studio Xet fallback shim and the early read-only cache redirect, and fall back to the
unsloth_zoo names on older zoo releases.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-15T13:31:22.188070Z 7417b37 Manual request
🔒 Security Review ⚠️ Failed 2026-10-15T12:44:36.460041Z 10366e0 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@danielhanchen danielhanchen self-assigned this Oct 15, 2026
@danielhanchen

Copy link
Copy Markdown
Member Author

@codex review

1 similar comment
@danielhanchen

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 7417b37d9d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

danielhanchen added a commit to Etherll/unsloth that referenced this pull request Oct 15, 2026
@danielhanchen
danielhanchen merged commit f9d41b1 into main Oct 15, 2026
3 of 54 checks passed
@danielhanchen
danielhanchen deleted the studio-light-download-helpers branch October 15, 2026 14:03
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.

1 participant