Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

`ModelMixin.from_pretrained` on a sharded checkpoint fails under `HF_HUB_OFFLINE=1` even when fully cached (`_get_checkpoint_shard_files` still calls `model_info`)

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#14,952 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
70/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python, pytorch
Lĩnh vực
backend, machine-learning

Hướng nghiên cứu

Bắt đầu với _get_checkpoint_shard_files trong src/diffusers/utils/hub_utils.py và theo dõi cách from_pretrained trong modeling_utils.py truyền local_files_only. So sánh cách xử lý ngoại tuyến trong loaders/lora_base.py và chạy bước tái hiện issue với một checkpoint phân mảnh đã được lưu trong bộ nhớ đệm cùng HF_HUB_OFFLINE=1. Công việc hoàn tất khi việc tải ngoại tuyến từ bộ nhớ đệm thành công, trong khi thiếu một phân mảnh vẫn tạo ra lỗi hiện có.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

bug models
Describe the bug

What happens. With HF_HUB_OFFLINE=1 set and the checkpoint fully cached, SomeModel.from_pretrained("<repo id>") raises huggingface_hub.errors.OfflineModeIsEnabled whenever the checkpoint is sharded (it has a *.safetensors.index.json). Single-file checkpoints load fine in the same setup. Passing local_files_only=True as well works around it. The env var alone is the documented way to run offline, and it is the only option when the call happens inside a library you do not control.

Why. _get_checkpoint_shard_files checks that the shards exist on the Hub before calling snapshot_download, and it skips that check only when local_files_only is truthy:

# src/diffusers/utils/hub_utils.py, main @ da1d382, lines 433-435
# If the repo doesn't have the required shards, error out early even before downloading anything.
if not local_files_only:
    model_files_info = model_info(pretrained_model_name_or_path, revision=revision, token=token)

ModelMixin.from_pretrained passes the caller's local_files_only straight through (modeling_utils.py line 1297), and that is None when the user relies on HF_HUB_OFFLINE. So model_info runs, and huggingface_hub refuses the request because offline mode is on. Earlier steps in the same load already handle offline mode: revision resolution logs Could not reach the Hub ... Using cached commit hash, and the config and index come from the cache. Only this pre-check makes the load fail. The guard comes from #12005, which fixed the local_files_only=True case (#11948). The env-var case was reported in #11447, which was closed citing #11428, a pipeline PR that does not touch this function.

With huggingface_hub 1.33, snapshot_download called afterwards also uses the network when it gets an already-resolved revision and the cache has no trees/<commit>.json listing. That listing is missing from caches written by older huggingface_hub versions and from hand-copied caches. So the fix should also pass the offline state to snapshot_download, as shown below.

I can open a PR for this once a maintainer confirms the approach.

Reproduction

Loads a real sharded checkpoint, first online to fill a fresh cache, then offline with the same call:

import os, subprocess, sys, tempfile, textwrap

cache = tempfile.mkdtemp()
code = textwrap.dedent("""
    from diffusers import FluxTransformer2DModel
    m = FluxTransformer2DModel.from_pretrained("hf-internal-testing/tiny-flux-sharded", subfolder="transformer")
    print("loaded", sum(p.numel() for p in m.parameters()), "params")
""")
env = dict(os.environ, HF_HOME=cache)
subprocess.run([sys.executable, "-c", code], env=env, check=True)        # online: fills the cache
env["HF_HUB_OFFLINE"] = "1"
sys.exit(subprocess.run([sys.executable, "-c", code], env=env).returncode)  # offline: same call fails

Output on main @ da1d382: the online call prints loaded 68484 params. The offline call fails with the trace under Logs. With the fix below, the offline call also prints loaded 68484 params.

Logs
loaded 68484 params
Could not reach the Hub (Cannot reach https://huggingface.co/api/models/hf-internal-testing/tiny-flux-sharded: offline mode is enabled. To disable it, please unset the `HF_HUB_OFFLINE` environment variable.). Using cached commit hash for 'hf-internal-testing/tiny-flux-sharded'.
Traceback (most recent call last):
  File "<string>", line 3, in <module>
  File ".../huggingface_hub/utils/_validators.py", line 89, in _inner_fn
    return fn(*args, **kwargs)
  File ".../diffusers/models/modeling_utils.py", line 1297, in from_pretrained
    resolved_model_file, sharded_metadata = _get_checkpoint_shard_files(
  File ".../diffusers/utils/hub_utils.py", line 435, in _get_checkpoint_shard_files
    model_files_info = model_info(pretrained_model_name_or_path, revision=revision, token=token)
  File ".../huggingface_hub/utils/_validators.py", line 89, in _inner_fn
    return fn(*args, **kwargs)
  File ".../huggingface_hub/hf_api.py", line 3322, in model_info
    r = get_session().get(path, headers=headers, timeout=timeout, params=params)
  [... httpx frames ...]
  File ".../huggingface_hub/utils/_http.py", line 284, in hf_request_event_hook
    raise OfflineModeIsEnabled(
huggingface_hub.errors.OfflineModeIsEnabled: Cannot reach https://huggingface.co/api/models/hf-internal-testing/tiny-flux-sharded/revision/main: offline mode is enabled. To disable it, please unset the `HF_HUB_OFFLINE` environment variable.

Suggested fix. In _get_checkpoint_shard_files, treat offline mode the same as local_files_only=True. This skips the model_info pre-check and makes snapshot_download read from the cache. A missing shard is still reported by the existing os.path.isfile check after the download step.

ignore_patterns = ["*.json", "*.md"]
# In offline mode the shards can only come from the cache, so behave as if `local_files_only=True`.
local_files_only = local_files_only or HF_HUB_OFFLINE

HF_HUB_OFFLINE is already imported in hub_utils.py, and loaders/lora_base.py line 298 uses the same local_files_only or HF_HUB_OFFLINE pattern. dynamic_modules_utils.py line 423 also calls model_info without an offline guard (custom code loaded from a Hub repo). I have not reproduced that path, so it is left out here.

System Info
  • Diffusers version: 0.41.0.dev0 (main @ da1d382, 2026-10-05); latest release v0.40.0 has the same guard
  • Platform: Linux-6.1 x86_64 (Amazon Linux 2023), glibc 2.34
  • Python version: 3.11.14
  • PyTorch version: 2.14.1+cpu (CPU only)
  • Huggingface_hub version: 1.33.0
  • Transformers version: 5.19.0.dev0
  • Accelerate version: not installed
  • Safetensors version: 0.8.0
  • Using GPU in script?: No
  • Using distributed or parallel set-up in script?: No
Who can help?

@sayakpaul @DN6

Ngôn ngữ chính
Python
Star
34.6k
Fork
7.4k
Merge trung bình
4 ngày 16 giờ
Pull request đã merge (30 ngày)
44

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của huggingface/diffusers

Tất cả issue của huggingface/diffusers

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.