离线部署 Nemotron-Labs-Diffusion 时，启动报错大多不是模型权重损坏，而是拷贝文件时漏掉了仓库里的子目录或配置，或者离线机器上的缓存路径与代码默认路径不一致。这里整理一份可直接执行的清单：用 snapshot_download 拉全文件，按本地目录方式部署，并在启动前跑一次文件完整性和 tokenizer 校验。执行这套步骤能减少断网环境下反复试错。

离线部署的核心是完整镜像 Hugging Face 仓库，并让加载代码显式指向本地目录。建议使用 snapshot_download 下载全部文件，再通过 HF_HOME 或 from_pretrained 的本地路径加载。启动前用脚本检查关键文件非空并测试 tokenizer。此方案适用于纯离线内网；具体镜像端点和依赖版本需结合环境确认。

先梳理模型仓库的完整目录结构

在动手下载前，先在 Hugging Face 仓库页面或已有缓存目录中确认顶层文件列表。DiffusionPipeline 这类模型通常包含以下文件类型：

• config.json：模型结构配置，transformers 和 diffusers 在 from_pretrained 时根据 config.json 初始化模型参数。
• model_index.json：Diffusers 库的入口文件，列出 pipeline 的子模块，如 unet、vae、text_encoder、scheduler。若缺少，加载时会提示找不到对应模块。
• 权重分片：常见为 .safetensors 或 .bin 文件，也可能拆成多个分片，例如 unet/diffusion_pytorch_model.safetensors、vae/diffusion_pytorch_model.safetensors。这是模型实际参数。
• tokenizer 文件：包括 tokenizer.json、tokenizer_config.json，以及可能出现的 vocab.txt 或 merges.txt。文本编码器依赖这些文件把提示词转换为输入 ID。
• scheduler 配置：如 scheduler/scheduler_config.json，控制去噪步进方式。

上述文件常分布在子目录中，人工逐个点击下载很容易漏掉子目录内容，尤其是 tokenizer 和 scheduler。建议先获取完整仓库文件清单，再开始下载。

用snapshot_download命令获取全部文件

推荐使用 huggingface_hub 的 snapshot_download 函数，snapshot_download 能根据仓库文件列表完整拉取，避免手动遗漏。命令如下：

from huggingface_hub import snapshot_download
snapshot_download(repo_id='nvidia/Nemotron-Labs-Diffusion', local_dir='./nemotron-labs-diffusion')

repo_id 用实际模型名替换，这里只是占位。网络受限时，先设置镜像端点再执行下载脚本：

export HF_ENDPOINT=https://hf-mirror.com
python download_script.py

也可在 Python 中直接设置环境变量：

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

使用 local_dir 下载时，文件不会写入 Hugging Face 默认缓存结构，后续加载必须显式传路径。

在离线机器上配置transformers缓存路径

离线机器上不要让代码去默认的 ~/.cache/huggingface 找模型，而是显式指定目录。推荐在启动脚本中设置：

export HF_HOME=/data/hf_cache

然后把下载的目录按 Hugging Face 缓存结构放进去，或者直接用本地镜像目录加载：

from diffusers import DiffusionPipeline
pipe = DiffusionPipeline.from_pretrained('/data/models/nemotron-labs-diffusion')

要确认加载时实际读取哪个路径，可在运行前打印环境变量或检查模型配置：

python -c "import os; print(os.environ.get('HF_HOME', 'not set'))"

如果代码里同时存在默认缓存和自定义路径，可能加载到旧缓存或触发重复下载，建议统一环境变量设置。

编写启动前自动校验文件完整性的脚本

启动前跑一个校验脚本，检查关键文件是否存在且大小非零，并测试 tokenizer 能否正常加载。放在离线机器上，每次推理前执行。

import os
from transformers import AutoTokenizer

model_dir = '/data/models/nemotron-labs-diffusion'
required_files = [
    'config.json',
    'model_index.json',
    'scheduler/scheduler_config.json',
    'tokenizer/tokenizer.json',
    'unet/diffusion_pytorch_model.safetensors',
    'vae/diffusion_pytorch_model.safetensors',
]

missing = [f for f in required_files
           if not os.path.exists(os.path.join(model_dir, f))
           or os.path.getsize(os.path.join(model_dir, f)) == 0]
if missing:
    print('缺失或空文件:', missing)
    raise SystemExit(1)

try:
    tok = AutoTokenizer.from_pretrained(model_dir, subfolder='tokenizer', trust_remote_code=True)
    enc = tok('a photo of a cat')
    print('tokenizer 正常，input_ids 长度:', len(enc.input_ids))
except Exception as exc:
    print('tokenizer 加载失败:', exc)
    raise SystemExit(1)

print('文件完整性与 tokenizer 校验通过')

脚本里的文件列表必须以实际下载目录为准，safetensors 文件名和子目录可能随仓库版本变化。如果 tokenizer 在根目录，去掉 subfolder 参数。校验通过后再启动推理，能减少加载到中途才发现分片缺失的情况。