#
# Лицензия 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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline), [Cosmos3OmniModularPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) и [Cosmos3DistilledModularPipeline](/docs/diffusers/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/main/cookbooks/cosmos3/generator/transfer/assets). Для примера с краем, приведённого ниже, скачайте их в локальную папку `assets/`:

```bash
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
```

```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/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3DistilledModularPipeline) (блоки: `Cosmos3DistilledBlocks`); базовые [Cosmos3OmniModularPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) и [Cosmos3OmniPipeline](/docs/diffusers/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/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/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline).