Buckets:
#
# مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص")
# لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص.
# يمكنك الحصول على نسخة من الترخيص في
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات
# تُوزَّع بموجب الرخصة على أساس "كما هي"،
# بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية.
# راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و
# قيود بموجب الترخيص. -->
# Cosmos 3
NVIDIA Cosmos 3 هو نموذج أساسي موحّد للعالم (WFM) للذكاء الاصطناعي الفيزيائي — وهو نموذج شامل واحد يجمع بين توليد العالم، والاستدلال الفيزيائي، وتوليد الإجراءات. إنه يحل محل نماذج التنبؤ، والاستدلال، والنقل المنفصلة من إصدارات Cosmos السابقة: سواء كنت تبني حلولاً للروبوتات، أو المركبات ذاتية القيادة، أو المساحات الذكية، فإن Cosmos 3 يمنحك أساساً واحداً لمحاكاة العالم الفيزيائي وفهمه.
ما يُشحن مع هذا الإصدار:
- النماذج على Hugging Face Hub مع بطاقات النماذج وترخيص
- تكامل Cosmos 3 Diffusers في خطوط أنابيب التوليد (هذه الصفحة)
- سكربتات ما بعد التدريب لضبط Cosmos 3 على بياناتك الخاصة
- مجموعات بيانات مفتوحة لتوليد البيانات الاصطناعية (SDG) للذكاء الاصطناعي الفيزيائي
## ما الجديد في Cosmos 3
أبرز تغيير عن إصدارات Cosmos السابقة هو أن Cosmos 3 هو *نموذج شامل*، مبني على بنية مزيج التحويلات (Mixture-of-Transformers، MoT). سابقًا، كان المطورون يعملون مع نماذج منفصلة لتوليد العالم (Predict)، والتوليد المُتحكَّم به (Transfer)، وفهم المشهد (Reason)، وتوليد سياسات الإجراء. يوحّد Cosmos 3 جميع هذه الوظائف في نموذج واحد يستنتج ويولّد عبر الأنماط المختلفة في تمريرة أمامية واحدة.
من نموذج واحد يمكنك:
- إنشاء عوالم فيديو فيزيائية معقولة من نصوص أو صور أو مدخلات إجراء (تحويل الصورة إلى فيديو، تحويل النص إلى فيديو، توليد فيديو مشروط بالإجراء).
- التفكير في الخصائص الفيزيائية مثل الحركة والسببية والعلاقات المكانية.
- تنبؤ بالتسلسلات المستقبلية للفيديو والإجراءات من الحالة الحالية.
- نقل المشاهد عبر نقاط نظر وظروف مختلفة مع تحكم هيكلي *(قريباً)*.
في الخلفية، يعمل نموذج `Cosmos3OmniTransformer` واحد على نموذج لغوي بنمط Qwen بالتوازي مع مسار توليد بالانتشار: حيث تمر رموز النص عبر تدفق "فهم" سببي، بينما تمر الكمونات (latents) الخاصة بالفيديو والصوت عبر تدفق "توليد" ذي انتباه ثنائي الاتجاه، وتُدمج معًا بواسطة RoPE متعدد الوسائط ثلاثي الأبعاد. راجع [ورقة Cosmos World Foundation Model Platform](https://huggingface.co/papers/2501.03575) للاطلاع على الخلفية المعمارية.
## نقاط التفتيش المتاحة
تم إصدار نقطتي تفتيش على الـ Hub — [`nvidia/Cosmos3-Nano`](https://huggingface.co/nvidia/Cosmos3-Nano) (أصغر حجمًا وأسرع) و [`nvidia/Cosmos3-Super`](https://huggingface.co/nvidia/Cosmos3-Super) (أكبر حجمًا وجودة أعلى). تدعم فئة خط الأنابيب نفسها تحويل النص إلى صورة، وتحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، و(مع نقطة تفتيش تدعم الصوت) تحويل النص والصورة إلى فيديو مع صوت — اختر مستودعًا واستخدم تبويب النموذج الخاص بكل سير عمل أدناه.
> [!TIP]
> تأكد من الاطلاع على [دليل المجدولين](../../using-diffusers/schedulers) لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم [إعادة استخدام المكونات عبر خطوط الأنابيب](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.
## إزالة الضوضاء المختلطة FP8 W8A8/W8A16
نُشر نقاط التفتيش الرسمية لـ ModelOpt FP8 الخاصة بـ Nano و Super و Edge كمستودعات Hub مستقلة: [`nvidia/Cosmos3-Nano-FP8`](https://huggingface.co/nvidia/Cosmos3-Nano-FP8)، و [`nvidia/Cosmos3-Super-FP8`](https://huggingface.co/nvidia/Cosmos3-Super-FP8)، و [`nvidia/Cosmos3-Edge-FP8`](https://huggingface.co/nvidia/Cosmos3-Edge-FP8). حمّل `main` من مستودع FP8. لا يتوفر لمستودع [`nvidia/Cosmos3-Super-Image2Video`](https://huggingface.co/nvidia/Cosmos3-Super-Image2Video) مستودع FP8 منفصل؛ حمّله باستخدام `revision="fp8"`.
جميع هذه نقاط التفتيش مُكمّمة بالطريقة نفسها. يستخدم **W8A8** أوزانًا بدقة 8 بت وتنشيطات بدقة 8 بت (GEMM المُستعاد من ModelOpt). يعيد **W8A16** استخدام تلك الأوزان ذاتها بدقة 8 بت لكنه يتخطى كمّمة التنشيطات: يتم فك كمّمة الوزن FP8 ويُنفَّذ خطي قياسي على تنشيطات BF16/FP16/FP32.
قد يؤدي تشغيل W8A8 في كل خطوة إلى ظهور وميض واضح في توليد الفيديو متعدد الخطوات. لذلك، تُعلن نقاط التفتيش الخاصة بالفيديو Nano وSuper وSuper-I2V وEdge FP8 عن جدول في `transformer/config.json`: **W8A16 في أول 3 خطوات وآخر 3 خطوات**، **W8A8 في المنتصف**. تقرأ مكتبة Diffusers هذه الأعداد من نقطة التفتيش بدلاً من تثبيتها في الكود. يتم اختيار الدقة مرة واحدة لكل خطوة من خطوات المجدول (scheduler) بحيث تتطابق استدعاءات cond/uncond الخاصة بالإرشاد الحر من التصنيف (classifier-free guidance).
لا تُظهر عمليات توليد الصور ونقاط التفتيش المُقطّرة بعدد خطوات قليلة ذلك الوميض، لذا فإن مستودع Super-T2I ومستودعات FP8 المُقطّرة ذات الخطوات الأربع لا تُعلن عن جدول زمني وتبقى على وضع W8A8 في كل خطوة. كما أن الجدول الزمني خاص بـ **ModelOpt FP8 فقط**: فواجهات الكمّية الأخرى (مثل TorchAO) تحافظ على عملياتها الأمامية الأصلية.
حمّل مستودع FP8 بمسار الاستعادة نفسه كما في [دليل ModelOpt](../../quantization/modelopt). يحتوي المستودع بالفعل على إعدادات التكميم. ثم يتبع الدقة المختلطة نقطة التفتيش تلقائيًا:
```python
import torch
from diffusers import Cosmos3OmniPipeline
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano-FP8",
dtype=torch.bfloat16,
device_map="cuda",
)
result = pipe(prompt="...", num_inference_steps=35)
```
خياران في وقت التوليد:
- **افتراضي** (`mixed_precision_format=None`): إذا كان ملف الحفظ (checkpoint) يُعلن عن `diffusion_step_policy`، فسيتم تشغيل W8A16 في الخطوات الأولى/الأخيرة N، وW8A8 الأصلية في الخطوات الوسطى. هذه هي الوصفة المقصودة لـ **فيديو** متعدد الخطوات FP8 (يقلل من الوميض مقارنةً باستخدام W8A8 بالكامل). أما نماذج FP8 المُقطّرة ذات الخطوات الأربع وSuper-T2I FP8 فتستثني السياسة، لذا فإن الوضع الافتراضي هو W8A8 بالكامل بالفعل.
- **`mixed_precision_format="none"`**: يُبقي كل خطوة على W8A8 الأصلي. أسرع، لأن W8A16 هو إلغاء تكميم + `torch.nn.functional.linear` بدلاً من GEMM FP8 المُستعاد، لكن الفيديو متعدد الخطوات قد يرتجف. استخدم هذا لاختبار جدولة A/B أو لمطابقة خط أساس مُكمَّم بالكامل.
على محطة عمل واحدة من Blackwell، كان Cosmos3-Nano-FP8 بدقة 720×1280 / 35 خطوة أبطأ بنسبة **27%** تقريبًا (T2I) وأبطأ بنسبة **13%** (T2V بإطار 49) مع الجدول المختلط الافتراضي مقارنةً باستخدام `"none"`. هذه الأرقام ليست ضمانًا لمعدل الإنتاجية. مرّر `"fp8"` فقط لفرض جدول أول/آخر N على نقطة تحقق ModelOpt FP8 التي لا تحتوي على سياسة.
## توسيع عينات المحفّز
تم تدريب Cosmos 3 على عناوين وصفية طويلة ومفصّلة للغاية. للحصول على جودة مثالية، يجب **توسيع نصوص الأوامر القصيرة إلى بنية JSON محددة** قبل تمريرها إلى خط المعالجة. يتوفر مُوسّع النصوص في حزمة [cosmos-framework](https://github.com/NVIDIA/cosmos-framework).
ابدأ من موجه نصي قصير بسيط واحفظه في `assets/prompt.txt`. في مثال النص إلى الفيديو أدناه، الموجه الأصلي هو *"ذراع روبوتية تنظف طبقاً في مطبخ"*:
```bash
mkdir -p assets
echo "A robotic arm is cleaning a plate in a kitchen" > assets/prompt.txt
```
ثم ثبّت الإطار وشغّل مُعظّم الدقة. يُعظّم المثال أدناه الدقة لتوليد الفيديو من النص باستخدام Opus-4.6:
```bash
git clone https://github.com/NVIDIA/cosmos-framework.git packages/cosmos-framework
pip install -e packages/cosmos-framework
export PROMPT_UPSAMPLER_ENDPOINT_URL="https://api.anthropic.com/v1/"
export PROMPT_UPSAMPLER_MODEL_NAME="claude-opus-4-6"
export PROMPT_UPSAMPLER_API_TOKEN="<your_token>"
python -m cosmos_framework.inference.prompt_upsampling \
--input assets/prompt.txt \
--output assets/example_t2v_prompt.json \
--mode text2video \
--endpoint-url "${PROMPT_UPSAMPLER_ENDPOINT_URL}" \
--model "${PROMPT_UPSAMPLER_MODEL_NAME}" \
--api-token "${PROMPT_UPSAMPLER_API_TOKEN}" \
--resolution 720 \
--aspect-ratio "16,9"
```
بدّل `--mode` ليتوافق مع سير العمل الذي تستهدفه (`text2image`، `text2video`، `image2video`). تكتب الأوامر الموجهات المُوسَّعة إلى ملف `--output` كمصفوفة JSON (كائن واحد لكل سطر غير فارغ في `--input`)؛ مرّر مسار `.jsonl` بدلاً من ذلك للحصول على كائن JSON واحد لكل سطر. فيما يتعلق بـ`image2video`، يجب عليك أيضاً تقديم صورة الشرط عبر `--image-url` (رابط URL أو مسار محلي) أو `--image-list` (صورة واحدة لكل موجه).
يُوفَّر موجه إيجابي مُوسَّع مسبقًا (`assets/example_t2v_prompt.json`) وموجه سلبي (`assets/negative_prompt.json`) لتسهيل الاستخدام، وتُستخدم في أمثلة التوليد أدناه. تقوم الأمثلة بتحميل هذه الملفات بصيغة JSON وتمريرها إلى خط الأنابيب كنصوص JSON عبر `json.dumps(...)`.
## النص إلى فيديو
توليد متعدد الإطارات مشروط بالنص فقط. اختر `num_frames` بناءً على المدة المستهدفة — القيمة الافتراضية `num_frames=189` تنتج ≈ 7.9 ثانية عند 24 إطارًا في الثانية. يتم قراءة الموجه والموجه السلبي من ملفات JSON المُحسَّنة الموصوفة في [تحسين الموجهات](#prompt-upsampling).
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
num_frames=189,
height=720,
width=1280,
num_inference_steps=35,
guidance_scale=6.0,
fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_t2v.mp4", fps=24, macro_block_size=1)
```
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
num_frames=189,
height=720,
width=1280,
num_inference_steps=35,
guidance_scale=6.0,
fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_t2v.mp4", fps=24, macro_block_size=1)
```
## النص إلى صورة
توليد إطار واحد. يُشترط على النموذج فقط على موجه النص؛ مرّر `num_frames=1`. استخدم `--mode text2image` لرفع الدقة وإنتاج موجه JSON.
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
# JSON-upsampled prompt (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2i_prompt.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
result = pipe(prompt=json.dumps(json_prompt), num_frames=1, height=720, width=1280)
result.video[0].save("cosmos3_t2i.jpg", format="JPEG", quality=85)
```
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
# JSON-upsampled prompt (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2i_prompt.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
result = pipe(prompt=json.dumps(json_prompt), num_frames=1, height=720, width=1280)
result.video[0].save("cosmos3_t2i.jpg", format="JPEG", quality=85)
```
## من الصورة إلى الفيديو
مرّر صورة شرطية عبر `image=`. يقوم خط الأنابيب بتثبيت الإطار 0 على الصورة المُقدَّمة وإزالة الضوضاء عن بقية الإطارات. يتم تغيير حجم الصورة مع الحفاظ على نسبة أبعادها، ثم يُجرى اقتطاع مركزي إلى حجم الإخراج المطلوب، وتُطبَّع باستخدام تقريب مكافئ لـ uint8. استخدم `--mode image2video` لرفع الدقة وإنتاج موجه JSON.
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import export_to_video, load_image
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_i2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
image = load_image(
"https://github.com/nvidia-cosmos/cosmos-dependencies/releases/download/assets/robot_153.jpg"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
image=image,
num_frames=189,
height=720,
width=1280,
fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_i2v.mp4", fps=24, macro_block_size=1)
```
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import export_to_video, load_image
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_i2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
image = load_image(
"https://github.com/nvidia-cosmos/cosmos-dependencies/releases/download/assets/robot_153.jpg"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
image=image,
num_frames=189,
height=720,
width=1280,
fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_i2v.mp4", fps=24, macro_block_size=1)
```
## من فيديو إلى فيديو
مرّر مقطعًا شرطيًا عبر `video=` (مثلًا من `load_video`). يقوم خط المعالجة بتثبيت الإطارات الكامنة الرائدة المحددة بواسطة `condition_frame_indexes_vision` (الافتراضي `[0, 1]`) على المقطع، ثم يُزيل الضوضاء عن بقية الإطارات. استخدم `condition_video_keep` (`"first"` أو `"last"`) لاختيار أي طرف من مقطع المصدر الأطول تُؤخذ منه الإطارات الشرطية. وكما هو الحال مع الأوضاع الأخرى، يجب أن يتبع الأمر البصري البنية الوصفية بصيغة JSON الموضحة في [توسيع الأوامر البصرية](#prompt-upsampling).
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
video=video,
condition_frame_indexes_vision=[0, 1],
condition_video_keep="first",
num_frames=189,
height=720,
width=1280,
num_inference_steps=35,
guidance_scale=6.0,
fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_v2v.mp4", fps=24, macro_block_size=1)
```
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
video=video,
condition_frame_indexes_vision=[0, 1],
condition_video_keep="first",
num_frames=189,
height=720,
width=1280,
num_inference_steps=35,
guidance_scale=6.0,
fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_v2v.mp4", fps=24, macro_block_size=1)
```
## من فيديو إلى فيديو مع الصوت
عندما تحتوي نقطة التفتيش على `sound_tokenizer`، أضف `enable_sound=True` إلى استدعاء تحويل الفيديو إلى فيديو لتوليد مسار صوتي متزامن بشكل مشترك. يُعاد الموجة الصوتية إلى جانب الفيديو ويمكن دمجها في ملف MP4 باستخدام [encode_video()](/docs/diffusers/main/ar/api/utilities#diffusers.utils.encode_video).
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import encode_video, load_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
video=video,
condition_frame_indexes_vision=[0, 1],
condition_video_keep="first",
num_frames=189,
height=720,
width=1280,
fps=24.0,
enable_sound=True,
)
encode_video(
result.video,
fps=24,
audio=result.sound,
audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
output_path="cosmos3_v2v_with_sound.mp4",
)
```
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import encode_video, load_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
video=video,
condition_frame_indexes_vision=[0, 1],
condition_video_keep="first",
num_frames=189,
height=720,
width=1280,
fps=24.0,
enable_sound=True,
)
encode_video(
result.video,
fps=24,
audio=result.sound,
audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
output_path="cosmos3_v2v_with_sound.mp4",
)
```
## نص إلى فيديو مع صوت
عندما يحمل نقطة التفتيش `sound_tokenizer`، مرّر `enable_sound=True` لتوليد مسار صوتي متزامن بشكل مشترك. يُعاد الموجة الصوتية إلى جانب الفيديو ويمكن دمجها في ملف MP4 باستخدام [encode_video()](/docs/diffusers/main/ar/api/utilities#diffusers.utils.encode_video).
هذا هو نفس الاستدعاء الموجود في مثال النص إلى الفيديو أعلاه مع إضافة `enable_sound=True`:
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import encode_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_sound_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
num_frames=189,
height=720,
width=1280,
fps=24.0,
enable_sound=True,
)
encode_video(
result.video,
fps=24,
audio=result.sound,
audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
output_path="cosmos3_with_sound.mp4",
)
```
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import encode_video
# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_sound_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
result = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
num_frames=189,
height=720,
width=1280,
fps=24.0,
enable_sound=True,
)
encode_video(
result.video,
fps=24,
audio=result.sound,
audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
output_path="cosmos3_with_sound.mp4",
)
```
## التوليد المشروط بالإجراء
تجمع عملية Action كل مدخلات محددة الإجراء في [CosmosActionCondition](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.CosmosActionCondition) تُمرَّر عبر الحجة `action` بدلاً من الحجج العليا `image` / `video` / `height` / `width`. اضبط `resolution_tier` (`256`/`480`/`704`/`720`) قريباً من الدقة الأصلية لفيديو الإدخال؛ فهو يختار لوحة التكييف. يدعم Cosmos 3 ثلاثة أوضاع للإجراء — `policy` و`forward_dynamics` و`inverse_dynamics`. يعتمد وضع `policy` ووضع `forward_dynamics` على الإطار الأول فقط (لذا يعمل كل من `image` و`video`)، بينما يتطلب وضع `inverse_dynamics` فيديو `video`. يُضبط فيديو التكييف لعملية الإجراء على `action.video` (أو `action.image`)، وليس على الحجة العليا `video` في خط الأنابيب.
مرّر وصفًا بسيطًا للمهمة كـ`prompt` واختر الكاميرا عبر `action.view_point` (الافتراضي `"ego_view"`؛ وكذلك `"third_person_view"`، `"wrist_view"`، `"concat_view"`). يحوّل خط الأنابيب هذه المدخلات إلى وصف JSON مُهيكِل تم تدريب النموذج عليه، لذا يجب ألا تكون أوامر الإجراءات مُوسَّعة بواسطة LLM.
### سياسة الإجراء
تتنبأ توليد سياسة الإجراء بعلامات الفيديو والإجراءات المستقبلية انطلاقًا من إطار الملاحظة الأول، والموجّه النصي، وبيانات الوصف الخاصة بمجال الإجراء. يستخدم المثال أدناه مجال روبوت Bridge ويكتب شريحة الإجراء المتنبأ بها إلى ملف JSON في فضاء الإجراء المعيارية للنموذج.
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline, CosmosActionCondition
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
prompt = "Put the pot to the left of the purple item."
video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/action/bridge_20260501_0.mp4"
)
result = pipe(
prompt=prompt,
action=CosmosActionCondition(
mode="policy",
chunk_size=16,
domain_name="bridge_orig_lerobot",
resolution_tier=480,
video=video,
view_point="ego_view",
),
fps=5,
num_inference_steps=30,
guidance_scale=1.0,
use_system_prompt=False,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "sample.mp4", fps=5, macro_block_size=1)
if result.action is not None:
with open("sample_action.json", "w") as f:
json.dump(result.action[0].tolist(), f)
```
```python
import json
import torch
from diffusers import Cosmos3OmniPipeline, CosmosActionCondition
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda" # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
prompt = "Put the pot to the left of the purple item."
video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/action/bridge_20260501_0.mp4"
)
result = pipe(
prompt=prompt,
action=CosmosActionCondition(
mode="policy",
chunk_size=16,
domain_name="bridge_orig_lerobot",
resolution_tier=480,
video=video,
view_point="ego_view",
),
fps=5,
num_inference_steps=30,
guidance_scale=1.0,
use_system_prompt=False,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "sample.mp4", fps=5, macro_block_size=1)
if result.action is not None:
with open("sample_action.json", "w") as f:
json.dump(result.action[0].tolist(), f)
```
## SeaCache
SeaCache معطّل افتراضيًا. يدعم Cosmos 3 تفعيله صراحةً باستخدام [SeaCacheConfig](/docs/diffusers/main/ar/api/cache#diffusers.SeaCacheConfig). يعيد SeaCache استخدام بقايا محوّلات التحويل (transformer residuals) عندما يتغير مؤشر Spectral-Evolution-Aware ببطء، مما يقلل عدد مرات تنفيذ محوّلات التحويل الكاملة. يحسب المؤشر من كامنات الرؤية الخام، بما في ذلك إطارات التكييف النظيفة لتوليد الفيديو من الصورة. فعّله على محوّل التحويل باستخدام مستدعات البيانات الوصفية للمجدول من خط الأنابيب:
```python
import torch
from diffusers import Cosmos3OmniPipeline, SeaCacheConfig
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"
)
pipe.transformer.enable_cache(SeaCacheConfig(threshold=0.2, max_consecutive_cached=2))
```
يعمل واجهة برمجة التطبيقات (API) على مستوى النموذج نفسه مع [Cosmos3OmniPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline) و[Cosmos3OmniModularPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) و[Cosmos3DistilledModularPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3DistilledModularPipeline). SeaCache تقريبي وقد يُغيّر المخرجات المولّدة. عطّله باستخدام `pipe.transformer.disable_cache()` عندما تحتاج إلى تنفيذ كل خطوة إزالة الضوضاء عبر المحوّل الكامل. يُعاد ضبط حالة الكاش بعد كل استدعاء للخطّ، وتحتفظ فروع التوجيه الشرطي وغير الشرطي بسجلات مستقلة.
يحافظ Cosmos 3 على بوابة SeaCache خارج طبقات المُفكِّك المتكررة، مما يجعله متوافقًا مع التجميع الإقليمي. قم بتجميع الطبقات بعد تمكين ذاكرة التخزين المؤقت:
```python
pipe.transformer.compile_repeated_blocks(fullgraph=True)
```
يدعم SeaCache أيضًا أدوات Ulysses الخاصة بالتوازي السياقي وDTensor الخاصة بالتوازي التّنسوري لنموذج Cosmos 3، والمُوثَّقة أدناه. يتم مزامنة قرارات التخزين المؤقت عبر الرتب. ولا يُدَّعى دعم تجميع النموذج الكامل أو استراتيجيات تقسيم النموذج الأخرى.
## توازي السياق
في حالة مقاطع الفيديو الطويلة أو الدقة العالية، قد يتجاوز المرور الأمامي الواحد ميزانية الذاكرة وزمن الاستجابة الخاصة بوحدة معالجة رسومية واحدة. يدعم Cosmos 3 **التوازي السياقي (CP)** لتقسيم بُعد التسلسل عبر وحدات معالجة رسومية متعددة، مما يقسم حساب الانتباه بحيث تحتفظ كل وحدة بشريحة من الرموز فقط.
يدعم Cosmos 3 توازياً سياقياً عبر **Ulysses** (تبادل تسلسلي/رؤوس بين الجميع). ولا يُدعم الانتباه الحلقي (Ring attention).
Unlike most diffusers models, Cosmos 3 does **not** wire CP into the transformer or the declarative `enable_parallelism()` path: its grouped-query attention, separate understanding/generation streams (the generation stream attends to both), and ragged per-stream lengths can't be expressed as a `_cp_plan`. Instead, the model exposes small no-op shard/gather seams, and the implementation lives in [`examples/cosmos3/cosmos_parallel.py`](https://github.com/huggingface/diffusers/blob/main/examples/cosmos3/cosmos_parallel.py) — a self-contained module you can read end to end and adapt. It offers two orthogonal, composable sharding axes:
| مساعد | شرائح | يُستخدم في |
|---|---|---|
| `enable_cosmos3_context_parallel(transformer, cp_mesh)` | التسلسل (CP / Ulysses) | زمن الاستجابة على نموذج يتسع على وحدة معالجة رسومية واحدة (`Nano`) |
| `enable_cosmos3_tensor_parallel(transformer, tp_mesh)` | الأوزان (TP) | تدريب نموذج لا يتسع على وحدة معالجة رسومية واحدة (`Super`) |
استخدم أيًّا منهما بمفرده أو كلاهما معًا على شبكة ثنائية الأبعاد `(tp, cp)` (انظر [ملاءمة النماذج الكبيرة باستخدام التوازي على مستوى الموترات](#fitting-large-models-with-tensor-parallelism)).
هناك متطلبان محددان لـ Cosmos 3:
- استخدم واجهة `native` الانتباه. يستخدم Cosmos 3 انتباه الاستعلام المجمّع (GQA)، وواجهة SDPA الأصلية هي الوحيدة التي تقبل `enable_gqa` (يرفضها cuDNN وflash). تقوم الدوال المساعدة بتوسيع رؤوس KV إلى عدد رؤوس الاستعلام وتستدعي SDPA مع `enable_gqa=False` حتى تستمر في التوجيه إلى نواة flash (فإن كان المسار البديل الرياضي سيُنتج مصفوفة كاملة من الدرجات `[S, S]` مما يؤدي إلى نفاد الذاكرة في التسلسلات الطويلة).
- يجب أن يكون درجة CP (Ulysses) قابلاً للقسمة على عدد رؤوس الاستعلام (32 لـ `Nano`، و64 لـ `Super`)؛ أما بالنسبة لـ TP، فيجب أن تكون الدرجة قابلة للقسمة على رؤوس KV (8). يتم تقسيم تدفقات الفهم (النص) والتوليد (الفيديو/الصوت) بشكل مستقل على طول التسلسل، وتُملأ الأطوال غير المنتظمة بصفر داخلياً حتى تصبح مضاعفاً لحجم العالم.
### شغّلها
يستخدم ملف سطر الأوامر الكامل [`examples/cosmos3/inference_cosmos3.py`](https://github.com/huggingface/diffusers/blob/main/examples/cosmos3/inference_cosmos3.py) [Cosmos3OmniModularPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) ويعيد استخدام هذه الأدوات المساعدة، لذا يمكن تشغيل **أي نمط** (نص إلى صورة/فيديو، صورة إلى فيديو، صوت، أوضاع الإجراء) على عدة وحدات معالجة رسومية عبر `--tp-degree` / `--cp-degree`. ابدأ التشغيل باستخدام [torchrun](https://docs.pytorch.org/docs/stable/elastic/run.html)؛ يجب أن يساوي `--tp-degree * --cp-degree` قيمة `--nproc_per_node`. تنتج كل رتبة نفس المخرجات؛ وتكتب الرتبة 0 هذه المخرجات.
```bash
# CP only — Nano (fits one GPU); CP degree must divide 32 query heads.
torchrun --nproc_per_node=4 examples/cosmos3/inference_cosmos3.py --model nano --cp-degree 4 --prompt "..."
# TP only — Super; TP degree must divide 64 query heads and 8 KV heads.
torchrun --nproc_per_node=4 examples/cosmos3/inference_cosmos3.py --model super --tp-degree 4 --prompt "..."
# TP + CP — Super, with sound (TP=2 x CP=2 across 4 GPUs).
torchrun --nproc_per_node=4 examples/cosmos3/inference_cosmos3.py \
--model super --tp-degree 2 --cp-degree 2 --enable-sound --prompt "..."
```
أوزان `Super` البالغة حوالي 120 غيغابايت لا تتسع على وحدة معالجة رسومية واحدة بسعة 96 غيغابايت، لذا فهي تتطلب TP؛ بينما تتسع `Nano` على وحدة معالجة رسومية واحدة، لذا فإن CP لها هي تحسين محض للزمن المستغرق. (تجاهل كلا العلمين لتشغيل وحدة معالجة رسومية واحدة.)
### تدريب نماذج كبيرة باستخدام توازي الموترات
يقوم CP بتجزئة *التفعيلات* لكنه يكرر كل الأوزان على كل رتبة، لذا لا يقلل من حجم الأوزان للنموذج — فأي نموذج لا يتسع على وحدة معالجة رسومية واحدة لن يتسع أيضاً باستخدام CP وحده. لتجزئة **الأوزان**، يطبّق `enable_cosmos3_tensor_parallel(transformer, tp_mesh)` توازياً على مستوى المصفوفات بأسلوب Megatron على محور شبكة ثانٍ متعامد:
- تُقسَّم إسقاطات الانتباه ووحدة التحويل متعددة الطبقات (MLP) عمودياً/صفوفياً عبر مجموعة TP (حيث تكون `to_q/to_k/to_v` و`add_q/k/v` وإسقاطات `gate/up` في وحدات التحويل متعددة الطبقات متوازية عمودياً؛ بينما تكون `to_out/to_add_out` وإسقاط `down` في وحدات التحويل متعددة الطبقات متوازية صفوفياً مع إجراء all-reduce). في النهاية، يمتلك كل رتبة `query_heads / tp` من رؤوس الاستعلام و`kv_heads / tp` من رؤوس KV.
- يتكامل TP مع CP على شبكة أجهزة ثنائية الأبعاد `(tp, cp)`: حيث يقسم TP الرؤوس/الأوزان بشكل دائم، بينما يقسم CP التسلسل فوق ذلك. القيود هي أن `tp` يقسم رؤوس KV (8)، وأن `tp * cp` يقسم رؤوس الاستعلام (32 لـ `Nano`، و64 لـ `Super`).
- تُحمَّل الأوزان إلى وحدة المعالجة المركزية (CPU) ثم تُقسَّم على وحدات معالجة الرسوميات (GPUs) طبقةً طبقة، بحيث لا يتم إنشاء النموذج الكامل على جهاز واحد.
> [!TIP]
> تصدر TP عملية all-reduce في كل كتلة انتباه وكتلة MLP، لذا فهي كثيفة النطاق الترددي. على الأجهزة التي لا تدعم NVLink، تُعدّ هذه العملية التكلفة المهيمنة؛ يُفضَّل استخدام درجة TP الأصغر التي تجعل الأوزان تتسع، وإدراج وحدات المعالجة الرسومية المتبقية في CP.
### استخدمه في خط أنابيبك الخاص ذي البنية المعيارية
تُعدّ أعلام سطر الأوامر مريحة، لكن يمكنك استدعاء أدوات المساعدة مباشرةً باستخدام [Cosmos3OmniModularPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline). حمّل إعدادات خط الأنابيب ومكوناته على المعالج المركزي (CPU)، وطبّق *قبل* نقل خط الأنابيب إلى وحدة معالجة الرسوميات المحلية للرتبة (rank-local GPU)، ثم بدّل إلى الخلفية `native`، وبعدها فعّل CP. لا تستخدم `device_map` لهذا التدفق:
```python
import os
import sys
import torch
import torch.distributed as dist
from diffusers import Cosmos3OmniModularPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from torch.distributed.device_mesh import init_device_mesh
# Make the helper module importable.
sys.path.insert(0, "examples/cosmos3")
from cosmos_parallel import (
enable_cosmos3_context_parallel,
enable_cosmos3_flash_attention,
enable_cosmos3_tensor_parallel,
)
# torchrun sets RANK / WORLD_SIZE / LOCAL_RANK. Pick tp_degree * cp_degree == world size.
local_rank = int(os.environ["LOCAL_RANK"])
torch.cuda.set_device(local_rank)
dist.init_process_group("nccl")
mesh = init_device_mesh("cuda", (tp_degree, cp_degree), mesh_dim_names=("tp", "cp"))
# Load components on CPU first; a TP-sharded model may not fit one GPU.
pipe = Cosmos3OmniModularPipeline.from_pretrained(model_id)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()
if tp_degree > 1:
enable_cosmos3_tensor_parallel(pipe.transformer, mesh["tp"]) # shard weights -> GPUs
pipe.to(f"cuda:{local_rank}") # move the replicated remainder
pipe.transformer.set_attention_backend("native")
if cp_degree > 1:
enable_cosmos3_context_parallel(pipe.transformer, mesh["cp"]) # shard the sequence
elif tp_degree > 1:
enable_cosmos3_flash_attention(pipe.transformer) # GQA-safe dense attention
# Modular pipelines replace components through update_components().
scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
pipe.update_components(scheduler=scheduler)
# A single output name returns that value; a list returns a dictionary.
outputs = pipe(
prompt='{"scene":"A robot arm in a kitchen"}',
num_frames=189,
height=720,
width=1280,
output=["videos", "sound", "sampling_rate", "action"],
)
videos = outputs["videos"]
sound = outputs["sound"] # None unless sound generation was requested.
action = outputs["action"] # None unless an action workflow produced actions.
```
في حالة CP فقط (بدون تقسيم الأوزان)، استخدم شبكة أحادية البعد: `init_device_mesh("cuda", (world_size,), mesh_dim_names=("cp",))` وفعّل `enable_cosmos3_context_parallel` فقط.
`enable_safety_checker()` يحمّل ويفعّل الفاحص الافتراضي؛ بينما `disable_safety_checker()` يعطّله صراحةً. استخدم تلك الطرق الخاصة بالخطوط الأنابيب بدلاً من معامل الإنشاء `enable_safety_checker=` الخاص بخط الأنابيب المهامي أو معامل الاستدعاء `enable_safety_check=`. كما لا تُرجع الخطوط الأنابيب المعيارية `Cosmos3OmniPipelineOutput`: استخدم `output="videos"` للإطارات وحدها، أو قائمة مخرجات وديكتمونيها المُرجَع كما هو موضح أعلاه بدلاً من `result.video` أو `result.sound` أو `result.action`.
> [!TIP]
> قد تتعطل أول عملية all-to-all في NCCL على بعض التكوينات متعددة وحدات معالجة الرسوميات. إذا توقفت عملية CP في بداية خطوة إزالة الضوضاء الأولى، فاضبط `NCCL_P2P_DISABLE=1` في البيئة قبل تشغيل `torchrun`.
يتكامل CP وTP مع جميع سير العمل المذكورة أعلاه (النص إلى فيديو، الصورة إلى فيديو، النص إلى فيديو مع صوت، والتوليد المشروط بالإجراء) ومع كلا نقطتي التفتيش `Nano` و`Super` — حيث تتغير فقط أسطر بناء خط الأنابيب وإعداد التوازي.
## قوالب البيانات الوصفية
تضيف `tokenize_prompt` جملًا قصيرة من البيانات الوصفية داخل رسالة المستخدم حتى يرى نموذج LLM الشروط التي تم تدريب النموذج عليها. تحصل الإيجابية على جمل مثل *"المقطع المصوَّر مدته 7.9 ثانية وبلغ 24 إطارًا في الثانية."* و *"هذا المقطع المصوَّر بدقة 720x1280."*؛ بينما تحصل السلبية على العكس (*"… ليس …"*).
كلاهما مفعّل افتراضيًا. يمكنك تعطيل أيٍّ من الزوجين عبر `__call__`:
```python
result = pipe(
prompt=prompt,
negative_prompt=negative_prompt,
num_frames=189,
height=720,
width=1280,
fps=24.0,
add_duration_template=False, # skip the duration sentence on both prompts
add_resolution_template=False, # skip the resolution sentence on both prompts
)
```
لا يؤثر `add_duration_template` عندما يكون `num_frames == 1` (وضع الصورة)؛ في هذه الحالة يُضاف جملة الدقة فقط.
## فاحص الأمان
يربط Cosmos3 بين [`cosmos_guardrail`](https://pypi.org/project/cosmos-guardrail/) و`CosmosSafetyChecker` ويشغّله **افتراضيًا**. يرفض حارس النصّ الأوامر غير الآمنة قبل التوليد (`ValueError`)؛ بينما يعمل حارس الفيديو على الإطارات المفكوكة، إما بتعتيم الوجوه المكتشفة أو رفض المخرجات. لا يخضع مخرج الصوت لأي حراسة.
قم بتثبيت الاعتمادية الاختيارية لتفعيل الفاحص الافتراضي:
```
pip install cosmos_guardrail
```
يُعدّ الفاحص إلزامياً بموجب اتفاقية ترخيص نماذج NVIDIA المفتوحة. وتوجد العلمان أدناه لاختبارات وسير عمل التطوير حيث يكون حاجز الحماية زائداً (على سبيل المثال، إذا كان المدخل قد تمّ تنفيته بالفعل، أو إذا كنت تختبر خط المعالجة عمداً على مدخلات حافة).
**تعطيل عند الإنشاء** (لا يتم إنشاء أي مُتحقّق، وبالتالي لا يتم تنزيل نماذج الحواجز أو تحميلها في الذاكرة):
```python
import torch
from diffusers import Cosmos3OmniPipeline
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano",
dtype=torch.bfloat16,
device_map="cuda", # or "mps", "xpu", "cpu"
enable_safety_checker=False,
)
```
**تعطيلها لاستدعاء واحد** (يبقى الفاحص محمّلاً — مفيد لتجاوز لمرة واحدة مع الإبقاء على الوضع الافتراضي مفعّلًا للاستدعاءات اللاحقة):
```python
result = pipe(
prompt=prompt,
num_frames=189,
height=720,
width=1280,
fps=24.0,
enable_safety_check=False,
)
```
لتزويد فاحص مخصص (مثل فئة فرعية لا تفعل شيئًا للاختبارات السريعة)، مرره كـ `safety_checker=`:
```python
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano",
dtype=torch.bfloat16,
device_map="cuda", # or "mps", "xpu", "cpu"
safety_checker=MyCustomSafetyChecker(),
)
```
## Cosmos3OmniPipeline[[diffusers.Cosmos3OmniPipeline]]
#### diffusers.Cosmos3OmniPipeline[[diffusers.Cosmos3OmniPipeline]]
```python
diffusers.Cosmos3OmniPipeline(transformer: Cosmos3OmniTransformer, text_tokenizer: AutoTokenizer, vae: AutoencoderKLWan, scheduler: UniPCMultistepScheduler, sound_tokenizer: diffusers.models.autoencoders.autoencoder_cosmos3_audio.Cosmos3AVAEAudioTokenizer | None = None, safety_checker: diffusers.pipelines.cosmos.pipeline_cosmos3_omni.CosmosSafetyChecker | None = None, enable_safety_checker: bool = True, default_use_system_prompt: bool = True, use_native_flow_schedule: bool = False)
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L413)
#### decode_sound[[diffusers.Cosmos3OmniPipeline.decode_sound]]
```python
decode_sound(latent: Tensor)
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L517)
فكّ تشفير صوت كامن `[C, T]` إلى موجة صوتية `[audio_ch, N]`.
يضيف/يحذف بُعد الدفعة (batch dimension) الذي يتوقعه مُفكّك رمز الصوت.
#### prepare_latents[[diffusers.Cosmos3OmniPipeline.prepare_latents]]
```python
prepare_latents(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, NoneType] = None, video: typing.Union[list[PIL.Image.Image], torch.Tensor, numpy.ndarray, NoneType] = None, condition_frame_indexes_vision: collections.abc.Iterable[int] = (0, 1), condition_video_keep: typing.Literal['first', 'last'] = 'first', num_frames: int | None = None, height: int | None = None, width: int | None = None, fps: float = 24.0, latents: typing.Optional[torch.Tensor] = None, sound_latents: typing.Optional[torch.Tensor] = None, action_latents: typing.Optional[torch.Tensor] = None, generator: typing.Optional[torch.Generator] = None, device: str = 'cuda', dtype: dtype = torch.bfloat16, enable_sound: bool = False, action: CosmosActionCondition | None = None)
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L763)
**يعيد:**
الموترات الضجيجية الأولية بالإضافة إلى أقنعة الشروط/البيانات الوصفية الخاصة بأوضاع الرؤية والصوت والإجراءات الاختيارية.
إنشاء شروط التوليد والضوضاء الأولية لعينة واحدة.
#### tokenize_prompt[[diffusers.Cosmos3OmniPipeline.tokenize_prompt]]
```python
tokenize_prompt(prompt: str, negative_prompt: str | None = None, num_frames: int = 189, height: int = 720, width: int = 1280, fps: float = 24.0, use_system_prompt: bool | None = None, add_resolution_template: bool = True, add_duration_template: bool = True, action_mode: str | None = None, action_view_point: str | None = None)
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L1132)
**يعيد:**
`(cond_input_ids, uncond_input_ids)` — قوائم معرّفات الرموز لهذا العينة.
Apply prompt-augmentation templates and tokenize cond/uncond prompts via the configured chat template.
لا يشغّل هذا الخطّ الأنابيبي مُشفِّر نصوص منفصلًا: يستهلك مُحوِّل Cosmos3 المشترك معرّفات الرموز الخام إلى جانب رموز الرؤية (وباختيار رموز الصوت).
عندما يكون `negative_prompt` بقيمة `None`، يُستخدم نص فارغ؛ وتوثّق صفحة Cosmos3 الموصى بها تلميحات سلبية للتحكم في الجودة يجب تمريرها صراحةً لتوليد الفيديو من النص / توليد الفيديو من الصورة. وتُضاف قوالب المدة والدقة إلى التلميح، وتُضاف القوالب المعكوسة إلى التلميح السلبي، عند تمكين ذلك.
عند ضبط `action_mode`، يتم تحويل الأمر إلى وصف JSON للإجراء المهيكلة التي تم تدريب النموذج عليها (انظر `_build_action_json_prompt`)، مع استخدام `action_view_point` لحقل الإطار؛ وتُتخطى قوالب البيانات الوصفية المسطحة لأن JSON يحمل بالفعل مدة العرض/معدل الإطارات/الدقة/نسبة الأبعاد.
- الكل
- __call__
## Cosmos3OmniModularPipeline
يتوفر Cosmos 3 أيضاً كخط أنابيب Modular Diffusers. لا يزال خط الأنابيب القائم على المهام [Cosmos3OmniPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline) متاحاً؛ ويتعايش خط الأنابيب المعياري معه ويغطي نفس الأوضاع (`text2image`، `text2video`، `image2video`، `video2video`، التوليد المشروط بالإجراء، و`transfer` (التحكم الهيكلي)، مع صوت اختياري عندما يدعمه نقطة التفتيش).
```python
import torch
from diffusers import Cosmos3OmniModularPipeline
pipe = Cosmos3OmniModularPipeline.from_pretrained(
"nvidia/Cosmos3-Nano", dtype=torch.bfloat16
)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()
videos = pipe(
prompt='{"scene":"A robot arm in a kitchen"}',
num_frames=1,
height=720,
width=1280,
output="videos",
)
# Modular pipelines expose declared outputs directly instead of using the task pipeline's
# `return_dict`/`Cosmos3OmniPipelineOutput` API.
image = videos[0]
```
يمكنك أيضًا التحميل عبر [ModularPipeline](/docs/diffusers/main/ar/api/modular_diffusers/pipeline#diffusers.ModularPipeline) ودع إعداد المستودع اختيار فئة الكتل:
```python
import torch
from diffusers import ModularPipeline
pipe = ModularPipeline.from_pretrained("nvidia/Cosmos3-Nano", dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()
videos = pipe(
prompt='{"scene":"A robot arm in a kitchen"}', num_frames=1, height=720, width=1280, output="videos"
)
```
لفحص أو تخصيص سير عمل Cosmos المعيّن، استخدم `available_workflows` + `get_workflow()`:
```python
available = pipe.blocks.available_workflows
image2video_blocks = pipe.blocks.get_workflow("image2video")
```
### أمثلة معيارية لجميع سير العمل الحالية
يدعم خط الأنابيب المعياري نفس توقيعات الاستدعاء التي يدعمها خط الأنابيب الخاص بالمهمة. تعكس المقاطع أدناه كل مثال توليد مُبيَّن أعلاه (`text2video`، `text2image`، `image2video`، `video2video`، `video2video_sound`، `text2video_sound`، و`action_policy`). ولأن النقل (التحكم الهيكلي) له مدخلاته الخاصة، فقد تم عرضه بشكل منفصل في [النقل المعياري](#modular-transfer-structural-control) أدناه.
```python
import json
import torch
from diffusers import Cosmos3OmniModularPipeline, CosmosActionCondition
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import encode_video, export_to_video, load_image, load_video
pipe = Cosmos3OmniModularPipeline.from_pretrained("nvidia/Cosmos3-Nano", dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()
pipe.to("cuda") # or "mps", "xpu", "cpu"
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
# text2video
json_prompt = json.load(open("assets/example_t2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
videos = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
num_frames=189,
height=720,
width=1280,
num_inference_steps=35,
guidance_scale=6.0,
fps=24.0,
output="videos",
)
export_to_video(videos, "cosmos3_modular_t2v.mp4", fps=24, macro_block_size=1)
# text2image
json_prompt = json.load(open("assets/example_t2i_prompt.json"))
videos = pipe(prompt=json.dumps(json_prompt), num_frames=1, height=720, width=1280, output="videos")
videos[0].save("cosmos3_modular_t2i.jpg", format="JPEG", quality=85)
# image2video
json_prompt = json.load(open("assets/example_i2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
image = load_image("https://github.com/nvidia-cosmos/cosmos-dependencies/releases/download/assets/robot_153.jpg")
videos = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
image=image,
num_frames=189,
height=720,
width=1280,
fps=24.0,
output="videos",
)
export_to_video(videos, "cosmos3_modular_i2v.mp4", fps=24, macro_block_size=1)
# video2video
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)
videos = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
video=video,
condition_frame_indexes_vision=[0, 1],
condition_video_keep="first",
num_frames=189,
height=720,
width=1280,
num_inference_steps=35,
guidance_scale=6.0,
fps=24.0,
output="videos",
)
export_to_video(videos, "cosmos3_modular_v2v.mp4", fps=24, macro_block_size=1)
# video2video_sound
outputs = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
video=video,
condition_frame_indexes_vision=[0, 1],
condition_video_keep="first",
num_frames=189,
height=720,
width=1280,
fps=24.0,
enable_sound=True,
output=["videos", "sound", "sampling_rate"],
)
encode_video(
outputs["videos"],
fps=24,
audio=outputs["sound"],
audio_sample_rate=outputs["sampling_rate"],
output_path="cosmos3_modular_v2v_with_sound.mp4",
)
# text2video_sound
json_prompt = json.load(open("assets/example_t2v_sound_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
outputs = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
num_frames=189,
height=720,
width=1280,
fps=24.0,
enable_sound=True,
output=["videos", "sound", "sampling_rate"],
)
encode_video(
outputs["videos"],
fps=24,
audio=outputs["sound"],
audio_sample_rate=outputs["sampling_rate"],
output_path="cosmos3_modular_t2v_with_sound.mp4",
)
# action_policy
prompt = "Put the pot to the left of the purple item."
action_video = load_video(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/action/bridge_20260501_0.mp4"
)
outputs = pipe(
prompt=prompt,
action=CosmosActionCondition(
mode="policy",
chunk_size=16,
domain_name="bridge_orig_lerobot",
resolution_tier=480,
video=action_video,
view_point="ego_view",
),
fps=5,
num_inference_steps=30,
guidance_scale=1.0,
use_system_prompt=False,
output=["videos", "action"],
)
export_to_video(outputs["videos"], "cosmos3_modular_action_policy.mp4", fps=5, macro_block_size=1)
if outputs["action"] is not None:
with open("cosmos3_modular_action_policy.json", "w") as f:
json.dump(outputs["action"][0].tolist(), f)
```
### النقل المعياري (التحكم الهيكلي)
يتبع النقل **فيديو تحكم محسوب مسبقاً** (حواف، ضبابية، عمق، تجزئة، أو خريطة سيناريو عالمي) يُمرر عبر `control_videos=` على شكل `{hint: video}`. وهو مخصص للفيديو فقط (لا يحتوي على `image` / `video` / `action` / `enable_sound`)، والموجّه عبارة عن وصف JSON مُوسَّع مسبقاً (انظر [توسيع الموجّه](#prompt-upsampling))، وتُولَّد المقاطع الطويلة ذاتياً في كتل من `num_video_frames_per_chunk` وتُدمج تلقائياً. `guidance_scale` هو CFG النصي المعتاد؛ بينما `control_guidance` (`!= 1.0`) يُعزّز إشارة التحكم بشكل إضافي. القيم الابتدائية الموصى بها لكل تلميح:
| تلميح | `guidance_scale` | `control_guidance` | `flow_shift` | الهندسة |
| --- | --- | --- | --- | --- |
| الحافة / الضبابية / العمق | 3.0 | 1.5 | 10.0 | 121 إطارًا @ 30 إطارًا في الثانية |
| التجزئة | 3.0 | 2.0 | 10.0 | 121 إطارًا @ 30 إطارًا في الثانية |
| السيناريو العالمي (WSM) | 1.0 | 3.0 | 10.0 | 101 إطارًا @ 10 إطارات في الثانية |
لا يتضمن Diffusers أصول التحكم. الأصول الجاهزة (فيديو تحكم + ملف `prompt.json` مطابق لكل تلميح، بالإضافة إلى ملف `negative_prompt.json` مشترك) متوفرة في [دليل Cosmos](https://github.com/NVIDIA/cosmos/tree/6e2c69afafd6444c1ca14a021aba93fcc6b7996a/cookbooks/cosmos3/generator/transfer/assets). بالنسبة لمثال الحافة أدناه، قم بتنزيلها إلى مجلد محلي باسم `assets/`:
```bash
base=https://github.com/NVIDIA/cosmos/raw/6e2c69afafd6444c1ca14a021aba93fcc6b7996a/cookbooks/cosmos3/generator/transfer/assets
mkdir -p assets/edge
curl -sL "$base/edge/control_edge.mp4" -o assets/edge/control_edge.mp4
curl -sL "$base/edge/prompt.json" -o assets/edge/prompt.json
curl -sL "$base/negative_prompt.json" -o assets/negative_prompt.json
```
```python
import json
import torch
from diffusers import Cosmos3OmniModularPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video
pipe = Cosmos3OmniModularPipeline.from_pretrained("nvidia/Cosmos3-Nano", dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
pipe.scheduler = UniPCMultistepScheduler.from_config(
pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
# Downloaded into assets/ from the Cosmos cookbook (see the curl snippet above).
json_prompt = json.load(open("assets/edge/prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
control_edge = load_video("assets/edge/control_edge.mp4")
videos = pipe(
prompt=json.dumps(json_prompt),
negative_prompt=json.dumps(negative_prompt),
control_videos={"edge": control_edge},
num_frames=121,
height=720,
width=1280,
fps=30.0,
num_inference_steps=35,
guidance_scale=3.0,
control_guidance=1.5,
output="videos",
)
export_to_video(videos, "cosmos3_modular_transfer_edge.mp4", fps=30, macro_block_size=1)
```
### Distilled نص إلى صورة (بخطوات قليلة) وصورة إلى فيديو[[diffusers.Cosmos3OmniModularPipeline]]
تُقدَّم نقاط التفتيش المُقطّرة بعدد خطوات قليلة عبر [Cosmos3DistilledModularPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3DistilledModularPipeline) (الكتل: `Cosmos3DistilledBlocks`)؛ ولا يدعم ذلك كلٌّ من [Cosmos3OmniModularPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) و[Cosmos3OmniPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline) الأساسيين. يُثبَّت `num_inference_steps` على طول إعداد خط أنابيب `distilled_sigmas` (من `modular_model_index.json` الخاص بنقطة التفتيش) ويُجبر `guidance_scale` على القيمة 1.0 لأن التوجيه مدمج في الأوزان — فتمرير أي قيمة أخرى لأيٍّ منهما يثير خطأً، بينما يُصدر تحذير تجاه `negative_prompt` ويُتجاهل.
لا تُعلن نقاط التفتيش المُقطّرة بدقة FP8 (`revision="fp8"`) عن سياسة دقة مختلطة، لذا تبقى كل خطوة على الدقة الأصلية W8A8.
تتبع الأوامر (Prompts) نفس بنية JSON الوصفية المستخدمة في النماذج غير المُصغَّرة (non-distilled)، لذا يجب أولاً رفع دقة النص القصير — استخدم `--mode text2image` (T2I) أو `--mode image2video` (I2V) كما هو موضح في [رفع دقة الأوامر](#prompt-upsampling)، ثم مرّر JSON عبر `json.dumps(...)`.
```python
import json
import torch
from diffusers import Cosmos3DistilledModularPipeline
from diffusers.utils import export_to_video, load_image
# JSON-upsampled prompt (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2i_prompt.json"))
repo = "nvidia/Cosmos3-Super-Text2Image-4Step"
pipe = Cosmos3DistilledModularPipeline.from_pretrained(repo, dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
# text-to-image (distilled)
videos = pipe(
prompt=json.dumps(json_prompt),
num_frames=1,
height=720,
width=1280,
output="videos",
)
videos[0].save("cosmos3_distilled_t2i.jpg", format="JPEG", quality=85)
# image-to-video (distilled) — load the I2V repo instead
# JSON-upsampled prompt (see "Prompt upsampling" above); upsampled from the source prompt
# "The right robotic hand picks up the red sphere on the shelf."
json_prompt_i2v = json.load(open("assets/example_i2v_prompt.json"))
repo_i2v = "nvidia/Cosmos3-Super-Image2Video-4Step"
pipe = Cosmos3DistilledModularPipeline.from_pretrained(repo_i2v, dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")
image = load_image(
"https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_153.jpg"
)
videos = pipe(
prompt=json.dumps(json_prompt_i2v),
image=image,
num_frames=189,
height=720,
width=1280,
output="videos",
)
export_to_video(videos, "cosmos3_distilled_i2v.mp4", fps=24, macro_block_size=1)
```
#### diffusers.Cosmos3OmniModularPipeline[[diffusers.Cosmos3OmniModularPipeline]]
```python
diffusers.Cosmos3OmniModularPipeline(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)
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/cosmos/modular_pipeline.py#L7)
ModularPipeline لتوليد Cosmos 3 omni.
- الكل
- __call__
## Cosmos3DistilledModularPipeline[[diffusers.Cosmos3DistilledModularPipeline]]
#### diffusers.Cosmos3DistilledModularPipeline[[diffusers.Cosmos3DistilledModularPipeline]]
```python
diffusers.Cosmos3DistilledModularPipeline(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)
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/cosmos/modular_pipeline.py#L121)
ModularPipeline لتوليد Cosmos 3 omni المُقطَّر (بعدد خطوات قليلة).
تدمج نقاط التفتيش المُصغَّرة (Distilled checkpoints) التوجيه الحر من المُصنِّف (classifier-free guidance) في الأوزان، وتُجري العينة وفق جدول ثابت يُقرأ من إعداد `distilled_sigmas` الخاص بالخط الأنابيب (يُعبأ من `modular_model_index.json`)، لذا فإن `guidance_scale` و`num_inference_steps` ثابتان، ولا يُدعم `negative_prompt`.
- الكل
- __call__
## CosmosActionCondition[[diffusers.CosmosActionCondition]]
#### diffusers.CosmosActionCondition[[diffusers.CosmosActionCondition]]
```python
diffusers.CosmosActionCondition(mode: typing.Literal['policy', 'forward_dynamics', 'inverse_dynamics'], chunk_size: int, domain_name: str, resolution_tier: int = 480, raw_actions: typing.Optional[torch.Tensor] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, NoneType] = None, video: typing.Union[list, numpy.ndarray, torch.Tensor, NoneType] = None, view_point: str = 'ego_view')
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L302)
**المعاملات:**
mode (`str`) : مهمة الإجراء. واحدة من `"forward_dynamics"` (توليد فيديو مستقبلي من إطار أولي وتسلسل `raw_actions` معطى)، أو `"inverse_dynamics"` (استنتاج الإجراءات التي تربط بين الإطارات الشرطية)، أو `"policy"` (توليد فيديو مستقبلي وإجراءات بشكل مشترك من الإطار الأولي).
chunk_size (`int`) : عدد خطوات الانتقال الإجراءي في الكتلة. يمتد فيديو الشروط المرافق على مدى `chunk_size + 1` إطارًا.
domain_name (`str`) : مجال التجسيد الذي يحدد أوزان الإسقاط الإجراءي الواعي بالمجال. يجب أن يكون أحد مجالات التجسيد المسجلة في Cosmos 3. كما يحدد عرض الإجراء غير المعبّأ المستخدم لتقطيع الإجراءات المتوقعة، ويُحلّ داخليًا من هذا الاسم (انظر `_EMBODIMENT_TO_RAW_ACTION_DIM`).
resolution_tier (`int`، القيمة الافتراضية `480`) : فئة *tier* لدقة تكييف الإجراء (إحدى القيم `256`، `480`، `704`، `720`). تختار الفئة لوحة مرسومة محددة مسبقاً يكون نسبة أبعادها أقرب ما تكون إلى المدخلات؛ حيث يتم تصغير المدخلات (بدون أي تكبير) وإضافة حشوة إليها لتكييفها. هذه ليست حجم الإطار الناتج، الذي يتبع محتوى المدخلات. طابق الفئة مع الدقة الأصلية للمدخلات: فالفئة الأدنى تتسبب في فقدان التفاصيل، بينما الفئة الأعلى لا تضيف أي دقة (لا يوجد تكبير)، وتهدر الحسابات على الحشوة، وتُشكّل عدم تطابق بين التدريب والاستدلال قد يُضعف الجودة.
raw_actions (`torch.Tensor`, *اختياري*) : متجهات إجراءات خام في المجال الأصلي، بأبعاد `[T, raw_action_dim]`، تُشغّل `"forward_dynamics"`. تتكرر آخر الإجراءات في التسلسلات الأقصر من `chunk_size`، بينما تُقتطع التسلسلات الأطول. تُرفض القنوات التي تتجاوز `action_dim` للنموذج، وتُملأ المدخلات الأضيق بالصفر حتى `action_dim`.
image (`PIL.Image.Image` أو `np.ndarray` أو `torch.Tensor`، *اختياري*) : إطار الشرط الخاص بـ `"policy"` / `"forward_dynamics"`. متنافٍ مع `video`.
video (`list` أو `np.ndarray` أو `torch.Tensor`، *اختياري*) : فيديو التكييف، وهو مطلوب عند استخدام `"inverse_dynamics"`. أما عند استخدام `"policy"` / `"forward_dynamics"` فيُستخدم إطاره الأول فقط. يتعارض مع `image`.
view_point (`str`، القيمة الافتراضية `"ego_view"`) : تسمية منظور الكاميرا المستخدمة لملء حقل `cinematography.framing` في وصف الإجراء. أحد القيم التالية: `"ego_view"` أو `"third_person_view"` أو `"wrist_view"` أو `"concat_view"`. تم تدريب نموذج الإجراء على أوصاف JSON منظمة تحمل جملة هذا المنظور؛ إذا كانت التسمية غير معروفة، يتم إسقاط حقل الإطار (مع تحذير).
يجمع كل مدخلات مطلوبة لمهمة توليد مشروطة بالإجراء في Cosmos 3.
مرر هذا إلى `Cosmos3OmniPipeline.__call__()` عبر معامل `action` بدلاً من المعاملات العلوية `image` / `height` / `width`، والتي مخصصة لتشغيلات t2v و i2v.
## Cosmos3OmniPipelineOutput[[diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput]]
#### diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput[[diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput]]
```python
diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput(video: Any, sound: typing.Optional[torch.Tensor] = None, action: list[torch.Tensor] | None = None)
```
[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L283)
**المعاملات:**
video : الفيديو المولّد. يعتمد النوع الدقيق على `output_type` المُمرَّر إلى خط الأنابيب: قائمة من إطارات PIL عند `"pil"` (الافتراضي)، مصفوفة `np.ndarray` بأبعاد `[T, H, W, C]` عند `"np"`، أو `torch.Tensor` بأبعاد `[T, C, H, W]` عند `"pt"`، أو متجه كامن خام عند `output_type="latent"`.
sound : موجة صوتية مُفكّكة الشكل `[C, N]`. تكون `None` عندما `enable_sound=False`.
action : رموز الإجراء المتوقعة. `None` ما لم يتنبأ وضع الإجراء بالإجراءات.
فئة بيانات المخرجات لـ [Cosmos3OmniPipeline](/docs/diffusers/main/ar/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline).
#
# مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص")
# لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص.
# يمكنك الحصول على نسخة من الترخيص في
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات
# تُوزَّع بموجب الرخصة على أساس "كما هي"،
# بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية.
# راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و
# قيود بموجب الترخيص. -->
# Cosmos 3
NVIDIA Cosmos 3 هو نموذج أساسي موحّد للعالم (WFM) للذكاء الاصطناعي الفيزيائي — وهو نموذج شامل واحد يجمع بين توليد العالم، والاستدلال الفيزيائي، وتوليد الإجراءات. إنه يحل محل نماذج التنبؤ، والاستدلال، والنقل المنفصلة من إصدارات Cosmos السابقة: سواء كنت تبني حلولاً للروبوتات، أو المركبات ذاتية القيادة، أو المساحات الذكية، فإن Cosmos 3 يمنحك أساساً واحداً لمحاكاة العالم الفيزيائي وفهمه.
ما يُشحن مع هذا الإصدار:
- النماذج على Hugging Face Hub مع بطاقات النماذج وترخيص
- تكامل Cosmos 3 Diffusers في خطوط أنابيب التوليد (هذه الصفحة)
- سكربتات ما بعد التدريب لضبط Cosmos 3 على بياناتك الخاصة
- مجموعات بيانات مفتوحة لتوليد البيانات الاصطناعية (SDG) للذكاء الاصطناعي الفيزيائي
## ما الجديد في Cosmos 3
أبرز تغيير عن إصدارات Cosmos السابقة هو أن Cosmos 3 هو *نموذج شامل*، مبني على بنية مزيج التحويلات (Mixture-of-Transformers، MoT). سابقًا، كان المطورون يعملون مع نماذج منفصلة لتوليد العالم (Predict)، والتوليد المُتحكَّم به (Transfer)، وفهم المشهد (Reason)، وتوليد سياسات الإجراء. يوحّد Cosmos 3 جميع هذه الوظائف في نموذج واحد يستنتج ويولّد عبر الأنماط المختلفة في تمريرة أمامية واحدة.
من نموذج واحد يمكنك:
- إنشاء عوالم فيديو فيزيائية معقولة من نصوص أو صور أو مدخلات إجراء (تحويل الصورة إلى فيديو، تحويل النص إلى فيديو، توليد فيديو مشروط بالإجراء).
- التفكير في الخصائص الفيزيائية مثل الحركة والسببية والعلاقات المكانية.
- تنبؤ بالتسلسلات المستقبلية للفيديو والإجراءات من الحالة الحالية.
- نقل المشاهد عبر نقاط نظر وظروف مختلفة مع تحكم هيكلي *(قريباً)*.
في الخلفية، يعمل نموذج `Cosmos3OmniTransformer` واحد على نموذج لغوي بنمط Qwen بالتوازي مع مسار توليد بالانتشار: حيث تمر رموز النص عبر تدفق "فهم" سببي، بينما تمر الكمونات (latents) الخاصة بالفيديو والصوت عبر تدفق "توليد" ذي انتباه ثنائي الاتجاه، وتُدمج معًا بواسطة RoPE متعدد الوسائط ثلاثي الأبعاد. راجع [ورقة Cosmos World Foundation Model Platform](https://huggingface.co/papers/2501.03575) للاطلاع على الخلفية المعمارية.
## نقاط التفتيش المتاحة
تم إصدار نقطتي تفتيش على الـ Hub — [`nvidia/Cosmos3-Nano`](https://huggingface.co/nvidia/Cosmos3-Nano) (أصغر حجمًا وأسرع) و [`nvidia/Cosmos3-Super`](https://huggingface.co/nvidia/Cosmos3-Super) (أكبر حجمًا وجودة أعلى). تدعم فئة خط الأنابيب نفسها تحويل النص إلى صورة، وتحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، و(مع نقطة تفتيش تدعم الصوت) تحويل النص والصورة إلى فيديو مع صوت — اختر مستودعًا واستخدم تبويب النموذج الخاص بكل سير عمل أدناه.
> [!TIP]
> تأكد من الاطلاع على [دليل المجدولين](../../using-diffusers/schedulers) لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم [إعادة استخدام المكونات عبر خطوط الأنابيب](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.
## إزالة الضوضاء المختلطة FP8 W8A8/W8A16
نُشر نقاط التفتيش الرسمية لـ ModelOpt FP8 الخاصة بـ Nano و Super و Edge كمستودعات Hub مستقلة: [`nvidia/Cosmos3-Nano-FP8`](https://huggingface.co/nvidia/Cosmos3-Nano-FP8)، و [`nvidia/Cosmos3-Super-FP8`](https://huggingface.co/nvidia/Cosmos3-Super-FP8)، و [`nvidia/Cosmos3-Edge-FP8`](https://huggingface.co/nvidia/Cosmos3-Edge-FP8). حمّل `main` من مستودع FP8. لا يتوفر لمستودع [`nvidia/Cosmos3-Super-Image2Video`](https://huggingface.co/nvidia/Cosmos3-Super-Image2Video) مستودع FP8 منفصل؛ حمّله باستخدام `revision="fp8"`.
جميع هذه نقاط التفتيش مُكمّمة بالطريقة نفسها. يستخدم **W8A8** أوزانًا بدقة 8 بت وتنشيطات بدقة 8 بت (GEMM المُستعاد من ModelOpt). يعيد **W8A16** استخدام تلك الأوزان ذاتها بدقة 8 بت لكنه يتخطى كمّمة التنشيطات: يتم فك كمّمة الوزن FP8 ويُنفَّذ خطي قياسي على تنشيطات BF16/FP16/FP32.
قد يؤدي تشغيل W8A8 في كل خطوة إلى ظهور وميض واضح في توليد الفيديو متعدد الخطوات. لذلك، تُعلن نقاط التفتيش الخاصة بالفيديو Nano وSuper وSuper-I2V وEdge FP8 عن جدول في `transformer/config.json`: **W8A16 في أول 3 خطوات وآخر 3 خطوات**، **W8A8 في المنتصف**. تقرأ مكتبة Diffusers هذه الأعداد من نقطة التفتيش بدلاً من تثبيتها في الكود. يتم اختيار الدقة مرة واحدة لكل خطوة من خطوات المجدول (scheduler) بحيث تتطابق استدعاءات cond/uncond الخاصة بالإرشاد الحر من التصنيف (classifier-free guidance).
لا تُظهر عمليات توليد الصور ونقاط التفتيش المُقطّرة بعدد خطوات قليلة ذلك الوميض، لذا فإن مستودع Super-T2I ومستودعات FP8 المُقطّرة ذات الخطوات الأربع لا تُعلن عن جدول زمني وتبقى على وضع W8A8 في كل خطوة. كما أن الجدول الزمني خاص بـ **ModelOpt FP8 فقط**: فواجهات الكمّية الأخرى (مثل TorchAO) تحافظ على عملياتها الأمامية الأصلية.
حمّل مستودع FP8 بمسار الاستعادة نفسه كما في [دليل ModelOpt](../../quantization/modelopt). يحتوي المستودع بالفعل على إعدادات التكميم. ثم يتبع الدقة المختلطة نقطة التفتيش تلقائيًا:
```python
import torch
from diffusers import Cosmos3OmniPipeline
pipe = Cosmos3OmniPipeline.from_pretrained(
"nvidia/Cosmos3-Nano-FP8",
dtype=torch.bfloat16,
device_map="cuda",
)
result = pipe(prompt="...", num_inference_steps=35)
```
خياران في وقت التوليد:
- **افتراضي** (`mixed_precision_format=None`): إذا كان ملف الحفظ (checkpoint) يُعلن عن `diffusion_step_policy`، فسيتم تشغيل W8A16 في الخطوات الأولى/الأخيرة N، وW8A8 الأصلية في الخطوات الوسطى. هذه هي الوصفة المقصودة لـ **فيديو** متعدد الخطوات FP8 (يقلل من الوميض مقارنةً باستخدام W8A8 بالكامل). أما نماذج FP8 المُقطّرة ذات الخطوات الأربع وSuper-T2I FP8 فتستثني السياسة، لذا فإن الوضع الافتراضي هو W8A8 بالكامل بالفعل.
- **`mixed_precision_format="none"`**: يُبقي كل خطوة على W8A8 الأصلي. أسرع، لأن W8A16 هو إلغاء تكميم + `torch.nn.functional.linear` بدلاً من GEMM FP8 المُستعاد، لكن الفيديو متعدد الخطوات قد يرتجف. استخدم هذا لاختبار جدولة A/B أو لمطابقة خط أساس مُكمَّم بالكامل.
على محطة عمل واحدة من Blackwell، كان Cosmos3-Nano-FP8 بدقة 720×1280 / 35 خطوة أبطأ بنسبة **27%** تقريبًا (T2I) وأبطأ بنسبة **13%** (T2V بإطار 49) مع الجدول المختلط الافتراضي مقارنةً باستخدام `"none"`. هذه الأرقام ليست ضمانًا لمعدل الإنتاجية. مرّر `"fp8"` فقط لفرض جدول أول/آخر N على نقطة تحقق ModelOpt FP8 التي لا تحتوي على سياسة.
## توسيع عينات المحفّز
تم تدريب Cosmos 3 على عناوين وصفية طويلة ومفصّلة للغاية. للحصول على جودة مثالية، يجب **توسيع نصوص الأوامر القصيرة إلى بنية JSON محددة** قبل تمريرها إلى خط المعالجة. يتوفر مُوسّع النصوص في حزمة [cosmos-framework](https://github.com/NVIDIA/cosmos-framework).
ابدأ من موجه نصي قصير بسيط واحفظه في `assets/prompt.txt`. في مثال النص إلى الفيديو أدناه، الموجه الأصلي هو *"ذراع روبوتية تنظف طبقاً في مطبخ"*:
```bash
mkdir -p assets
echo "A robotic arm is cleaning a plate in a kitchen" > assets/prompt.txt
```
ثم ثبّت الإطار وشغّل مُعظّم الدقة. يُعظّم المثال أدناه الدقة لتوليد الفيديو من النص باستخدام Opus-4.6:
```bash
git clone https://github.com/NVIDIA/cosmos-framework.git packages/cosmos-framework
pip install -e packages/cosmos-framework
export PROMPT_UPSAMPLER_ENDPOINT_URL="https://api.anthropic.com/v1/"
export PROMPT_UPSAMPLER_MODEL_NAME="claude-opus-4-6"
export PROMPT_UPSAMPLER_API_TOKEN="<your_token>"
python -m cosmos_framework.inference.prompt_upsampling \
--input assets/prompt.txt \
--output assets/example_t2v_prompt.json \
--mode text2video \
Xet Storage Details
- Size:
- 77.3 kB
- Xet hash:
- 3d1bd912f4845af93881bb00f2c89f9758e024878c5bc2c35395e6600630bc76
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.