RuntimeError: We could not revert some weight conversions because of offlading, and several weights needed for a single conversion operation living in different shard files. Try reducing `max_sh

快速结论：该报错通常出现在使用 Hugging Face Transformers 对启用磁盘卸载（disk offload）的大模型（如 Qwen/Qwen3-30B-A3B）调用 `save_pretrained()` 时。优先排查 Transformers 版本是否包含已修复的语法错误（modeling_utils.py 第 3667 行），并尝试降低 `max_shard_size` 或设置 `save_original_format=False`。

问题场景

用户使用 Transformers 5.13.0.dev0 从预训练加载 Qwen/Qwen3-30B-A3B 模型，设置了 `device_map=”auto”` 并指定 `offload_folder`（磁盘卸载路径）。加载后调用 `model.save_pretrained(“save_path”)` 保存模型时触发报错。

报错原文

Traceback (most recent call last):
  File "/home/kylesayrs/transformers/src/transformers/modeling_utils.py", line 3667, in save_pretrained
    weight_map.update({k: os.path.basename(shard_file)} for k in shard_state_dict.keys())  # ty: ignore[unresolved-attribute]
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ValueError: dictionary update sequence element #0 has length 1; 2 is required

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/kylesayrs/llm-compressor/disk_save_repro.py", line 13, in <module>
    model.save_pretrained("tmp_save_path")
  File "/home/kylesayrs/transformers/src/transformers/modeling_utils.py", line 3669, in save_pretrained
    raise RuntimeError(
RuntimeError: We could not revert some weight conversions because of offlading, and several weights needed for a single conversion operation living in different shard files. Try reducing `max_shard_size` a bit, or worst case set `save_original_format=False`.

原因分析

根本原因是 `modeling_utils.py` 第 3667 行存在 Python 语法错误：`weight_map.update()` 参数中使用的生成器表达式生成的是字典对象而非键值对，导致 `ValueError`。该异常被捕获后，代码抛出了一个 `RuntimeError` 提示用户尝试降低 `max_shard_size` 或设置 `save_original_format=False`。此外，在磁盘卸载场景下，meta 张量（offloaded to disk）无法直接转换到 CPU 也是潜在问题（与 PR #46902 有关）。

环境排查

Transformers 版本：确认是否使用 dev 版本（如 5.13.0.dev0），该版本包含此语法错误；稳定版（如 4.x）可能无此问题。
模型加载参数：是否启用了 `device_map=”auto”`、`offload_folder`。
磁盘卸载路径：`offload_folder` 是否有足够写入权限。
Python 版本：3.12.12（本 Issue 所用版本）。

解决步骤

更新 Transformers 至已修复的版本：检查 Issue #47333 是否被修复，或直接拉取最新 dev 分支（其中已包含对应 PR 的修复，如与 #47333 关联的提交）。
尝试降低 `max_shard_size`：在 `save_pretrained()` 中指定较小的分片大小，例如 `model.save_pretrained(“save_path”, max_shard_size=”5GB”)`。
设置 `save_original_format=False`：在 `save_pretrained()` 中添加参数 `save_original_format=False`，可绕过权重格式转换逻辑。
（代码级别修复）：如果无法更新版本，可手动修改 `modeling_utils.py`，将第 3667 行的语法错误修复为字典推导式，例如：
weight_map.update({k: os.path.basename(shard_file) for k in shard_state_dict.keys()})（注意删除生成器外的额外括号）。

验证方法

修复后重新执行 `model.save_pretrained(“save_path”)`，正常保存完成且无 `RuntimeError` 和 `NotImplementedError` 即为成功。可检查保存目录下是否生成了预期数量的分片文件（.safetensors）和配置文件。

参考来源

huggingface/transformers #47333

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

RuntimeError: We could not revert some weight conversions because of offlading, and several weights needed for a single conversion operation living in different shard files. Try reducing `max_sh