智谱AI GLM-Image部署教程：HuggingFace模型缓存路径与离线加载方案

你刚下载完GLM-Image镜像，双击启动脚本，浏览器打开，点击「加载模型」——结果卡在“正在下载模型”界面，进度条纹丝不动。刷新页面，提示“网络连接失败”；查日志，发现报错；再看磁盘，下空空如也。

这不是你的网络问题，也不是显卡故障，而是所有本地部署GLM-Image的用户都会撞上的第一堵墙：模型太大（34GB）、依赖太深（Diffusers+Transformers+Torch）、默认缓存路径分散且不可控。

更现实的问题是：你在内网环境、机场隔离区、客户现场服务器上，根本连不上HuggingFace官网。而官方文档只告诉你，却没说清楚——

• 模型文件到底存在哪？
• 下载中断后怎么续传？
• 能不能把别人下好的模型直接拷贝过来用？
• 如何彻底告别“首次加载=等一小时+反复重试”？

这篇教程不讲原理，不堆参数，只给你一套经过生产验证的离线部署闭环方案：从缓存路径重定向、模型手动预置、WebUI无缝识别，到异常恢复技巧，全部一步到位。

GLM-Image不是单个文件，而是一套由HuggingFace Diffusers库驱动的多组件模型。它启动时会按固定顺序查找三类资源，每类对应一个独立缓存路径。搞不清它们的关系，就永远在“找不到模型”的死循环里打转。

2.1 HuggingFace Hub缓存：模型权重与配智谱 AI GLM 教程置的核心仓库

这是最核心的路径，存放模型权重（）、分词器（）、配置文件（）等。默认位置是：

但GLM-Image项目已通过环境变量将其重定向到项目目录内：

所以实际路径是：

这个路径下必须包含完整子目录结构：

注意：下的文件夹名不是固定字符串，而是HuggingFace模型仓库的commit hash（如）。如果你手动复制模型，必须确保hash与中记录的一致，否则Diffusers会拒绝加载。

2.2 Torch Hub缓存：PyTorch预训练权重的备用源

当模型中引用了PyTorch官方预训练模块（如），Diffusers会尝试从Torch Hub下载。默认路径：

项目已重定向为：

即：

虽然GLM-Image本身不强依赖此路径，但某些自定义组件或未来升级可能触发。建议提前创建该目录并赋予写权限：

2.3 Gradio临时缓存：前端交互产生的中间文件

Gradio在运行时会生成临时文件（如上传的图片、session状态），默认存于系统临时目录。项目未重定向此路径，但需注意：

• 它不存储模型，但若磁盘空间不足（尤其挂载在小分区），会导致WebUI无法响应；
• 所有生成图像均保存在，与Gradio缓存无关。

以下操作全程无需联网，适用于内网服务器、离线笔记本、客户交付环境。假设你已获得一台预装Ubuntu 22.04、CUDA 12.1、NVIDIA驱动535的机器。

3.1 第一步：准备离线模型包（34GB）

不要指望“先联网下载再断网”，那等于把34GB流量塞进内网。正确做法是：在有网环境提前打包好完整模型快照。

在联网机器上执行：

此命令会下载完整模型到，包含正确的结构和文件。

打包并传输：

将拷贝至目标机器目录下。

3.2 第二步：解压并修复路径结构

在目标机器（离线环境）执行：

如果下有多个hash文件夹，打开查看内容，例如：

确保下存在同名文件夹。若不一致，重命名文件夹或更新内容。

3.3 第三步：修改启动脚本，跳过在线检查

原脚本在启动时会调用，而后者默认尝试连接HuggingFace API验证模型可用性。离线环境下这一步必然失败。

编辑，在命令前添加环境变量屏蔽网络请求：

完整启动段落应类似：

3.4 第四步：首次启动与验证

观察终端输出：

• 若看到，说明模型路径识别成功；
• 若出现，证明离线加载生效；
• 浏览器访问，点击「加载模型」，进度条应快速走完，显示“模型加载完成”。

验证成功标志：WebUI左上角显示，且生成按钮可点击。

即使按上述步骤操作，仍可能遇到加载失败。别急着重装，先检查这三个高频雷区：

4.1 缓存路径权限错误（最常见）

解决方案：

4.2 模型文件损坏或不完整

解决方案：

4.3 CUDA版本不兼容

解决方案（二选一）：

• 推荐：升级CUDA至12.1（NVIDIA官网下载runfile）
• 临时方案：启用CPU Offload（在WebUI参数中勾选，牺牲速度保可用）

5.1 创建模型健康检查脚本

新建，每次部署后一键验证：

赋予执行权限：

5.2 预生成测试图像，验证端到端流程

避免用户首次生成时因参数错误而怀疑模型失效。在中加入离线测试逻辑：

运行：

5.3 多模型共存方案

若需同时部署GLM-Image、SDXL、Kandinsky等模型，只需为每个模型分配独立缓存子目录，并在启动时切换：

目录结构自动隔离，互不干扰。

GLM-Image的离线部署，从来不是“把模型文件拷过去就行”的简单操作。它是一场对HuggingFace生态底层逻辑的理解：

• 路径可控：通过、等环境变量，把所有缓存锚定在项目目录内，杜绝的不可预测性；
• 依赖显式化：用替代，确保模型版本、commit hash、文件结构完全透明；
• 行为可预测：通过和关闭所有后台网络探针，让每一次加载都成为确定性事件。

当你不再被“正在下载”卡住，当客户现场3分钟内就能生成第一张图，你就真正掌握了AI模型落地的第一道关卡——不是模型多强大，而是它是否随时待命。