Diffusers 中的 Kandinsky 5.0 视频生成管线Kandinsky5T2VPipeline 与 Kandinsky5I2VPipeline 实战指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本文以docs/source/en/api/pipelines/kandinsky5_video.md为骨架系统讲解在 Hugging Face Diffusers 中使用 Kandinsky 5.0 系列模型进行文生视频T2V与图生视频I2V的完整流程。Kandinsky 5.0 是 Kandinsky Lab 推出的视频与图像扩散模型家族论文编号 arXiv:2511.14993官方文档将其划分为 Lite20 亿参数轻量级与 Pro190 亿参数高清高质量两条产品线。读完本文你将掌握不同变体SFT / no-CFG / 蒸馏 / 预训练模型的选择、T2V 与 I2V 管线的调用方式、10 秒长视频与蒸馏加速模型的正确推理姿势以及背后基于 Flow Matching DiT NABLA 稀疏注意力的源码级实现原理。Kandinsky 5.0 视频模型家族概览根据官方文档Kandinsky 5.0 提供两条视频生成产品线Kandinsky 5.0 Lite轻量级视频生成模型约 2B 参数官方文档称其在同类开源模型中排名第一在保持轻量的同时超越更大体量的模型并在开源生态中拥有最佳俄语概念理解能力。Kandinsky 5.0 Pro大型高质量视频生成模型约 19B 参数支持高清HD生成以及 I2V 等更多生成格式。官方文档归纳了模型引入的几项关键技术这些技术均可从仓库源码中得到印证技术说明仓库证据潜在扩散 Flow Matching在潜在空间做扩散去噪用流匹配提升训练稳定性管线使用FlowMatchEulerDiscreteScheduler完成去噪见 pipeline_kandinsky.pyDiffusion TransformerDiT主生成骨干网络通过交叉注意力注入文本嵌入Kandinsky5Transformer3DModel定义于 transformer_kandinsky.py双文本编码使用 Qwen2.5-VL 与 CLIP 联合编码提示词管线同时持有Qwen2_5_VLForConditionalGeneration与CLIPTextModel两个文本编码器HunyuanVideo 3D VAE高效的视频潜在空间编解码管线使用AutoencoderKLHunyuanVideo时间压缩比默认 4、空间压缩比默认 8NABLA 稀疏注意力稀疏注意力机制高效处理长序列fast_sta_nabla/get_sparse_params方法生成稀疏掩码见 pipeline_kandinsky.py可用模型清单与选型建议官方文档列出了 Hub 上kandinskylab组织发布的官方 Diffusers 格式检查点。文生视频T2V模型的完整清单如下Kandinsky 5.0 T2V Promodel_id说明适用场景kandinskylab/Kandinsky-5.0-T2V-Pro-sft-5s-Diffusers5 秒文生视频 Pro 模型高质量文生视频kandinskylab/Kandinsky-5.0-I2V-Pro-sft-5s-Diffusers5 秒图生视频 Pro 模型高质量图生视频Kandinsky 5.0 T2V Litemodel_id说明适用场景kandinskylab/Kandinsky-5.0-T2V-Lite-sft-5s-Diffusers5 秒监督微调SFT模型最高生成质量kandinskylab/Kandinsky-5.0-T2V-Lite-sft-10s-Diffusers10 秒监督微调模型最高生成质量kandinskylab/Kandinsky-5.0-T2V-Lite-nocfg-5s-Diffusers5 秒无分类器引导CFG蒸馏模型推理提速约 2 倍kandinskylab/Kandinsky-5.0-T2V-Lite-nocfg-10s-Diffusers10 秒无 CFG 蒸馏模型推理提速约 2 倍kandinskylab/Kandinsky-5.0-T2V-Lite-distilled16steps-5s-Diffusers5 秒扩散蒸馏至 16 步模型推理提速约 6 倍、质量损失极小kandinskylab/Kandinsky-5.0-T2V-Lite-distilled16steps-10s-Diffusers10 秒扩散蒸馏至 16 步模型推理提速约 6 倍、质量损失极小kandinskylab/Kandinsky-5.0-T2V-Lite-pretrain-5s-Diffusers5 秒基础预训练模型研究与微调kandinskylab/Kandinsky-5.0-T2V-Lite-pretrain-10s-Diffusers10 秒基础预训练模型研究与微调选型要点追求开箱即用的最高质量选sft系列推理速度敏感、可接受少量质量折损选nocfg无 CFG约 2 倍提速或distilled16steps蒸馏至 16 步约 6 倍提速系列做二次开发、继续预训练或微调选pretrain系列视频时长需求5 秒 vs 10 秒直接决定选择5s还是10s变体。环境准备与管线加载Kandinsky 5.0 管线依赖 PyTorch、transformers 与 diffusers 本体。加载管线只需一行import torch from diffusers import Kandinsky5T2VPipeline model_id kandinskylab/Kandinsky-5.0-T2V-Lite-sft-5s-Diffusers pipe Kandinsky5T2VPipeline.from_pretrained(model_id, dtypetorch.bfloat16) pipe pipe.to(cuda) # 也可用 mps、xpu、cpu其中dtypetorch.bfloat16以 bfloat16 精度加载权重以节省显存仓库 docstring 示例中对应写法为torch_dtypetorch.bfloat16两者含义一致。从源码看Kandinsky5T2VPipeline继承自DiffusionPipeline与KandinskyLoraLoaderMixin支持 LoRA 权重加载构造时注册了 7 个核心组件transformerKandinsky5Transformer3DModel负责去噪的视频 DiTvaeAutoencoderKLHunyuanVideo视频潜在空间编解码器text_encodertokenizerQwen2.5-VL 文本编码器及其处理器text_encoder_2tokenizer_2CLIPclip-vit-large-patch14 变体文本编码器及其分词器schedulerFlowMatchEulerDiscreteScheduler。文生视频T2V基础用法Pro 模型官方文档特别提示所有 Pro 模型都必须配合pipeline.enable_model_cpu_offload()使用否则 19B 参数规模难以装入单卡显存。完整示例import torch from diffusers import Kandinsky5T2VPipeline from diffusers.utils import export_to_video # 加载 Pro 管线官方建议配合 CPU offload 使用 model_id kandinskylab/Kandinsky-5.0-T2V-Pro-sft-5s-Diffusers pipe Kandinsky5T2VPipeline.from_pretrained(model_id, dtypetorch.bfloat16) pipe pipe.to(cuda) # 或 mps、xpu、cpu pipe.transformer.set_attention_backend(flex) # 设置注意力后端为 Flex pipe.enable_model_cpu_offload() # 单卡推理启用 CPU offload pipe.transformer.compile(modemax-autotune-no-cudagraphs, dynamicTrue) # 使用 max-autotune-no-cudagraphs 编译 # 生成视频 prompt A cat and a dog baking a cake together in a kitchen. negative_prompt Static, 2D cartoon, cartoon, 2d animation, paintings, images, worst quality, low quality, ugly, deformed, walking backwards output pipe( promptprompt, negative_promptnegative_prompt, height768, width1024, num_frames121, # 24fps 下约 5 秒 num_inference_steps50, guidance_scale5.0, ).frames[0] export_to_video(output, output.mp4, fps24, quality9)注意原文档该示例中pipeline.transformer与pipeline.enable_model_cpu_offload()实为pipe的笔误本文已修正为pipe请以变量名保持一致。Lite 模型Lite 模型参数更小无需强制 CPU offloadimport torch from diffusers import Kandinsky5T2VPipeline from diffusers.utils import export_to_video # 加载 Lite 管线 model_id kandinskylab/Kandinsky-5.0-T2V-Lite-sft-5s-Diffusers pipe Kandinsky5T2VPipeline.from_pretrained(model_id, dtypetorch.bfloat16) pipe pipe.to(cuda) # 或 mps、xpu、cpu # 生成视频 prompt A cat and a dog baking a cake together in a kitchen. negative_prompt Static, 2D cartoon, cartoon, 2d animation, paintings, images, worst quality, low quality, ugly, deformed, walking backwards output pipe( promptprompt, negative_promptnegative_prompt, height512, width768, num_frames121, # 24fps 下约 5 秒 num_inference_steps50, guidance_scale5.0, ).frames[0] export_to_video(output, output.mp4, fps24, quality9)图生视频I2V基础用法I2V 使用Kandinsky5I2VPipeline定义于 pipeline_kandinsky_i2v.py与 T2V 管线共享相同的组件结构与双文本编码逻辑差异在于额外接收一张image作为视觉条件输入。同样Pro 模型必须使用enable_model_cpu_offload()import torch from diffusers import Kandinsky5I2VPipeline from diffusers.utils import export_to_video, load_image # 加载 I2V Pro 管线 model_id kandinskylab/Kandinsky-5.0-I2V-Pro-sft-5s-Diffusers pipe Kandinsky5I2VPipeline.from_pretrained(model_id, dtypetorch.bfloat16) pipe pipe.to(cuda) # 或 mps、xpu、cpu pipe.transformer.set_attention_backend(flex) # 设置注意力后端为 Flex pipe.enable_model_cpu_offload() # 单卡推理启用 CPU offload pipe.transformer.compile(modemax-autotune-no-cudagraphs, dynamicTrue) # 使用 max-autotune-no-cudagraphs 编译 # 准备输入图片替换为你本地的图片路径即可 image load_image(path/to/your/image.jpg) height 896 width 896 image image.resize((width, height)) prompt An funny furry creture smiles happily and holds a sign that says Kandinsky negative_prompt output pipe( imageimage, promptprompt, negative_promptnegative_prompt, heightheight, widthwidth, num_frames121, # 24fps 下约 5 秒 num_inference_steps50, guidance_scale5.0, ).frames[0] export_to_video(output, output.mp4, fps24, quality9)原文档示例使用在线图片 URL 加载为遵循本地仓库环境这里示意为本地图片路径你也可以使用任意PIL.Image对象。从源码看I2V 的视觉条件注入发生在潜在空间prepare_latents中当self.transformer.visual_cond为真时会把随机噪声与零向量视觉条件、视觉条件掩码在最后一维拼接torch.cat([latents, visual_cond, visual_cond_mask], dim-1)T2V 与 I2V 因此可以共用同一套 Transformer 前向逻辑。10 秒长视频模型的推理姿势官方文档强调所有 10 秒模型都应配合 Flex 注意力与max-autotune-no-cudagraphs编译使用。10 秒 24fps 对应约 241 帧序列长度翻倍对注意力的时间与显存开销压力显著增大因此需要这两项优化pipe Kandinsky5T2VPipeline.from_pretrained( kandinskylab/Kandinsky-5.0-T2V-Lite-sft-10s-Diffusers, dtypetorch.bfloat16, ) pipe pipe.to(cuda) # 或 mps、xpu、cpu pipe.transformer.set_attention_backend(flex) # 设置注意力后端为 Flex pipe.transformer.compile( modemax-autotune-no-cudagraphs, dynamicTrue, ) # 使用 max-autotune-no-cudagraphs 编译 prompt A cat and a dog baking a cake together in a kitchen. negative_prompt Static, 2D cartoon, cartoon, 2d animation, paintings, images, worst quality, low quality, ugly, deformed, walking backwards output pipe( promptprompt, negative_promptnegative_prompt, height512, width768, num_frames241, # 24fps 下约 10 秒 num_inference_steps50, guidance_scale5.0, ).frames[0] export_to_video(output, output.mp4, fps24, quality9)关于帧数源码中有两条硬性约束值得留意num_frames - 1必须能被 VAE 时间压缩比整除HunyuanVideo VAE 默认为 4否则管线会取整到最近的合法值并打印 warning相关逻辑见 pipeline_kandinsky.py。因此 121、241 这类4k1帧数是推荐写法height与width必须能被 16 整除否则直接抛出ValueError见check_inputs。扩散蒸馏模型16 步与无 CFG 模型官方文档特别提示所有 nocfg 与扩散蒸馏模型都必须以无 CFG 方式推理即guidance_scale1.0。这类模型在训练阶段已蒸馏掉了 CFG 分支如果继续使用大于 1 的引导尺度反而会破坏生成质量model_id kandinskylab/Kandinsky-5.0-T2V-Lite-distilled16steps-5s-Diffusers pipe Kandinsky5T2VPipeline.from_pretrained(model_id, dtypetorch.bfloat16) pipe pipe.to(cuda) # 或 mps、xpu、cpu output pipe( promptA beautiful sunset over mountains, num_inference_steps16, # 模型蒸馏为 16 步无需 50 步 guidance_scale1.0, # 无 CFG ).frames[0] export_to_video(output, output.mp4, fps24, quality9)从源码 pipeline_kandinsky.py 可以确认 CFG 的触发逻辑只有当guidance_scale 1.0时管线才会编码 negative prompt 并执行条件/无条件双分支去噪当guidance_scale 1.0时直接跳过无条件分支。这也是 no-CFG 蒸馏模型能获得约 2 倍、16 步蒸馏模型约 6 倍提速的根本原因——每次去噪迭代只需一次 Transformer 前向。核心调用参数详解以下参数完整继承自Kandinsky5T2VPipeline.__call__的签名pipeline_kandinsky.py与Kandinsky5I2VPipeline完全一致I2V 额外多一个image参数参数默认值说明prompt无生成引导提示词str或list[str]negative_prompt无负向提示词仅当guidance_scale 1.0时生效。未提供时源码会自动填入默认负向提示词Static, 2D cartoon, cartoon, 2d animation, paintings, images, worst quality, low quality, ugly, deformed, walking backwardsheight/width512 / 768视频像素尺寸必须能被 16 整除num_frames121视频帧数要求num_frames - 1能被 4VAE 时间压缩比整除num_inference_steps50去噪步数蒸馏模型为 16guidance_scale5.0CFG 引导尺度no-CFG/蒸馏模型必须设为 1.0num_videos_per_prompt1每个提示词生成的视频数量generator无torch.Generator用于复现随机结果latents无预生成的噪声潜在变量可做视频续接/风格控制prompt_embeds_qwen/prompt_embeds_clip/prompt_cu_seqlens无预计算的 Qwen/CLIP 文本嵌入与累计序列长度三者必须同时提供check_inputs强制校验适合批量复用编码结果negative_prompt_embeds_*无负向文本嵌入及其cu_seqlens规则同上output_typepil输出格式设为latent可跳过 VAE 解码直接返回潜在变量return_dictTrue为True返回KandinskyPipelineOutput否则返回 tuplecallback_on_step_end无每步去噪结束后的回调函数支持PipelineCallback/MultiPipelineCallbackscallback_on_step_end_tensor_inputs[latents]传给回调的张量列表可包含prompt_embeds_qwen、prompt_embeds_clip等见_callback_tensor_inputsmax_sequence_length512Qwen 文本编码最大序列长度必须小于 1024注意prompt_cu_seqlens这类“累计序列长度”参数服务于 Qwen 文本嵌入的变长注意力由于 Qwen 编码的序列长度随提示词变化管线用cu_seqlenscumulative sequence lengths把不同长度的嵌入拼接后一次性送入 Transformer配合text_rope_pos计算文本侧 RoPE 位置编码属于高性能实现细节。源码级原理一次完整的前向链路综合 pipeline_kandinsky.py 的实现Kandinsky5T2VPipeline的__call__按以下 11 步执行输入校验check_inputs校验max_sequence_length 1024、height/width被 16 整除、嵌入参数成组出现等帧数规整把num_frames规整到4k1形式批次解析把prompt统一为 list 并推导batch_size提示词编码encode_prompt先经prompt_cleanftfy 修复 HTML 反转义 空白归一清洗文本再用内置的 prompt 模板包装模板以 You are a promt engineer. Describe the video in detail. 开头要求模型描述镜头运动、构图、主体动作、视觉风格等模板编码起点为第 129 个 token随后分别经 Qwen2.5-VL 与 CLIP 编码得到prompt_embeds_qwen、prompt_embeds_clip与cu_seqlens时间步准备scheduler.set_timesteps(num_inference_steps)潜在变量准备prepare_latents按 VAE 时空压缩比计算潜在张量形状(B, T, H/8, W/8, C)采样高斯噪声若visual_cond为真I2V拼接视觉条件与掩码RoPE 位置准备按潜在帧数、H/2、W/2 构造visual_rope_pos按文本序列长度构造text_rope_pos动态尺度因子_get_scale_factor分辨率在 480p854p 区间返回(1, 2, 2)否则返回(1, 3.16, 3.16)稀疏注意力参数get_sparse_params当 Transformer 配置attention_type nabla时调用fast_sta_nabla生成窗口大小为wT/wH/wW的时空稀疏掩码默认窗口 3×3×3把注意力限制在邻近帧与邻近空间位置显著降低长视频的计算量去噪循环每步用 Transformer 预测速度场pred_velocityFlow Matching 范式若guidance_scale 1.0再算无条件分支并执行 CFG 插值uncond g * (cond - uncond)最后scheduler.step更新潜在变量支持 XLA 场景下的xm.mark_step()后处理与解码截取主通道潜在变量按(B, C, T, H/8, W/8)重塑并除以vae.config.scaling_factor归一化经 HunyuanVideo 3D VAE 解码再由VideoProcessor.postprocess_video输出为 PIL 帧序列最终封装为KandinskyPipelineOutput(framesvideo)——这也是output.frames[0]取法的由来。整个去噪过程对应的端到端行为由仓库测试覆盖见 tests/pipelines/kandinsky5/test_kandinsky5.py 与 tests/pipelines/kandinsky5/test_kandinsky5_i2v.py读者可据此验证管线与真实检查点的兼容性。内存与性能优化建议综合官方文档的警告与源码实现针对不同硬件条件给出如下建议Pro 模型19B必须调用pipe.enable_model_cpu_offload()。源码中model_cpu_offload_seq text_encoder-text_encoder_2-transformer-vae规定了卸载顺序——两个文本编码器最先被卸载接着是占显存最大的 Transformer最后是 VAE从而把单次驻留显存压到单个模块的规模10 秒模型务必设置 Flex 注意力后端pipe.transformer.set_attention_backend(flex)并用pipe.transformer.compile(modemax-autotune-no-cudagraphs, dynamicTrue)编译以缓解翻倍的帧序列带来的注意力开销nocfg / distilled 模型坚持guidance_scale1.0跳过无条件分支实现 26 倍提速LoRA 微调管线继承KandinskyLoraLoaderMixin可直接使用load_lora_weights加载 LoRA 权重低显存环境可选用 Lite 系列、降低height/width如 512×768、减少num_frames或使用output_typelatent延迟解码。Pipeline API 速览本文涉及的两种管线均已在 diffusers 顶层导出API 文档由 autodoc 自动生成Kandinsky5T2VPipeline文生视频管线核心方法为__call__另含encode_prompt、prepare_latents等内部方法Kandinsky5I2VPipeline图生视频管线在 T2V 基础上增加image输入视觉条件。两者共享的输出类型为KandinskyPipelineOutput定义于 pipeline_output.pyframes属性保存生成的视频帧列表。引用Kandinsky 5.0 的官方 BibTeX 引用信息出自原文档已省略外部链接字段misc{kandinsky2025, author {Alexander Belykh and Alexander Varlamov and Alexey Letunovskiy and others}, title {Kandinsky 5.0: A family of diffusion models for Video Image generation}, year 2025 }官方文档还提供了 Pro / Lite / 蒸馏模型的 Side-by-Side 对比评估如与 Veo 3、Wan 2.2、Sora 等模型的对比以及 Lite 5s 与蒸馏 5s 的质量对比Lite 评估基于 Movie Gen benchmark 的扩展提示词进行。这些对比图以外部资源形式存在于原文档中仓库内无对应本地图片读者可参考论文与官方仓库了解详细评测结论。【免费下载链接】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），仅供参考