Diffusers documentation
Kandinsky S2V 1.0
Kandinsky S2V 1.0
يولّد Kandinsky S2V 1.0 فيديوً لشخصية افتراضية من إطار مرجعي ومسار صوتي. يتم تحريك الشخص الموجود في الإطار ليتوافق مع الكلام — الشخصية بأكملها، وليس الرأس فقط. يُعدّ الكلام شرطًا وليس ناتجًا: لا يولّد النموذج صوتًا، ومسار الصوت في النتيجة هو المسار الذي تمرره.
تمرّ الشرطان معًا عبر Qwen2.5-Omni-7B: فحالاته المخفية ترمّز المُوجِّه، وبرجه الصوتي يرمّز الكلام، الذي يدخل المحوّل عبر محوِّلات الانتباه المتقاطع المُحاذاة إطارًا بإطار، بحيث يُنتبه كل إطار كامن فقط إلى الكلام الذي يغطيه. يتم توليد المقطع على شكل قطع من 5 ثوانٍ (125 إطارًا بمعدل 25 إطارًا في الثانية)، تحمل كلٌّ منها ذاكرة FramePack للقطع السابقة، مما يُبقي المسارات الأطول متسقة عبر حدود القطع.
يُدمج Kandinsky S2V 1.0 كـخط أنابيب معياري فقط؛ لا توجد فئة DiffusionPipeline قياسية له.
نقاط التفتيش
| نقطة التفتيش | Transformer | الكتل | المجدول | الخطوات | إرشادات |
|---|---|---|---|---|---|
| Lite | 2B | KandinskyS2VAutoBlocks | FlowMatchEulerDiscreteScheduler | 50 | 3.0 |
| احترافي | 21B | KandinskyS2VAutoBlocks | FlowMatchEulerDiscreteScheduler | 50 | 3.0 |
| مُصغَّر خفيف | 2B | KandinskyS2VDistilledAutoBlocks | PiflowScheduler | 16 | إيقاف |
| محسّن احترافي | 21B | KandinskyS2VDistilledAutoBlocks | PiflowScheduler | 16 | إيقاف |
تُهيّئ نقاط التفتيش المُصغّرة PiflowScheduler باستخدام shift=10.0 وn_grid=5، وليس القيم الافتراضية الخاصة بها.
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
< 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 )
خط أنابيب ModularPipeline لتوليد الفيديو من الكلام في Kandinsky S2V 1.0.
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, اختياري، الافتراضي هو: يعرض الفيديو لقطة متوسطة قريبة مستقرة لشخص يواجه
الكاميرا مباشرة. يُظهر الشخص ديناميكيات جسدية طبيعية وواقعية: تتحرك الرأس والكتيفان بسلاسة
مع إيقاع الكلام. الإضاءة متساوية، وتحافظ على تعريض طبيعي متوازن لتحديد ملامح
الوجه بوضوح دون غمرها بالضوء. على مدار التسلسل، ينخرط الشخص في كلام مستمر يتميز
بنطق دقيق وعالي الدقة. تتحرك الشفاه بنمط إيقاعي وطبيعي: تتناوب بين إغلاقات
قصيرة وحازمة وفتوحات مرتخية. أثناء هذه الفتوحات، تظهر أطراف الأسنان العلوية لحظياً و
بواقعية، مُظهرةً ملمس مينا طبيعي. ترفع الشفة العلوية قليلاً فوق الأسنان أثناء
النطق، بينما يؤدي الفك اهتزازات عمودية ضئيلة متزامنة مع إيقاع الكلام.
تتسم التعبيرات الدقيقة للوجه بالنشاط مع الاحتشام؛ ترتفع الحاجبان وتنخفض قليلاً مع عدم تناظر دقيق.
تحتفظ العينان بنظر ثابت ومشارك للأمام، تتخلله رمشات ناعمة ومدروسة. ):
الموجّه (Prompt) الذي يوجّه عملية التوليد.
negative_prompt (str, اختياري):
الموجّه (Prompt) الخاص بالمرحلة غير الشرطية من التوجيه. يكون الافتراضي DEFAULT_NEGATIVE_PROMPT عندما
يحتاج التوجيه إلى ذلك.
audio (Tensor | ndarray):
مسار الصوت الذي يقود عملية التوليد: موجة صوتية أحادية (Mono) من نوع float في المدى [-1, 1] بمعدل عينة 16000 هرتز،
بشكل (samples,).
num_latent_frames (int, اختياري، الافتراضي 32):
عدد الإطارات الكامنة (Latent frames) لكل شريحة؛ 32 تعطي 125 إطارا (5 ثوانٍ بمعدل 25 إطاراً في الثانية).
fps (int, اختياري، الافتراضي 25):
معدل الإطارات الذي يُحسب على أساسه طول الشريحة.
num_chunks (int, اختياري):
عدد الشرائح المراد توليدها. يكون الافتراضي هو العدد اللازم لتغطية مسار الصوت؛ يتم قص الفيديو ليتطابق مع
المسار في كل الأحوال.
image (Image):
الإطار المرجعي الذي سيتم تحريكه.
height (int, اختياري):
الارتفاع بالبكسلات للفيديو المولّد. يكون الافتراضي هو أقرب دلو (Bucket) بحجم 512 إلى الإطار المرجعي.
width (int, اختياري):
العرض بالبكسلات للفيديو المولّد، ويختار معاً مع height.
generator (Generator, اختياري):
مولّد Torch لتوليد حتمي (Deterministic).
num_inference_steps (int, اختياري، الافتراضي 50):
عدد خطوات إزالة الضوضاء (Denoising steps).
scale_factor (tuple, اختياري، الافتراضي (1.0, 2.0, 2.0)):
معامل مقياس RoPE لكل محور لدلو الدقة (Resolution bucket).
output_type (str, اختياري، الافتراضي pil):
صيغة الإخراج: ‘pil’، ‘np’، ‘pt’.
المخرجات:
فيديوهات (list):
الفيديوهات المولّدة.
KandinskyS2VDistilledModularPipeline
فئة 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 )
ModularPipeline لفحوصات pi-Flow المُصغّرة لنموذج Kandinsky S2V 1.0.
يتم تقطير التوجيه إلى الطالب، لذا فإن كتله لا تحتوي على موجّه ولا على موجه سلبي، وتُنفَّذ تمريرة أمامية واحدة لكل مقطع.
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, اختياري، الافتراضي هو: يعرض الفيديو لقطة متوسطة مستقرة لشخص يواجه الكاميرا مباشرة. يُظهر الشخص حركات جسم طبيعية وواقعية: تتحرك الرأس والكتيفان بسلاسة مع إيقاع الكلام. الإضاءة متساوية، مما يحافظ على تعريض طبيعي متوازن لتحديد ملامح الوجه بوضوح دون غمر. على مدار التسلسل، يشارك الشخص في كلام مستمر يتميز بنطق دقيق وعالي الدقة. تتحرك الشفاه بنمط إيقاعي طبيعي: تتناوب بين إغلاقات قصيرة وحازمة وفتحات مرتخية. خلال هذه الفتحات، تكون أطراف الأسنان العلوية مرئية مؤقتًا وواقعيًا، معروضةً لملمس مينا طبيعي. ترفع الشفة العليا الأسنان بشكل خفيف أثناء النطق، بينما يؤدي الفك تذبذبات رأسية طفيفة متزامنة مع إيقاع الكلام. تعبيرات الوجه الدقيقة نشطة ولكن مقيدة؛ ترتفع الحاجبان وتنخفضان قليلًا مع عدم تماثل دقيق. تحافظ العينان على نظرة ثابتة ومتفاعلة للأمام، تتخللها رمشات سلسة ومدروسة. ):
الموجّه (Prompt) الذي يوجه عملية التوليد.
audio (Tensor | ndarray):
مسار الصوت الذي يقود عملية التوليد: موجة صوتية أحادية (mono) من نوع float في النطاق [-1, 1] بمعدل عينة 16000 هرتز، على شكل
(samples,).
num_latent_frames (int, اختياري، الافتراضي هو 32):
عدد الإطارات الكامنة (Latent frames) لكل شريحة؛ 32 تعطي 125 إطارًا (5 ثوانٍ بمعدل 25 إطارًا في الثانية).
fps (int, اختياري، الافتراضي هو 25):
معدل الإطارات الذي يُحسب على أساسه طول الشريحة.
num_chunks (int, اختياري):
عدد الشرائح المراد توليدها. الافتراضي هو العدد اللازم لتغطية مسار الصوت؛ يتم قص الفيديو ليتطابق مع المسار في جميع الأحوال.
image (Image):
الإطار المرجعي الذي سيتم تحريكه.
height (int, اختياري):
الارتفاع بالبكسل للفيديو المولّد. الافتراضي هو أقرب دلو (bucket) بقياس 512 إلى الإطار المرجعي.
width (int, اختياري):
العرض بالبكسل للفيديو المولّد، ويُختار معًا مع height.
generator (Generator, اختياري):
مولّد Torch لتوليد حتمي (deterministic).
num_inference_steps (int, اختياري، الافتراضي هو 16):
عدد خطوات إزالة الضوضاء (denoising steps).
scale_factor (tuple, اختياري، الافتراضي هو (1.0, 2.0, 2.0)):
معامل مقياس RoPE لكل محور للدلو (bucket) الخاص بالدقة.
output_type (str, اختياري، الافتراضي هو pil):
صيغة الإخراج: ‘pil’، ‘np’، ‘pt’.
المخرجات:
فيديوهات (list):
الفيديوهات المولّدة.