Diffusers 中 LongCat-Image 文生图管线实战：中文渲染、提示词改写与编辑能力全解析

Diffusers 中 LongCat-Image 文生图管线实战中文渲染、提示词改写与编辑能力全解析【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读LongCat-Image 是一个由美团 LongCat 团队提出的开源、中英双语图像生成基础模型其核心亮点在于以仅 6B 参数量的规模在中文文字渲染、逼真度与部署效率之间取得平衡并配套了面向指令编辑的 LongCat-Image-Edit 模型。本文以 LongCat-Image 官方 API 文档 为主体结合本仓库中 LongCatImagePipeline 源码、LongCatImageEditPipeline 源码 与对应模型实现系统讲解如何在 Diffusers 中加载该模型、理解其独有的提示词改写Prompt Rewrite与 CFG Renorm 机制、掌握文生图与图像编辑两条调用路径以及底层 Transformer 与调度器的实现原理。LongCat-Image 是什么定位与核心特性根据 LongCat-Image 官方文档LongCat-Image 是一个开源、中英双语Chinese-English的图像生成基础模型设计初衷是应对当前主流模型在多语言文字渲染、照片级真实感、部署效率与开发者可及性等方面的核心挑战。其特性可以归纳为五点卓越的效率与性能仅约 6B 参数即在多个基准上超越参数量数倍于自身的开源模型体现高效模型设计的潜力领先的编辑能力LongCat-Image-Edit 在开源模型中达到领先水平指令遵循与图像质量出色且与原始图像保持高度视觉一致性强大的中文文字渲染在常见汉字渲染的准确性与稳定性上优于现有开源 SOTA 模型对中文字典的覆盖达到行业领先水平出色的照片级真实感通过创新的数据策略与训练框架实现完整的开源生态提供从中间 checkpoint 到完整训练代码的一整套工具链降低研究与二次开发门槛。该模型的完整技术细节可参考 LongCat-Image 技术报告arXiv:2412.11963。在本文仓库中与之对应的实现分散在三处管线代码位于 src/diffusers/pipelines/longcat_image/核心扩散 Transformer 位于 src/diffusers/models/transformers/transformer_longcat_image.py模型级测试位于 tests/models/transformers/test_models_transformer_longcat_image.py。可用模型一览模型类型说明LongCat-ImageText-to-Image最终发布版开箱即用推理的标准模型LongCat-Image-DevText-to-Image开发版中期训练 checkpoint适合用于微调LongCat-Image-EditImage Editing面向图像编辑的专用模型三个模型在 Diffusers 中均可通过from_pretrained加载管线入口分别是LongCatImagePipeline与LongCatImageEditPipeline。快速上手文生图示例官方文档给出了一段可直接运行的最小示例见 文档「Usage Example」。下面结合源码对每一步进行解读import torch import diffusers from diffusers import LongCatImagePipeline weight_dtype torch.bfloat16 pipe LongCatImagePipeline.from_pretrained(meituan-longcat/LongCat-Image, dtypetorch.bfloat16) pipe.to(cuda) # or mps, xpu, cpu # pipe.enable_model_cpu_offload() prompt 一个年轻的亚裔女性身穿黄色针织衫搭配白色项链。她的双手放在膝盖上表情恬静。背景是一堵粗糙的砖墙午后的阳光温暖地洒在她身上营造出一种宁静而温馨的氛围。镜头采用中距离视角突出她的神态和服饰的细节。光线柔和地打在她的脸上强调她的五官和饰品的质感增加画面的层次感与亲和力。整个画面构图简洁砖墙的纹理与阳光的光影效果相得益彰突显出人物的优雅与从容。 image pipe( prompt, height768, width1344, guidance_scale4.0, num_inference_steps50, num_images_per_prompt1, generatortorch.Generator(cpu).manual_seed(43), enable_cfg_renormTrue, enable_prompt_rewriteTrue, ).images[0] image.save(f./longcat_image_t2i_example.png)几个要点说明精度与设备示例使用torch.bfloat16加载权重以降低显存占用pipe.to(cuda)支持cuda、mps、xpu、cpu等设备。显存紧张时可改用注释掉的pipe.enable_model_cpu_offload()其内部依赖源码中声明的model_cpu_offload_seq text_encoder-transformer-vae见 pipeline_longcat_image.py即按文本编码器 → 扩散 Transformer → VAE 的顺序做 CPU 卸载。中英文提示词均可管线内部会通过正则[\u4e00-\u9fff]自动判断提示词语言get_prompt_language中文输入走中文改写模板英文输入走英文改写模板。输出pipe(...)返回LongCatImagePipelineOutput其images字段是list[PIL.Image.Image]或np.ndarray列表取[0]即得到首张图像。__call__核心参数速查结合 pipeline_longcat_image.py 的__call__签名与文档字符串将常用参数整理如下参数默认值说明promptNone生成提示词str或list[str]与prompt_embeds二选一negative_promptNone负向提示词仅在启用 CFG 时生效不传则内部使用空字符串height/widthNone输出图像尺寸像素不传时默认128 × vae_scale_factornum_inference_steps50去噪步数sigmasNone自定义去噪 sigma 序列不传则使用np.linspace(1.0, 1.0/num_inference_steps, num_inference_steps)guidance_scale4.5无分类器引导CFG强度大于 1 时启用 CFGnum_images_per_prompt1每个提示词生成的图像数量generatorNonetorch.Generator或列表用于可复现生成latentsNone预生成的噪声潜变量可跳过随机初始化prompt_embedsNone预计算文本嵌入跳过内部编码output_typepil输出格式可为pil或latentreturn_dictTrue为False时返回裸tupleenable_cfg_renormTrue是否启用 CFG 重归一化可提升图像质量cfg_renorm_min0.0renorm 缩放范围最小值0~11.0相当于禁用 renorm0.0使范围最宽enable_prompt_rewriteTrue是否启用提示词自动改写架构拆解五个组件如何协作LongCatImagePipeline.__init__见 pipeline_longcat_image.py注册了五个核心模块这一组合决定了 LongCat-Image 的架构形态组件类型作用text_encoderQwen2_5_VLForConditionalGeneration多模态文本编码器负责把提示词编码为prompt_embeds同时承担提示词改写推理tokenizerQwen2Tokenizer对提示词与模板做分词text_processorQwen2VLProcessor组装聊天模板chat template供提示词改写时构造输入transformerLongCatImageTransformer2DModel核心扩散主干接受文本/图像序列做联合注意力去噪vaeAutoencoderKL在像素空间与 16 通道潜空间之间编解码schedulerFlowMatchEulerDiscreteSchedulerFlow Matching 离散 Euler 调度器执行x_t → x_{t-1}去噪步源码中还设置了几个关键内部参数default_sample_size 128默认潜变量采样尺寸乘以 VAE 缩放因子后得到默认输出分辨率、tokenizer_max_length 512提示词最大 token 数超出即截断并告警、vae_scale_factor 2 ** (len(block_out_channels) - 1)通常为 8即 VAE 对图像做 8 倍压缩。3D 位置编码文本与图像统一坐标LongCat-Image 的 Transformer 不使用传统一维位置嵌入而是通过 prepare_pos_ids 构造3 维位置 id每个 token 携带(modality_id, pos_h, pos_w)。文本 token 使用modality_id0图像 token 使用modality_id1编辑管线中还有modality_id2表示参考图像。文本与图像位置起始偏移均从tokenizer_max_length512开始配合模型内部的LongCatImagePosEmbed基于theta10000的三维 RoPE见 transformer_longcat_image.py让单一阵列中不同模态各自拥有独立、可区分的坐标系统。潜变量打包16 通道与 2×2 拼接与 SDXL/FLUX 等模型一致LongCat-Image 采用潜变量打包latent packing_pack_latents将(B, 16, H, W)的潜变量重排为(B, (H/2)×(W/2), 64)的 token 序列_unpack_latents则执行逆操作见 pipeline_longcat_image.py。因此生成时要求height/width能被vae_scale_factor * 2即 16整除源码中的check_inputs会对此发出告警并自动调整。时间步调度基于图像序列长度的 mu 偏移管线通过 calculate_shift 依据打包后的图像序列长度image_seq_len线性插值计算调度器偏移量mu默认base_seq_len256、max_seq_len4096、base_shift0.5、max_shift1.15均可从 scheduler config 覆盖。随后通过retrieve_timesteps从 Stable Diffusion 管线复制而来把自定义sigmas与mu一并传给FlowMatchEulerDiscreteScheduler.set_timesteps得到最终的 timestep 序列。两大特色机制提示词改写与 CFG Renorm提示词改写Prompt RewriteLongCat-Image 认为文生图模型对用户提示词的理解能力有限因此在推理前端内置了一个专家改写步骤rewire_prompt见 pipeline_longcat_image.py根据提示词语言中文/英文选用 system_messages.py 中定义的SYSTEM_PROMPT_ZH或SYSTEM_PROMPT_EN构造用户输入为...\n改写后的prompt为这样的提问模板用text_processor.apply_chat_template组装对话并交给Qwen2.5-VL文本编码器做generatemax_new_tokens512对生成结果做batch_decode把改写后的提示词作为后续编码的输入。改写模板本身是 Few-Shot 的内含 7 组中英文示例约束包括保留原始信息不删改、输入输出语言一致、未指定风格时默认真实摄影风格、需要生成文字时用双引号圈定如限时5折、移除否定词、禁止擅自添加文字内容等。这正是 LongCat-Image 在中文文字海报、标语渲染上表现出色的关键设计先让语言模型把要写什么字显式化再交给扩散模型渲染。此外_encode_prompt中的split_quotationpipeline_longcat_image.py会把提示词按单双引号含中文弯引号拆分为普通文本与引号内文本两段分别分词后再拼接从而保证引号内的文字内容被完整、独立地编码避免与其他描述混淆。CFG Renorm当guidance_scale 1时启用无分类器引导去噪循环会对同一潜变量分别执行条件cache_context(cond)与无条件cache_context(uncond)前向然后按noise_pred noise_pred_uncond guidance_scale * (noise_pred_text - noise_pred_uncond)合并。若enable_cfg_renormTrue管线还会额外做一步归一化见 pipeline_longcat_image.pycond_norm torch.norm(noise_pred_text, dim-1, keepdimTrue) noise_norm torch.norm(noise_pred, dim-1, keepdimTrue) scale (cond_norm / (noise_norm 1e-8)).clamp(mincfg_renorm_min, max1.0) noise_pred noise_pred * scale即按条件预测的范数对融合后的噪声预测做逐位置缩放并将缩放系数限制在[cfg_renorm_min, 1.0]区间内。官方文档说明开启 renorm 能提升图像质量但可能降低部分输出的稳定性cfg_renorm_min1.0相当于关闭 renormcfg_renorm_min0.0则让调整范围最宽。图像编辑LongCatImageEditPipeline与文生图共用同一套 Transformer 与调度器的LongCatImageEditPipelinepipeline_longcat_image_edit.py面向指令式编辑官方示例from PIL import Image import torch from diffusers import LongCatImageEditPipeline pipe LongCatImageEditPipeline.from_pretrained( meituan-longcat/LongCat-Image-Edit, torch_dtypetorch.bfloat16 ) pipe.to(cuda) prompt change the cat to dog. input_image Image.open(test.jpg).convert(RGB) image pipe( input_image, prompt, num_inference_steps50, guidance_scale4.5, generatortorch.Generator(cpu).manual_seed(43), ).images[0] image.save(longcat_image_edit.png)编辑管线与文生图管线的主要差异多模态输入_encode_prompt通过text_processor.image_processor对输入图像做预处理pixel_values与image_grid_thw把|image_pad|占位符按视觉 token 数量展开后拼入系统模板再一并送入 Qwen2.5-VL 编码使模型看见原图参考图像潜变量prepare_latents会用 VAE 以argmax模式编码输入图像得到image_latents位置 id 的modality_id2去噪时与待生成的latents在序列维拼接torch.cat([latents, image_latents], dim1)预测结果再截取回image_seq_len自动尺寸适配calculate_dimensions依据输入图像宽高比把总像素面积约束在约 1024×1024 并向上取整到 16 的倍数无提示词改写编辑管线__call__不包含enable_prompt_rewrite/enable_cfg_renorm参数指令由用户直接给定。底层模型LongCatImageTransformer2DModel作为扩散主干LongCatImageTransformer2DModel 采用类 MMDiT 的双流结构transformer_blocks默认 19 层同时处理文本与图像分支的联合注意力single_transformer_blocks默认 38 层单流块完整参数如下默认值取自register_to_config配置项默认值说明patch_size1潜变量 patch 尺寸in_channels64打包后潜变量通道数16 × 4num_layers19双流 Transformer 块数num_single_layers38单流 Transformer 块数attention_head_dim128每头维度num_attention_heads24注意力头数inner_dim 24 × 128 3072joint_attention_dim3584文本嵌入映射维度context_embedderpooled_projection_dim3584池化投影维度axes_dims_rope[16, 56, 56]3D RoPE 各轴维度注意力实现LongCatImageAttnProcessor依赖F.scaled_dot_product_attention要求 PyTorch 2.0支持文本/图像联合注意力encoder_query/encoder_key/encoder_value与视觉分支拼接后再做 RoPE 与注意力计算并通过dispatch_attention_fn支持后端分发。模型声明支持梯度检查点_supports_gradient_checkpointing True对应测试 test_models_transformer_longcat_image.py 中专门断言了LongCatImageTransformer2DModel的梯度检查点会被正确应用。调用链与可复现性提示文生图的完整调用链可概括为__call__ ├─ check_inputs尺寸/参数合法性 ├─ rewire_prompt可选Qwen2.5-VL 改写提示词 ├─ encode_prompt分词 模板拼接 hidden_states 提取 3D text_ids ├─ prepare_latents随机噪声 2×2 打包 3D img_ids ├─ 调度器 set_timestepssigmas mu 偏移 └─ 去噪循环cond/uncond 双前向 → CFG → renorm → scheduler.step └─ VAE decode postprocess → LongCatImagePipelineOutput实际使用中几点建议想要可复现输出时务必传入固定种子的torch.Generator希望节省显存时开启enable_model_cpu_offload()或改用torch.bfloat16需要深度控制采样过程时可通过latents、prompt_embeds、sigmas等高级参数接管管线内部步骤negative_prompt仅在guidance_scale 1时生效。若想验证模型前向逻辑可参考 test_models_transformer_longcat_image.py 中的测试配置小尺寸num_layers1、num_attention_heads2等进行轻量复现。小结LongCat-Image 在 Diffusers 中的落地体现了小模型 强工程的思路6B 规模的双流 Transformer 配合 Flow Matching Euler 调度器完成高效去噪Qwen2.5-VL 编码器同时承担提示词编码与改写推理配合引号分词策略解决多语言文字渲染难题CFG Renorm 与基于图像序列长度的 mu 偏移则为输出质量与稳定性提供精细控制而 LongCat-Image-Edit 通过多模态编码与参考潜变量拼接在统一的架构上实现了指令式图像编辑。无论是文生图、中文海报文字生成还是图像编辑都可以直接基于LongCatImagePipeline/LongCatImageEditPipeline两条管线快速落地。【免费下载链接】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），仅供参考