Diffusers documentation
Kandinsky S2V 1.0
Kandinsky S2V 1.0
Kandinsky S2V 1.0 genera un video de avatar a partir de un fotograma de referencia y una pista de audio. La persona en el fotograma se anima para que coincida con el habla: se anima la figura completa, no solo la cabeza. El habla es una condición, no una salida: el modelo no genera audio, y la banda sonora del resultado es la pista que se proporciona.
Ambas condiciones pasan por Qwen2.5-Omni-7B: sus estados ocultos codifican el prompt y su torre de audio codifica el habla, que entra en el transformer a través de adaptadores de atención cruzada alineados cuadro a cuadro, de modo que cada cuadro latente atiende solo al habla que cubre. Un clip se genera en fragmentos de 5 s (125 cuadros a 25 fps), cada uno con memoria FramePack de los anteriores, para que las pistas más largas mantengan la coherencia en los límites entre fragmentos.
Kandinsky S2V 1.0 se integra únicamente como pipeline modular; no existe una clase estándar DiffusionPipeline para él.
Puntos de control
| Checkpoint | Transformer | Bloques | Programador | Pasos | Orientación |
|---|---|---|---|---|---|
| Lite | 2B | KandinskyS2VAutoBlocks | FlowMatchEulerDiscreteScheduler | 50 | 3.0 |
| Pro | 21B | KandinskyS2VAutoBlocks | FlowMatchEulerDiscreteScheduler | 50 | 3.0 |
| Destilado Lite | 2B | KandinskyS2VDistilledAutoBlocks | PiflowScheduler | 16 | off |
| Pro destilado | 21B | KandinskyS2VDistilledAutoBlocks | PiflowScheduler | 16 | off |
Los puntos de control destilados configuran PiflowScheduler con shift=10.0 y n_grid=5, no con sus valores predeterminados.
ModularPipeline.from_pretrained selecciona los bloques del checkpoint. Los pasos
por defecto son los valores anteriores. La guía sin clasificador es el componente guider,
no un argumento de llamada: los checkpoints base lo incluyen en 3.0. Los destilados no
tienen guider ni negative_prompt, porque la guía ya forma parte del estudiante.
Uso
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,
)Los checkpoints de Pro no caben en una GPU de 80 GB junto al codificador de voz y texto de 7B cuando todos los componentes están en el dispositivo. Descárguelos a través de un 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,
)El margen es la memoria que se mantiene libre además de los pesos cuando un modelo se mueve a la GPU.
Debe contener la decodificación VAE de un fragmento, aproximadamente 33 GiB a 512x768: con los 3 GB
predeterminados, el transformer permanece en la GPU durante la decodificación, lo que agota la memoria. Con
40 GiB, el pico es de unos 50 GiB en una GPU de 80 GB. Habilite el offload después de load_components,
para que se aplique a cada componente.
Notas
imagees una imagen PIL yaudiouna forma de onda mono flotante en [-1, 1] a 16 kHz, como tensor o matriz con forma(samples,); la pipeline no lee archivos.- Los bloques de nivel superior (
text_encoder,vae_encoder,denoise,decode) también se ejecutan de forma independiente; pasa el mismonum_latent_framesyfpsa cada uno cuando los ejecutes por separado. - El número de fragmentos sigue la duración de la pista de audio a menos que se pase
num_chunks. De todos modos, el video se recorta a la pista, por lo que los fragmentos que exceden su final se calculan y se descartan, con una advertencia. - Con la guía, el paso incondicional sustituye el prompt negativo y silencia el habla, por lo que la guía es conjunta sobre el texto y el habla.
KandinskyS2VModularPipeline
clase 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 )
Un ModularPipeline para la generación de video a partir de voz de Kandinsky S2V 1.0.
KandinskyS2VAutoBlocks
Pipeline modular para la generación de video a partir de voz con Kandinsky S2V 1.0: un video de avatar a partir de un fotograma de referencia y una pista de voz, generado por fragmentos.
Componentes:
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)
Entradas:
prompt (str, opcional, predeterminado: 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. ):
El prompt para guiar la generación.
negative_prompt (str, opcional):
El prompt para el paso incondicional de la guía. Predeterminado a DEFAULT_NEGATIVE_PROMPT cuando la
guía lo necesita.
audio (Tensor | ndarray):
La pista de voz que impulsa la generación: una forma de onda mono flotante en [-1, 1] a 16000 Hz, con forma
(samples,).
num_latent_frames (int, opcional, predeterminado: 32):
Marcos latentes por bloque; 32 da 125 marcos (5 s a 25 fps).
fps (int, opcional, predeterminado: 25):
Tasa de fotogramas a la que se calcula la longitud del bloque.
num_chunks (int, opcional):
Número de bloques a generar. Predeterminado a los necesarios para cubrir la pista de voz; el video se recorta
a la pista de todos modos.
image (Image):
El marco de referencia para animar.
height (int, opcional):
La altura en píxeles del video generado. Predeterminado al cubo de 512 más cercano al marco de referencia.
width (int, opcional):
El ancho en píxeles del video generado, elegido junto con height.
generator (Generator, opcional):
Generador de Torch para generación determinista.
num_inference_steps (int, opcional, predeterminado: 50):
El número de pasos de desruido.
scale_factor (tuple, opcional, predeterminado: (1.0, 2.0, 2.0)):
Escala RoPE por eje para el cubo de resolución.
output_type (str, opcional, predeterminado: pil):
Formato de salida: ‘pil’, ‘np’, ‘pt’.
Salidas:
videos (list):
Los videos generados.
KandinskyS2VDistilledModularPipeline
clase 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 )
Un ModularPipeline para los puntos de control destilados de pi-Flow de Kandinsky S2V 1.0.
La guía se destila en el estudiante, por lo que sus bloques no tienen guía ni prompt negativo, y se ejecuta una sola pasada de adelante por segmento.
KandinskyS2VDistilledAutoBlocks
Pipeline modular para la generación de video a partir de voz con los puntos de control destilados de pi-Flow Kandinsky S2V 1.0: 16 segmentos por bloque y sin guía, lo cual se destila en el estudiante.
Componentes:
text_encoder (Qwen2_5OmniThinkerForConditionalGeneration) tokenizer (Qwen2_5OmniProcessor) text_encoder_2
(CLIPTextModel) tokenizer_2 (CLIPTokenizer) vae (AutoencoderKLHunyuanVideo) video_processor
(VideoProcessor) transformer (KandinskyS2VTransformer3DModel) scheduler (PiflowScheduler)
Entradas:
prompt (str, opcional, predeterminado: 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. ):
El prompt para guiar la generación.
audio (Tensor | ndarray):
La pista de voz que impulsa la generación: una forma de onda mono flotante en [-1, 1] a 16000 Hz, con forma
(samples,).
num_latent_frames (int, opcional, predeterminado: 32):
Marcos latentes por bloque; 32 da 125 marcos (5 s a 25 fps).
fps (int, opcional, predeterminado: 25):
Tasa de fotogramas a la que se calcula la longitud del bloque.
num_chunks (int, opcional):
Número de bloques a generar. El valor predeterminado es el necesario para cubrir la pista de voz; el video se recorta a la pista de todos modos.
image (Image):
El fotograma de referencia para animar.
height (int, opcional):
La altura en píxeles del video generado. El valor predeterminado es el cubo de 512 más cercano al fotograma de referencia.
width (int, opcional):
El ancho en píxeles del video generado, elegido junto con height.
generator (Generator, opcional):
Generador de Torch para una generación determinista.
num_inference_steps (int, opcional, predeterminado: 16):
El número de pasos de desruido.
scale_factor (tuple, opcional, predeterminado: (1.0, 2.0, 2.0)):
Escala RoPE por eje para el cubo de resolución.
output_type (str, opcional, predeterminado: pil):
Formato de salida: ‘pil’, ‘np’, ‘pt’.
Salidas:
videos (list):
Los videos generados.