Diffusers documentation
Sana-Video
Sana-Video
SANA-Video: توليد فيديو فعّال باستخدام محوّل الانتشار الخطي الكتلوي من NVIDIA وMIT HAN Lab، بقلم Junsong Chen وYuyang Zhao وJincheng Yu وRuihang Chu وJunyu Chen وShuai Yang وXianbang Wang وYicheng Pan وDaquan Zhou وHuan Ling وHaozhe Liu وHongwei Yi وHao Zhang وMuyang Li وYukang Chen وHan Cai وSanja Fidler وPing Luo وSong Han وEnze Xie.
ملخص الورقة البحثية هو:
نقدّم SANA-Video، وهو نموذج انتشار صغير قادر على توليد مقاطع فيديو بكفاءة تصل دقتها إلى 720x1280 ومدة تصل إلى دقيقة واحدة. يولّد SANA-Video مقاطع فيديو عالية الدقة والجودة وطويلة المدة مع توافق قوي بين النص والفيديو وبسرعة فائقة، ويمكن نشره على بطاقة RTX 5090 GPU. تضمن تصميمان أساسيان توليد فيديو فعّال وكفء وطويل: (1) Linear DiT: نستفيد من الانتباه الخطي كعملية أساسية، وهو أكثر كفاءة من الانتباه التقليدي نظرًا لعدد الرموز الكبير الذي تتم معالجته في توليد الفيديو. (2) ذاكرة KV ثابتة الذاكرة للانتباه الخطي الكتلي: صممنا نهجًا ذاتي التراجع على مستوى الكتلة لتوليد الفيديو الطويل من خلال استخدام حالة ذاكرة ثابتة، مشتقة من الخصائص التراكمية للانتباه الخطي. توفر هذه ذاكرة KV لـ Linear DiT سياقًا عامًا بتكلفة ذاكرة ثابتة، مما يلغي الحاجة إلى ذاكرة KV تقليدية ويمكّن من توليد فيديو طويل المدة بكفاءة. بالإضافة إلى ذلك، نستكشف مرشحات بيانات فعّالة واستراتيجيات تدريب للنموذج، مما ضيّق تكلفة التدريب إلى 12 يومًا على 64 بطاقة H100 GPU، وهي تكلفة لا تمثل سوى 1% من تكلفة MovieGen. نظرًا لتكلفته المنخفضة، يحقق SANA-Video أداءً تنافسيًا مقارنةً بنماذج الانتشار الصغيرة الحديثة المتقدمة (مثل Wan 2.1-1.3B و SkyReel-V2-1.3B) مع كونه أسرع 16 مرة في زمن الاستجابة المقاس. علاوة على ذلك، يمكن نشر SANA-Video على بطاقات RTX 5090 GPU بدقة NVFP4، مما يسرّع سرعة الاستدلال لتوليد فيديو بدقة 720p ومدته 5 ثوانٍ من 71 ثانية إلى 29 ثانية (تسريع بمقدار 2.4 مرة). باختصار، يمكّن SANA-Video من توليد فيديو عالي الجودة بتكلفة منخفضة. this https URL.
تمت مساهمة خط المعالجة هذا من فريق SANA. يمكن العثور على قاعدة الكود الأصلية هنا. يمكن العثور على الأوزان الأصلية تحت hf.co/Efficient-Large-Model.
النماذج المتاحة:
| النموذج | نوع البيانات الموصى به |
|---|---|
Efficient-Large-Model/SANA-Video_2B_480p_diffusers | torch.bfloat16 |
راجع هذه المجموعة لمزيد من المعلومات.
ملاحظة: نوع البيانات (dtype) الموصى به المذكور أعلاه هو لأوزان المحوّل (transformer). يجب أن تبقى أوزان مُشفِّر النص (text encoder) ووحدة الترميز/فك الترميز التباينية (VAE) في torch.bfloat16 أو torch.float32 لكي يعمل النموذج بشكل صحيح. يُرجى الرجوع إلى مثال الاستدلال أدناه لمعرفة كيفية تحميل النموذج باستخدام نوع البيانات الموصى به.
خطوط أنابيب التوليد
يُبيّن المثال أدناه كيفية استخدام خط أنابيب النص إلى الفيديو لتوليد فيديو باستخدام وصف نصي.
pipe = SanaVideoPipeline.from_pretrained(
"Efficient-Large-Model/SANA-Video_2B_480p_diffusers",
dtype=torch.bfloat16,
)
pipe.text_encoder.to(torch.bfloat16)
pipe.vae.to(torch.float32)
pipe.to("cuda") # or "mps", "xpu", "cpu"
prompt = "A cat and a dog baking a cake together in a kitchen. The cat is carefully measuring flour, while the dog is stirring the batter with a wooden spoon. The kitchen is cozy, with sunlight streaming through the window."
negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience."
motion_scale = 30
motion_prompt = f" motion score: {motion_scale}."
prompt = prompt + motion_prompt
video = pipe(
prompt=prompt,
negative_prompt=negative_prompt,
height=480,
width=832,
frames=81,
guidance_scale=6,
num_inference_steps=50,
generator=torch.Generator(device="cuda").manual_seed(0),
).frames[0]
export_to_video(video, "sana_video.mp4", fps=16)يُبيّن المثال أدناه كيفية استخدام خط أنابيب الصورة إلى الفيديو لتوليد فيديو باستخدام وصف نصي وإطار بداية.
pipe = SanaImageToVideoPipeline.from_pretrained(
"Efficient-Large-Model/SANA-Video_2B_480p_diffusers",
dtype=torch.bfloat16,
)
pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(pipe.scheduler.config, flow_shift=8.0)
pipe.vae.to(torch.float32)
pipe.text_encoder.to(torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
image = load_image("https://raw.githubusercontent.com/NVlabs/Sana/refs/heads/main/asset/samples/i2v-1.png")
prompt = "A woman stands against a stunning sunset backdrop, her long, wavy brown hair gently blowing in the breeze. She wears a sleeveless, light-colored blouse with a deep V-neckline, which accentuates her graceful posture. The warm hues of the setting sun cast a golden glow across her face and hair, creating a serene and ethereal atmosphere. The background features a blurred landscape with soft, rolling hills and scattered clouds, adding depth to the scene. The camera remains steady, capturing the tranquil moment from a medium close-up angle."
negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience."
motion_scale = 30
motion_prompt = f" motion score: {motion_scale}."
prompt = prompt + motion_prompt
motion_scale = 30.0
video = pipe(
image=image,
prompt=prompt,
negative_prompt=negative_prompt,
height=480,
width=832,
frames=81,
guidance_scale=6,
num_inference_steps=50,
generator=torch.Generator(device="cuda").manual_seed(0),
).frames[0]
export_to_video(video, "sana-i2v.mp4", fps=16)التكميم
يساعد التكميم (Quantization) في تقليل متطلبات الذاكرة للنماذج الكبيرة جدًا من خلال تخزين أوزان النموذج في نوع بيانات بدقة أقل. ومع ذلك، قد يكون للتكميم تأثير متباين على جودة الفيديو اعتمادًا على نموذج الفيديو المستخدم.
راجع نظرة عامة حول التكميم لمعرفة المزيد حول محركات التكميم المدعومة واختيار محرك تكميم يدعم حالتك الاستخدامية. يوضح المثال أدناه كيفية تحميل SanaVideoPipeline مُكمَّم للاستدلال باستخدام bitsandbytes.
import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, SanaVideoTransformer3DModel, SanaVideoPipeline
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, AutoModel
quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = AutoModel.from_pretrained(
"Efficient-Large-Model/SANA-Video_2B_480p_diffusers",
subfolder="text_encoder",
quantization_config=quant_config,
dtype=torch.float16,
)
quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = SanaVideoTransformer3DModel.from_pretrained(
"Efficient-Large-Model/SANA-Video_2B_480p_diffusers",
subfolder="transformer",
quantization_config=quant_config,
dtype=torch.float16,
)
pipeline = SanaVideoPipeline.from_pretrained(
"Efficient-Large-Model/SANA-Video_2B_480p_diffusers",
text_encoder=text_encoder_8bit,
transformer=transformer_8bit,
dtype=torch.float16,
device_map="balanced",
)
model_score = 30
prompt = "Evening, backlight, side lighting, soft light, high contrast, mid-shot, centered composition, clean solo shot, warm color. A young Caucasian man stands in a forest, golden light glimmers on his hair as sunlight filters through the leaves. He wears a light shirt, wind gently blowing his hair and collar, light dances across his face with his movements. The background is blurred, with dappled light and soft tree shadows in the distance. The camera focuses on his lifted gaze, clear and emotional."
negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience."
motion_prompt = f" motion score: {model_score}."
prompt = prompt + motion_prompt
output = pipeline(
prompt=prompt,
negative_prompt=negative_prompt,
height=480,
width=832,
num_frames=81,
guidance_scale=6.0,
num_inference_steps=50
).frames[0]
export_to_video(output, "sana-video-output.mp4", fps=16)SanaVideoPipeline
فئة diffusers.SanaVideoPipeline
< source >( tokenizer: GemmaTokenizertext_encoder: Gemma2PreTrainedModelvae: diffusers.models.autoencoders.autoencoder_dc.AutoencoderDC | diffusers.models.autoencoders.autoencoder_kl_ltx2.AutoencoderKLLTX2Video | diffusers.models.autoencoders.autoencoder_kl_wan.AutoencoderKLWantransformer: SanaVideoTransformer3DModelscheduler: DPMSolverMultistepScheduler )
المعاملات
- tokenizer (
GemmaTokenizerأوGemmaTokenizerFast) — المجزّئ المستخدم لتجزئة الاستعلام. - text_encoder (
Gemma2PreTrainedModel) — نموذج ترميز النص لتشفير أوامر الإدخال. - vae ([
AutoencoderKLWan،AutoencoderDC، أوAutoencoderKLLTX2Video]) — نموذج الترميز التبايني التلقائي (VAE) لتشفير وفك تشفير مقاطع الفيديو إلى تمثيلات كامنة ومنها. - transformer (SanaVideoTransformer3DModel) — نموذج Transformer مشروط لإزالة الضوضاء من المتغيرات الكامنة المدخلة.
- scheduler (DPMSolverMultistepScheduler) —
جدول زمني يُستخدم بالاقتران مع
transformerلإزالة الضوضاء من كائنات الفيديو المُرمّزة.
خط أنابيب لتوليد الفيديو من النص باستخدام Sana. يرث هذا النموذج من DiffusionPipeline. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المنفذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).
__call__
< source >( prompt: str | list[str] = Nonenegative_prompt: str = ''num_inference_steps: int = 50timesteps: list = Nonesigmas: list = Noneguidance_scale: float = 6.0num_videos_per_prompt: int | None = 1height: int = 480width: int = 832frames: int = 81eta: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueclean_caption: bool = Falseuse_resolution_binning: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 300complex_human_instruction: list = ["Given a user prompt, generate an 'Enhanced prompt' that provides detailed visual descriptions suitable for video generation. Evaluate the level of detail in the user prompt:", '- If the prompt is simple, focus on adding specifics about colors, shapes, sizes, textures, motion, and temporal relationships to create vivid and dynamic scenes.', '- If the prompt is already detailed, refine and enhance the existing details slightly without overcomplicating.', 'Here are examples of how to transform or refine prompts:', '- User Prompt: A cat sleeping -> Enhanced: A small, fluffy white cat slowly settling into a curled position, peacefully falling asleep on a warm sunny windowsill, with gentle sunlight filtering through surrounding pots of blooming red flowers.', '- User Prompt: A busy city street -> Enhanced: A bustling city street scene at dusk, featuring glowing street lamps gradually lighting up, a diverse crowd of people in colorful clothing walking past, and a double-decker bus smoothly passing by towering glass skyscrapers.', 'Please generate only the enhanced description for the prompt below and avoid including any additional commentary or evaluations:', 'User Prompt: '] ) → SanaVideoPipelineOutput or tuple
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الفيديو. إذا لم يُعرَّف، يجب تمريرprompt_embedsبدلاً من ذلك. - negative_prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الفيديو. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). - num_inference_steps (
int، اختياري، القيمة الافتراضية 50) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى فيديو بجودة أعلى على حساب بطء الاستدلال. - timesteps (
list[int], اختياري) — خطوات زمنية مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معاملtimestepsفي طريقةset_timestepsالخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمريرnum_inference_steps. يجب أن تكون بترتيب تنازلي. - sigmas (
list[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معاملsigmasفي طريقةset_timestepsالخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمريرnum_inference_steps. - guidance_scale (
float، اختياري، القيمة الافتراضية 4.5) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّفguidance_scaleعلى أنهwمن المعادلة 2 في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيينguidance_scale > 1. كلما زاد مقياس التوجيه، شجّع ذلك على توليد مقاطع فيديو مرتبطة ارتباطًا وثيقًا بـpromptالنصي، وعادةً على حساب انخفاض جودة الفيديو. - num_videos_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد مقاطع الفيديو التي سيتم توليدها لكل موجه. - height (
int، اختياري، القيمة الافتراضية 480) — ارتفاع الفيديو المولّد بالبكسل. - width (
int، اختياري، القيمة الافتراضية 832) — عرض الفيديو المولّد بالبكسل. - frames (
int، اختياري، القيمة الافتراضية 81) — عدد الإطارات في الفيديو المولّد. - eta (
float، اختياري، القيمة الافتراضية 0.0) — يتوافق مع المعامل eta (η) في ورقة DDIM: https://huggingface.co/papers/2010.02502. ينطبق فقط على schedulers.DDIMScheduler، وسيتم تجاهله في الحالات الأخرى. - generator (
torch.Generatorأوlist[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا. - latents (
torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كائن latents عن طريق الاستخراج باستخدامgeneratorالعشوائي المُقدَّم. - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص. - negative_prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. بالنسبة إلى PixArt-Sigma، يجب أن يكون هذا الموجه السلبي "". إذا لم يُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخالnegative_prompt. - negative_prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص السلبية. - output_type (
str، اختياري، الافتراضي"pil") — صيغة مخرجات الفيديو المولّد. اختر بين mp4 أوnp.array. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاعSanaVideoPipelineOutputبدلاً من tuple عادي. - attention_kwargs —
قاموس kwargs يُمرَّر إلى
AttentionProcessorكما هو معرَّف تحتself.processorفي diffusers.models.attention_processor إذا تمَّ تحديده. - clean_caption (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم تنظيف الوصف قبل إنشاء التضمينات. يتطلب تثبيتbeautifulsoup4وftfy. إذا لم يتم تثبيت الاعتماديات، فسيتم إنشاء التضمينات من النص الخام. - use_resolution_binning (
boolالقيمة الافتراضيةTrue) — إذا تم ضبطها علىTrue، تُخضع الارتفاع والعرض المطلوبان أولاً إلى إسقاط على أقرب دقة باستخدامASPECT_RATIO_480_BINأوASPECT_RATIO_720_BIN. بعد فك ترميز الكامنات الناتجة إلى مقاطع فيديو، يتم تغيير حجمها مرة أخرى إلى الدقة المطلوبة. مفيد لتوليد مقاطع فيديو غير مربعة. - callback_on_step_end (
Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). ستتضمنcallback_kwargsقائمة بجميع المصفوفات كما حددتهاcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, اختياري) — قائمة مدخلات المصفوفات (tensors) لدالةcallback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كحجةcallback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية._callback_tensor_inputsلفئة خط الأنابيب (pipeline) الخاص بك. - max_sequence_length (
intالافتراضي300) — أقصى طول تسلسل يُستخدم معprompt. - complex_human_instruction (
list[str]، اختياري) — تعليمات للانتباه البشري المعقد: https://github.com/NVlabs/Sana/blob/main/configs/sana_app_config/Sana_1600M_app.yaml#L55.
يعيد
SanaVideoPipelineOutput أو tuple
إذا كان return_dict هو True، يُعاد SanaVideoPipelineOutput، وإلا يُعاد tuple حيث يكون العنصر الأول قائمة بالفيديوهات المولّدة
الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.
أمثلة:
>>> import torch
>>> from diffusers import SanaVideoPipeline
>>> from diffusers.utils import export_to_video
>>> pipe = SanaVideoPipeline.from_pretrained("Efficient-Large-Model/SANA-Video_2B_480p_diffusers")
>>> pipe.transformer.to(torch.bfloat16)
>>> pipe.text_encoder.to(torch.bfloat16)
>>> pipe.vae.to(torch.float32)
>>> pipe.to("cuda")
>>> motion_score = 30
>>> prompt = "Evening, backlight, side lighting, soft light, high contrast, mid-shot, centered composition, clean solo shot, warm color. A young Caucasian man stands in a forest, golden light glimmers on his hair as sunlight filters through the leaves. He wears a light shirt, wind gently blowing his hair and collar, light dances across his face with his movements. The background is blurred, with dappled light and soft tree shadows in the distance. The camera focuses on his lifted gaze, clear and emotional."
>>> negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience."
>>> motion_prompt = f" motion score: {motion_score}."
>>> prompt = prompt + motion_prompt
>>> output = pipe(
... prompt=prompt,
... negative_prompt=negative_prompt,
... height=480,
... width=832,
... frames=81,
... guidance_scale=6,
... num_inference_steps=50,
... generator=torch.Generator(device="cuda").manual_seed(42),
... ).frames[0]
>>> export_to_video(output, "sana-video-output.mp4", fps=16)encode_prompt
< source >( prompt: str | list[str]do_classifier_free_guidance: bool = Truenegative_prompt: str = ''num_videos_per_prompt: int = 1device: typing.Optional[torch.device] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneclean_caption: bool = Falsemax_sequence_length: int = 300complex_human_instruction: list[str] | None = Nonelora_scale: float | None = None )
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه الذي سيتم ترميزه - negative_prompt (
strأوlist[str]، اختياري) — الموجّه الذي لا يُستخدم لتوجيه توليد الفيديو. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً منه. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). بالنسبة إلى PixArt-Alpha، يجب أن يكون "". - do_classifier_free_guidance (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم استخدام classifier free guidance أم لا - num_videos_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد الفيديوهات التي يجب توليدها لكل موجه - device — (
torch.device، اختياري): جهاز torch لوضع التضمينات الناتجة عليه - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - negative_prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. بالنسبة إلى Sana، يجب أن تكون تضمينات السلسلة "". - clean_caption (
bool، القيمة الافتراضيةFalse) — إذا كانتTrue، سيقوم الدالة بمعالجة الوصف المقدم وتنظيفه قبل الترميز. - max_sequence_length (
int، القيمة الافتراضية 300) — أقصى طول تسلسل يُستخدم للموجّه. - complex_human_instruction (
list[str])، القيمة الافتراضيةcomplex_human_instruction— إذا لم يكنcomplex_human_instructionفارغًا، فسيستخدم الدالة التعليمات البشرية المعقدة للتلميح.
يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.
SanaImageToVideoPipeline
فئة diffusers.SanaImageToVideoPipeline
< source >( tokenizer: GemmaTokenizertext_encoder: Gemma2PreTrainedModelvae: diffusers.models.autoencoders.autoencoder_dc.AutoencoderDC | diffusers.models.autoencoders.autoencoder_kl_ltx2.AutoencoderKLLTX2Video | diffusers.models.autoencoders.autoencoder_kl_wan.AutoencoderKLWantransformer: SanaVideoTransformer3DModelscheduler: FlowMatchEulerDiscreteScheduler )
المعاملات
- tokenizer (
GemmaTokenizerأوGemmaTokenizerFast) — المجزّئ المستخدم لتجزئة الاستعلام. - text_encoder (
Gemma2PreTrainedModel) — نموذج ترميز النص لتشفير أوامر الإدخال. - vae ([
AutoencoderKLWan،AutoencoderDC، أوAutoencoderKLLTX2Video]) — نموذج الترميز التبايني التلقائي (VAE) لتشفير وفك تشفير مقاطع الفيديو إلى تمثيلات كامنة ومنها. - transformer (SanaVideoTransformer3DModel) — نموذج Transformer مشروط لإزالة الضوضاء من المتغيرات الكامنة المدخلة.
- scheduler (FlowMatchEulerDiscreteScheduler) —
جدول زمني يُستخدم بالاقتران مع
transformerلإزالة الضوضاء من كائنات الفيديو المُرمّزة.
خط أنابيب لتوليد الفيديو من صورة/نص باستخدام Sana. يرث هذا النموذج من DiffusionPipeline. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المنفذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).
__call__
< source >( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]prompt: str | list[str] = Nonenegative_prompt: str = ''num_inference_steps: int = 50timesteps: list = Nonesigmas: list = Noneguidance_scale: float = 6.0num_videos_per_prompt: int | None = 1height: int = 480width: int = 832frames: int = 81eta: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueclean_caption: bool = Falseuse_resolution_binning: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 300complex_human_instruction: list = ["Given a user prompt, generate an 'Enhanced prompt' that provides detailed visual descriptions suitable for video generation. Evaluate the level of detail in the user prompt:", '- If the prompt is simple, focus on adding specifics about colors, shapes, sizes, textures, motion, and temporal relationships to create vivid and dynamic scenes.', '- If the prompt is already detailed, refine and enhance the existing details slightly without overcomplicating.', 'Here are examples of how to transform or refine prompts:', '- User Prompt: A cat sleeping -> Enhanced: A small, fluffy white cat slowly settling into a curled position, peacefully falling asleep on a warm sunny windowsill, with gentle sunlight filtering through surrounding pots of blooming red flowers.', '- User Prompt: A busy city street -> Enhanced: A bustling city street scene at dusk, featuring glowing street lamps gradually lighting up, a diverse crowd of people in colorful clothing walking past, and a double-decker bus smoothly passing by towering glass skyscrapers.', 'Please generate only the enhanced description for the prompt below and avoid including any additional commentary or evaluations:', 'User Prompt: '] ) → SanaVideoPipelineOutput or tuple
المعاملات
- image (
PipelineImageInput) — الصورة المدخلة التي تُشترط عليها توليد الفيديو. سيتم اشتراط الإطار الأول من الفيديو المولّد على هذه الصورة. - prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الفيديو. إذا لم يُعرَّف، يجب تمريرprompt_embedsبدلاً من ذلك. - negative_prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الفيديو. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). - num_inference_steps (
int، اختياري، القيمة الافتراضية 50) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى فيديو بجودة أعلى على حساب بطء الاستدلال. - timesteps (
list[int], اختياري) — خطوات زمنية مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معاملtimestepsفي طريقةset_timestepsالخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمريرnum_inference_steps. يجب أن تكون بترتيب تنازلي. - sigmas (
list[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معاملsigmasفي طريقةset_timestepsالخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمريرnum_inference_steps. - guidance_scale (
float، اختياري، القيمة الافتراضية 4.5) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّفguidance_scaleعلى أنهwمن المعادلة 2 في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيينguidance_scale > 1. كلما زاد مقياس التوجيه، شجّع ذلك على توليد مقاطع فيديو مرتبطة ارتباطًا وثيقًا بـpromptالنصي، وعادةً على حساب انخفاض جودة الفيديو. - num_videos_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد مقاطع الفيديو التي سيتم توليدها لكل موجه. - height (
int، اختياري، القيمة الافتراضية 480) — ارتفاع الفيديو المولّد بالبكسل. - width (
int، اختياري، القيمة الافتراضية 832) — عرض الفيديو المولّد بالبكسل. - frames (
int، اختياري، القيمة الافتراضية 81) — عدد الإطارات في الفيديو المولّد. - eta (
float، اختياري، القيمة الافتراضية 0.0) — يتوافق مع المعامل eta (η) في ورقة DDIM: https://huggingface.co/papers/2010.02502. ينطبق فقط على schedulers.DDIMScheduler، وسيتم تجاهله في الحالات الأخرى. - generator (
torch.Generatorأوlist[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا. - latents (
torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الفيديو. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم إنشاء كائن latents عن طريق الاستخراج باستخدامgeneratorالعشوائي المُقدَّم. - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص. - negative_prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. بالنسبة إلى PixArt-Sigma، يجب أن يكون هذا الموجه السلبي "". إذا لم يُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخالnegative_prompt. - negative_prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه المُولَّد مسبقًا لتضمينات النص السلبية. - output_type (
str، اختياري، الافتراضي"pil") — صيغة مخرجات الفيديو المولّد. اختر بين mp4 أوnp.array. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاعSanaVideoPipelineOutputبدلاً من tuple عادي. - attention_kwargs —
قاموس kwargs يُمرَّر إلى
AttentionProcessorكما هو معرَّف تحتself.processorفي diffusers.models.attention_processor إذا تمَّ تحديده. - clean_caption (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم تنظيف الوصف قبل إنشاء التضمينات. يتطلب تثبيتbeautifulsoup4وftfy. إذا لم يتم تثبيت الاعتماديات، فسيتم إنشاء التضمينات من النص الخام. - use_resolution_binning (
boolالقيمة الافتراضيةTrue) — إذا تم ضبطها علىTrue، تُخضع الارتفاع والعرض المطلوبان أولاً إلى إسقاط على أقرب دقة باستخدامASPECT_RATIO_480_BINأوASPECT_RATIO_720_BIN. بعد فك ترميز الكامنات الناتجة إلى مقاطع فيديو، يتم تغيير حجمها مرة أخرى إلى الدقة المطلوبة. مفيد لتوليد مقاطع فيديو غير مربعة. - callback_on_step_end (
Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). ستتضمنcallback_kwargsقائمة بجميع المصفوفات كما حددتهاcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, اختياري) — قائمة مدخلات المصفوفات (tensors) لدالةcallback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كحجةcallback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية._callback_tensor_inputsلفئة خط الأنابيب (pipeline) الخاص بك. - max_sequence_length (
intالافتراضي300) — أقصى طول تسلسل يُستخدم معprompt. - complex_human_instruction (
list[str]، اختياري) — تعليمات للانتباه البشري المعقد: https://github.com/NVlabs/Sana/blob/main/configs/sana_app_config/Sana_1600M_app.yaml#L55.
يعيد
SanaVideoPipelineOutput أو tuple
إذا كان return_dict هو True، يُعاد SanaVideoPipelineOutput، وإلا يُعاد tuple حيث يكون العنصر الأول قائمة بالفيديوهات المولّدة
الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.
أمثلة:
>>> import torch
>>> from diffusers import SanaImageToVideoPipeline
>>> from diffusers.utils import export_to_video, load_image
>>> pipe = SanaImageToVideoPipeline.from_pretrained("Efficient-Large-Model/SANA-Video_2B_480p_diffusers")
>>> pipe.transformer.to(torch.bfloat16)
>>> pipe.text_encoder.to(torch.bfloat16)
>>> pipe.vae.to(torch.float32)
>>> pipe.to("cuda")
>>> motion_score = 30
>>> prompt = "A woman stands against a stunning sunset backdrop, her long, wavy brown hair gently blowing in the breeze. She wears a sleeveless, light-colored blouse with a deep V-neckline, which accentuates her graceful posture. The warm hues of the setting sun cast a golden glow across her face and hair, creating a serene and ethereal atmosphere. The background features a blurred landscape with soft, rolling hills and scattered clouds, adding depth to the scene. The camera remains steady, capturing the tranquil moment from a medium close-up angle."
>>> negative_prompt = "A chaotic sequence with misshapen, deformed limbs in heavy motion blur, sudden disappearance, jump cuts, jerky movements, rapid shot changes, frames out of sync, inconsistent character shapes, temporal artifacts, jitter, and ghosting effects, creating a disorienting visual experience."
>>> motion_prompt = f" motion score: {motion_score}."
>>> prompt = prompt + motion_prompt
>>> image = load_image("https://raw.githubusercontent.com/NVlabs/Sana/refs/heads/main/asset/samples/i2v-1.png")
>>> output = pipe(
... image=image,
... prompt=prompt,
... negative_prompt=negative_prompt,
... height=480,
... width=832,
... frames=81,
... guidance_scale=6,
... num_inference_steps=50,
... generator=torch.Generator(device="cuda").manual_seed(42),
... ).frames[0]
>>> export_to_video(output, "sana-ti2v-output.mp4", fps=16)encode_prompt
< source >( prompt: str | list[str]do_classifier_free_guidance: bool = Truenegative_prompt: str = ''num_videos_per_prompt: int = 1device: typing.Optional[torch.device] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneclean_caption: bool = Falsemax_sequence_length: int = 300complex_human_instruction: list[str] | None = Nonelora_scale: float | None = None )
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه الذي سيتم ترميزه - negative_prompt (
strأوlist[str]، اختياري) — الموجّه الذي لا يُستخدم لتوجيه توليد الفيديو. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً منه. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). بالنسبة إلى PixArt-Alpha، يجب أن يكون "". - do_classifier_free_guidance (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم استخدام classifier free guidance أم لا - num_videos_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد الفيديوهات التي يجب توليدها لكل موجه - device — (
torch.device، اختياري): جهاز torch لوضع التضمينات الناتجة عليه - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - negative_prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. بالنسبة إلى Sana، يجب أن تكون تضمينات السلسلة "". - clean_caption (
bool، القيمة الافتراضيةFalse) — إذا كانتTrue، سيقوم الدالة بمعالجة الوصف المقدم وتنظيفه قبل الترميز. - max_sequence_length (
int، القيمة الافتراضية 300) — أقصى طول تسلسل يُستخدم للموجّه. - complex_human_instruction (
list[str])، القيمة الافتراضيةcomplex_human_instruction— إذا لم يكنcomplex_human_instructionفارغًا، فسيستخدم الدالة التعليمات البشرية المعقدة للتلميح.
يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.
SanaVideoPipelineOutput
فئة diffusers.pipelines.sana_video.pipeline_output.SanaVideoPipelineOutput
< source >( frames: Tensor )
المعاملات
- frames (
torch.Tensorأوnp.ndarrayأو قائمة[قائمة[PIL.Image.Image]]) — قائمة من مخرجات الفيديو - يمكن أن تكون قائمة متداخلة بطولbatch_size,حيث تحتوي كل قائمة فرعية على سلاسل صور PIL منزوعة الضوضاء بطولnum_frames.كما يمكن أن تكون مصفوفة NumPy أو متجه Torch من الشكل(batch_size, num_frames, channels, height, width).
فئة الإخراج لخطوط أنابيب Sana-Video.