部署图像生成模型 (Diffusers)

一、模型原理与结构

图像生成模型基于**扩散模型（Diffusion Models）或流匹配（Flow Matching）**架构，通过逐步去噪过程将随机噪声转化为高质量图像：

U-Net / Transformer 主干网络：学习噪声预测或流场方向
文本编码器（CLIP / T5）：将 prompt 映射为语义向量，引导生成过程
VAE（变分自编码器）：在潜在空间中压缩与解码图像，降低计算成本
采样器（Sampler）：控制去噪步数与路径（如 Euler、DPM-Solver）

FLUX 系列采用流变换器（Flow Transformer）架构，在质量与速度上达到 SOTA；Qwen-Image 系列针对中文 prompt 与文字渲染做了专项优化。

二、应用场景

图像生成模型可应用于：

艺术创作与概念设计：游戏美术、电影分镜、插画生成
电商与营销：商品图、海报、社交媒体素材
内容生产：文章配图、教育插图、自媒体封面
图像编辑：风格迁移、局部修改、背景替换
虚拟场景生成：建筑可视化、室内设计预览

三、部署指南与示例

本指南提供了一套基于 Hugging Face Diffusers 的通用部署方案，旨在解决国产算力的适配难题，助您在不同硬件架构上高效运行各类文生图模型。我们将以 FLUX.2-klein-4B 为示例模型。

推理框架概览

Hugging Face Diffusers：生图领域最基础、最灵活的库，适合进行快速原型设计、算法研究、LoRA 微调及本地推理。

前提条件

资源准备：
- 内置模型：使用平台内置模型库（路径 /mnt/moark-models/），零等待、零流量，实现即刻加载。
- 依赖库：根据各章节指定版本安装依赖库。
环境一致性：
- 镜像匹配：国产芯片对底层驱动（Driver）和编译工具链（Toolkit）有严格要求。请严格按照各章节指定的镜像版本创建实例，错误的镜像将导致 import error 或无法调用加速卡。

一、沐曦 (MetaX) 部署指南

本章节适用于 曦云 C500 等沐曦系列算力卡。

1. 通用环境准备

所有沐曦模型部署均需基于以下环境配置进行：

算力型号：曦云 C500 (64GB)
镜像选择：PyTorch / 2.6.0 / Python 3.10 / maca 3.2.1.3
版本要求：pytorch>=2.4

镜像选择

基础操作步骤：

进入工作台：启动实例后，点击 JupyterLab 进入容器环境。
新建脚本：点击 "Notebook" 图标，新建一个 .ipynb 文件。

2. 模型部署实战

请根据您需要的模型选择对应的实战案例代码。

2.1 FLUX.2-klein-4B

本示例演示如何在 曦云 C500 算力环境下，加载平台内置模型并生成高质量图像。

运行推理代码： 新建 Notebook 单元格运行

# 1. 安装必要的依赖库
!pip install diffusers

from diffusers import FluxPipeline
import torch

# 2. 引用沐曦内置模型库 (无需下载)
model_name = "/mnt/moark-models/FLUX.2-klein-4B"

# 3. 自动检测计算设备
if torch.cuda.is_available():
    torch_dtype = torch.bfloat16
    device = "cuda"
else:
    torch_dtype = torch.float32
    device = "cpu"

# 4. 加载生成管道
pipe = FluxPipeline.from_pretrained(model_name, torch_dtype=torch_dtype)
pipe = pipe.to(device)

# 5. 定义 Prompt (赛博美学风格社交卡片)
prompt = '''一张 9:16 竖版逼真的赛博美学未来社交资料卡照片：一只手轻握一张竖直半透明的亚克力质感卡片，
占据画面视觉中心。卡片呈现未来社交平台"模力方舟"的个人主页界面，设计极简，无冗余装饰。
卡片边缘圆润柔和，泛着粉紫色与冰蓝色的渐变霓虹光晕，背景深邃模糊，进一步突显卡片本身如水晶般清澈的质感。
界面信息仿佛微雕其中，立体而清晰，依次展示：
头像（居中悬浮，带全息环绕特效）
用户名与顶部"认证会员"动态徽章
名称 模力方舟(MoArk)算力体验官
关注数 2777
被关注数 1.2w
加入时间： 2025/11/7
关注按钮（呈现可点击的柔光质感）
手指轻触处反射出柔和光影，整体氛围既富有电影感，又充满高科技终端的沉浸体验。'''

negative_prompt = ""

# 设置宽高 (9:16)
width, height = 928, 1664

# 6. 执行生成
image = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=width,
    height=height,
    num_inference_steps=30,
    true_cfg_scale=4.0,
    generator=torch.Generator(device="cuda").manual_seed(42)
).images[0]

# 7. 保存结果
image.save("image.png")
print("图片生成完成，已保存为 image.png")

查看结果与排查： 代码运行结束后，您可以在左侧文件栏找到 image.png，双击即可查看生成的图片。图像结果

二、燧原 (Enflame) 部署指南

本章节适用于 S60 等燧原系列算力卡。由于底层架构差异，需引入适配库：import torch_gcu 与from torch_gcu import transfer_to_gcu

1. 通用环境准备

所有燧原模型部署均需基于以下环境配置进行：

算力型号：Enflame S60 (48GB)
镜像选择：Ubuntu / 22.04 / Python 3.13 / ef 1.5.0.604

镜像选择

基础操作步骤：

进入工作台：启动实例后，点击 JupyterLab 进入容器。
新建脚本：点击图标新建一个 .ipynb 文件。

2. 模型部署实战

请根据您需要的模型选择对应的实战案例代码。

2.1 FLUX.1-Krea-dev

本示例演示如何在 燧原 S60 算力环境下，加载平台内置模型并生成赛博朋克风格图像。

运行推理代码： 新建 Notebook 单元格运行。

import torch
import torch_gcu # 引入torch_gcu库
from torch_gcu import transfer_to_gcu # CUDA代码一键迁移
from diffusers import FluxPipeline

# 引用燧原 S60 的内置模型库
model_name = "/mnt/moark-models/FLUX.1-Krea-dev"

if torch.cuda.is_available():
    torch_dtype = torch.bfloat16
    device = "cuda"
else:
    torch_dtype = torch.float32
    device = "cpu"

pipe = FluxPipeline.from_pretrained(model_name, torch_dtype=torch_dtype)
pipe = pipe.to(device)

prompt = '''A 9:16 vertical, realistic cyber-aesthetic future social profile card photo: A hand gently holds a vertically semi-transparent acrylic card, occupying the visual center of the picture. The card presents the personal homepage interface of the future social platform "MoArk", with a minimalist design and no redundant decorations. The edges of the card are rounded and soft, with a gradient neon halo of pink-purple and ice blue. The background is deep and blurry, further highlighting the crystal-clear texture of the card itself. The interface information seems to be micro-engraved, three-dimensional and clear, displayed in sequence:
Avatar (suspended in the center, with a holographic surround effect)
Username and the dynamic "Verified Member" badge at the top
Name: MoArk (MoArk) Computing Power Experience Officer
Followers: 2,777
Following: 12,000
Join Date: 11/7/2025
Follow button (presenting a soft light touchable effect)
A soft light and shadow is reflected at the point where the finger touches, creating an atmosphere that is both cinematic and immersive, like a scene from a near-future live-action game.'''

image = pipe(
    prompt,
    height=1024,
    width=1024,
    guidance_scale=3.5,
    num_inference_steps=30,
    max_sequence_length=512,
    generator=torch.Generator(device="cuda").manual_seed(42)
).images[0]

# 保存结果
image.save("flux-dev.png")

查看结果与排查： 运行完成后在左侧文件栏查看 flux-dev.png。

图像结果

显存溢出 (OOM) 解决方案

如果在运行 FLUX 这类大模型时遇到 OutOfMemoryError：

打开终端 (Terminal)。
输入 efsmi -pmon 查看显存占用（按 Ctrl+C 退出）。
找到僵尸进程 PID，输入 kill -9 <PID> 强制释放显存。

问题排查

三、昇腾 (Ascend) 部署指南

本章节适用于 昇腾 910B 等华为系列算力卡。由于底层架构差异，需引入适配库：import torch_npu 与from torch_npu.contrib import transfer_to_npu

1. 通用环境准备

所有昇腾的模型部署均需基于以下环境配置进行：

算力型号：Ascend 910B (64GB)
镜像选择：PyTorch / 2.8.0 / Python 3.11 / CANN 8.3.RC2

镜像选择

基础操作步骤：

进入工作台：启动实例后，点击 JupyterLab 进入容器。
新建脚本：点击图标新建一个 .ipynb 文件。

2. 模型部署实战

请根据您需要的模型选择对应的实战案例代码。

2.1 Qwen-Image-Edit-2511

本示例演示如何在 Ascend 910B 算力环境下，加载平台内置模型并生成赛博朋克风格图像。

运行推理代码： 新建 Notebook 单元格运行。

!pip install diffusers
!pip install transformers
!pip install accelerate
import os
import torch
import torch_npu
from PIL import Image
from diffusers import QwenImageEditPlusPipeline
from torch_npu.npu import amp # 导入AMP模块
from torch_npu.contrib import transfer_to_npu    # 使能自动迁移

pipeline = QwenImageEditPlusPipeline.from_pretrained("/mnt/moark-models/Qwen-Image-Edit-2511", torch_dtype=torch.bfloat16)
print("pipeline loaded")

pipeline.enable_model_cpu_offload()
pipeline.set_progress_bar_config(disable=None)
image1 = Image.open("/mnt/moark-models/input1.jpg").convert('RGB') 
prompt = """请根据图片中的角色，设计一张风格诙谐、荒诞、有表演感的2025年度总结的海报。
#版式要求
1.设计一组 3:4 竖版比例、适合小红书传播的梗图
#文案设计
1.文案内容
"2025年"
"攒了很多想买的，但没攒钱"
2.文字放置在画面上方，要清晰可读，并且与画面留有足够呼吸空间
3.不与角色主体重叠
#角色设计
1.保持角色的一致性
2.更改角色的肢体动作，呈现出跑步的姿态，以配合文案传达情绪
#背景设计
1.干净、简洁背景，纯色或浅灰背景
2.不添加复杂装饰，不要场景叠加
#辅助元素
1.可少量加入辅助性的购物元素修饰，仅用于强化情绪，不可喧宾夺主"""
inputs = {
    "image": [image1],
    "prompt": prompt,
    "generator": torch.manual_seed(0),
    "true_cfg_scale": 4.0,
    "negative_prompt": " ",
    "num_inference_steps": 40,
    "guidance_scale": 0.9,
    "num_images_per_prompt": 1,
}
with torch.inference_mode():
    output = pipeline(**inputs)
    output_image = output.images[0]
    output_image.save("2025_happy_engding.png")
    print("image saved at", os.path.abspath("2025_happy_engding.png"))

查看结果与排查： 运行完成后在左侧文件栏查看 2025_happy_ending.png。

图像结果

显存溢出 (OOM) 解决方案

如果在运行 Qwen-Image 这类大模型时遇到 OutOfMemoryError：

打开终端 (Terminal)。
输入 npu-smi info 查看显存占用（按 Ctrl+C 退出）。
找到僵尸进程 PID，输入 kill -9 <PID> 强制释放显存。

四、本地访问与服务验证

请参考【SSH 隧道配置指南】建立安全连接。

五、实战课题

课题目标

使用 Z-Image 或 Qwen-Image-2512 模型完成以下两项任务，所有输出文件请保存至 /data/exam/ 目录。

任务一：单次推理测试

任务要求：

使用 Z-Image 或 Qwen-Image-2512 模型（路径：/mnt/moark-models/）

生成以下描述的图像：

一只可爱的橘色小猫坐在窗台上，窗外是夕阳余晖洒满的城市天际线，
温暖的光线透过玻璃照在猫咪的毛发上，营造出宁静祥和的氛围。
高清摄影风格，细节丰富。

将生成图像保存为 /data/exam/image_output.png

实现提示：

使用 Hugging Face Diffusers 库
参考部署指南中的图像生成流程
注意设置合适的 num_inference_steps 和 guidance_scale

任务二：部署 OpenAI 兼容 API

任务要求：

使用 FastAPI 创建图像生成服务
在 8188 端口运行
提供 /v1/images/generations 端点，兼容 OpenAI 格式
接口需要支持文生图
接收 JSON 请求，必须包含 prompt 和 size 字段，其他字段可以作为非必传
返回 base64 编码的图像数据

实现提示：

使用 FastAPI + Pydantic 定义请求/响应模型
在服务启动时加载 Diffusers 模型
将生成的 PIL Image 转换为 base64 字符串
通过 SSH 隧道映射到本地测试

提交要求：完成作答后，直接提交检测即可。本课程采取程序自动检测的方式。

需确保以下文件输出完整：

生成图像文件：/data/exam/image_output.png

一、模型原理与结构​

二、应用场景​

三、部署指南与示例​

推理框架概览​

前提条件​

一、 沐曦 (MetaX) 部署指南​

1. 通用环境准备​

2. 模型部署实战​

2.1 FLUX.2-klein-4B​

二、 燧原 (Enflame) 部署指南​

1. 通用环境准备​

2. 模型部署实战​

2.1 FLUX.1-Krea-dev​

三、 昇腾 (Ascend) 部署指南​

1. 通用环境准备​

2. 模型部署实战​

2.1 Qwen-Image-Edit-2511​

四、本地访问与服务验证​

五、实战课题​

课题目标​

任务一：单次推理测试​

任务二：部署 OpenAI 兼容 API​

一、模型原理与结构

二、应用场景

三、部署指南与示例

推理框架概览

前提条件

一、沐曦 (MetaX) 部署指南

1. 通用环境准备

2. 模型部署实战

2.1 FLUX.2-klein-4B

二、燧原 (Enflame) 部署指南

1. 通用环境准备

2. 模型部署实战

2.1 FLUX.1-Krea-dev

三、昇腾 (Ascend) 部署指南

1. 通用环境准备

2. 模型部署实战

2.1 Qwen-Image-Edit-2511

四、本地访问与服务验证

五、实战课题

课题目标

任务一：单次推理测试

任务二：部署 OpenAI 兼容 API