Diffusers documentation
Kandinsky S2V 1.0
Kandinsky S2V 1.0
Kandinsky S2V 1.0은 참조 프레임과 음성 트랙을 입력받아 아바타 영상을 생성합니다. 프레임 속 인물은 음성に合わせて 애니메이션 처리되며, 머리뿐만 아니라 전체 인물이 움직입니다. 음성은 출력물이 아닌 조건으로 작용합니다. 즉, 모델은 오디오를 생성하지 않으며, 결과물의 사운드트랙은 사용자가 전달한 트랙 그대로입니다.
두 조건 모두 Qwen2.5-Omni-7B를 통해 처리됩니다. 이 모델의 hidden states는 프롬프트를 인코딩하고, 오디오 타워는 음성(스피치)을 인코딩합니다. 이 음성 인코딩 결과는 프레임별로 정렬된 cross-attention 어댑터를 통해 transformer에 입력되며, 각 latent 프레임은 자신이 커버하는 음성에만 attention을 기울입니다. 클립은 5초(25 fps 기준 125프레임) 단위의 청크로 생성되며, 각 청크는 이전 청크들의 FramePack memory를 포함하므로 더 긴 트랙도 청크 경계에서 일관성을 유지합니다.
Kandinsky S2V 1.0은 모듈형 파이프라인으로만 통합되어 있으며, 이를 위한 표준 DiffusionPipeline 클래스는 없습니다.
체크포인트
| 체크포인트 | Transformer | 블록 | 스케줄러 | 단계 | 가이드 |
|---|---|---|---|---|---|
| Lite | 2B | KandinskyS2VAutoBlocks | FlowMatchEulerDiscreteScheduler | 50 | 3.0 |
| Pro | 21B | KandinskyS2VAutoBlocks | FlowMatchEulerDiscreteScheduler | 50 | 3.0 |
| 라이트 디스티드 | 2B | KandinskyS2VDistilledAutoBlocks | PiflowScheduler | 16 | off |
| Pro 디스틸드 | 21B | KandinskyS2VDistilledAutoBlocks | PiflowScheduler | 16 | off |
디스틸된 체크포인트는 기본값이 아닌 PiflowScheduler에 shift=10.0 및 n_grid=5를 설정합니다.
ModularPipeline.from_pretrained는 체크포인트에서 블록을 선택합니다. 각 단계의 기본값은 위의 값입니다. Classifier-free guidance는 호출 인수가 아니라 guider 구성 요소입니다. 기본 체크포인트에는 3.0으로 포함되어 있습니다. 증류된 체크포인트에는 guider와 negative_prompt가 없으며, 이는 guidance가 이미 student에 포함되어 있기 때문입니다.
사용
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를 통해 오프로드하세요:
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를 활성화하세요.
The input is a single word "Notes". 참고
image는 PIL 이미지이고,audio는 16 kHz의 [-1, 1] 범위를 가지는 모노 float 웨이브폼으로,(samples,)모양의 텐서 또는 배열입니다. 파이프라인은 파일을 읽지 않습니다.- 최상위 블록(
text_encoder,vae_encoder,denoise,decode)는 각각 독립적으로 실행할 수도 있습니다. 각 블록을 별도로 실행할 때는 동일한num_latent_frames와fps값을 전달하세요. num_chunks가 전달되지 않는 한, 청크의 수는 음성 트랙의 길이를 따릅니다. 어쨌든 비디오는 트랙에 맞게 잘리므로, 트랙 끝을 초과하는 청크는 계산된 후 경고와 함께 삭제됩니다.- 가이던스가 적용되면, 무조건적 패스는 음성 대신 음성을 삽입하고 음성을 무음 처리하므로, 가이던스는 텍스트와 음성 모두에 대해 결합됩니다.
KandinskyS2VModularPipeline
class diffusers.KandinskyS2VModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Kandinsky S2V 1.0 음성-영상 생성을 위한 ModularPipeline.
KandinskyS2VAutoBlocks
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, optional, defaults to The video presents a stable medium close-up of a subject facing the
camera directly. The subject exhibits natural, lifelike body dynamics: the head and shoulders move fluidly
with the rhythm of speech. The lighting is even, maintaining a balanced natural exposure to clearly define
facial features without washout. Throughout the sequence, the subject engages in continuous speech marked by
precise, high-fidelity articulation. The lips move in a rhythmic, natural pattern: alternating between brief
firm closures and relaxed openings. During these openings, the tips of the upper teeth are momentarily and
realistically visible, exhibiting natural enamel texture. The upper lip lifts subtly over the teeth during
enunciation, while the jaw performs minimal vertical oscillations synchronized with the speech cadence.
Facial micro-expressions are active yet restrained; eyebrows rise and lower slightly with minute asymmetry.
The eyes maintain a steady, engaged gaze forward, punctuated by smooth, deliberate blinks. ):
The prompt to guide the generation.
negative_prompt (str, optional):
The prompt for the unconditional pass of the guidance. Defaults to DEFAULT_NEGATIVE_PROMPT when the
guidance needs one.
audio (Tensor | ndarray):
The speech track that drives the generation: a mono float waveform in [-1, 1] at 16000 Hz, shaped
(samples,).
num_latent_frames (int, optional, defaults to 32):
Latent frames per chunk; 32 gives 125 frames (5 s at 25 fps).
fps (int, optional, defaults to 25):
Frame rate the chunk length is computed at.
num_chunks (int, optional):
Number of chunks to generate. Defaults to however many cover the speech track; the video is trimmed to
the track either way.
image (Image):
The reference frame to animate.
height (int, optional):
The height in pixels of the generated video. Defaults to the 512 bucket closest to the reference frame.
width (int, optional):
The width in pixels of the generated video, chosen together with height.
generator (Generator, optional):
Torch generator for deterministic generation.
num_inference_steps (int, optional, defaults to 50):
The number of denoising steps.
scale_factor (tuple, optional, defaults to (1.0, 2.0, 2.0)):
Per-axis RoPE scale for the resolution bucket.
output_type (str, optional, defaults to pil):
Output format: ‘pil’, ‘np’, ‘pt’.
Outputs:
videos (list):
생성된 비디오.
KandinskyS2VDistilledModularPipeline
class diffusers.KandinskyS2VDistilledModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
pi-Flow에서 증류된 Kandinsky S2V 1.0 체크포인트를 위한 ModularPipeline.
Guidance는 student로 증류되므로, 해당 블록에는 guider와 negative prompt가 없으며, 각 segment마다 단일 forward pass만 실행됩니다.
KandinskyS2VDistilledAutoBlocks
pi-Flow distilled Kandinsky S2V 1.0 체크포인트를 활용한 음성-영상 생성을 위한 모듈형 파이프라인: 16 세그먼트 per chunk, guidance 없음. 이는 student로 distilled됩니다.
구성 요소:
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, optional, defaults to The video presents a stable medium close-up of a subject facing the
camera directly. The subject exhibits natural, lifelike body dynamics: the head and shoulders move fluidly
with the rhythm of speech. The lighting is even, maintaining a balanced natural exposure to clearly define
facial features without washout. Throughout the sequence, the subject engages in continuous speech marked by
precise, high-fidelity articulation. The lips move in a rhythmic, natural pattern: alternating between brief
firm closures and relaxed openings. During these openings, the tips of the upper teeth are momentarily and
realistically visible, exhibiting natural enamel texture. The upper lip lifts subtly over the teeth during
enunciation, while the jaw performs minimal vertical oscillations synchronized with the speech cadence.
Facial micro-expressions are active yet restrained; eyebrows rise and lower slightly with minute asymmetry.
The eyes maintain a steady, engaged gaze forward, punctuated by smooth, deliberate blinks. ):
The prompt to guide the generation.
audio (Tensor | ndarray):
The speech track that drives the generation: a mono float waveform in [-1, 1] at 16000 Hz, shaped
(samples,).
num_latent_frames (int, optional, defaults to 32):
Latent frames per chunk; 32 gives 125 frames (5 s at 25 fps).
fps (int, optional, defaults to 25):
Frame rate the chunk length is computed at.
num_chunks (int, optional):
Number of chunks to generate. Defaults to however many cover the speech track; the video is trimmed to
the track either way.
image (Image):
The reference frame to animate.
height (int, optional):
The height in pixels of the generated video. Defaults to the 512 bucket closest to the reference frame.
width (int, optional):
The width in pixels of the generated video, chosen together with height.
generator (Generator, optional):
Torch generator for deterministic generation.
num_inference_steps (int, optional, defaults to 16):
The number of denoising steps.
scale_factor (tuple, optional, defaults to (1.0, 2.0, 2.0)):
Per-axis RoPE scale for the resolution bucket.
output_type (str, optional, defaults to pil):
Output format: ‘pil’, ‘np’, ‘pt’.
Outputs:
videos (list):
생성된 비디오.