Buckets:
#
# Лицензия Apache License, Version 2.0 («Лицензия»);
# вы можете использовать этот файл только в соответствии с Лицензией.
# Вы можете получить копию Лицензии по адресу
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Если это не требуется применимым законодательством или не оговорено письменно, программное
# распространяется по Лицензии на условиях «КАК ЕСТЬ»,
# БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ, прямо указанных или подразумеваемых.
# См. Лицензию для получения конкретных условий, регулирующих разрешения и
# ограничениями Лицензии. -->
# Cosmos 3
NVIDIA Cosmos 3 — это единая базовая модель мира (WFM) для Physical AI: универсальная модель, объединяющая генерацию мира, физическое рассуждение и генерацию действий. Она заменяет отдельные модели Predict, Reason и Transfer из предыдущих релизов Cosmos: независимо от того, разрабатываете ли вы решения для робототехники, автономных транспортных средств или умных пространств, Cosmos 3 предоставляет единую основу для симуляции и понимания физического мира.
Что входит в этот релиз:
- Модели на Hugging Face Hub с карточками моделей и лицензиями
- Интеграция Cosmos 3 Diffusers для конвейеров генерации (эта страница)
- Скрипты постобучения для дообучения Cosmos 3 на собственных данных
- Открытые наборы данных для генерации синтетических данных (SDG) для Physical AI
## Что нового в Cosmos 3
Главное отличие Cosmos 3 от предыдущих релизов Cosmos заключается в том, что это *омни-модель*, построенная на архитектуре Mixture-of-Transformers (MoT). Ранее разработчики работали с отдельными моделями для генерации мира (Predict), управляемой генерации (Transfer), понимания сцены (Reason) и генерации политик действий. Cosmos 3 объединяет все эти функции в одной модели, которая рассуждает и генерирует данные в разных модальностях за один прямой проход.
Из одной модели можно:
- Генерация физически правдоподобных видеомиров по тексту, изображениям или входным действиям (генерация видео из изображений, генерация видео по тексту, генерация видео с условием на действия).
- Рассуждать о физических свойствах, таких как движение, причинно-следственные связи и пространственные отношения.
- Предсказывайте будущие последовательности видео и действий на основе текущего состояния.
- Перенос сцен между точками обзора и условиями с структурным контролем *(скоро)*.
Внутри единый `Cosmos3OmniTransformer` параллельно запускает языковую модель в стиле Qwen и путь диффузионной генерации: токены текста проходят через каузальный поток «понимания», а латенты видео и звука — через поток «генерации» с двунаправленным вниманием, которые объединяются с помощью 3D мультимодального RoPE. Архитектурные подробности описаны в [статье о платформе Cosmos World Foundation Model](https://huggingface.co/papers/2501.03575).
## Доступные контрольные точки
На Hugging Face опубликованы две контрольные точки — [`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 считывает эти значения из чекпоинта, а не использует жёстко закодированные константы. Точность выбирается один раз на каждый шаг планировщика, чтобы вызовы cond/uncond для classifier-free guidance совпадали.
Генерация изображений и дистиллированные чекпоинты с малым числом шагов не демонстрируют мерцания, поэтому Super-T2I и дистиллированные репозитории 4-шагового FP8 не объявляют расписание и остаются в режиме W8A8 на каждом шаге. Расписание также поддерживается только в **ModelOpt FP8**: другие бэкенды квантования (например, TorchAO) сохраняют свои нативные forward-вычисления.
Загрузите репозиторий 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`): если чекпоинт объявляет `diffusion_step_policy`, выполняется W8A16 на первых/последних N шагах и нативный W8A8 в середине. Это рекомендуемый рецепт для многошагового **видео** FP8 (меньше мерцания, чем при полностью W8A8). Дистиллированные 4-шаговые и Super-T2I FP8 не указывают политику, поэтому по умолчанию используется полностью W8A8.
- **`mixed_precision_format="none"`**: каждый шаг выполняется в нативном режиме W8A8. Это быстрее, так как W8A16 использует dequant и `torch.nn.functional.linear`, а не восстановленный FP8 GEMM, но при генерации видео из нескольких шагов возможны мерцания. Используйте этот режим для сравнения расписаний (A/B) или для соответствия полностью квантованной базовой линии.
На одной рабочей станции Blackwell Cosmos3-Nano-FP8 при разрешении 720×1280 и 35 шагах был примерно на **27% медленнее** (T2I) и на **13% медленнее** (T2V с 49 кадрами) при использовании смешанного расписания по умолчанию, чем при значении `"none"`. Эти значения не являются гарантией пропускной способности. Передавайте `"fp8"` только для принудительного применения расписания first/last-N для контрольной точки ModelOpt FP8, у которой нет политики.
## Увеличение размера промпта
Cosmos 3 обучался на длинных, высокоинформативных описаниях. Для достижения оптимального качества короткие текстовые промпты следует **апсемплировать в конкретную JSON-структуру** перед передачей в пайплайн. Апсемплер находится в пакете [cosmos-framework](https://github.com/NVIDIA/cosmos-framework).
Начните с короткого текстового промпта и сохраните его в `assets/prompt.txt`. Для примера генерации видео из текста ниже исходный промпт — *"A robotic arm is cleaning a plate in a kitchen"*:
```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 FPS. Промпт и негативный промпт читаются из файлов, описанных в разделе [Увеличение промптов](#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)
```
## Видео-в-видео со звуком
When the checkpoint carries a `sound_tokenizer`, add `enable_sound=True` to the video-to-video call to jointly generate a synchronized audio track. The waveform is returned alongside the video and can be muxed into the MP4 with [encode_video()](/docs/diffusers/main/ru/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/ru/api/utilities#diffusers.utils.encode_video).
Это тот же вызов, что и в примере text-to-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 runs группирует все специфичные для действия входные данные в [CosmosActionCondition](/docs/diffusers/main/ru/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/ru/api/cache#diffusers.SeaCacheConfig). SeaCache повторно использует остатки трансформера, когда индикатор 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/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline), [Cosmos3OmniModularPipeline](/docs/diffusers/main/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) и [Cosmos3DistilledModularPipeline](/docs/diffusers/main/ru/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, описанные ниже. Решения по кэшированию синхронизируются между рангами. Полная компиляция модели и другие стратегии шардирования модели не заявлены.
## Параллелизм контекста
Для длинных видео или высокого разрешения один прямой проход может превысить бюджет памяти и задержки одного GPU. Cosmos 3 поддерживает **контекстную параллельность (CP)**, чтобы распределять размерность последовательности по нескольким GPU, разделяя вычисления внимания так, чтобы каждое устройство хранило только часть токенов.
Cosmos 3 поддерживает контекстную параллельность **Ulysses** (обмен последовательностей/голов all-to-all). Ring attention не поддерживается.
В отличие от большинства моделей diffusers, Cosmos 3 не **интегрирует** CP в трансформер или декларативный путь `enable_parallelism()`: его групповое запросное внимание, отдельные потоки понимания/генерации (поток генерации обращается к обоим) и неравномерные длины потоков нельзя выразить в виде `_cp_plan`. Вместо этого модель предоставляет небольшие заглушки для шардирования/сбора, а реализация находится в [`examples/cosmos3/cosmos_parallel.py`](https://github.com/huggingface/diffusers/blob/main/examples/cosmos3/cosmos_parallel.py) — в самодостаточном модуле, который можно прочитать целиком и адаптировать. Он предлагает два ортогональных, комбинируемых оси шардирования:
| Вспомогательный | Шарды | Использование |
|---|---|---|
| `enable_cosmos3_context_parallel(transformer, cp_mesh)` | sequence (CP / Ulysses) | задержка на модели, которая помещается на один GPU (`Nano`) |
| `enable_cosmos3_tensor_parallel(transformer, tp_mesh)` | веса (TP) | обучение модели, которая не помещается на один GPU (`Super`) |
Используйте любой из них по отдельности или оба вместе на 2-мерной `(tp, cp)` сетке (см. [Размещение больших моделей с использованием тензорного параллелизма](#fitting-large-models-with-tensor-parallelism)).
Два требования специфичны для Cosmos 3:
- Используйте бэкенд внимания `native`. Cosmos 3 использует групповое запросное внимание (GQA), и только нативный бэкенд SDPA принимает `enable_gqa` (cuDNN и flash его отклоняют). Вспомогательные функции расширяют KV-головы до количества query-голов и вызывают SDPA с `enable_gqa=False`, чтобы он по-прежнему обращался к flash-ядру (иначе сработает математический fallback, который материализует полную матрицу скоростей `[S, S]` и приведёт к OOM на длинных последовательностях).
- Степень CP (Ulysses) должна делить количество query-head (32 для `Nano`, 64 для `Super`); для TP степень должна делить количество KV heads (8). Потоки понимания (текст) и генерации (видео/звук) шардируются независимо вдоль последовательности, а неравные длины внутри дополняются нулями до кратного world size.
### Запустите
Полный CLI [`examples/cosmos3/inference_cosmos3.py`](https://github.com/huggingface/diffusers/blob/main/examples/cosmos3/inference_cosmos3.py) использует [Cosmos3OmniModularPipeline](/docs/diffusers/main/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) и переиспользует эти вспомогательные функции, поэтому **любая модальность** (текст в изображение/видео, изображение в видео, звук, режимы действий) запускается на нескольких GPU через `--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 ГБ и не помещаются на одну GPU с 96 ГБ, поэтому для неё требуется TP; модель `Nano` помещается на одну GPU, поэтому CP для неё является чистой оптимизацией задержки. (Чтобы запустить на одной GPU, опустите оба флага.)
### Обучение больших моделей с использованием тензорного параллелизма
CP разделяет *активации*, но дублирует все веса на каждом ранге, поэтому он не уменьшает объём весов модели — модель, которая не помещается на одном GPU, по-прежнему не влезет при использовании только CP. Чтобы разделить **веса**, `enable_cosmos3_tensor_parallel(transformer, tp_mesh)` применяет тензорный параллелизм в стиле Megatron по второй, ортогональной оси сетки:
- Проекции внимания и MLP распределяются по столбцам/строкам в пределах группы TP (`to_q/to_k/to_v` + `add_q/k/v` и `gate/up` MLP используют параллелизм по столбцам; `to_out/to_add_out` и `down` MLP используют параллелизм по строкам с all-reduce). В итоге каждый ранг владеет `query_heads / tp` заголовками запроса и `kv_heads / tp` заголовками KV.
- TP комбинируется с CP на 2-мерной сетке устройств `(tp, cp)`: TP постоянно разделяет головы/веса, а CP размещает шарды последовательности поверх этого. Ограничения: `tp` должно делить количество KV-голов (8), а `tp * cp` — количество query-голов (32 для `Nano`, 64 для `Super`).
- Веса загружаются на CPU и распределяются по GPU послойно, поэтому полная модель никогда не материализуется на одном устройстве.
> [!TIP]
> TP выполняет all-reduce на каждом блоке внимания и MLP, поэтому требует высокой пропускной способности. На хостах без NVLink это становится основным расходом; выбирайте минимальную степень TP, при которой веса помещаются в память, и распределяйте оставшиеся GPU на CP.
### Используйте его в собственном модульном конвейере
Флаги CLI удобны, но вы можете вызывать хелперы напрямую с помощью [Cosmos3OmniModularPipeline](/docs/diffusers/main/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline). Загрузите конфигурацию пайплайна и компоненты на CPU, примените TP *до* перемещения пайплайна на локальный для ранга 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 (без шардирования весов) используйте 1-мерную сетку: `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]
> On some multi-GPU topologies the first NCCL all-to-all can hang. If a CP run stalls at the start of the first denoising step, set `NCCL_P2P_DISABLE=1` in the environment before launching `torchrun`.
CP и TP сочетаются со всеми описанными выше рабочими процессами (генерация видео по тексту, генерация видео по изображению, генерация видео по тексту со звуком и генерация, управляемая действиями), а также с контрольными точками `Nano` и `Super` — меняются только строки, отвечающие за построение конвейера и настройку параллелизма.
## Шаблоны метаданных
`tokenize_prompt` добавляет короткие метаданные в сообщение пользователя, чтобы LLM видела те условия, с которыми обучалась модель. В положительный промпт добавляются предложения вида *"Видео длится 7,9 секунды и имеет частоту кадров 24 FPS."* и *"Разрешение этого видео составляет 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` и запускает его **по умолчанию**. Текстовый guardrail отклоняет небезопасные промпты до генерации (`ValueError`); guardrail для видео работает с декодированными кадрами и либо пикселизирует обнаруженные лица, либо отклоняет результат. Аудиовыход не защищается guardrail.
Установите необязательную зависимость, чтобы включить проверщик по умолчанию:
```
pip install cosmos_guardrail
```
Проверка является обязательной в соответствии с лицензионным соглашением NVIDIA Open Model. Два флага ниже существуют для тестов и рабочих процессов разработки, где защитный механизм был бы избыточным (например, входные данные уже очищены, или вы намеренно проверяете работу конвейера на граничных входных данных).
**Отключение при создании** (проверщик не создаётся, поэтому модели guardrail не скачиваются и не загружаются в память):
```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,
)
```
Чтобы передать собственный проверяющий модуль (например, подкласс no-op для быстрых тестов), укажите его как `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]`.
Добавляет/удаляет размерность батча, ожидаемую декодером звукового токенизатора.
#### 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)` — списки идентификаторов токенов для этого примера.
Примените шаблоны дополнения промпта и токенизируйте условные и безусловные промпты с помощью настроенного шаблона чата.
Этот конвейер не запускает отдельный текстовый энкодер: объединённый трансформер Cosmos3 принимает сырые идентификаторы токенов наряду с визуальными (и, при необходимости, звуковыми) токенами.
Если `negative_prompt` равен `None`, используется пустая строка; на странице документации Cosmos3 описаны рекомендуемые негативные промпты для контроля качества, которые следует передавать явно для text2video / image2video. Шаблоны длительности и разрешения добавляются к промпту, а обратные шаблоны — к негативному промпту, если эта функция включена.
Когда задано `action_mode`, промпт преобразуется в структурированную JSON-подпись действия, на которой обучалась модель (см. `_build_action_json_prompt`), при этом поле `action_view_point` используется для поля framing; плоские шаблоны метаданных пропускаются, поскольку JSON уже содержит duration/fps/resolution/aspect_ratio.
- все
- __call__
## Cosmos3OmniModularPipeline
Cosmos 3 также доступен в виде конвейера Modular Diffusers. Конвейер [Cosmos3OmniPipeline](/docs/diffusers/main/ru/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/ru/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`). Transfer (структурное управление) имеет собственные входные данные и показан отдельно в разделе [Модульный transfer](#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` | Геометрия |
| --- | --- | --- | --- | --- |
| Edge / Blur / Depth | 3.0 | 1.5 | 10.0 | 121 кадр @ 30 FPS |
| Сегментация | 3.0 | 2.0 | 10.0 | 121 кадр @ 30 FPS |
| Мировой сценарий (WSM) | 1.0 | 3.0 | 10.0 | 101 кадр @ 10 FPS |
Diffusers не включает в себя контрольные ресурсы. Готовые (видео для управления + соответствующий `prompt.json` для каждого подсказки, а также общий `negative_prompt.json`) находятся в [Cosmos cookbook](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 (few-step) генерация изображений по тексту и видео по изображению[[diffusers.Cosmos3OmniModularPipeline]]
Чекпоинты с дистилляцией в несколько шагов обслуживаются [Cosmos3DistilledModularPipeline](/docs/diffusers/main/ru/api/pipelines/cosmos3#diffusers.Cosmos3DistilledModularPipeline) (блоки: `Cosmos3DistilledBlocks`); базовые [Cosmos3OmniModularPipeline](/docs/diffusers/main/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) и [Cosmos3OmniPipeline](/docs/diffusers/main/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline) их не поддерживают. Значение `num_inference_steps` фиксировано и равно длине конфигурации пайплайна `distilled_sigmas` (из файла `modular_model_index.json` чекпоинта), а `guidance_scale` принудительно устанавливается в 1.0, поскольку guidance уже встроен в веса — передача любого другого значения для любого из этих параметров приводит к ошибке, а `negative_prompt` игнорируется с выводом предупреждения.
FP8 дистиллированные контрольные точки (`revision="fp8"`) не объявляют политику смешанной точности, поэтому каждый шаг остаётся нативным W8A8.
Промпты используют ту же описательную структуру JSON, что и недистиллированные модели, поэтому короткий текст сначала нужно увеличить — используйте `--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.
Дистиллированные контрольные точки встраивают 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-описаниях, содержащих это предложение о точке зрения; нераспознанная метка приводит к удалению поля framing (с выводом предупреждения).
Группирует все входные данные, необходимые для задачи генерации с управлением действиями в 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`, если режим действия не предсказывает действия.
Dataclass выходных данных для [Cosmos3OmniPipeline](/docs/diffusers/main/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline).
#
# Лицензия Apache License, Version 2.0 («Лицензия»);
# вы можете использовать этот файл только в соответствии с Лицензией.
# Вы можете получить копию Лицензии по адресу
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Если это не требуется применимым законодательством или не оговорено письменно, программное
# распространяется по Лицензии на условиях «КАК ЕСТЬ»,
# БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ, прямо указанных или подразумеваемых.
# См. Лицензию для получения конкретных условий, регулирующих разрешения и
# ограничениями Лицензии. -->
# Cosmos 3
NVIDIA Cosmos 3 — это единая базовая модель мира (WFM) для Physical AI: универсальная модель, объединяющая генерацию мира, физическое рассуждение и генерацию действий. Она заменяет отдельные модели Predict, Reason и Transfer из предыдущих релизов Cosmos: независимо от того, разрабатываете ли вы решения для робототехники, автономных транспортных средств или умных пространств, Cosmos 3 предоставляет единую основу для симуляции и понимания физического мира.
Что входит в этот релиз:
- Модели на Hugging Face Hub с карточками моделей и лицензиями
- Интеграция Cosmos 3 Diffusers для конвейеров генерации (эта страница)
- Скрипты постобучения для дообучения Cosmos 3 на собственных данных
- Открытые наборы данных для генерации синтетических данных (SDG) для Physical AI
## Что нового в Cosmos 3
Главное отличие Cosmos 3 от предыдущих релизов Cosmos заключается в том, что это *омни-модель*, построенная на архитектуре Mixture-of-Transformers (MoT). Ранее разработчики работали с отдельными моделями для генерации мира (Predict), управляемой генерации (Transfer), понимания сцены (Reason) и генерации политик действий. Cosmos 3 объединяет все эти функции в одной модели, которая рассуждает и генерирует данные в разных модальностях за один прямой проход.
Из одной модели можно:
- Генерация физически правдоподобных видеомиров по тексту, изображениям или входным действиям (генерация видео из изображений, генерация видео по тексту, генерация видео с условием на действия).
- Рассуждать о физических свойствах, таких как движение, причинно-следственные связи и пространственные отношения.
- Предсказывайте будущие последовательности видео и действий на основе текущего состояния.
- Перенос сцен между точками обзора и условиями с структурным контролем *(скоро)*.
Внутри единый `Cosmos3OmniTransformer` параллельно запускает языковую модель в стиле Qwen и путь диффузионной генерации: токены текста проходят через каузальный поток «понимания», а латенты видео и звука — через поток «генерации» с двунаправленным вниманием, которые объединяются с помощью 3D мультимодального RoPE. Архитектурные подробности описаны в [статье о платформе Cosmos World Foundation Model](https://huggingface.co/papers/2501.03575).
## Доступные контрольные точки
На Hugging Face опубликованы две контрольные точки — [`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 считывает эти значения из чекпоинта, а не использует жёстко закодированные константы. Точность выбирается один раз на каждый шаг планировщика, чтобы вызовы cond/uncond для classifier-free guidance совпадали.
Генерация изображений и дистиллированные чекпоинты с малым числом шагов не демонстрируют мерцания, поэтому Super-T2I и дистиллированные репозитории 4-шагового FP8 не объявляют расписание и остаются в режиме W8A8 на каждом шаге. Расписание также поддерживается только в **ModelOpt FP8**: другие бэкенды квантования (например, TorchAO) сохраняют свои нативные forward-вычисления.
Загрузите репозиторий 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`): если чекпоинт объявляет `diffusion_step_policy`, выполняется W8A16 на первых/последних N шагах и нативный W8A8 в середине. Это рекомендуемый рецепт для многошагового **видео** FP8 (меньше мерцания, чем при полностью W8A8). Дистиллированные 4-шаговые и Super-T2I FP8 не указывают политику, поэтому по умолчанию используется полностью W8A8.
- **`mixed_precision_format="none"`**: каждый шаг выполняется в нативном режиме W8A8. Это быстрее, так как W8A16 использует dequant и `torch.nn.functional.linear`, а не восстановленный FP8 GEMM, но при генерации видео из нескольких шагов возможны мерцания. Используйте этот режим для сравнения расписаний (A/B) или для соответствия полностью квантованной базовой линии.
На одной рабочей станции Blackwell Cosmos3-Nano-FP8 при разрешении 720×1280 и 35 шагах был примерно на **27% медленнее** (T2I) и на **13% медленнее** (T2V с 49 кадрами) при использовании смешанного расписания по умолчанию, чем при значении `"none"`. Эти значения не являются гарантией пропускной способности. Передавайте `"fp8"` только для принудительного применения расписания first/last-N для контрольной точки ModelOpt FP8, у которой нет политики.
## Увеличение размера промпта
Cosmos 3 обучался на длинных, высокоинформативных описаниях. Для достижения оптимального качества короткие текстовые промпты следует **апсемплировать в конкретную JSON-структуру** перед передачей в пайплайн. Апсемплер находится в пакете [cosmos-framework](https://github.com/NVIDIA/cosmos-framework).
Начните с короткого текстового промпта и сохраните его в `assets/prompt.txt`. Для примера генерации видео из текста ниже исходный промпт — *"A robotic arm is cleaning a plate in a kitchen"*:
```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:
- 85.6 kB
- Xet hash:
- c707e87277ea5de87072f0a84a521dca1c14dfd170e79761a8da0680ddf15ff1
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.