Cosmos3

Cosmos3

NVIDIA Cosmos3는 텍스트/이미지/비디오 생성, 선택적 동기화 사운드, 로봇 행동(action) 예측을 아우르는 옴니모달 세계 모델(world-model) 제품군이에요. 가장 큰 장점은 폭이 넓다는 점이에요. 같은 네이티브 SGLang 파이프라인이 LLM 샘플러를 거치지 않고 미디어 생성 체크포인트와 DROID 정책 체크포인트를 모두 서빙할 수 있어요. 가장 넓은 모달리티 커버리지와 낮은 배포 비용을 원하면 Nano, 더 큰 64B 이미지/비디오 모델이 필요하면 Super, T2I/I2V만 필요할 때는 전용 체크포인트를 고르세요.

사운드와 action은 체크포인트 특화 헤드이므로 모든 Cosmos3 저장소에서 사용할 수 있는 것은 아니에요.

출처: 문서

본문

1. 모델 소개

NVIDIA Cosmos3는 텍스트/이미지/비디오 생성, 선택적 동기화 사운드, 로봇 action 예측을 아우르는 옴니모달 세계 모델 제품군이에요. 가장 큰 장점은 폭이 넓다는 점이에요. 같은 네이티브 SGLang 파이프라인이 LLM 샘플러를 거치지 않고 미디어 생성 체크포인트와 DROID 정책 체크포인트를 모두 서빙할 수 있어요.

가장 넓은 모달리티 커버리지와 낮은 배포 비용에는 Nano, 더 큰 64B 이미지/비디오 모델에는 Super, T2I 또는 I2V만 필요할 때는 전용 체크포인트를 선택하세요. 사운드와 action은 체크포인트 특화 헤드이므로 모든 Cosmos3 저장소에서 제공되지는 않아요.

Model Status Notes
nvidia/Cosmos3-Nano Supported T2I, T2V, I2V, V2V, joint sound, action
nvidia/Cosmos3-Super Supported T2I, T2V, I2V, V2V; 64B 체크포인트는 멀티 GPU 사용
nvidia/Cosmos3-Super-Text2Image Supported T2I 전용 체크포인트
nvidia/Cosmos3-Super-Image2Video Supported I2V 전용 체크포인트
nvidia/Cosmos3-Nano-Policy-DROID Supported DROID 정책 action 생성
nvidia/Cosmos3-Edge Supported T2I, T2V, I2V, V2V, action 생성용 4B dense 모델
nvidia/Cosmos3-Edge-Policy-DROID Supported 4B DROID 정책 action 생성
nvidia/Cosmos3-Super-Text2Image-4Step Supported 고정 4-step 스케줄로 증류된 64B T2I 체크포인트
nvidia/Cosmos3-Super-Image2Video-4Step Supported 고정 4-step 스케줄로 증류된 64B I2V 체크포인트

사운드와 action 생성은 해당 체크포인트 헤드가 필요해요. 파이프라인은 시작 시 트랜스포머와 스케줄러 구성을 읽으므로, Edge 및 증류 체크포인트는 아키텍처별 서버 플래그가 필요 없어요. 비-증류 체크포인트는 flow 네이티브 FlowUniPCMultistepScheduler를, 증류 체크포인트는 체크포인트에 저장된 고정 sigma 스케줄을 사용해요.

기본 flow_shift는 T2I가 3.0, 비-Edge 비디오와 모든 action 모드가 10.0, Edge 비디오 모드가 3.0이에요. 증류 체크포인트는 스케줄을 sigmas에 구워 넣으므로 요청 수준 flow_shift를 사용하지 않아요.

2. 설치

diffusion 의존성과 함께 SGLang을 설치하세요:

pip install -e "python[diffusion]"

패키지가 있을 때 Cosmos3 가드레일(guardrail)은 기본으로 활성화돼요:

pip install "cosmos-guardrail==0.3.1"

cosmos-guardrail은 게이티드 NVIDIA 가드레일 가중치를 다운로드하므로 환경에 필요하면 Hugging Face 토큰을 전달하세요. 패키지가 설치되지 않으면 SGLang은 Cosmos3 가드레일을 건너뛰고 경고를 기록해요. 로컬 실험에서 Cosmos3 가드레일을 비활성화하려면 서버 시작 전에 SGLANG_DISABLE_COSMOS3_GUARDRAILS=1을 설정하세요.

Ascend NPU에서 Cosmos-1.0-Guardrail 가중치 로딩에 문제가 있을 수 있어요. 시작 중 *\_pickle.UnpicklingError 오류가 발생하면 cosmos\_guardrail/cosmos\_utils.py에서 weight_only=True를 weights_only=False 파라미터로 바꾸세요:

#!/usr/bin/env bash
COSMOS_GUARDRAIL_DIR="$(dirname "$(python -c 'import cosmos_guardrail; print(cosmos_guardrail.__file__)')")"
sed -i 's/weights_only=True/weights_only=False/g' "$COSMOS_GUARDRAIL_DIR/cosmos_utils.py"

3. Cosmos3 서빙

Hugging Face 모델 ID로 Cosmos3-Nano를 직접 서빙하세요:

sglang serve \
  --model-path nvidia/Cosmos3-Nano \
  --num-gpus 1

--performance-mode auto에서는 시작 시 선택된 모든 GPU에 최소 90 GiB가 있으면 Cosmos3-Nano가 DiT와 VAE를 상주시켜요. 다른 Cosmos3 체크포인트는 120 GiB 임계값을 사용해요. 해당 임계값 미만에서는 auto 모드가 보수적인 DiT component-offload 정책을 유지해요. Cosmos3는 파이프라인당 DiT 하나를 실행하므로 임계값 이상에서의 component offload는 매 요청마다 가중치를 호스트 메모리로 내보냈다 다시 가져오는 비용만 들어요. 아래처럼 Cosmos3-Super를 여러 GPU에 걸쳐 서빙해 각 랭크가 가중치의 샤드를 유지하게 하세요.

Cosmos3-Super는 여러 GPU에 걸쳐 모델을 분할하세요:

sglang serve \
  --model-path nvidia/Cosmos3-Super \
  --num-gpus 4

서버는 전용 nvidia/Cosmos3-Super-Text2Image와 nvidia/Cosmos3-Super-Image2Video 체크포인트 ID도 허용해요.

Edge 체크포인트

Cosmos3-Edge는 4B dense 모델이며 한 GPU에서 서빙 가능해요:

sglang serve \
  --model-path nvidia/Cosmos3-Edge \
  --num-gpus 1

Edge는 256p와 480p 생성을 위해 훈련됐어요. 기본 비디오 구성은 832x480에 guidance_scale=5.0, 기본 이미지 구성은 640x640에 guidance_scale=7.0이에요. 지원 크기는 832x480, 480x832, 640x480, 480x640, 480x480, 640x640, 448x256, 256x448, 256x256이에요.

Edge DROID 정책 체크포인트는 같은 단일 GPU 구성으로, 모델 경로를 nvidia/Cosmos3-Edge-Policy-DROID로 바꿔 서빙하세요.

증류 체크포인트

증류된 Super 체크포인트는 64B 모델이에요. 완전한 모델과 요청 워크로드가 한 GPU에 맞지 않으면 여러 GPU를 사용하세요:

sglang serve \
  --model-path nvidia/Cosmos3-Super-Text2Image-4Step \
  --num-gpus 4

증류 I2V는 모델 경로를 nvidia/Cosmos3-Super-Image2Video-4Step로 바꾸세요. SGLang은 scheduler/scheduler_config.json에서 두 체크포인트를 감지하고, 체크포인트의 고정 4-step sigma 스케줄을 사용하며 guidance_scale=1.0을 강제해요. 이 체크포인트들에는 num_inference_steps나 flow_shift를 튜닝하지 마세요.

4. OpenAI 호환 요청

텍스트-이미지

Cosmos3 텍스트-이미지는 /v1/images/generations를 사용해요. 기본 Cosmos3 이미지 응답은 b64_json으로 vLLM-Omni 예제와 일치해요.

curl -sS -X POST http://127.0.0.1:30010/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warehouse robot folds a blue cloth on a clean workbench.",
    "size": "1280x720",
    "n": 1,
    "num_inference_steps": 35,
    "guidance_scale": 6.0,
    "flow_shift": 3.0,
    "seed": 0,
    "extra_body": {
      "use_resolution_template": false,
      "guardrails": true
    }
  }'

nvidia/Cosmos3-Super-Text2Image-4Step을 실행하는 서버에서는 스케줄러 제어를 생략하고 guidance_scale=1.0을 사용하세요:

curl -sS -X POST http://127.0.0.1:30010/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warehouse robot folds a blue cloth on a clean workbench.",
    "size": "640x640",
    "n": 1,
    "guidance_scale": 1.0,
    "seed": 0,
    "extra_body": {
      "use_resolution_template": false,
      "guardrails": true
    }
  }'

사운드가 있는 텍스트-비디오

/v1/videos로 비동기 작업을 만들고 작업을 폴링한 뒤 완성된 MP4를 다운로드하세요. generate_sound=true를 설정하면 스테레오 48 kHz 오디오 트랙을 생성·멀티플렉싱하고, 생략하면 무성 비디오예요.

job_id=$(curl -sS -X POST http://127.0.0.1:30010/v1/videos \
  --form-string "prompt=A small warehouse robot moves a blue box across a clean floor." \
  --form-string "negative_prompt=blurry, distorted, low quality" \
  --form-string "size=1280x720" \
  --form-string "num_frames=81" \
  --form-string "fps=24" \
  --form-string "num_inference_steps=35" \
  --form-string "guidance_scale=4.0" \
  --form-string "flow_shift=10.0" \
  --form-string "generate_sound=true" \
  --form-string "seed=42" \
  --form-string 'extra_params={"guardrails":true,"use_resolution_template":false,"use_duration_template":false}' \
  | python -c 'import json, sys; print(json.load(sys.stdin)["id"])')

while true; do
  status=$(curl -sS "http://127.0.0.1:30010/v1/videos/${job_id}" \
    | python -c 'import json, sys; print(json.load(sys.stdin)["status"])')
  [ "$status" = "completed" ] && break
  [ "$status" = "failed" ] && exit 1
  sleep 1
done

curl -sS -L "http://127.0.0.1:30010/v1/videos/${job_id}/content" \
  -o cosmos3_t2v.mp4

이미지-비디오

이것은 공식 nvidia/Cosmos3-Nano Hugging Face 이미지-비디오 예제를 반영해요:

from pathlib import Path

from huggingface_hub import snapshot_download

base_url = "http://127.0.0.1:30010"
model_dir = Path(snapshot_download("nvidia/Cosmos3-Nano"))
asset_dir = model_dir / "assets"

prompt = json.dumps(json.loads((asset_dir / "example_i2v_prompt.json").read_text()))
negative_prompt = json.dumps(
    json.loads((asset_dir / "negative_prompt.json").read_text())
)

data = {
    "prompt": prompt,
    "negative_prompt": negative_prompt,
    "size": "1280x720",
    "num_frames": "189",
    "fps": "24",
    "num_inference_steps": "35",
    "guidance_scale": "6.0",
    "max_sequence_length": "4096",
    "flow_shift": "10.0",
    "seed": "1111",
    "extra_params": json.dumps(
        {
            "use_resolution_template": False,
            "use_duration_template": False,
            "guardrails": True,
        }
    ),
}

with (asset_dir / "example_i2v_input.jpg").open("rb") as image:
    response = requests.post(
        f"{base_url}/v1/videos",
        data=data,
        files={"input_reference": ("example_i2v_input.jpg", image, "image/jpeg")},
        timeout=60,
    )
response.raise_for_status()
video_id = response.json()["id"]

while True:
    job = requests.get(f"{base_url}/v1/videos/{video_id}", timeout=30).json()
    if job["status"] == "completed":
        break
    if job["status"] == "failed":
        raise RuntimeError(job.get("error") or "Video generation failed")
    time.sleep(1)

response = requests.get(f"{base_url}/v1/videos/{video_id}/content", timeout=300)
response.raise_for_status()
Path("cosmos3_i2v.mp4").write_bytes(response.content)

증류 I2V 체크포인트의 경우 nvidia/Cosmos3-Super-Image2Video-4Step을 실행하는 서버로 같은 API를 사용해요. 권장 요청은 480p이며 스케줄러 제어를 지정하지 않아요:

job_id=$(curl -sS -X POST http://127.0.0.1:30010/v1/videos \
  --form-string "prompt=A warehouse robot carefully places a blue box on a shelf." \
  --form "input_reference=@first_frame.png;type=image/png" \
  --form-string "size=832x480" \
  --form-string "num_frames=189" \
  --form-string "fps=24" \
  --form-string "guidance_scale=1.0" \
  --form-string "seed=42" \
  --form-string 'extra_params={"guardrails":true,"use_resolution_template":false,"use_duration_template":false}' \
  | python -c 'import json, sys; print(json.load(sys.stdin)["id"])')

이 작업을 T2V 예제가 사용하는 것과 같은 status·content 엔드포인트로 폴링하고 다운로드하세요.

비디오-비디오

video_reference로 소스 비디오를 업로드하세요. Cosmos3는 기본적으로 latent 프레임 [0, 1]을 유지하고 나머지 프레임을 생성해요. condition_frame_indexes로 다른 latent 프레임을 선택하고, condition_video_keep으로 조건 프레임을 소스의 시작 또는 끝에서 가져와요.

job_id=$(curl -sS -X POST http://127.0.0.1:30010/v1/videos \
  --form-string "prompt=A robotic arm pours liquid into a glass on a white tabletop." \
  --form "video_reference=@robot_pouring.mp4;type=video/mp4" \
  --form-string "size=1280x704" \
  --form-string "num_frames=45" \
  --form-string "fps=24" \
  --form-string "num_inference_steps=35" \
  --form-string "guidance_scale=6.0" \
  --form-string 'condition_frame_indexes=[0,1]' \
  --form-string "condition_video_keep=first" \
  | python -c 'import json, sys; print(json.load(sys.stdin)["id"])')

이 작업을 T2V 예제와 같은 status·content 엔드포인트로 폴링하고 다운로드하세요.

Action 생성

DROID 정책 생성을 위해 Nano 또는 Edge 정책 체크포인트로 단일 GPU 서버를 시작하세요. Cosmos3 action 생성은 현재 CFG나 시퀀스 병렬 처리를 지원하지 않아요.

sglang serve \
  --model-path nvidia/Cosmos3-Nano-Policy-DROID \
  --num-gpus 1

같은 명령에서 nvidia/Cosmos3-Edge-Policy-DROID를 사용하면 더 작은 4B 정책 체크포인트를 서빙할 수 있어요.

policy와 inverse_dynamics는 action을 반환하므로 그 정규 API는 동기식 /v1/actions/generations 엔드포인트예요. 다음 요청은 하나의 observation 이미지로부터 16-step action 청크를 예측해요. action_horizon=16은 모델의 num_frames=17 규약에 대응해요.

from pathlib import Path


image_b64 = base64.b64encode(Path("observation.png").read_bytes()).decode()
response = requests.post(
    "http://127.0.0.1:30010/v1/actions/generations",
    json={
        "input": {
            "task": "Put the pot to the left of the purple item.",
            "observation": {
                "image": {"b64_json": image_b64},
            },
        },
        "parameters": {
            "action_mode": "policy",
            "action_horizon": 16,
            "domain_name": "droid_lerobot",
            "height": 480,
            "width": 832,
            "fps": 5,
            "num_inference_steps": 30,
            "guidance_scale": 1.0,
            "seed": 42,
        },
    },
    timeout=300,
)
response.raise_for_status()
action = response.json()["data"][0]["action"]
print(action["shape"], action["values"])

GET /v1/actions/metadata로 action 모드, 기본 horizon, 패딩된 action 차원, 허용 observation 모달리티를 확인하세요. Msgpack 요청과 /v1/actions/realtime 웹소켓은 같은 action 인벨로프를 사용해요.

한 요청 안에서 정책 observation을 배치하려면 제한된 배치 크기로 옵트인하세요:

sglang serve \
  --model-path nvidia/Cosmos3-Nano-Policy-DROID \
  --num-gpus 1 \
  --batching-max-size 4

observation마다 이미지 하나를 리스트나 [B, H, W, C] uint8 배열로 input.input_reference에 보내고, 이미지당 프롬프트 하나 또는 배치 전체에 브로드캐스트할 스칼라 프롬프트 하나를 보내세요. Cosmos3 GEN cross-attention이 패딩된 텍스트 K/V를 마스킹하지 않으므로, 배치 프롬프트는 현재 같은 길이로 토큰화되어야 해요. 한 요청의 모든 항목은 domain, 해상도, action horizon, denoise 설정을 공유해요. 표준 action 인벨로프는 입력마다 data[i] 항목 하나를 반환하며 각 항목은 action shape [H, D]를 가져요. 하나의 [B, H, D] 배열을 담은 컴팩트한 msgpack 응답을 원하면 runtime.response_format="raw"를 설정하고 최상위 actions 필드를 읽으세요.

JSON에서는 input_reference가 base64 이미지 페이로드 리스트일 수 있어요. msgpack에서는 패킹된 uint8 numpy 배열을 직접 쓸 수 있어요:

{
  "input": {
    "prompt": ["pick up the block", "close the drawer"],
    "input_reference": [
      {"b64_json": "<first-image-base64>"},
      {"b64_json": "<second-image-base64>"}
    ]
  },
  "parameters": {
    "action_mode": "policy",
    "domain_name": "droid_lerobot"
  }
}

배치 크기는 --batching-max-size를 초과할 수 없어요. 이렇게 하면 한 요청이 서버의 구성된 메모리 한도를 우회하지 못해요. 배칭은 action_mode="policy"에만 적용돼요. 요청 시드는 전체 배치의 랜덤 스트림을 제어하므로, 배치 결과는 그 요청에 대해 결정적이지만 별도 시드의 B=1 요청과 비트 단위로 정확할 것으로 기대되지는 않아요.

inverse_dynamics도 /v1/actions/generations를 사용해요. action_mode="inverse_dynamics"를 설정하고 input.observation.video로 observation 비디오 URL 또는 서버 로컬 경로를 전달하세요. domain_name 또는 domain_id로 embodiment 헤드를 선택하고, domain 이름에서 추론할 수 없을 때 raw_action_dim을 명시적으로 설정하세요.

forward_dynamics는 의도적으로 달라요. action 배열을 소비하고 비디오를 예측하므로 /v1/videos에 유지돼요. /v1/videos에 제출된 action 생성 모드는 오류 메시지에 정식 action 엔드포인트를 담아 HTTP 400을 반환해요.

5. Cosmos3 파라미터

Cosmos3는 size, num_frames, fps, num_inference_steps, guidance_scale, negative_prompt, seed 같은 표준 SGLang 비디오·이미지 필드를 지원해요. 증류 체크포인트에서는 SGLang이 num_inference_steps를 체크포인트의 고정 4-step 스케줄로 대체하고 guidance_scale=1.0을 강제해요. negative-prompt CFG와 요청 수준 flow_shift는 적용되지 않아요.

최상위 Cosmos3 요청 필드:

  • max_sequence_length: Cosmos3 토크나이저가 사용하는 최대 텍스트 토큰 길이.
  • flow_shift: 비-증류 체크포인트용 요청별 스케줄러 시프트. 생략하면 SGLang이 --flow-shift, 그다음 모드 기본값(T2I는 3.0, 비-Edge 비디오와 모든 action 모드는 10.0, Edge 비디오는 3.0)을 사용해요.
  • guidance_interval: CFG용 선택적 [start, end] 노이즈 구간. 비-증류 T2I 기본값은 [400, 1000]이고, 비디오 모드는 매 step에서 guidance해요.

Cosmos3 옴니모달 필드는 추가 JSON 필드 또는 multipart form 필드로 받아들여져요:

  • generate_sound: 길이가 num_frames / fps를 따르는 사운드 트랙 생성.
  • sound_duration: 초 단위 명시적 사운드 길이. 파생된 길이보다 우선해요.
  • condition_frame_indexes: 소스 비디오에서 유지할 V2V latent-frame 인덱스. 기본값 [0, 1].
  • condition_video_keep: V2V 컨디셔닝에 소스의 first 또는 last 프레임 사용.
  • action_mode: policy, forward_dynamics, 또는 inverse_dynamics.
  • domain_name / domain_id: action embodiment 헤드 선택.
  • raw_action_dim: 활성 action 차원 수. 알려진 domain 이름에서는 추론됨.
  • action: shape [T, D]의 action 배열. forward_dynamics에 필요.
  • action_fps: temporal mRoPE용 action-토큰 프레임 레이트. 기본값은 비디오 FPS.
  • action_view_point: 구조화된 action 캡션에 사용되는 뷰포인트.
  • action_normalization: 데이터셋 정규화 모드(예: quantile, meanstd, minmax).

모델별 제어는 OpenAI Python SDK로 extra_body를 통해 전달하세요. Raw JSON은 최상위에 유지할 수 있고, multipart 비디오 요청은 extra_params JSON 객체에 넣어야 해요. 레거시 이미지 extra_args 컨테이너는 호환을 위해 계속 허용되지만, 새 클라이언트는 extra_body를 사용하세요:

  • use_duration_template: 비디오 프롬프트에 SGLang 생성 duration 접미사를 추가할지 여부.
  • use_resolution_template: vLLM-Omni 요청 호환을 위해 허용.
  • use_system_prompt: 채팅 템플릿에 Cosmos3 시스템 프롬프트를 추가할지 여부.
  • guardrails 또는 use_guardrails: 서버가 가드레일로 시작했을 때 요청별 가드레일 토글.

6. ComfyUI에서 실행

더 알아보기 (Learn more)