Cosmos 3

NVIDIA Cosmos 3, Physical AI için birleşik bir dünya temel modelidir (WFM) — dünya üretimi, fiziksel akıl yürütme ve eylem üretimini birleştiren tek bir omni-modeldir. Daha önceki Cosmos sürümlerindeki ayrı Predict, Reason ve Transfer modellerinin yerini alır: robotik, otonom araçlar veya akıllı alanlar için geliştirme yapıyor olmanız fark etmeksizin, Cosmos 3 size fiziksel dünyayı simüle etmenizi ve anlamanızı sağlayan tek bir temel sunar.

Bu sürümle birlikte gelenler:

• Model kartları ve lisanslamaya sahip Hugging Face Hub'daki modeller
• Cosmos 3 Diffusers entegrasyonu, üretim hatları için (bu sayfa)
• Kendi verilerinizde Cosmos 3'ü ince ayar yapmak için eğitim sonrası betikleri
• Fiziksel Yapay Zeka için açık sentetik veri üretimi (SDG) veri kümeleri

Cosmos 3'te yenilikler

Önceki Cosmos sürümlerine kıyasla en büyük değişiklik, Cosmos 3'ün bir omni-model olması ve Mixture-of-Transformers (MoT) mimarisi üzerine inşa edilmesidir. Daha önce geliştiriciler, dünya üretimi (Predict), kontrollü üretim (Transfer), sahne anlama (Reason) ve eylem-politikası üretimi için ayrı modellerle çalışıyordu. Cosmos 3, tüm bu işlevleri, tek bir ileri geçişte (forward pass) modlar arası akıl yürüten ve üreten tek bir modelde birleştiriyor.

Tek bir modelden şunları yapabilirsiniz:

• Metin, görüntü veya eylem girdilerinden (görüntüden görüntüye, metinden görüntüye, eylem koşullu görüntü üretimi) fiziksel olarak olası görüntü dünyaları üretin.
• Hareket, nedensellik ve uzamsal ilişkiler gibi fiziksel özellikler hakkında akıl yürütün.
• Mevcut durumdan gelecekteki video ve eylem dizilerini tahmin edin.
• Yapısal kontrol ile sahneleri farklı bakış açıları ve koşullar arasında aktarın (yakında).

Arka planda, tek bir Cosmos3OmniTransformer, Qwen tarzı bir dil modelini difüzyon tabanlı bir üretim yoluyla paralel olarak çalıştırır: metin jetonları nedensel bir “anlama” akışından geçerken, video ve ses latentleri çift yönlü dikkat mekanizmasına sahip bir “üretim” akışından geçer; bu iki akış 3B çok modlu RoPE ile birleştirilir. Mimari arka plan için Cosmos World Foundation Model Platform makalesine bakın.

Mevcut denetim noktaları

Hub üzerinde iki checkpoint yayınlanmıştır: nvidia/Cosmos3-Nano (daha küçük, daha hızlı) ve nvidia/Cosmos3-Super (daha büyük, daha yüksek kalite). Aynı pipeline sınıfı metinden görüntüye, metinden videoya, görüntüden videoya ve (ses yeteneğine sahip bir checkpoint ile) metin+görüntüden sesli videoya dönüşümü destekler — bir repo seçin ve aşağıdaki her iş akışında model başına sekmeyi kullanın.

Scheduler'lar kılavuzunu inceleyerek scheduler hızı ve kalitesi arasındaki ödünleşimi nasıl keşfedebileceğinizi öğrenin ve aynı bileşenleri birden fazla pipeline'a nasıl verimli bir şekilde yükleyebileceğinizi öğrenmek için pipeline'lar arasında bileşenleri yeniden kullanma bölümüne göz atın.

FP8 karışık W8A8/W8A16 gürültü azaltma

Resmi ModelOpt FP8 denetim noktaları Hub'da fp8 revizyonunda bulunur (örneğin nvidia/Cosmos3-Nano ile revision="fp8").

Tüm bu kontrol noktaları aynı şekilde kuantize edilmiştir. W8A8, 8-bit ağırlıklar ve 8-bit aktivasyonlar kullanır (yeniden oluşturulmuş ModelOpt GEMM). W8A16, aynı 8-bit ağırlıkları yeniden kullanır ancak aktivasyon kuantizasyonunu atlar: FP8 ağırlığı dequantize edilir ve standart bir lineer katman, BF16/FP16/FP32 aktivasyonları üzerinde çalıştırılır.

Her adımda W8A8 çalıştırılması, çok adımlı video üretiminde belirgin titremeye neden olabilir. Bu nedenle video Nano / Super / Super-I2V FP8 checkpoint'leri, transformer/config.json içinde bir zaman çizelgesi bildirir: ilk 3 ve son 3 adımda W8A16, ortada W8A8. Diffusers bu sayıları checkpoint'ten okur, bunları kodda sabit olarak yazmaz. Hassasiyet, her zamanlayıcı adımı için bir kez seçilir; böylece classifier-free guidance cond/uncond çağrıları eşleşir.

Görsel üretimi ve az adımlı damıtılmış checkpoint'ler bu titremeyi göstermediğinden, Super-T2I ve damıtılmış 4 adımlı FP8 depoları zaman çizelgesi beyan etmez ve her adımda W8A8 olarak kalır. Zaman çizelgesi yalnızca ModelOpt FP8 içindir: diğer kuantizasyon arka uçları (örneğin TorchAO) yerel ileri geçişlerini korur.

fp8 revizyonunu, ModelOpt kılavuzu ile aynı geri yükleme yoluyla yükleyin (revision="fp8" zaten kuantizasyon yapılandırmasını taşır). Karmaşıklık hassasiyeti (mixed precision) ardından otomatik olarak kontrol noktasını (checkpoint) takip eder:

import torch
from diffusers import Cosmos3OmniPipeline

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano",
    revision="fp8",
    dtype=torch.bfloat16,
    device_map="cuda",
)
result = pipe(prompt="...", num_inference_steps=35)

İki üretim zamanı seçeneği:

• Varsayılan (mixed_precision_format=None): checkpoint diffusion_step_policy bildiriyorsa, ilk/son N adımda W8A16, ortada ise yerel W8A8 çalıştırılır. Bu, çok adımlı video FP8 için önerilen tariftir (tamamen W8A8'e kıyasla daha az titreme). Distilled 4-step ve Super-T2I FP8 bu politikayı içermediği için varsayılan zaten tamamen W8A8'dir.
• mixed_precision_format="none": her adımı yerel W8A8 üzerinde tutar. W8A16, geri yüklenen FP8 GEMM yerine dequant + torch.nn.functional.linear olduğu için daha hızlıdır, ancak çok adımlı videoda titreme görülebilir. Bunu zaman çizelgesini A/B test etmek veya tamamen kuantize edilmiş bir tabanla eşleşmek için kullanın.

Tek bir Blackwell iş istasyonunda, Cosmos3-Nano @fp8 720×1280 / 35 adım için varsayılan karışık zamanlamayla "none" kullanıldığında yaklaşık %27 daha yavaş (T2I) ve %13 daha yavaş (49 kareli T2V) idi. Bu sayılar bir işleme hızı garantisi değildir. Sadece bir politika içermeyen bir ModelOpt FP8 kontrol noktasında ilk/son-N zamanlamasını zorlamak için "fp8" parametresini geçin.

Prompt örnekleme

Cosmos 3, uzun ve oldukça betimleyici altyazılar üzerinde eğitildi. En iyi kalite için, kısa metin istemleri pipeline'a iletilmeden önce belirli bir JSON yapısına genişletilmelidir. Genişletici, cosmos-framework paketinde yer alır.

Kısa, düz metin bir istemden başlayın ve bunu assets/prompt.txt dosyasına kaydedin. Aşağıdaki metinden videoya örnekte orijinal istem “A robotic arm is cleaning a plate in a kitchen” şeklindedir:

mkdir -p assets
echo "A robotic arm is cleaning a plate in a kitchen" > assets/prompt.txt

Ardından çerçeveyi (framework) yükleyin ve upsampler'ı çalıştırın. Aşağıdaki örnek, Opus-4.6 kullanarak metinden videoya (text-to-video) upsampling yapar:

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"

Hedeflediğiniz iş akışına (text2image, text2video, image2video) uygun olacak şekilde --mode değerini değiştirin. Komut, örneklemesi artırılmış istemleri --output dosyasına bir JSON dizisi olarak yazar (--input içindeki her boş olmayan satır için bir nesne); satır başına bir JSON nesnesi almak için bunun yerine bir .jsonl yolu iletin. image2video için, koşullandırma görselini --image-url (bir URL veya yerel yol) veya --image-list (istem başına bir görsel) ile de belirtmeniz gerekir.

Kolaylık sağlamak amacıyla önceden örneklem artırılmış olumlu bir istem (assets/example_t2v_prompt.json) ve olumsuz bir istem (assets/negative_prompt.json) sağlanmıştır ve aşağıdaki üretim örneklerinde kullanılır. Örnekler bu JSON dosyalarını yükler ve json.dumps(...) aracılığıyla JSON dizeleri olarak pipeline'a iletir.

Metinden videoya

Sadece metin koşullu çok kareli üretim. Hedef süreye göre num_frames değerini seçin — varsayılan num_frames=189 değeri 24 FPS'de ≈ 7,9 sn üretir. İstem ve negatif istem, İstem örneklemesi artırma bölümünde açıklanan JSON örneklemesi artırılmış dosyalardan okunur.

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)

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)

Metinden görüntüye

Tek kare üretimi. Model yalnızca metin komutuna koşullandırılır; num_frames=1 parametresini iletin. JSON komutunu oluşturmak için --mode text2image ile örnekleme yapın.

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)

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)

Görüntüden videoya

image= parametresi üzerinden bir koşullandırma görseli iletin. Pipeline, 0. kareyi sağlanan görselle sabitler ve kalan kareleri gürültüden arındırır. Görsel, en-boy oranını koruyacak şekilde yeniden boyutlandırılır, istenen çıktı boyutuna ortadan kırpılır ve uint8 eşdeğeri yuvarlama ile normalize edilir. JSON istemini üretmek için --mode image2video ile örnekleme yapın.

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)

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'dan videoya

video= parametresi üzerinden bir koşullandırma klipleri geçin (ör. load_video ile). Pipeline, condition_frame_indexes_vision ile verilen (varsayılan [0, 1]) başlangıç gizli karelerini klip ile eşleştirir ve kalan kısımları gürültüden arındırır. Daha uzun bir kaynak klipten koşullandırma karelerinin hangi ucundan alınacağını seçmek için condition_video_keep ("first" veya "last") kullanın. Diğer modlarda olduğu gibi, istem Prompt upsampling bölümünde açıklanan betimleyici JSON yapısını takip etmelidir.

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)

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)

Sesli video-to-video

Kontrol noktası sound_tokenizer içeriyorsa, senkronize bir ses parçası oluşturmak için video-to-video çağrısına enable_sound=True ekleyin. Dalga formu video ile birlikte döndürülür ve encode_video() ile MP4 dosyasına eklenebilir.

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",
)

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",
)

Sesli metinden videoya

Kontrol noktası sound_tokenizer içeriyorsa, senkronize bir ses parçası oluşturmak için enable_sound=True parametresini iletin. Dalga formu, videoyla birlikte döndürülür ve encode_video() ile MP4 dosyasına eklenebilir.

Bu, yukarıdaki metinden videoya örneğindeki çağrının aynısıdır; yalnızca enable_sound=True eklenmiştir:

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",
)

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",
)

Eylem koşullu üretim

Action runs, her eyleme özgü girdiyi üst düzey image / video / height / width argümanları yerine action argümanı üzerinden geçirilen bir CosmosActionCondition içinde birleştirir. resolution_tier değerini (256/480/704/720) girdi videosunun yerel çözünürlüğüne yakın tutun; bu ayar, koşullandırma tuvalini seçer. Cosmos 3, üç eylem modunu destekler: policy, forward_dynamics ve inverse_dynamics. policy ve forward_dynamics yalnızca ilk kareye koşullanır (bu nedenle hem image hem de video kullanılabilir), oysa inverse_dynamics bir video gerektirir. Bir eylem çalışması için koşullandırma videosu, hattın üst düzey video argümanında değil, action.video (veya action.image) üzerinde ayarlanır.

Düz bir görev açıklamasını prompt olarak iletin ve action.view_point ile kamerayı seçin (varsayılan "ego_view"; ayrıca "third_person_view", "wrist_view", "concat_view"). Pipeline, bu girdileri modelin eğitiminde kullanılan yapılandırılmış JSON başlığına dönüştürür; bu nedenle eylem istemleri LLM ile genişletilmemelidir.

Eylem politikası

Action policy generation, ilk gözlem çerçevesinden, metin komutundan ve eylem alanı meta verilerinden gelecekteki video ve eylem tokenlarını tahmin eder. Aşağıdaki örnek, Bridge robot alanını kullanır ve tahmin edilen eylem parçasını model-normalize edilmiş eylem uzayında JSON olarak yazar.

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)

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 varsayılan olarak devre dışıdır. Cosmos 3, SeaCacheConfig ile açıkça etkinleştirilmesini destekler. SeaCache, Spektral-Evrim-Bilinçli gösterge yavaş değiştiğinde dönüştürücü artıklarını yeniden kullanarak tam dönüştürücü çalıştırma sayısını azaltır. Göstergeyi, görüntüden video üretimi için temiz koşullandırma karelerini de içeren ham görme gizli değişkenlerinden hesaplar. Pipeline'dan zamanlayıcı meta veri geri çağrıları ile dönüştürücüde etkinleştirin:

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

Aynı model düzeyi API'si Cosmos3OmniPipeline, Cosmos3OmniModularPipeline ve Cosmos3DistilledModularPipeline ile çalışır. SeaCache yaklaşık bir yöntemdir ve üretilen çıktıları değiştirebilir. Her gürültü azaltma adımının tam dönüştürücüyü çalıştırması gerektiğinde pipe.transformer.disable_cache() ile devre dışı bırakın. Önbellek durumu her pipeline çağrısından sonra sıfırlanır ve koşullu ile koşulsuz yönlendirme dalları bağımsız geçmişler tutar.

Cosmos 3, SeaCache kapısını tekrarlanan decoder katmanlarının dışında tutar, bu nedenle bölgesel derlemeyle uyumludur. Önbelleği etkinleştirdikten sonra katmanları derleyin:

pipe.transformer.compile_repeated_blocks(fullgraph=True)

SeaCache, aşağıda belgelenen Cosmos 3 Ulysses bağlam paralelliği ve DTensor tabanlı tensör paralelliği yardımcılarını da destekler. Önbellek kararları, sıralar (ranks) arasında senkronize edilir. Tam model derlemesi ve diğer model bölme stratejileri için bir iddia bulunmamaktadır.

Bağlam paralelliği

Uzun videolar veya yüksek çözünürlüklerde, tek bir ileri geçiş tek bir GPU'nun bellek ve gecikme bütçesini aşabilir. Cosmos 3, dizgi boyutunu birden fazla GPU arasında paylaştırmak ve dikkat hesaplamasını bölmek suretiyle her cihazın yalnızca token'ların bir dilimini tutmasını sağlamak için bağlam paralelliğini (CP) destekler.

Cosmos 3, Ulysses bağlam paralelliğini (all-to-all dizi/başlık değişimi) destekler. Ring attention desteklenmez.

Çoğu diffusers modelinin aksine, Cosmos 3, CP'yi transformer'a veya beyan edici enable_parallelism() yoluna bağlamaz: gruplanmış sorgu dikkati, ayrı anlama/üretim akışları (üretim akışı her ikisine de dikkat eder) ve akış başına düzensiz uzunluklar, bir _cp_plan olarak ifade edilemez. Bunun yerine, model küçük, işlevsiz shard/gather dikiş noktaları sunar ve uygulama examples/cosmos3/cosmos_parallel.py içinde yer alır — baştan sona okuyup uyarlayabileceğiniz, kendi içinde tam bir modül. İki dik, birleştirilebilir shardlama ekseni sunar:

2-B (tp, cp) ızgarasında bunlardan herhangi birini tek başına veya ikisini birlikte kullanın (bkz. Tensor paralelliği ile büyük modelleri sığdırma).

Cosmos 3'e özgü iki gereksinim vardır:

• native dikkat (attention) arka ucunu kullanın. Cosmos 3, gruplu sorgu dikkati (GQA) kullanır ve yerel SDPA arka ucu, enable_gqa parametresini kabul eden tek arka uçtur (cuDNN ve flash bunu reddeder). Yardımcı işlevler, KV başlarını sorgu başı sayısına genişletir ve SDPA'yı enable_gqa=False ile çağırır; böylece yine de flash çekirdeğine yönlendirilir (matematiksel yedek çözüm, tam [S, S] skorlarını oluşturur ve uzun dizilerde bellek taşmasına (OOM) yol açar).
• CP (Ulysses) derecesi, sorgu başı sayısına (32 Nano için, 64 Super için) bölünmelidir; TP için derecenin KV başlarına (8) bölünmesi gerekir. Anlama (metin) ve üretim (video/ses) akışları, dizilim boyunca bağımsız olarak parçalanır ve düzensiz uzunluklar, dünya boyutunun katına sıfır dolgusuyla içsel olarak tamamlanır.

Çalıştırın

Tam CLI examples/cosmos3/inference_cosmos3.py, Cosmos3OmniModularPipeline kullanır ve bu yardımcıları yeniden kullanır; bu sayede herhangi bir modalite (metinden görüntüye/videoya, görüntüden videoya, ses, eylem modları) --tp-degree / --cp-degree ile çoklu GPU üzerinde çalışır. torchrun ile başlatın; --tp-degree * --cp-degree değeri --nproc_per_node değerine eşit olmalıdır. Her rank aynı çıktıyı üretir; rank 0 bunu yazar.

# 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'ın ~120 GB'lık ağırlıkları tek bir 96 GB GPU'ya sığmadığı için TP gerektirir; Nano ise tek bir GPU'ya sığıyor, bu yüzden CP için saf bir gecikme optimizasyonudur. (Tek GPU'da çalıştırmak için her iki bayrağı da atlayın.)

Gerginlik paralelliği ile büyük modellerin eğitimi

CP, aktivasyonları parçalara ayırır (shard) ancak her ağırlığı her sırada (rank) kopyalar; bu nedenle bir modelin ağırlık ayak izini (weight footprint) azaltmaz — tek bir GPU'ya sığmayan bir model, yalnızca CP kullanıldığında da sığmayacaktır. Ağırlıkları parçalamak için, enable_cosmos3_tensor_parallel(transformer, tp_mesh) ikinci, dik (orthogonal) bir mesh ekseninde Megatron tarzı tensor paralelliğini uygular:

• Dikkat ve MLP projeksiyonları TP grubu boyunca sütun/satır olarak bölünmüştür (to_q/to_k/to_v + add_q/k/v ve MLP'lerin gate/up katmanları sütun paralel; to_out/to_add_out ve MLP'lerin down katmanları all-reduce ile satır paraleldir). Her rank, query_heads / tp sorgu başı ve kv_heads / tp KV başına sahip olur.
• TP, CP ile 2 boyutlu bir (tp, cp) cihaz ızgarasında birleşir: TP, başlıkları/ağırlıkları kalıcı olarak böler, CP ise bunun üzerine diziyi parçalar. Kısıtlar şunlardır: tp, KV başlıklarını (8) böler ve tp * cp, sorgu başlıklarını (Nano için 32, Super için 64) böler.
• Ağırlıklar CPU'ya yüklenir ve katman katman GPU'lara dağıtılır, böylece tam model hiçbir zaman tek bir cihazda oluşturulmaz.

TP, her dikkat ve MLP bloğunda bir all-reduce işlemleri başlatır, bu nedenle bant genişliği açısından yoğun bir yük oluşturur. NVLink'e sahip olmayan konaklarda baskın maliyet budur; ağırlıkların sığmasını sağlayan en küçük TP derecesini tercih edin ve kalan GPU'ları CP'ye aktarın.

Kendi modüler hattınızda kullanın

CLI bayrakları kullanışlıdır, ancak yardımcıları doğrudan Cosmos3OmniModularPipeline ile çağırabilirsiniz. Hattın yapılandırmasını ve bileşenlerini CPU üzerinde yükleyin, hattı rank-yerel GPU'ya taşımadan önce TP'yi uygulayın, native arka ucuna geçin ve ardından CP'yi etkinleştirin. Bu akış için device_map kullanmayın:

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.

Sadece CP için (ağırlık bölme olmadan), 1-B bir ızgara kullanın: init_device_mesh("cuda", (world_size,), mesh_dim_names=("cp",)) ve yalnızca enable_cosmos3_context_parallel.

enable_safety_checker() varsayılan denetleyiciyi yükler ve etkinleştirir; disable_safety_checker() ise bunu açıkça devre dışı bırakır. Görev hattı enable_safety_checker= inşaat argümanı veya enable_safety_check= çağrı argümanı yerine bu boru hattı yöntemlerini kullanın. Modüler boru hatları ayrıca Cosmos3OmniPipelineOutput döndürmez: yalnızca kareler için output="videos" kullanın veya yukarıda gösterildiği gibi result.video, result.sound veya result.action yerine bir çıktı listesi ve bunun döndürdüğü sözlüğü kullanın.

Bazı çoklu GPU topolojilerinde ilk NCCL all-to-all işlemi takılabilir. Bir CP çalışması ilk gürültü azaltma adımının başlangıcında duruyorsa, torchrun başlatılmadan önce ortamda NCCL_P2P_DISABLE=1 değerini ayarlayın.

CP ve TP, yukarıdaki tüm iş akışlarıyla (metinden videoya, görüntüden videoya, sesli metinden videoya ve eylem koşullu üretim) hem de Nano ve Super kontrol noktalarıyla birleşir; yalnızca iş akışı inşası ve paralellik kurulumu satırları değişir.

Meta veri şablonları

tokenize_prompt appends short metadata sentences inside the user message so the LLM sees the conditioning the model was trained with. The positive prompt gets sentences like “The video is 7.9 seconds long and is of 24 FPS.” and “This video is of 720x1280 resolution.”; the negative prompt gets the inverse (”… is not …”).

Her ikisi de varsayılan olarak açıktır. __call__ üzerinden herhangi bir çifti devre dışı bırakabilirsiniz:

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 (görsel modu) durumunda etkisizdir; bu durumda yalnızca çözünürlük cümlesi eklenir.

Güvenlik denetleyicisi

Cosmos3, cosmos_guardrail bileşenindeki CosmosSafetyChecker sınıfını bağlar ve bunu varsayılan olarak çalıştırır. Metin koruma katmanı, üretimden önce güvensiz istekleri reddeder (ValueError); video koruma katmanı ise çözümlenen kareler üzerinde çalışır ve tespit edilen yüzleri pikselleştirir ya da çıktıyı reddeder. Ses çıktısı koruma katmanından geçirilmez.

Varsayılan denetleyiciyi etkinleştirmek için isteğe bağlı bağımlılığı yükleyin:

pip install cosmos_guardrail

Denetleyici, NVIDIA Açık Model Lisans Anlaşması kapsamında zorunludur. Aşağıdaki iki bayrak, koruma mekanizmasının gereksiz olduğu test ve geliştirme iş akışları için mevcuttur (ör. girdi zaten temizlenmişse veya boru hattını bilinçli olarak sınır girdiler üzerinde çalıştırıyorsanız).

Kurulumda devre dışı bırak (hiçbir denetleyici örneklenmediğinden, hiçbir koruma modeli indirilmez veya belleğe yüklenmez):

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,
)

Tek bir çağrı için devre dışı bırak (denetleyici yüklü kalır — varsayılan olarak sonraki çağrılar için açık tutulurken tek seferlik atlamada kullanışlıdır):

result = pipe(
    prompt=prompt,
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_safety_check=False,
)

Özel bir denetleyici (ör. hızlı testler için no-op bir alt sınıf) sağlamak için, bunu safety_checker= olarak iletin:

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano",
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
    safety_checker=MyCustomSafetyChecker(),
)

Cosmos3OmniPipeline

• tümü
• call

Cosmos3OmniModularPipeline

Cosmos 3 ayrıca Modular Diffusers hattı olarak da kullanılabilir. Görev tabanlı Cosmos3OmniPipeline hâlâ kullanılabilir durumda; modüler hat onunla birlikte var olur ve aynı modları kapsar (text2image, text2video, image2video, video2video, eylem koşullu üretim ve transfer (yapısal kontrol), checkpoint destekliyorsa isteğe bağlı ses).

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]

Ayrıca ModularPipeline üzerinden de yükleyebilir ve bloklar sınıfının seçilmesini depo yapılandırmasına bırakabilirsiniz:

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"
)

Belirli bir Cosmos modüler iş akışını denetlemek veya özelleştirmek için available_workflows + get_workflow() kullanın:

available = pipe.blocks.available_workflows
image2video_blocks = pipe.blocks.get_workflow("image2video")

Tüm mevcut iş akışları için modüler örnekler

Modüler pipeline, görev pipeline'ı ile aynı çağrı imzalarını destekler. Aşağıdaki kod parçacıkları, yukarıda gösterilen her bir üretim örneğini (text2video, text2image, image2video, video2video, video2video_sound, text2video_sound ve action_policy) yansıtır. Transfer (yapısal kontrol) kendi girdilerine sahiptir ve aşağıdaki Modüler transfer bölümünde ayrı olarak gösterilir.

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)

Modüler aktarım (yapısal kontrol)

Transfer, control_videos= üzerinden {hint: video} eşlemesi olarak geçirilen önceden hesaplanmış bir kontrol videosunu (kenar, bulanıklık, derinlik, segmentasyon veya dünya senaryosu haritası) takip eder. Yalnızca video içindir (image / video / action / enable_sound yoktur), istem önceden örneklemesi artırılmış bir JSON altyazısıdır (bkz. İstem örneklemesi artırma) ve uzun klipler num_video_frames_per_chunk parçacıklar halinde otoregresif olarak üretilir ve otomatik olarak birleştirilir. guidance_scale standart metin CFG'dir; control_guidance (!= 1.0) ayrıca kontrol sinyalini güçlendirir. İpucu başına önerilen başlangıç değerleri:

Diffusers, kontrol varlıklarını içermez. Hazır olanlar (her ipucu için bir kontrol videosu + eşleşen prompt.json, ayrıca paylaşılan negative_prompt.json) Cosmos cookbook içinde bulunur. Aşağıdaki kenar örneği için bunları yerel bir assets/ klasörüne indirin:

base=https://github.com/NVIDIA/cosmos/raw/refs/heads/main/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

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)

Damıtılmış (az adımlı) metinden görüntüye ve görüntüden videoya

Az adımlı damıtılmış checkpoint'ler Cosmos3DistilledModularPipeline tarafından sunulur (bloklar: Cosmos3DistilledBlocks); temel Cosmos3OmniModularPipeline ve Cosmos3OmniPipeline bunları desteklemez. num_inference_steps, pipeline yapılandırmasının (checkpoint'in modular_model_index.json dosyasından) distilled_sigmas uzunluğuna sabitlenir ve rehberlik ağırlıklara gömülü olduğundan guidance_scale 1.0 olarak zorlanır — bu parametrelerden herhangi biri için başka bir değer verilirse hata oluşur ve negative_prompt hakkında uyarı verilir, yok sayılır.

FP8 damıtılmış checkpoint'ler (revision="fp8") karma hassasiyet politikası beyan etmediği için her adım yerel W8A8 olarak kalır.

Prompts, distille edilmemiş modellerle aynı açıklayıcı JSON yapısını izlediğinden, kısa metinler önce yukarı örneklenmelidir — Prompt upsampling bölümünde anlatıldığı gibi --mode text2image (T2I) veya --mode image2video (I2V) kullanın, ardından JSON'u json.dumps(...) ile iletin.

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)

• tümü
• call

Cosmos3DistilledModularPipeline

• tümü
• call

CosmosActionCondition

Cosmos3OmniPipelineOutput