Stable Diffusion 保姆级教程｜HF 国内镜像配置 + 一键安装 + 本地模型加载 + 完整代码

🔥Stable Diffusion 保姆级教程｜HF 国内镜像配置 + 一键安装 + 本地模型加载 + 完整代码

---

设置 Hugging Face 国内镜像

设置 Hugging Face 国内镜像的环境变量，解决下载模型（diffusers/transformers）超时、失败问题，让你能快速下载 Stable Diffusion、LLM 等模型。

不同系统使用方法

1. Windows 系统（CMD 命令行）

set HF_ENDPOINT=https://hf-mirror.com

2. Windows 系统（PowerShell）

$env:HF_ENDPOINT="https://hf-mirror.com"

3. Mac / Linux 系统

export HF_ENDPOINT=https://hf-mirror.com

永久配置（推荐，不用每次都输）

Windows

1. 右键此电脑 → 属性 → 高级系统设置 → 环境变量
2. 新建用户变量 ：
   • 变量名：HF_ENDPOINT
   • 变量值：https://hf-mirror.com

Mac/Linux

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

配置完镜像后，再运行AI 绘画、模型下载代码，速度会大幅提升。

一键安装命令（最常用、最稳定）

CPU版

直接复制运行：

pip install diffusers transformers accelerate torch safetensors pillow

GPU版

如果你有 NVIDIA GPU ，强烈建议安装 CUDA 版本的 PyTorch（速度快 10~50 倍）：

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132
pip install diffusers transformers accelerate safetensors pillow

补充依赖

依据自己的需求酌情安装

pip install modelscope
pip install huggingface_hub diffusers torch transformers

每个库的作用

1. diffusers

   Hugging Face 官方的扩散模型库 ，专门用来跑 Stable Diffusion、文生图、图生图、超分、换脸、视频生成 等 AI 绘画模型。

2. transformers

   跑 大语言模型（LLM）、CLIP 文本编码器 的核心库，Stable Diffusion 里的文本理解全靠它。

3. accelerate

   让 PyTorch 模型自动加速、支持 GPU/TPU、多卡训练，不用自己写复杂的分布式代码。

4. torch

   就是 PyTorch，深度学习框架，所有 AI 模型的底层运行环境。

5. safetensors

   比 .bin 更安全、更快的模型权重存储格式，现在 Stable Diffusion 模型几乎都用这个。

6. pillow

   Python 图像处理库，用来打开、保存、显示图片，AI 绘画必用。

它们之间的关系（一句话总结）

• torch 是地基
• transformers 提供文本理解
• diffusers 提供图像生成
• accelerate 加速训练/推理
• safetensors 安全存储模型
• pillow 处理最终图片

---

最小可运行代码：文生图（直接复制用）

最简代码：

# 从 diffusers 库导入 StableDiffusionPipeline 类
# diffusers 是 Hugging Face 提供的扩散模型库，用于图像生成
from diffusers import StableDiffusionPipeline

# 导入 PyTorch 深度学习框架
import torch

# ============================================
# 模型加载部分
# ============================================

# 定义模型 ID，指向 Hugging Face Hub 上的 runwayml/stable-diffusion-v1-5 模型
# 这是 Stable Diffusion 1.5 版本，由 Runway ML 团队发布
model_id = "runwayml/stable-diffusion-v1-5"

# 从预训练模型加载 Stable Diffusion 管道
pipe = StableDiffusionPipeline.from_pretrained(
    model_id,                    # 模型标识符
    torch_dtype=torch.float16,   # 使用半精度浮点数（FP16），减少显存占用约50%
    use_safetensors=True         # 使用 safetensors 格式加载权重，比传统 .bin 更安全、更快
).to("cuda")                     # 将模型移动到 GPU（CUDA 设备）进行加速推理

# ============================================
# 图像生成部分
# ============================================

# 定义文本提示词（prompt），描述想要生成的图像内容
# "a cute cat running on the grass" - 一只可爱的猫在草地上奔跑
# "8k" - 提示高质量图像
# "realistic" - 提示写实风格
prompt = "a cute cat running on the grass, 8k, realistic"

# 调用管道生成图像
# pipe(prompt) 执行完整的扩散过程：文本编码 → 潜空间去噪 → 图像解码
# .images[0] 获取返回的 PIL Image 对象列表中的第一张图
image = pipe(prompt).images[0]

# ============================================
# 保存结果部分
# ============================================

# 使用 Pillow (PIL) 的 save 方法将图像保存为 PNG 文件
image.save("cat.png")

# 打印确认信息，提示用户图像已保存
print("图片已保存：cat.png")

关键概念补充

组件	说明
StableDiffusionPipeline	端到端的图像生成管道，包含：文本编码器 (CLIP)、UNet 去噪网络、VAE 解码器
torch_dtype=torch.float16	FP16 精度，显存需求从 ~6GB 降至 ~3-4GB，速度更快
use_safetensors	替代 PyTorch 的 pickle 格式，防止恶意代码执行
.to("cuda")	必须在有 NVIDIA GPU 且安装了 CUDA 的环境中运行
pipe() 参数	可传 num_inference_steps（步数，默认50）、guidance_scale（CFG 强度，默认7.5）、seed（随机种子）等

---

文件拆分

文件一：download_model.py --- 下载并保存模型

# 从 diffusers 库导入 StableDiffusionPipeline 管道类
# 这是 Hugging Face 提供的 Stable Diffusion 封装接口
from diffusers import StableDiffusionPipeline

# 导入 PyTorch 深度学习框架
import torch

# ============================================
# 配置参数
# ============================================

# Hugging Face 模型仓库 ID
# runwayml/stable-diffusion-v1-5 是官方发布的 SD 1.5 版本
model_id = "runwayml/stable-diffusion-v1-5"

# 本地保存路径，./ 表示当前目录下的 models 文件夹
# 模型文件将保存在这里，方便下次离线加载
local_path = "./models/stable-diffusion-v1-5"

# ============================================
# 下载模型
# ============================================

# 从 Hugging Face Hub 下载预训练模型
# from_pretrained 会自动下载权重、配置文件、分词器等
pipe = StableDiffusionPipeline.from_pretrained(
    model_id,                    # 远程模型标识符
    torch_dtype=torch.float16,   # 使用半精度浮点数，减少显存和磁盘占用
    use_safetensors=True         # 使用 safetensors 格式，比 pickle 更安全
)

# ============================================
# 保存到本地
# ============================================

# 将下载的完整模型保存到本地路径
# 包括：UNet、VAE、文本编码器、调度器、分词器等所有组件
pipe.save_pretrained(local_path)

# 打印确认信息，提示用户保存位置
print(f"✓ 模型已保存到: {local_path}")

---

文件二：generate_image.py --- 从本地加载并生成图片

# 从 diffusers 库导入 StableDiffusionPipeline 管道类
from diffusers import StableDiffusionPipeline

# 导入 PyTorch 深度学习框架
import torch

# ============================================
# 配置参数
# ============================================

# 本地模型路径，指向之前 download_model.py 保存的目录
# 必须是完整路径，包含 model_index.json 和所有子文件夹
local_path = "./models/stable-diffusion-v1-5"

# ============================================
# 加载本地模型
# ============================================

# 从本地路径加载预训练模型
# 与下载时不同，这里使用 local_path 而不是 model_id
pipe = StableDiffusionPipeline.from_pretrained(
    local_path,                  # 本地模型目录路径
    torch_dtype=torch.float16,   # 保持与保存时一致的精度
    use_safetensors=True,        # 使用 safetensors 格式加载
    local_files_only=True        # 强制只使用本地文件，禁止联网下载
                                 # 如果本地文件缺失会报错，不会自动去 HF 下载
).to("cuda")                     # 将模型移动到 GPU 加速推理

# ============================================
# 生成图片
# ============================================

# 定义文本提示词，描述想要生成的图像内容
# a cute cat running on the grass: 主体内容（可爱的猫在草地上奔跑）
# 8k: 提示高质量、高分辨率
# realistic: 提示写实摄影风格
prompt = "a cute cat running on the grass, 8k, realistic"

# 执行图像生成
# pipe(prompt) 内部流程：
# 1. 文本编码器将 prompt 转为语义向量
# 2. UNet 在潜空间进行多步去噪（默认 50 步）
# 3. VAE 将潜变量解码为像素图像
# .images[0] 获取返回的 PIL Image 列表中的第一张图
image = pipe(prompt).images[0]

# 使用 Pillow 保存图像为 PNG 格式
image.save("cat.png")

# 打印完成信息
print("✓ 图片已保存: cat.png")

---

文件三：sd_generate.py --- 智能判断（自动下载或本地加载）

# 从 diffusers 库导入 StableDiffusionPipeline 管道类
from diffusers import StableDiffusionPipeline

# 导入 PyTorch 深度学习框架
import torch

# 导入操作系统模块，用于文件路径判断
import os

# ============================================
# 配置参数
# ============================================

# Hugging Face 远程模型 ID，用于首次下载
model_id = "runwayml/stable-diffusion-v1-5"

# 本地模型保存/加载路径
local_path = "./models/stable-diffusion-v1-5"

# ============================================
# 智能判断：本地存在则用本地，否则下载
# ============================================

# 使用 os.path.exists 检查本地模型目录是否存在
# 判断依据：目录存在且包含有效模型文件（至少要有 model_index.json）
if os.path.exists(local_path):
    # 本地模型已存在，进入此分支
    print("📁 从本地加载模型...")
    
    # 从本地路径加载，不联网
    pipe = StableDiffusionPipeline.from_pretrained(
        local_path,              # 使用本地路径
        torch_dtype=torch.float16,
        use_safetensors=True,
        local_files_only=True    # 强制离线模式
    )

else:
    # 本地模型不存在，首次运行或模型被删除
    print("🌐 从 Hugging Face 下载模型...")
    
    # 从远程 Hub 下载完整模型
    pipe = StableDiffusionPipeline.from_pretrained(
        model_id,                # 使用远程模型 ID
        torch_dtype=torch.float16,
        use_safetensors=True
    )
    
    # 将下载的模型保存到本地，方便下次使用
    pipe.save_pretrained(local_path)
    
    # 提示用户模型已缓存
    print(f"✓ 模型已缓存到: {local_path}")

# ============================================
# 统一处理：移动到 GPU
# ============================================

# 无论上面哪个分支，都将模型加载到 CUDA GPU
# 注意：这一步在 save_pretrained 之后，因为保存不需要 GPU
pipe = pipe.to("cuda")

# ============================================
# 生成图片
# ============================================

# 定义提示词，描述想要的图像内容
prompt = "a cute cat running on the grass, 8k, realistic"

# 执行扩散过程生成图像
image = pipe(prompt).images[0]

# 保存生成的图像
image.save("cat.png")

# 打印完成信息
print("✓ 图片已保存: cat.png")

---

三个文件关系图

首次运行 ──→ download_model.py ──→ 保存模型到 ./models/
    │
    └────→ sd_generate.py ───────→ 自动检测 → 下载 → 保存 → 生成
              ↑
日常运行 ──→ generate_image.py ──→ 直接从本地加载 → 生成
              ↑
           sd_generate.py ───────→ 检测到本地存在 → 直接加载 → 生成

文件	用途	运行次数
download_model.py	仅下载保存	1 次（或更新模型时）
generate_image.py	仅生图，依赖本地模型	无数次
sd_generate.py	二合一，自动判断	任意（首次会下载）

---