如何快速本地部署Qwen-Image-2512-FP8：新手零基础上手文生图推理完整教程

想在本地部署 Qwen-Image-2512-FP8并跑通文生图推理吗？这份新手零基础教程带你用最短路径完成：一个仓库、两步命令、一张图片。Qwen-Image-2512-FP8 是 Unsloth 团队对阿里通义文生图基础模型 Qwen-Image-2512 推出的FP8 / INT8 动态激活量化版本，在大幅降低显存占用的同时，画质与原版 bf16 模型几乎一致（同种子 LPIPS 距离：INT8 为 0.029，FP8 为 0.109，越低越好）。

这个仓库里有什么？

本仓库是一个模型权重仓库（基于apache-2.0协议开源，支持中英文提示词），核心内容如下：

💡 量化权重由 torchao 动态激活量化构建，加载即推理：加载检查点与“现场量化 bf16 模型”逐位一致，直接省去了显存翻倍的全量加载 + 在线量化过程。

环境准备：硬件与软件要求

上手前确认你的机器满足以下条件：

• 硬件：建议 NVIDIA GPU，显存 ≥ 16 GB 可跑 FP8 版本；INT8 版本权重更大但推理精度更优；纯 CPU 可用 float32 运行，速度较慢。
• 软件：Python 3.10+、PyTorch（CUDA 版本）、最新版diffusers与torchao。

快速获取模型权重：一条命令搞定

通过 git 克隆仓库即可拿到全部模型文件（需安装 git-lfs 才能拉取真实权重）：

git lfs install git clone https://gitcode.com/hf_mirrors/unsloth/Qwen-Image-2512-FP8.git

克隆完成后，你会得到上面表格中的所有文件。如果显存紧张，可以只保留Qwen-Image-2512-FP8.safetensors一个权重文件来节省磁盘空间。

安装依赖：3 步完成

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 pip install "diffusers[torch]" transformers accelerate pip install torchao safetensors

注意：仓库 README 中给出的pip install git+https://github.com/huggingface/diffusers需要安装最新版 diffusers 才能正确识别 Qwen-Image 系列流水线，如果 pip 安装版本偏旧，请按官方文档升级。

运行推理：生成你的第一张图

下面的最小示例展示了加载流水线并生成一张 16:9 图片的关键流程（完整说明见 README.md 的 Quick Start 章节）：

from diffusers import DiffusionPipeline import torch pipe = DiffusionPipeline.from_pretrained( "Qwen/Qwen-Image-2512", # 加载模型；量化权重可指向本仓库 .pt/.safetensors 文件 torch_dtype=torch.bfloat16 ).to("cuda") image = pipe( prompt="cute sloth typing on a computer", negative_prompt="低分辨率，低画质，肢体畸形，手指畸形，画面过饱和，蜡像感，AI感", width=1664, height=928, # 16:9 num_inference_steps=50, true_cfg_scale=4.0, generator=torch.Generator(device="cuda").manual_seed(42) ).images[0] image.save("example.png")

把model_name换成本仓库路径、并按 torchao 文档加载量化检查点后，即可使用 FP8 / INT8 权重推理——这正是本仓库存在的意义。

关键参数速查表

FP8 还是 INT8？一张表帮你选

🎯 简单记：显存选 FP8，画质选 INT8。

常见问题 FAQ

Q1：加载时报activation_value_lb相关错误？请升级到 torchao ≥ 0.13，加载器需要 floor 动态激活缩放（activation_value_lb=1e-12），防止全零激活行产生零缩放。

Q2：.pt和.safetensors两份文件怎么选？两者是同一检查点。.pt为torch.loadstate dict（torchao 张量子类携带 qdata 与 scales，safetensors 无法完整表达）；新环境优先试.safetensors（torchao 0.18 布局），加载更安全。

Q3：没有 NVIDIA 显卡能跑吗？可以。CPU 下把torch_dtype改为torch.float32、device设为cuda改cpu即可，但生成一张图需要数分钟以上，建议配合num_inference_steps=20快速验证。

小结

通过本教程，你已掌握 Qwen-Image-2512-FP8 本地部署的完整链路：克隆仓库 → 安装 diffusers + torchao → 加载量化权重 → 一条 pipe 调用出图。量化版让你在消费级显卡上也能跑起当前开源第一梯队的文生图模型（超 1 万轮盲测中位列开源最强），下一步可以试试调整宽高比、更换种子，或阅读 README.md 了解更多模型能力细节。