diffusers 中的 Lumina2Pipeline基于 20 亿参数流式扩散 Transformer 的文本生图实战指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusersLumina Image 2.0Lumina-Image 2.0是 Alpha-VLLM 提出的基于流匹配flow matching的扩散 Transformer 模型参数量约 20 亿能够在统一架构中把文本与图像 token 拼成联合序列做跨模态交互。本文以 diffusers 仓库中的 Lumina2Pipeline 文档 为核心骨架结合 pipeline 源码 与 transformer 源码系统讲解该管线的组件构成、标准推理流程、Single File 权重加载、GGUF 量化加载以及__call__全部核心参数与底层去噪细节读完即可在自己的环境中复现文本生图并进阶到 LoRA 微调。Lumina Image 2.0 是什么Lumina-Image 2.0 是一个面向文本到图像生成的扩散模型。论文摘要指出它在多个基准上超越了此前的 SOTA 方法并具备向通用视觉智能模型演进的潜力其三个关键特性是统一Unification采用统一架构将文本 token 与图像 token 视为一条联合序列joint sequence自然地进行跨模态交互并便于任务扩展同时引入统一字幕系统 UniCaptioner为训练提供语义对齐更佳的文图对加速收敛、提升提示词跟随能力、支持变长提示与基于提示模板的任务泛化。高效Efficiency为提升统一架构效率开发了一组优化技术在训练期间改进语义学习与细粒度纹理生成并引入不牺牲图像质量的推理期加速策略。透明Transparency开源全部训练细节、代码与模型保证完全可复现。在 diffusers 中与该模型对应的管线是Lumina2Pipeline模型主体为Lumina2Transformer2DModel一个基于 Transformer 骨干的扩散模型源码注释中称之为 Lumina2NextDiT。Lumina2Pipeline 的组件构成从 pipeline_lumina2.py 的类定义可以看到Lumina2Pipeline继承自DiffusionPipeline与Lumina2LoraLoaderMixin后者提供 LoRA 加载能力由五个组件构成组件类型作用vaeAutoencoderKL在图像与潜空间表示之间编码/解码text_encoderGemma2PreTrainedModel冻结将文本提示编码为嵌入tokenizerGemmaTokenizer/GemmaTokenizerFast文本分词transformerLumina2Transformer2DModel去噪图像潜变量文本条件schedulerFlowMatchEulerDiscreteScheduler与 transformer 配合完成去噪初始化时还设定了若干关键属性vae_scale_factor 8VAE 对图像做 8 倍压缩默认采样尺寸取自 transformer 配置默认sample_size 128见 transformer_lumina2.py默认图像尺寸为sample_size * vae_scale_factor即默认生成 1024×1024 图像。管线还会注入一个默认系统提示词You are an assistant designed to generate superior images with the superior degree of image-text alignment based on textual prompts or user prompts.该提示词会在编码阶段与用户提示拼接格式为system_prompt Prompt Start p可通过system_prompt参数覆盖。文本编码细节_get_gemma_prompt_embeds与encode_prompt展示了文本编码流程pipeline_lumina2.pytokenizer 使用paddingmax_length、truncationTrue默认max_sequence_length 256最大不超过 512check_inputs会校验取 Gemma2 的倒数第二层隐藏状态hidden_states[-2]作为提示嵌入若文本被截断会打印告警日志进行 classifier-free guidanceCFG时负向提示默认取空字符串的嵌入支持传入预计算的prompt_embeds/negative_prompt_embeds/ 对应 attention mask便于做提示加权等操作。标准推理流程从加载到出图仓库文档与源码 docstringpipeline_lumina2.py给出的最简用法如下import torch from diffusers import Lumina2Pipeline pipe Lumina2Pipeline.from_pretrained(Alpha-VLLM/Lumina-Image-2.0, torch_dtypetorch.bfloat16) # Enable memory optimizations. pipe.enable_model_cpu_offload() prompt Upper body of a young woman in a Victorian-era outfit with brass goggles and leather straps. Background shows an industrial revolution cityscape with smoky skies and tall, metal structures image pipe(prompt).images[0]要点说明使用torch.bfloat16半精度加载显著降低显存占用enable_model_cpu_offload()会按model_cpu_offload_seq text_encoder-transformer-vae的顺序把组件在 CPU/GPU 间调度是低显存环境下的推荐做法默认推理步数num_inference_steps 30默认guidance_scale 4.0返回ImagePipelineOutputreturn_dictTrue时通过.images[0]取出 PIL 图像。基于源头的全流程解读__call__方法的执行步骤pipeline_lumina2.py与标准扩散管线一致检查输入check_inputs校验height、width必须能被vae_scale_factor * 2 16整除、prompt与prompt_embeds二选一、max_sequence_length 512等编码提示调用encode_prompt见上文准备潜变量prepare_latents中先对高宽做2 * (int(height) // (vae_scale_factor * 2))的取整处理VAE 8 倍压缩 2 倍 patch 打包约束再采样高斯噪声准备时间步默认用np.linspace(1.0, 1 / num_inference_steps, num_inference_steps)构造 sigma 序列也可通过sigmas参数自定义去噪循环核心在步骤 6下面单独展开解码latents / vae.config.scaling_factor vae.config.shift_factor后经 VAE 解码再经VaeImageProcessor后处理输出 PIL 图像。去噪循环中的两个关键机制在去噪循环中有两个 Lumina 特有的处理值得注意时间步反转由于 Lumina 以t0表示噪声、t1表示图像源码中执行current_timestep 1 - t / self.scheduler.config.num_train_timesteps反转时间步后再送入 transformer。基于归一化的 CFG 截断循环内计算do_classifier_free_truncation (i 1) / num_inference_steps cfg_trunc_ratio只有当未超过cfg_trunc_ratio默认 1.0即全程开启时才执行 CFGnoise_pred noise_pred_uncond guidance_scale * (noise_pred_cond - noise_pred_uncond) if cfg_normalization: cond_norm torch.norm(noise_pred_cond, dim-1, keepdimTrue) noise_norm torch.norm(noise_pred, dim-1, keepdimTrue) noise_pred noise_pred * (cond_norm / noise_norm)即 CFG 之后做一次条件预测与合成预测的范数归一化这是论文中提到的推理期加速/质量优化策略之一。此外calculate_shift复用自 Flux 管线会根据图像序列长度在base_shift0.5与max_shift1.15之间线性插值得到 time shift 参数mu再传给调度器的set_timesteps(sigmas..., mu...)。retrieve_timesteps支持timesteps或sigmas自定义调度但二者只能传一个且要求调度器set_timesteps支持对应参数源码会做签名检测。Lumina2Pipeline 核心参数速查结合 pipeline_lumina2.py 的__call__签名常用参数如下参数默认值说明promptNone提示词字符串或字符串列表width/height默认 1024生成尺寸必须能被 16 整除num_inference_steps30去噪步数越多质量越高但越慢guidance_scale4.0CFG 引导强度大于 1 时启用 CFGnegative_promptNone负向提示Lumina 通常应传sigmasNone自定义 sigma 序列覆盖默认线性调度num_images_per_prompt1每个提示生成的图像数generatorNone随机数生成器用于可复现生成latentsNone预生成噪声潜变量prompt_embeds/negative_prompt_embedsNone预计算文本嵌入prompt_attention_mask/negative_prompt_attention_maskNone嵌入对应的 attention maskoutput_typepil输出格式pil或pt等return_dictTrue返回ImagePipelineOutput还是裸 tuplecallback_on_step_end/callback_on_step_end_tensor_inputsNone/[latents]每步结束回调tensor 输入限定为[latents, prompt_embeds]system_prompt内置默认自定义系统提示词cfg_trunc_ratio1.0应用归一化 CFG 的时间步区间比例cfg_normalizationTrue是否启用基于归一化的引导尺度max_sequence_length256提示最大 token 数≤512参数校验方面check_inputs明确要求prompt与prompt_embeds不能同时传入传prompt_embeds时必须同时传prompt_attention_masknegative_prompt_embeds同理直接传入的嵌入形状必须一致。使用 Single File 加载 Lumina Image 2.0Lumina2Transformer2DModel支持 Single File 加载官方文档 lumina2.md 明确说明可以直接从原始的.pth权重文件实例化模型import torch from diffusers import Lumina2Transformer2DModel, Lumina2Pipeline ckpt_path https://huggingface.co/Alpha-VLLM/Lumina-Image-2.0/blob/main/consolidated.00-of-01.pth transformer Lumina2Transformer2DModel.from_single_file( ckpt_path, dtypetorch.bfloat16 ) pipe Lumina2Pipeline.from_pretrained( Alpha-VLLM/Lumina-Image-2.0, transformertransformer, dtypetorch.bfloat16 ) pipe.enable_model_cpu_offload() image pipe( a cat holding a sign that says hello, generatortorch.Generator(cpu).manual_seed(0), ).images[0] image.save(lumina-single-file.png)底层原理从原始权重到 diffusers 状态字典Single File 能力来自FromOriginalModelMixinsingle_file_model.py其from_single_file类方法接受三类输入Hub 上的.safetensors/.ckpt文件链接、本地权重文件路径、或直接的状态字典state dict。加载时模型默认置于model.eval()模式。对于Lumina2Transformer2DModeldiffusers 注册了专门的权重映射函数convert_lumina2_to_diffusers见 single_file_model.py 与 single_file_utils.py。该函数做的主要工作包括删除原始检查点中未使用的norm_final.weight兼容 Comfy 检查点常见的model.diffusion_model.前缀通过LUMINA_KEY_MAP完成键名映射如cap_embedder → time_caption_embed.caption_embedder、attention → attn、q_norm/k_norm → norm_q/norm_k等处理 GQA 的融合 QKV 权重将原始融合的qkv张量按[q_dim2304, k_dim768, v_dim768]切分成to_q/to_k/to_v三份映射 context refiner、final layer 与 adaLN modulation 等特殊结构。这一实现事实也印证了原始权重与 diffusers 格式之间存在命名与张量布局差异from_single_file会自动完成转换用户无需手工处理。使用 GGUF 量化检查点加载 Lumina Image 2.0除了原始权重Lumina2Transformer2DModel还支持通过from_single_file配合GGUFQuantizationConfig加载 GGUF 量化检查点文档见 lumina2.mdimport torch from diffusers import Lumina2Transformer2DModel, Lumina2Pipeline, GGUFQuantizationConfig ckpt_path https://huggingface.co/calcuis/lumina-gguf/blob/main/lumina2-q4_0.gguf transformer Lumina2Transformer2DModel.from_single_file( ckpt_path, quantization_configGGUFQuantizationConfig(compute_dtypetorch.bfloat16), dtypetorch.bfloat16, ) pipe Lumina2Pipeline.from_pretrained( Alpha-VLLM/Lumina-Image-2.0, transformertransformer, dtypetorch.bfloat16 ) pipe.enable_model_cpu_offload() image pipe( a cat holding a sign that says hello, generatortorch.Generator(cpu).manual_seed(0), ).images[0] image.save(lumina-gguf.png)关于GGUFQuantizationConfig定义于 quantization_config.py需要了解核心参数为compute_dtype默认torch.float32表示计算精度——例如输入为 fp32 时可将计算设为 bf16 换取加速。上面示例显式传入torch.bfloat16配置会标记quant_method GGUF、pre_quantized True即加载的是预量化权重GGUF 量化通常对应 4-bit 级别压缩示例中的lumina2-q4_0.gguf能显著降低显存与磁盘占用适用于低资源推理场景。模型结构纵深Lumina2Transformer2DModel 的关键设计Lumina2Transformer2DModeltransformer_lumina2.py的默认配置为sample_size128、patch_size2、in_channels16、hidden_size2304、num_layers26、num_refiner_layers2、num_attention_heads24、num_kv_heads8GQA 分组查询注意力。几个值得注意的结构点联合序列建模forward 中先把 caption 嵌入与图像 patch 嵌入拼接为联合序列joint_hidden_states统一送入 Transformer blocks这正是论文文本与图像 token 联合序列的架构落地输出时再按序列长度切回图像部分并做 unpatchifyQK-Norm RoPELumina2AttnProcessor2_0在注意力中先对 query/key 做 RMS 归一化再应用旋转位置编码RoPE并使用 PyTorch 2.0 的scaled_dot_product_attention要求 PyTorch ≥ 2.03D 旋转位置编码Lumina2RotaryPosEmbed基于 caption 序列长度、图像行/列三维坐标构造位置 IDaxes_lens(300, 512, 512)caption 与图像各自获得独立的 RoPE 频率Refiner 结构模型包含context_refiner细化文本上下文与noise_refiner细化噪声分支两组各 2 层的前置块之后才是 26 层主 Transformer 块调制modulation主块使用LuminaRMSNormZero生成 gate/scale 系数类似 adaLNrefiner 块则用纯 RMSNorm训练支持_supports_gradient_checkpointing True支持梯度检查点节省训练显存。如果只想加载标准 diffusers 格式的 transformer 组件可以使用 Lumina2Transformer2DModel 文档 中的方式from diffusers import Lumina2Transformer2DModel transformer Lumina2Transformer2DModel.from_pretrained( Alpha-VLLM/Lumina-Image-2.0, subfoldertransformer, dtypetorch.bfloat16 )进阶LoRA 微调与生态支持Lumina2Pipeline通过Lumina2LoraLoaderMixin原生支持 LoRA 加载仓库还提供了 DreamBooth LoRA 微调脚本 train_dreambooth_lora_lumina2.py 及其说明文档 README_lumina2.md。核心训练命令示例export MODEL_NAMEAlpha-VLLM/Lumina-Image-2.0 export INSTANCE_DIRdog export OUTPUT_DIRtrained-lumina2-lora accelerate launch train_dreambooth_lora_lumina2.py \ --pretrained_model_name_or_path$MODEL_NAME \ --instance_data_dir$INSTANCE_DIR \ --output_dir$OUTPUT_DIR \ --mixed_precisionbf16 \ --instance_prompta photo of sks dog \ --resolution1024 \ --train_batch_size1 \ --gradient_accumulation_steps4 \ --use_8bit_adam \ --learning_rate1e-4 \ --report_towandb \ --lr_schedulerconstant \ --lr_warmup_steps0 \ --max_train_steps500 \ --validation_promptA photo of sks dog in a bucket \ --validation_epochs25 \ --seed0 \ --push_to_hub训练脚本还支持以下与 Lumina 相关的自定义参数见 README_lumina2.md--lora_layers指定施加 LoRA 的 transformer 模块逗号分隔如to_k,to_q,to_v表示只训练注意力投影层--system_prompt自定义系统提示词为模型提供额外人设--max_sequence_length文本嵌入的最大序列长度内存优化选项--offloadtext encoder 与 VAE 不用时卸载到 CPU、cache_latents预计算 VAE 潜变量、--use_8bit_adambitsandbytes 8bit 优化器。训练前需安装 PEFT 后端peft0.14.0并先完成accelerate config配置。测试验证行为如何被守护仓库为 Lumina2 提供了三层测试可作为复现与排查问题的参考管线测试 test_pipeline_lumina2.py构造迷你组件单头注意力、2 层 transformer 的 dummy Gemma2 编码器等后执行test_inference用 CPU 上的期望输出切片做逐元素比对误差atol1e-3同时覆盖内存占用与 LoRA 加载/卸载Single File 测试 test_lumina2_transformer.py验证Lumina2Transformer2DModel能从 Comfy 打包的 bf16 safetensors 单文件权重正确加载模型测试 test_models_transformer_lumina2.py覆盖 transformer 前向与配置。实用建议小结低显存环境优先torch.bfloat16enable_model_cpu_offload()显存仍不足时改用 GGUF 4-bit 量化检查点可复现生成传入generatortorch.Generator(cpu).manual_seed(0)固定随机种子负向提示Lumina 的 CFG 负向提示官方建议为空字符串尺寸约束height/width需能被 16 整除默认 1024自定义调度可通过sigmas传入自定义 sigma 序列精细控制去噪过程但不要与num_inference_steps之外的timesteps混用进一步学习调度器速度与质量权衡可参考 schedulers 指南复用组件加载多个管线可参考 loading 指南模型层完整 API 见 Lumina2Transformer2DModel 文档。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考