diffusers/main/ar/api/pipelines/kandinsky_s2v.md

Kandinsky S2V 1.0

يولّد Kandinsky S2V 1.0 فيديوً لشخصية افتراضية من إطار مرجعي ومسار صوتي. يتم تحريك الشخص الموجود في الإطار ليتوافق مع الكلام — الشخصية بأكملها، وليس الرأس فقط. يُعدّ الكلام شرطًا وليس ناتجًا: لا يولّد النموذج صوتًا، ومسار الصوت في النتيجة هو المسار الذي تمرره.

تمرّ الشرطان معًا عبر Qwen2.5-Omni-7B: حيث ترمّز حالاته المخفية (hidden states) الأمر النصي (prompt)، بينما يرمّز برج الصوت (audio tower) الكلام، الذي يدخل إلى المحوّل (transformer) عبر محوِّلات الانتباه المتقاطع (cross-attention adapters) المُحاذاة إطارًا بإطار، بحيث ينتبه كل إطار كامن (latent frame) فقط إلى الجزء من الكلام الذي يغطيه. يتم توليد المقطع على شكل مقاطع فرعية (chunks) مدتها 5 ثوانٍ (125 إطارًا بمعدل 25 إطارًا في الثانية)، تحمل كلٌّ منها ذاكرة FramePack للمقاطع السابقة، مما يضمن اتساق المسارات الأطول عبر حدود المقاطع الفرعية.

يُدمج Kandinsky S2V 1.0 كـخط أنابيب معياري فقط؛ لا توجد فئة DiffusionPipeline قياسية له.

نقاط التفتيش

نقطة التفتيش	Transformer	الكتل	المجدول	الخطوات	إرشادات
[خفيف][lite]	2B	KandinskyS2VAutoBlocks	FlowMatchEulerDiscreteScheduler	50	3.0
[Pro][pro]	21B	KandinskyS2VAutoBlocks	FlowMatchEulerDiscreteScheduler	50	3.0
[مُقطَّر خفيف][lite-distill]	2B	KandinskyS2VDistilledAutoBlocks	PiflowScheduler	16	إيقاف
[مُقطّر احترافي][pro-distill]	21B	KandinskyS2VDistilledAutoBlocks	PiflowScheduler	16	إيقاف

تُهيّئ نقاط التفتيش المُصغّرة 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 يختار الكتل من نقطة الحفظ. تكون الخطوات افتراضيًا بالقيم المذكورة أعلاه. التوجيه الحر من التصنيف هو مكوّن guider وليس معامل استدعاء: نقاط الحفظ الأساسية تأتي به عند 3.0. أما المُقطّرة فلا تحتوي على مُوجّه ولا على negative_prompt، لأن التوجيه جزء أصيل من الطالب.

الاستخدام

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 مع وحدة معالجة رسومية سعة 80 جيجابايت إلى جانب مشفّر الصوت والنص 7B عندما تكون جميع المكونات على الجهاز. قم بإزاحتها عبر 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,
)

الهامش هو الذاكرة التي تُبقيها فارغةً إلى جانب الأوزان عند نقل النموذج إلى وحدة معالجة الرسوميات (GPU). يجب أن يستوعب هذا الهامش فك ترميز VAE لقسم من البيانات، وهو ما يتطلب حوالي 33 GiB عند دقة 512x768: مع القيمة الافتراضية البالغة 3 GB، يبقى المُحوِّل (transformer) على وحدة معالجة الرسوميات أثناء فك الترميز، مما يؤدي إلى نفاد الذاكرة. عند استخدام 40 GiB، يبلغ الذروة حوالي 50 GiB على وحدة معالجة رسوميات بسعة 80 GB. فعِّل التحميل الجزئي (offload) بعد load_components حتى ينطبق على كل مكوّن.

ملاحظات

• image هو صورة بصيغة PIL وaudio موجة صوتية أحادية القناة من نوع float ضمن النطاق [-1, 1] بمعدل عينة 16 kHz، على شكل tensor أو مصفوفة بأبعاد (samples,)؛ ولا يقوم خط المعالجة بقراءة الملفات.
• تعمل الكتل العليا (text_encoder، vae_encoder، denoise، decode) بشكل مستقل أيضاً؛ عند تشغيلها بشكل منفصل، مرّر نفس قيم num_latent_frames وfps إلى كل منها.
• يتبع عدد المقاطع طول مسار الصوت ما لم يتم تمرير num_chunks. يتم قص الفيديو ليتطابق مع المسار في جميع الأحوال، لذا تُحسب المقاطع التي تتجاوز نهايته ثم تُستبعد، مع إصدار تحذير.
• مع التوجيه، يستبدل المرور غير الشرطي الموجه السلبي و يُسكت الكلام، لذا يكون التوجيه مشتركًا بين النص والكلام.

KandinskyS2VModularPipeline[[diffusers.KandinskyS2VModularPipeline]]

diffusers.KandinskyS2VModularPipeline[[diffusers.KandinskyS2VModularPipeline]]

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)

المصدر

خط أنابيب ModularPipeline لتوليد الفيديو من الكلام في Kandinsky S2V 1.0.

KandinskyS2VAutoBlocks[[diffusers.KandinskyS2VAutoBlocks]]

diffusers.KandinskyS2VAutoBlocks[[diffusers.KandinskyS2VAutoBlocks]]

diffusers.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)

المدخلات: prompt (str, اختياري, الافتراضي هو يعرض الفيديو لقطة متوسطة مستقرة لموضوع يواجه الكاميرا مباشرة. يُظهر الموضوع ديناميكيات جسم طبيعية وواقعية: تتحرك الرأس والكتيفان بسلاسة مع إيقاع الكلام. الإضاءة متساوية، مما يحافظ على تعريض طبيعي متوازن لتحديد ملامح الوجه بوضوح دون غمر. على مدار التسلسل، يشارك الموضوع في كلام مستمر يتسم بنطق دقيق وعالي الدقة. تتحرك الشفاه بنمط إيقاعي طبيعي: تتناوب بين إغلاقات قصيرة وحازمة وفتحات مرتخية. أثناء هذه الفتحات، تكون أطراف الأسنان العلوية مرئية لحظياً وبواقعية، معروضةً لملمس مينا طبيعي. يرتفع الشفاه العلوية بشكل خفيف فوق الأسنان أثناء النطق، بينما يؤدي الفك اهتزازات رأسية دنيا متزامنة مع إيقاع الكلام. تعبيرات الوجه الدقيقة نشطة لكن مقيّدة؛ ترتفع الحاجبان وتنخفض قليلاً مع عدم تماثل دقيق. تحافظ العينان على نظرة ثابتة ومتجهة للأمام، تتخللها رمشات سلسة ومتعمدة. ): الأمر الموجّه للتوليد. negative_prompt (str, اختياري): الأمر للمسار غير الشرطي للإرشاد. الافتراضي هو DEFAULT_NEGATIVE_PROMPT عندما يحتاج الإرشاد إلى ذلك. audio (Tensor | ndarray): المسار الصوتي الذي يقود التوليد: موجة صوتية أحادية العائمة في [-1, 1] عند 16000 هرتز، بشكل (samples,). num_latent_frames (int, اختياري, الافتراضي هو 32): الإطارات الكامنة لكل شريحة؛ 32 تعطي 125 إطاراً (5 ثوانٍ عند 25 إطاراً في الثانية). 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'.

المخرجات: مقاطع فيديو (list): مقاطع الفيديو المولّدة.

KandinskyS2VDistilledModularPipeline[[diffusers.KandinskyS2VDistilledModularPipeline]]

diffusers.KandinskyS2VDistilledModularPipeline[[diffusers.KandinskyS2VDistilledModularPipeline]]

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)

المصدر

ModularPipeline لفحوصات pi-Flow المُصغّرة لنموذج Kandinsky S2V 1.0.

يتم تقطير التوجيه إلى الطالب، لذا فإن كتله لا تحتوي على موجّه ولا على موجه سلبي، وتُنفَّذ تمريرة أمامية واحدة لكل مقطع.

KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

diffusers.KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

diffusers.KandinskyS2VDistilledAutoBlocks()

المصدر

خط أنابيب معياري لتوليد الفيديو من الكلام باستخدام نقاط التفتيش المُقطّرة 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)

المدخلات: prompt (str, اختياري, الافتراضي هو يعرض الفيديو لقطة متوسطة مستقرة لموضوع يواجه الكاميرا مباشرة. يُظهر الموضوع ديناميكيات جسم طبيعية وواقعية: تتحرك الرأس والكتيفان بسلاسة مع إيقاع الكلام. الإضاءة متساوية، مما يحافظ على تعريض طبيعي متوازن لتحديد ملامح الوجه بوضوح دون غمرها بالضوء. على مدار التسلسل، يشارك الموضوع في كلام مستمر يتسم بنطق دقيق وعالي الدقة. تتحرك الشفاه بنمط إيقاعي طبيعي: تتناوب بين إغلاقات قصيرة وحازمة وفتحات مرتخية. أثناء هذه الفتحات، تكون أطراف الأسنان العلوية مرئية لحظياً وبواقعية، معبّرة عن ملمس مينا طبيعي. يرتفع الشفاه العلوية بشكل خفيف فوق الأسنان أثناء النطق، بينما يؤدي الفك اهتزازات رأسية طفيفة متزامنة مع إيقاع الكلام. تعبيرات الوجه الدقيقة نشطة لكنها مقيّدة؛ ترتفع الحاجبان وتنخفضان قليلاً مع عدم تماثل دقيق. تحافظ العينان على نظرة ثابتة ومتجهة للأمام، تتخللها رمشات سلسة ومتعمدة. ): الأمر الموجّه للتوليد. audio (Tensor | ndarray): المسار الصوتي الذي يقود التوليد: موجة صوتية أحادية العائمة في [-1, 1] عند 16000 هرتز، بشكل (samples,). num_latent_frames (int, اختياري, الافتراضي هو 32): الإطارات الكامنة لكل شريحة؛ 32 تعطي 125 إطاراً (5 ثوانٍ عند 25 إطاراً في الثانية). 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'.

المخرجات: مقاطع فيديو (list): مقاطع الفيديو المولّدة.