Diffusers 中 NucleusMoE-Image 文生图流水线单流 DiT MoE 专家层 Qwen3-VL 文本编码的全链路解析【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本篇指南基于 Diffusers 仓库中的 NucleusMoE-Image 官方文档页docs/source/en/api/pipelines/nucleusmoe_image.md与对应源码系统讲解NucleusMoEImagePipeline的组件构成、全部调用参数、去噪循环中动态 shift 与范数重标定 CFG 的实现细节以及底层NucleusMoEImageTransformer2DModel的专家选择路由expert-choice routing机制。读完后你将能够正确加载并调用该流水线生成图像、理解每个关键参数的作用与默认值、深入源码定位去噪与 MoE 前向的具体实现并利用仓库测试用例验证行为。1. 模型定位与组件构成NucleusMoE-Image 是一个文生图text-to-image模型其技术组合为单流 DiTDiffusion Transformer Mixture-of-Experts 前馈层 对 Qwen3-VL 文本编码器的交叉注意力 flow-matching Euler 离散调度器官方文档原文如此描述。在 Diffusers 中它对应一个标准的DiffusionPipeline子类由五个组件装配而成见 pipeline_nucleusmoe_image.py组件类型作用transformerNucleusMoEImageTransformer2DModel条件 Transformer负责去噪潜在表示schedulerFlowMatchEulerDiscreteSchedulerflow-matching Euler 离散调度器定义去噪步长vaeAutoencoderKLQwenImage在图像与潜在空间之间编解码text_encoderQwen3VLForConditionalGeneration计算提示词嵌入processorQwen3VLProcessor对文本输入做分词与 chat 模板格式化构造函数中还注册了几个贯穿全流程的默认值第 171-176 行vae_scale_factor由 VAE 的temperal_downsample层数决定2 ** len(...)通常为 8image_processor VaeImageProcessor(vae_scale_factor * 2)像素与 patch 网格之间换算的缩放系数为 16default_sample_size 128不传height/width时默认生成分辨率为128 × 8 1024像素的方形图像default_max_sequence_length 1024文本编码的默认最大 token 数default_return_index -8取 Qwen3-VL 倒数第 8 层隐状态作为提示词嵌入。另外流水线声明了model_cpu_offload_seq text_encoder-transformer-vae第 152 行即在启用 CPU offload 时三个大模块按 text_encoder → transformer → vae 的顺序依次换入换出 GPU 显存。2. 加载与基础调用官方文档给出的最小可运行示例与源码EXAMPLE_DOC_STRING一致见 第 43-55 行import torch from diffusers import NucleusMoEImagePipeline pipe NucleusMoEImagePipeline.from_pretrained(NucleusAI/NucleusMoE-Image, torch_dtypetorch.bfloat16) pipe.to(cuda) prompt A cat holding a sign that says hello world image pipe(prompt, num_inference_steps50).images[0] image.save(nucleus_moe.png)两个实用建议来自官方文档页的 TIP 提示框若需权衡采样速度与质量阅读调度器指南 docs/source/en/using-diffusers/schedulers.md若要在多条流水线间共享同一组件例如复用 VAE 或文本编码器参考 docs/source/en/using-diffusers/loading.md 中 “Reusing models in multiple pipelines” 一节。由于组件中包含完整的多模态大模型Qwen3VLForConditionalGeneration显存需求较高实践中通常配合torch_dtypetorch.bfloat16与设备转移/CPU offload 使用。3.__call__参数详解NucleusMoEImagePipeline.__call__的完整签名与默认值第 381-404 行逐参数说明如下参数默认值说明promptNone引导生成的提示词str或list[str]。若不传则必须传prompt_embeds二者互斥见check_inputsnegative_promptNone负向提示词当guidance_scale 1且未提供时自动用空字符串列表填充以启用 CFGguidance_scale4.0无分类器引导强度大于 1 才启用 CFGheight/widthNone输出图像像素尺寸为None时回落到default_sample_size * vae_scale_factor1024。check_inputs要求二者能被vae_scale_factor * 2整除否则打印告警并按实际取整num_inference_steps50去噪步数sigmasNone自定义噪声尺度调度为None时使用np.linspace(1.0, 1/num_inference_steps, num_inference_steps)线性调度num_images_per_prompt1每个提示词生成的图像数嵌入会按repeat_interleave复制max_sequence_lengthNone文本最大 token 数回落为default_max_sequence_length1024return_indexNone取文本编码器哪一层隐状态回落为-8其绝对值必须小于编码器层数否则check_inputs抛错generatorNonetorch.Generator或列表用于确定性采样若传列表其长度必须等于有效 batch sizelatentsNone预生成的初始噪声潜在张量提供时直接跳过randn_tensorprompt_embeds/prompt_embeds_maskNone预生成的文本嵌入及注意力掩码与prompt互斥negative_prompt_embeds/negative_prompt_embeds_maskNone负向提示词的预生成嵌入与negative_prompt互斥output_typepil输出格式可选pil、np或latent直接返回潜在张量return_dictTrueTrue时返回NucleusMoEImagePipelineOutputFalse时返回(image,)元组attention_kwargsNone透传给注意力处理器的字典内部会弹出可选的scaleLoRA 缩放并支持cached_txt_key/cached_txt_value缓存键callback_on_step_endNone每步结束时的回调函数callback_on_step_end_tensor_inputs[latents]回调可见的张量名必须是[latents, prompt_embeds]的子集否则抛错入参校验集中在check_inputs第 251-300 行分辨率整除性只告警不报错prompt/prompt_embeds必须且只能传其一return_index越界会直接ValueError。4. 去噪循环的四个关键机制4.1 动态 shift按分辨率自适应噪声调度流水线内嵌了一份从 Flux 复用的calculate_shift第 58-69 行标注Copied from diffusers.pipelines.flux.pipeline_flux.calculate_shift。它把图像 token 序列长度线性映射到 shift 参数mudef calculate_shift(image_seq_len, base_seq_len256, max_seq_len4096, base_shift0.5, max_shift1.15): m (max_shift - base_shift) / (max_seq_len - base_seq_len) b base_shift - m * base_seq_len return image_seq_len * m b在__call__中四个边界值均从调度器配置读取base_image_seq_len、max_image_seq_len、base_shift、max_shift有同名缺省值再连同线性sigmas一起交给retrieve_timesteps该函数同样复用自 Stable Diffusion 流水线支持timesteps或sigmas二选一定制二者同传会报错。这意味着分辨率越大token 越多mu越大去噪重心越向高噪声端偏移与 Flux 系列的实践一致。4.2 时间步缩放与 flow-matching 速度取负每一步中时间步先被缩放到训练尺度再送入 Transformertimestep t.expand(latents.shape[0]).to(latents.dtype) noise_pred self.transformer( hidden_stateslatents, timesteptimestep / self.scheduler.config.num_train_timesteps, ... )[0]拿到预测后执行noise_pred -noise_pred再交给scheduler.step。从源码结构看Transformer 输出的是与 velocity 方向相反的预测取负后与FlowMatchEulerDiscreteScheduler约定的更新方向对齐——这是 flow-matching 类流水线的典型约定。4.3 CFG 带范数重标定当guidance_scale 1时流水线做一次条件、一次无条件前向然后组合第 583-597 行comb_pred neg_noise_pred guidance_scale * (noise_pred - neg_noise_pred) cond_norm torch.norm(noise_pred, dim-1, keepdimTrue) noise_norm torch.norm(comb_pred, dim-1, keepdimTrue) noise_pred comb_pred * (cond_norm / noise_norm)与教科书式 CFG 相比这里多做了一步范数重标定norm rescaling把组合后的预测范数缩回条件预测的范数避免大引导系数放大更新步长导致色彩漂移或过饱和。4.4 潜在打包/解包与 VAE 反归一化图像以 patch 化 token 序列的形式进入 Transformer。prepare_latents先用randn_tensor生成(B, 1, C, H, W)的高斯噪声C transformer.config.in_channels // 4再经_pack_latents按patch_size重排为(B, H*W, C*p*p)的序列解码端_unpack_latents逆操作还原随后按 VAE 配置的latents_mean/latents_std做反归一化vae.decode(...)[0][:, :, 0]取第一帧VAE 为时间下采样结构图像生成只消费单帧最后由VaeImageProcessor.postprocess转成pil/np输出。循环内的latents_dtype判断专门处理 MPS 后端 dtype 漂移。5. 文本编码chat 模板、系统提示词与return_indexencode_prompt第 187-249 行是理解该流水线文本侧的关键chat 模板格式化_format_prompt把用户提示词包装成两角色消息——固定的DEFAULT_SYSTEM_PROMPT第 41 行You are an image generation assistant. Follow the users prompt literally. Pay careful attention to spatial layout: objects described as on the left must appear on the left, on the right on the right. Match exact object counts and assign colors to the correct objects.该提示词显式强调空间布局与数量/颜色一致性随后经processor.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue)渲染成最终字符串。分词参数paddinglongest、pad_to_multiple_of8、max_lengthmax_sequence_length、truncationTrue与encode_prompt文档串中的默认 1024 对应。取隐状态文本编码器以output_hidden_statesTrue前向取hidden_states[return_index]默认-8作为嵌入全 1 的注意力掩码会被置None以减少下游分支。批量扩展num_images_per_prompt 1时嵌入与掩码repeat_interleave复制。系统提示词是模型行为的一部分——它把“左侧物体放左边、数量精确”这类约束写进了上下文。若需改变风格化倾向可在推理侧研究_format_prompt对system_prompt的开放当前encode_prompt未暴露该入口属内部实现。6. 底层 Transformer单流 DiT 与专家选择路由NucleusMoEImageTransformer2DModel定义在 transformer_nucleusmoe_image.py默认配置第 775-796 行揭示了完整模型规模patch_size2、in_channels64、num_layers24、attention_head_dim128、num_attention_heads16inner_dim2048、joint_attention_dim3584对齐 Qwen3-VL 隐层维度、axes_dims_rope(16, 56, 56)、num_experts128、moe_intermediate_dim1344、capacity_factor8.0、route_scale2.5。6.1 哪些层启用 MoEdense_moe_strategy策略函数_is_moe_layer第 348-359 行支持五种取值策略MoE 层范围leave_first_three_and_last_block_dense默认3 idx num_layers - 1前 3 层与最后 1 层保持 denseleave_first_three_blocks_denseidx 3leave_first_block_denseidx 1all_moe全部层all_dense无6.2 专家选择路由 共享专家NucleusMoELayer第 501-604 行是 MoE 的核心采用专家选择expert-choice路由而非 token 选择且路由输入融合了时间步路由器输入为cat([timestep 展开, 未调制隐状态])即路由决策同时感知去噪步与内容use_additional_t_cond之外的第二处时间条件注入点gate nn.Linear(hidden_size * 2, num_experts, biasFalse)打分经 sigmoid可选或 softmax 得到每个专家对每个 token 的亲和度转置为(B, E, S)每个专家按capacity ceil(capacity_factor * S / E)选 top-K token专家分到的 token 数恒为B * capacity天然负载均衡门控权重按 token 被选中的总得分归一化再乘route_scale共享专家一个 SwiGLUFeedForward处理全部 token路由专家的加权输出通过scatter_add叠加到共享专家输出上——每个 token 至少得到一份共享处理被路由选中的 token 再额外获得专家修正。专家权重由SwiGLUExperts以打包形式存储第 362-498 行gate_up_proj形状(num_experts, hidden, 2*moe_intermediate_dim)融合 gate/up 两个投影运行时仅两次分组 matmul。两条执行路径for-loop 路径默认逐专家切片 matmulnum_tokens_per_expert.tolist()会引入一次 host-device 同步源码注释明确说明会形成 pipeline bubblegrouped-mm 路径use_grouped_mmTrue调用F.grouped_mm做融合分组 GEMM全程驻留设备、兼容torch.compile且要求输入恰好被排列permute成每专家连续块、无 padding。6.3 单流块结构与注意力NucleusMoEImageTransformerBlock第 607-723 行是单流 DiT 块只有图像流接受temb的自适应调制img_mod产出scale1, gate1, scale2, gate2gate 被clamp(-2, 2)后再tanh文本上下文经每块独立的encoder_projLinear(joint_attention_dim, dim)投影后仅作为交叉注意力的 K/V不作为 query。注意力处理器NucleusMoEAttnProcessor2_0第 259-345 行特点图像 query 对拼接后的 [img_key, txt_key]做联合注意力无文本 query支持GQAnum_key_value_heads num_attention_heads时对 KV 头repeat_interleave分组Q/K 可选 RMSNormqk_normrms_norm并施加NucleusMoEEmbedRope生成的旋转位置编码——图像侧按(frame, height, width)三维轴axes_dims_rope(16, 56, 56)构造文本侧频率从max_vid_index arange(text_len)处接续使文本 token 的相位紧接图像序列之后scale_ropeTrue时高度/宽度轴采用正负频率拼接的中心化布局支持attention_kwargs传入的cached_txt_key/cached_txt_value命中缓存时跳过add_k_proj/add_v_proj避免跨去噪步重复投影文本 K/V块内context_pre_only即据此置空。前向收尾AdaLayerNormContinuous归一化后经proj_out投影到patch_size * patch_size * out_channels。模块还混入了PeftAdapterMixin支持 LoRA、CacheMixin流水线中is_cache_enabled时循环前_reset_stateful_cache与FromOriginalModelMixin并支持梯度检查点。7. 输出类与回调输出包装类NucleusMoEImagePipelineOutput定义在 pipeline_output.py是继承BaseOutput的数据类仅含一个字段imageslist[PIL.Image.Image]或形状(batch, H, W, C)的np.ndarray。_callback_tensor_inputs [latents, prompt_embeds]声明了回调可安全触碰的张量配合callback_on_step_end可实现每步干预如实时预览、提前终止。8. 用仓库测试用例验证理解测试文件 tests/pipelines/nucleusmoe_image/test_nucleusmoe_image.py 用微型组件把上述机制都走了一遍值得对照阅读dummy 组件2 层 Transformermoe_enabledFalse、in_channels16、axes_dims_rope(8,4,4)、z_dim4的AutoencoderKLQwenImage、真实FlowMatchEulerDiscreteScheduler、8 层微型Qwen3VLForConditionalGeneration与Qwen3VLProcessor——完整复现了“文本栈需要同时保留text_encoder与processor”这一隔离测试约束dummy 输入guidance_scale1.0默认走无 CFG 路径、return_index-1、max_sequence_length16、output_typept验证输出形状(3, 32, 32)test_true_cfgguidance_scale4.0negative_promptlow quality覆盖第 4.3 节的条件/无条件双前向路径test_prompt_embeds先pipe.encode_prompt(...)再回传prompt_embeds/prompt_embeds_mask验证与直接传prompt等价TestNucleusMoEImagePipelineMemory基于MemoryTesterMixin验证 CPU offload、group offload 与逐层 casting依赖model_cpu_offload_seq声明的组件顺序。9. 小结与适用边界NucleusMoE-Image 流水线在 Diffusers 中的价值是展示了一条面向大规模 DiT 的现代装配范式Qwen3-VL 多模态编码器 chat 模板系统提示词 flow-matching Euler 调度 动态 shift 范数重标定 CFG 专家选择路由 MoE 分组 GEMM 加速路径且每个环节都留有可插拔入口sigmas定制调度、prompt_embeds预编码、attention_kwargs文本 KV 缓存、use_grouped_mm编译友好路径。使用时的适用前提需要安装transformersQwen3VLForConditionalGeneration等符号在其导入结构中为硬依赖缺失时模块退化为 dummy 对象见 pipelines/nucleusmoe_image/init.py、torch_dtypebfloat16与充足显存或 CPU offload、以及grouped_mm路径所需的 PyTorch 版本支持。若要进一步深入建议按本文引用的源码路径顺序阅读先 流水线实现再 Transformer 实现最后对照 测试配置 与 官方文档页。【免费下载链接】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），仅供参考 Diffusers 中 NucleusMoE-Image 文生图流水线：单流 DiT + MoE 专家层 + Qwen3-VL 文本编码的全链路解析
Diffusers 中 NucleusMoE-Image 文生图流水线单流 DiT MoE 专家层 Qwen3-VL 文本编码的全链路解析【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本篇指南基于 Diffusers 仓库中的 NucleusMoE-Image 官方文档页docs/source/en/api/pipelines/nucleusmoe_image.md与对应源码系统讲解NucleusMoEImagePipeline的组件构成、全部调用参数、去噪循环中动态 shift 与范数重标定 CFG 的实现细节以及底层NucleusMoEImageTransformer2DModel的专家选择路由expert-choice routing机制。读完后你将能够正确加载并调用该流水线生成图像、理解每个关键参数的作用与默认值、深入源码定位去噪与 MoE 前向的具体实现并利用仓库测试用例验证行为。1. 模型定位与组件构成NucleusMoE-Image 是一个文生图text-to-image模型其技术组合为单流 DiTDiffusion Transformer Mixture-of-Experts 前馈层 对 Qwen3-VL 文本编码器的交叉注意力 flow-matching Euler 离散调度器官方文档原文如此描述。在 Diffusers 中它对应一个标准的DiffusionPipeline子类由五个组件装配而成见 pipeline_nucleusmoe_image.py组件类型作用transformerNucleusMoEImageTransformer2DModel条件 Transformer负责去噪潜在表示schedulerFlowMatchEulerDiscreteSchedulerflow-matching Euler 离散调度器定义去噪步长vaeAutoencoderKLQwenImage在图像与潜在空间之间编解码text_encoderQwen3VLForConditionalGeneration计算提示词嵌入processorQwen3VLProcessor对文本输入做分词与 chat 模板格式化构造函数中还注册了几个贯穿全流程的默认值第 171-176 行vae_scale_factor由 VAE 的temperal_downsample层数决定2 ** len(...)通常为 8image_processor VaeImageProcessor(vae_scale_factor * 2)像素与 patch 网格之间换算的缩放系数为 16default_sample_size 128不传height/width时默认生成分辨率为128 × 8 1024像素的方形图像default_max_sequence_length 1024文本编码的默认最大 token 数default_return_index -8取 Qwen3-VL 倒数第 8 层隐状态作为提示词嵌入。另外流水线声明了model_cpu_offload_seq text_encoder-transformer-vae第 152 行即在启用 CPU offload 时三个大模块按 text_encoder → transformer → vae 的顺序依次换入换出 GPU 显存。2. 加载与基础调用官方文档给出的最小可运行示例与源码EXAMPLE_DOC_STRING一致见 第 43-55 行import torch from diffusers import NucleusMoEImagePipeline pipe NucleusMoEImagePipeline.from_pretrained(NucleusAI/NucleusMoE-Image, torch_dtypetorch.bfloat16) pipe.to(cuda) prompt A cat holding a sign that says hello world image pipe(prompt, num_inference_steps50).images[0] image.save(nucleus_moe.png)两个实用建议来自官方文档页的 TIP 提示框若需权衡采样速度与质量阅读调度器指南 docs/source/en/using-diffusers/schedulers.md若要在多条流水线间共享同一组件例如复用 VAE 或文本编码器参考 docs/source/en/using-diffusers/loading.md 中 “Reusing models in multiple pipelines” 一节。由于组件中包含完整的多模态大模型Qwen3VLForConditionalGeneration显存需求较高实践中通常配合torch_dtypetorch.bfloat16与设备转移/CPU offload 使用。3.__call__参数详解NucleusMoEImagePipeline.__call__的完整签名与默认值第 381-404 行逐参数说明如下参数默认值说明promptNone引导生成的提示词str或list[str]。若不传则必须传prompt_embeds二者互斥见check_inputsnegative_promptNone负向提示词当guidance_scale 1且未提供时自动用空字符串列表填充以启用 CFGguidance_scale4.0无分类器引导强度大于 1 才启用 CFGheight/widthNone输出图像像素尺寸为None时回落到default_sample_size * vae_scale_factor1024。check_inputs要求二者能被vae_scale_factor * 2整除否则打印告警并按实际取整num_inference_steps50去噪步数sigmasNone自定义噪声尺度调度为None时使用np.linspace(1.0, 1/num_inference_steps, num_inference_steps)线性调度num_images_per_prompt1每个提示词生成的图像数嵌入会按repeat_interleave复制max_sequence_lengthNone文本最大 token 数回落为default_max_sequence_length1024return_indexNone取文本编码器哪一层隐状态回落为-8其绝对值必须小于编码器层数否则check_inputs抛错generatorNonetorch.Generator或列表用于确定性采样若传列表其长度必须等于有效 batch sizelatentsNone预生成的初始噪声潜在张量提供时直接跳过randn_tensorprompt_embeds/prompt_embeds_maskNone预生成的文本嵌入及注意力掩码与prompt互斥negative_prompt_embeds/negative_prompt_embeds_maskNone负向提示词的预生成嵌入与negative_prompt互斥output_typepil输出格式可选pil、np或latent直接返回潜在张量return_dictTrueTrue时返回NucleusMoEImagePipelineOutputFalse时返回(image,)元组attention_kwargsNone透传给注意力处理器的字典内部会弹出可选的scaleLoRA 缩放并支持cached_txt_key/cached_txt_value缓存键callback_on_step_endNone每步结束时的回调函数callback_on_step_end_tensor_inputs[latents]回调可见的张量名必须是[latents, prompt_embeds]的子集否则抛错入参校验集中在check_inputs第 251-300 行分辨率整除性只告警不报错prompt/prompt_embeds必须且只能传其一return_index越界会直接ValueError。4. 去噪循环的四个关键机制4.1 动态 shift按分辨率自适应噪声调度流水线内嵌了一份从 Flux 复用的calculate_shift第 58-69 行标注Copied from diffusers.pipelines.flux.pipeline_flux.calculate_shift。它把图像 token 序列长度线性映射到 shift 参数mudef calculate_shift(image_seq_len, base_seq_len256, max_seq_len4096, base_shift0.5, max_shift1.15): m (max_shift - base_shift) / (max_seq_len - base_seq_len) b base_shift - m * base_seq_len return image_seq_len * m b在__call__中四个边界值均从调度器配置读取base_image_seq_len、max_image_seq_len、base_shift、max_shift有同名缺省值再连同线性sigmas一起交给retrieve_timesteps该函数同样复用自 Stable Diffusion 流水线支持timesteps或sigmas二选一定制二者同传会报错。这意味着分辨率越大token 越多mu越大去噪重心越向高噪声端偏移与 Flux 系列的实践一致。4.2 时间步缩放与 flow-matching 速度取负每一步中时间步先被缩放到训练尺度再送入 Transformertimestep t.expand(latents.shape[0]).to(latents.dtype) noise_pred self.transformer( hidden_stateslatents, timesteptimestep / self.scheduler.config.num_train_timesteps, ... )[0]拿到预测后执行noise_pred -noise_pred再交给scheduler.step。从源码结构看Transformer 输出的是与 velocity 方向相反的预测取负后与FlowMatchEulerDiscreteScheduler约定的更新方向对齐——这是 flow-matching 类流水线的典型约定。4.3 CFG 带范数重标定当guidance_scale 1时流水线做一次条件、一次无条件前向然后组合第 583-597 行comb_pred neg_noise_pred guidance_scale * (noise_pred - neg_noise_pred) cond_norm torch.norm(noise_pred, dim-1, keepdimTrue) noise_norm torch.norm(comb_pred, dim-1, keepdimTrue) noise_pred comb_pred * (cond_norm / noise_norm)与教科书式 CFG 相比这里多做了一步范数重标定norm rescaling把组合后的预测范数缩回条件预测的范数避免大引导系数放大更新步长导致色彩漂移或过饱和。4.4 潜在打包/解包与 VAE 反归一化图像以 patch 化 token 序列的形式进入 Transformer。prepare_latents先用randn_tensor生成(B, 1, C, H, W)的高斯噪声C transformer.config.in_channels // 4再经_pack_latents按patch_size重排为(B, H*W, C*p*p)的序列解码端_unpack_latents逆操作还原随后按 VAE 配置的latents_mean/latents_std做反归一化vae.decode(...)[0][:, :, 0]取第一帧VAE 为时间下采样结构图像生成只消费单帧最后由VaeImageProcessor.postprocess转成pil/np输出。循环内的latents_dtype判断专门处理 MPS 后端 dtype 漂移。5. 文本编码chat 模板、系统提示词与return_indexencode_prompt第 187-249 行是理解该流水线文本侧的关键chat 模板格式化_format_prompt把用户提示词包装成两角色消息——固定的DEFAULT_SYSTEM_PROMPT第 41 行You are an image generation assistant. Follow the users prompt literally. Pay careful attention to spatial layout: objects described as on the left must appear on the left, on the right on the right. Match exact object counts and assign colors to the correct objects.该提示词显式强调空间布局与数量/颜色一致性随后经processor.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue)渲染成最终字符串。分词参数paddinglongest、pad_to_multiple_of8、max_lengthmax_sequence_length、truncationTrue与encode_prompt文档串中的默认 1024 对应。取隐状态文本编码器以output_hidden_statesTrue前向取hidden_states[return_index]默认-8作为嵌入全 1 的注意力掩码会被置None以减少下游分支。批量扩展num_images_per_prompt 1时嵌入与掩码repeat_interleave复制。系统提示词是模型行为的一部分——它把“左侧物体放左边、数量精确”这类约束写进了上下文。若需改变风格化倾向可在推理侧研究_format_prompt对system_prompt的开放当前encode_prompt未暴露该入口属内部实现。6. 底层 Transformer单流 DiT 与专家选择路由NucleusMoEImageTransformer2DModel定义在 transformer_nucleusmoe_image.py默认配置第 775-796 行揭示了完整模型规模patch_size2、in_channels64、num_layers24、attention_head_dim128、num_attention_heads16inner_dim2048、joint_attention_dim3584对齐 Qwen3-VL 隐层维度、axes_dims_rope(16, 56, 56)、num_experts128、moe_intermediate_dim1344、capacity_factor8.0、route_scale2.5。6.1 哪些层启用 MoEdense_moe_strategy策略函数_is_moe_layer第 348-359 行支持五种取值策略MoE 层范围leave_first_three_and_last_block_dense默认3 idx num_layers - 1前 3 层与最后 1 层保持 denseleave_first_three_blocks_denseidx 3leave_first_block_denseidx 1all_moe全部层all_dense无6.2 专家选择路由 共享专家NucleusMoELayer第 501-604 行是 MoE 的核心采用专家选择expert-choice路由而非 token 选择且路由输入融合了时间步路由器输入为cat([timestep 展开, 未调制隐状态])即路由决策同时感知去噪步与内容use_additional_t_cond之外的第二处时间条件注入点gate nn.Linear(hidden_size * 2, num_experts, biasFalse)打分经 sigmoid可选或 softmax 得到每个专家对每个 token 的亲和度转置为(B, E, S)每个专家按capacity ceil(capacity_factor * S / E)选 top-K token专家分到的 token 数恒为B * capacity天然负载均衡门控权重按 token 被选中的总得分归一化再乘route_scale共享专家一个 SwiGLUFeedForward处理全部 token路由专家的加权输出通过scatter_add叠加到共享专家输出上——每个 token 至少得到一份共享处理被路由选中的 token 再额外获得专家修正。专家权重由SwiGLUExperts以打包形式存储第 362-498 行gate_up_proj形状(num_experts, hidden, 2*moe_intermediate_dim)融合 gate/up 两个投影运行时仅两次分组 matmul。两条执行路径for-loop 路径默认逐专家切片 matmulnum_tokens_per_expert.tolist()会引入一次 host-device 同步源码注释明确说明会形成 pipeline bubblegrouped-mm 路径use_grouped_mmTrue调用F.grouped_mm做融合分组 GEMM全程驻留设备、兼容torch.compile且要求输入恰好被排列permute成每专家连续块、无 padding。6.3 单流块结构与注意力NucleusMoEImageTransformerBlock第 607-723 行是单流 DiT 块只有图像流接受temb的自适应调制img_mod产出scale1, gate1, scale2, gate2gate 被clamp(-2, 2)后再tanh文本上下文经每块独立的encoder_projLinear(joint_attention_dim, dim)投影后仅作为交叉注意力的 K/V不作为 query。注意力处理器NucleusMoEAttnProcessor2_0第 259-345 行特点图像 query 对拼接后的 [img_key, txt_key]做联合注意力无文本 query支持GQAnum_key_value_heads num_attention_heads时对 KV 头repeat_interleave分组Q/K 可选 RMSNormqk_normrms_norm并施加NucleusMoEEmbedRope生成的旋转位置编码——图像侧按(frame, height, width)三维轴axes_dims_rope(16, 56, 56)构造文本侧频率从max_vid_index arange(text_len)处接续使文本 token 的相位紧接图像序列之后scale_ropeTrue时高度/宽度轴采用正负频率拼接的中心化布局支持attention_kwargs传入的cached_txt_key/cached_txt_value命中缓存时跳过add_k_proj/add_v_proj避免跨去噪步重复投影文本 K/V块内context_pre_only即据此置空。前向收尾AdaLayerNormContinuous归一化后经proj_out投影到patch_size * patch_size * out_channels。模块还混入了PeftAdapterMixin支持 LoRA、CacheMixin流水线中is_cache_enabled时循环前_reset_stateful_cache与FromOriginalModelMixin并支持梯度检查点。7. 输出类与回调输出包装类NucleusMoEImagePipelineOutput定义在 pipeline_output.py是继承BaseOutput的数据类仅含一个字段imageslist[PIL.Image.Image]或形状(batch, H, W, C)的np.ndarray。_callback_tensor_inputs [latents, prompt_embeds]声明了回调可安全触碰的张量配合callback_on_step_end可实现每步干预如实时预览、提前终止。8. 用仓库测试用例验证理解测试文件 tests/pipelines/nucleusmoe_image/test_nucleusmoe_image.py 用微型组件把上述机制都走了一遍值得对照阅读dummy 组件2 层 Transformermoe_enabledFalse、in_channels16、axes_dims_rope(8,4,4)、z_dim4的AutoencoderKLQwenImage、真实FlowMatchEulerDiscreteScheduler、8 层微型Qwen3VLForConditionalGeneration与Qwen3VLProcessor——完整复现了“文本栈需要同时保留text_encoder与processor”这一隔离测试约束dummy 输入guidance_scale1.0默认走无 CFG 路径、return_index-1、max_sequence_length16、output_typept验证输出形状(3, 32, 32)test_true_cfgguidance_scale4.0negative_promptlow quality覆盖第 4.3 节的条件/无条件双前向路径test_prompt_embeds先pipe.encode_prompt(...)再回传prompt_embeds/prompt_embeds_mask验证与直接传prompt等价TestNucleusMoEImagePipelineMemory基于MemoryTesterMixin验证 CPU offload、group offload 与逐层 casting依赖model_cpu_offload_seq声明的组件顺序。9. 小结与适用边界NucleusMoE-Image 流水线在 Diffusers 中的价值是展示了一条面向大规模 DiT 的现代装配范式Qwen3-VL 多模态编码器 chat 模板系统提示词 flow-matching Euler 调度 动态 shift 范数重标定 CFG 专家选择路由 MoE 分组 GEMM 加速路径且每个环节都留有可插拔入口sigmas定制调度、prompt_embeds预编码、attention_kwargs文本 KV 缓存、use_grouped_mm编译友好路径。使用时的适用前提需要安装transformersQwen3VLForConditionalGeneration等符号在其导入结构中为硬依赖缺失时模块退化为 dummy 对象见 pipelines/nucleusmoe_image/init.py、torch_dtypebfloat16与充足显存或 CPU offload、以及grouped_mm路径所需的 PyTorch 版本支持。若要进一步深入建议按本文引用的源码路径顺序阅读先 流水线实现再 Transformer 实现最后对照 测试配置 与 官方文档页。【免费下载链接】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），仅供参考