企业官网建设流程全解析

DiffSynth-Studio：手把手跑通 AI 图像与视频生成的完整指南

【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio

DiffSynth-Studio 是魔搭社区维护的开源扩散模型引擎，一套框架同时支持 FLUX、Wan、LingBot-Video、ACE-Step 等主流模型的文生图、文生视频、音频生成和图像编辑，还能在低显存显卡上跑大模型推理、做 LoRA 训练。读完本文，你能完成三件事：把框架装进本地环境、跑出一条 Z-Image 生图推理、启动自带的 Streamlit 推理 WebUI 并理解常见报错的解决方向。

环境自检清单：安装 DiffSynth-Studio 前需要装什么

• 操作系统：Linux / macOS / Windows 均可（Apple Silicon 需把代码里的"cuda"改为"mps"）
• Python：3.10.1 及以上版本
• GPU：NVIDIA 显卡配好 CUDA 与对应版本的 PyTorch；AMD 需 ROCm 版 torch；昇腾 NPU 参考官方文档
• 磁盘空间：预留 10 GB 以上（依赖包 + 首次推理会自动下载的模型权重）
• 网络：能访问模型托管站（默认 ModelScope，可切换为 HuggingFace）

📦 分步搭建：从克隆仓库到依赖装完

把代码拉到本地并建立虚拟环境

建议先建虚拟环境，避免污染系统 Python。两条命令即可：

git clone https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio cd DiffSynth-Studio && python -m venv .venv && source .venv/bin/activate

以源码方式安装框架本体

官方推荐源码安装，pip 会自动带齐 torch、transformers、accelerate、peft 等基础依赖：

pip install -e .

如需音频模型（ACE-Step、MiniMax-Music3）或量化推理，可追加对应依赖组：

pip install -e ".[audio,quant]"

配置模型下载源

框架默认从 ModelScope 拉取权重，首次运行推理脚本时自动下载，无需手动拷贝。如果你在海外网络环境，可以切到 ModelScope 国际站；想从 HuggingFace 下载则换环境变量（注意两个平台的模型 ID 可能不同）：

export DIFFSYNTH_DOWNLOAD_SOURCE="huggingface"

更多下载源细节可参考仓库内 docs/zh/Pipeline_Usage/Environment_Variables.md。

确认 PyTorch 与显卡匹配

这是新手最容易卡住的一环。执行下面这句，若打印出显卡名和显存大小即正常：

import torch print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))

如果torch.cuda.is_available()为 False，先检查 pip 装的 torch 是否带 CUDA 后缀（形如2.x.x+cu121），纯 CPU 版需要按显卡驱动重装对应 wheel。

🚀 跑通第一次推理与启动 WebUI

用一条示例脚本出第一张图

仓库为每个模型都备好了可直接运行的脚本。以 Z-Image-Turbo 为例，它会自动下载权重、生成图片并保存为image_Z-Image-Turbo.jpg：

python examples/z_image/model_inference/Z-Image-Turbo.py

看到进度条走完、当前目录出现保存的图片，说明推理链路完全通了。显存吃紧时可换 examples/z_image/model_inference_low_vram/ 下的低显存版本。

启动推理 WebUI

WebUI 基于 Streamlit，额外装一个包后启动：

pip install streamlit streamlit run examples/dev_tools/webui.py --server.fileWatcherType none

浏览器打开 Streamlit 提示的本地地址（默认 localhost:8501），看到按参数自动渲染的推理界面即成功。界面控件与 Pipeline 代码的参数一一对应，适合用来调试参数组合。

关键路径速查

⚠️ 新手高频问题

CUDA 版本不匹配导致装不上或跑不动

典型报错是torch.cuda.is_available()返回 False 或加载时抛 CUDA 错误。解决方向：按 NVIDIA 官方指引查驱动支持的 CUDA 版本，用pip install torch --index-url指定对应 cu 后缀的 wheel，不要混装。详见仓库 docs/zh/Pipeline_Usage/Setup.md。

模型权重下载中断

权重体积常达数 GB，网络抖动会断在中间。解决方向：直接重跑脚本，下载器会续传或重新拉取；网络环境差时切换DIFFSYNTH_DOWNLOAD_SOURCE换源，或手动把权重放到对应模型缓存目录后重试。

显存不足 OOM

先换model_inference_low_vram目录下的低显存脚本（框架会把参数在磁盘、内存、显存间动态调度）；仍不够就开启量化：pip install -e ".[quant]"后按 docs/zh/Pipeline_Usage/Quantization.md 配置 NF4/INT8 精度。

【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio