# Kandinsky S2V 1.0

Kandinsky S2V 1.0 根据参考帧和语音轨道生成头像视频。帧中的人物会随语音进行动画处理——动画覆盖整个身体，而不仅仅是头部。语音是条件输入，而非输出：模型不生成音频，最终结果的音轨即为您传入的轨道。

两种条件均通过 [Qwen2.5-Omni-7B](https://huggingface.co/Qwen/Qwen2.5-Omni-7B) 处理：其隐藏状态编码提示词，其音频塔编码语音，语音通过逐帧对齐的交叉注意力适配器进入 Transformer，因此每个潜在帧仅关注其覆盖的语音。片段以 5 秒（25 fps 下为 125 帧）为单位生成，每个片段携带前序片段的 FramePack 记忆，从而确保较长的音轨在片段边界处保持一致性。

Kandinsky S2V 1.0 仅以[模块化流水线](../../modular_diffusers/overview)的形式集成；它没有标准的`DiffusionPipeline`类。

## 检查点

| 检查点 | Transformer | 块 | 调度器 | 步骤 | 指导 |
|---|---|---|---|---|---|
| [Lite][lite] | 2B | [KandinskyS2VAutoBlocks](/docs/diffusers/v0.43.0/zh/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Pro][pro] | 21B | [KandinskyS2VAutoBlocks](/docs/diffusers/v0.43.0/zh/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Lite 蒸馏][lite-distill] | 2B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/v0.43.0/zh/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/piflow#diffusers.PiflowScheduler) | 16 | off |
| [Pro 蒸馏][pro-distill] | 21B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/v0.43.0/zh/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/piflow#diffusers.PiflowScheduler) | 16 | off |

蒸馏检查点将 `PiflowScheduler` 配置为 `shift=10.0` 和 `n_grid=5`，而非其默认值。

[lite]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Lite-Diffusers [pro]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Pro-Diffusers [lite-distill]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Lite-distill-Diffusers [pro-distill]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Pro-distill-Diffusers

`ModularPipeline.from_pretrained` 会从检查点中选取各个模块。各步骤的默认值如上所述。Classifier-free guidance 是 `guider` 组件，而非调用参数：基础检查点中该值默认为 3.0。蒸馏后的检查点不包含 guider，也没有 `negative_prompt`，因为 guidance 已经内化到学生模型中。

## 用法

```py
import librosa
import torch
from diffusers import ModularPipeline
from diffusers.utils import encode_video, load_image

pipe = ModularPipeline.from_pretrained("kandinskylab/Kandinsky-S2V-1.0-Lite-distill-Diffusers")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = load_image("reference.png")
audio, _ = librosa.load("speech.wav", sr=16000)  # a mono waveform at 16 kHz, for the model
speech, sample_rate = librosa.load("speech.wav", sr=None)  # the original track, added to the output video

video = pipe(image=image, audio=audio, output="videos")[0]
encode_video(
    video,
    fps=25,
    output_path="avatar.mp4",
    audio=torch.from_numpy(speech)[None],
    audio_sample_rate=sample_rate,
)
```

当所有组件都位于设备上时，Pro 检查点无法与 7B 语音和文本编码器同时放入 80 GB 的 GPU 中。请通过 `ComponentsManager` 将它们卸载：

```py
import librosa
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import encode_video, load_image

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("kandinskylab/Kandinsky-S2V-1.0-Pro-Diffusers", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="40GiB")

image = load_image("reference.png")
audio, _ = librosa.load("speech.wav", sr=16000)
speech, sample_rate = librosa.load("speech.wav", sr=None)

video = pipe(image=image, audio=audio, output="videos")[0]
encode_video(
    video,
    fps=25,
    output_path="avatar.mp4",
    audio=torch.from_numpy(speech)[None],
    audio_sample_rate=sample_rate,
)
```

margin 是指模型移至 GPU 时，在权重之外额外预留的内存。它需要容纳一个数据块的 VAE 解码，在 512x768 分辨率下约为 33 GiB：若使用默认的 3 GB，transformer 会在解码期间一直驻留在 GPU 上，随后导致内存耗尽。当设置为 40 GiB 时，在 80 GB 的 GPU 上峰值内存约为 50 GiB。请在 `load_components` 之后启用 offload，以便其应用于所有组件。

## 备注

- `image` 是一个 PIL 图像，`audio` 是 16 kHz 采样率下取值范围为 [-1, 1] 的单声道浮点波形，以张量或形状为 `(samples,)` 的数组形式提供；该 pipeline 不会读取文件。
- 顶层块（`text_encoder`、`vae_encoder`、`denoise`、`decode`）也可以独立运行；单独运行每个块时，请传入相同的 `num_latent_frames` 和 `fps`。
- 除非传入 `num_chunks`，否则分块数量取决于语音轨道的长度。无论如何，视频都会被裁剪至与轨道长度一致，因此超出其末尾的分块会被计算并丢弃，同时会发出警告。
- 在引导机制下，无条件分支会替换为负向提示词 *并* 静音语音，因此引导是联合作用于文本和语音的。

## KandinskyS2VModularPipeline[[diffusers.KandinskyS2VModularPipeline]]

#### diffusers.KandinskyS2VModularPipeline[[diffusers.KandinskyS2VModularPipeline]]

```python
diffusers.KandinskyS2VModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_pipeline.py#L91)

用于 Kandinsky S2V 1.0 语音到视频生成的 ModularPipeline。

## KandinskyS2VAutoBlocks[[diffusers.KandinskyS2VAutoBlocks]]

#### diffusers.KandinskyS2VAutoBlocks[[diffusers.KandinskyS2VAutoBlocks]]

```python
diffusers.KandinskyS2VAutoBlocks()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_blocks_kandinsky_s2v.py#L108)

基于 Kandinsky S2V 1.0 的模块化语音转视频生成流水线：根据参考帧和语音轨道，逐块生成虚拟形象视频。

组件：text_encoder (`Qwen2_5OmniThinkerForConditionalGeneration`) tokenizer (`Qwen2_5OmniProcessor`) text_encoder_2 (`CLIPTextModel`) tokenizer_2 (`CLIPTokenizer`) vae (`AutoencoderKLHunyuanVideo`) video_processor (`VideoProcessor`) transformer (`KandinskyS2VTransformer3DModel`) scheduler (`FlowMatchEulerDiscreteScheduler`) guider (`ClassifierFreeGuidance`)

Inputs: prompt (`str`, *可选*，默认为 视频呈现了一个面向镜头的主体稳定中近景。主体展现出自然、逼真的身体动态：头部和肩部随着说话的节奏流畅移动。光线均匀，保持平衡的自然曝光，清晰呈现面部特征而无过曝。在整个序列中，主体进行连续说话，发音精准且保真度高。嘴唇以有节奏、自然的方式运动：在短暂紧闭和放松张开之间交替。在这些张开期间，上牙尖短暂且真实地可见，展现出自然的牙釉质纹理。发音时上唇在牙齿上方轻微抬起，同时下颌进行与说话节奏同步的最小垂直振荡。面部微表情活跃但克制；眉毛以微小的不对称性轻微升降。眼睛保持稳定、专注的前视目光，穿插着平滑、刻意的眨眼。 )：用于引导生成的提示词。 negative_prompt (`str`, *可选*)：用于引导无条件路径的提示词。当引导需要时，默认为 `DEFAULT_NEGATIVE_PROMPT`。 audio (`Tensor | ndarray`)：驱动生成的语音轨道：频率为 16000 Hz 的单声道浮点波形，取值范围为 [-1, 1]，形状为 (samples,)。 num_latent_frames (`int`, *可选*，默认为 32)：每个块中的潜在帧数；32 对应 125 帧（25 fps 下的 5 秒）。 fps (`int`, *可选*，默认为 25)：用于计算块长度的帧率。 num_chunks (`int`, *可选*)：要生成的块数。默认为覆盖语音轨道所需的数量；无论如何，视频都会被裁剪以匹配轨道长度。 image (`Image`)：要动画化的参考帧。 height (`int`, *可选*)：生成视频的高度（像素）。默认为最接近参考帧的 512 分桶。 width (`int`, *可选*)：生成视频的宽度（像素），与 `height` 一起选择。 generator (`Generator`, *可选*)：用于确定性生成的 Torch 生成器。 num_inference_steps (`int`, *可选*，默认为 50)：去噪步骤数。 scale_factor (`tuple`, *可选*，默认为 (1.0, 2.0, 2.0))：分辨率分桶的每轴 RoPE 缩放因子。 output_type (`str`, *可选*，默认为 pil)：输出格式：'pil'、'np'、'pt'。

输出：videos (`list`)：生成的视频。

## KandinskyS2VDistilledModularPipeline[[diffusers.KandinskyS2VDistilledModularPipeline]]

#### diffusers.KandinskyS2VDistilledModularPipeline[[diffusers.KandinskyS2VDistilledModularPipeline]]

```python
diffusers.KandinskyS2VDistilledModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_pipeline.py#L109)

用于 pi-Flow 蒸馏版 Kandinsky S2V 1.0 检查点的 ModularPipeline。

Guidance 被蒸馏到学生模型中，因此其块没有 guider，也没有负面提示，每个片段只需执行一次前向传播。

## KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

#### diffusers.KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

```python
diffusers.KandinskyS2VDistilledAutoBlocks()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_blocks_kandinsky_s2v_distilled.py#L103)

使用 pi-Flow 蒸馏的 Kandinsky S2V 1.0 检查点构建的模块化语音转视频生成流水线：每个块包含 16 个片段且不使用引导，该设置已蒸馏至学生模型。

组件：text_encoder (`Qwen2_5OmniThinkerForConditionalGeneration`) tokenizer (`Qwen2_5OmniProcessor`) text_encoder_2 (`CLIPTextModel`) tokenizer_2 (`CLIPTokenizer`) vae (`AutoencoderKLHunyuanVideo`) video_processor (`VideoProcessor`) transformer (`KandinskyS2VTransformer3DModel`) scheduler (`PiflowScheduler`)

Inputs: prompt (`str`, *可选*，默认为 视频展示了一个面向镜头的对象的稳定中近景。对象展现出自然、逼真的身体动态：头部和肩部随着说话的韵律流畅移动。光线均匀，保持平衡的自然曝光，以清晰界定面部特征而不产生过曝。在整个序列中，对象进行连续的说话，发音精准且保真度高。嘴唇以有节奏、自然的方式移动：在短暂的紧闭和放松的张开之间交替。在张开期间，上牙尖短暂且真实地可见，展现出自然的珐琅质纹理。在发音时，上唇在牙齿上方微妙地抬起，同时下颌进行与说话节奏同步的最小垂直振荡。面部微表情活跃但克制；眉毛以微小的不对称性轻微升降。眼睛保持稳定、专注的向前凝视，间以平滑、有意的眨眼。 )：用于引导生成的提示词。 audio (`Tensor | ndarray`)：驱动生成的语音轨道：频率为 16000 Hz 的单声道浮点波形，取值范围为 [-1, 1]，形状为 (samples,)。 num_latent_frames (`int`, *可选*，默认为 32)：每个块（chunk）的潜在帧数；32 对应 125 帧（25 fps 下为 5 秒）。 fps (`int`, *可选*，默认为 25)：用于计算块长度的帧率。 num_chunks (`int`, *可选*)：要生成的块数。默认为覆盖整个语音轨道所需的块数；无论如何，视频都会被裁剪以匹配轨道长度。 image (`Image`)：用于动画化的参考帧。 height (`int`, *可选*)：生成视频的高度（像素）。默认为最接近参考帧的 512 分桶值。 width (`int`, *可选*)：生成视频的宽度（像素），与 `height` 共同选择。 generator (`Generator`, *可选*)：用于确定性生成的 Torch 生成器。 num_inference_steps (`int`, *可选*，默认为 16)：去噪步数。 scale_factor (`tuple`, *可选*，默认为 (1.0, 2.0, 2.0))：分辨率分桶的逐轴 RoPE 缩放因子。 output_type (`str`, *可选*，默认为 pil)：输出格式：'pil'、'np' 或 'pt'。

输出：videos (`list`)：生成的视频。