Skip to content

[new-model] Add Cosmos Predict2.5 2B distilled T2W inference - #1767

Open
Mister-Raggs wants to merge 16 commits into
hao-ai-lab:mainfrom
Mister-Raggs:feat/cosmos25-distilled-sampler
Open

[new-model] Add Cosmos Predict2.5 2B distilled T2W inference#1767
Mister-Raggs wants to merge 16 commits into
hao-ai-lab:mainfrom
Mister-Raggs:feat/cosmos25-distilled-sampler

Conversation

@Mister-Raggs

@Mister-Raggs Mister-Raggs commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Purpose

Add initial FastVideo inference support for NVIDIA's released Cosmos Predict2.5 2B distilled Text2World student. The port follows the student's official fixed-noise four-step TrigFlow rollout rather than reusing the full model's UniPC path.

This is a draft because a public converted FastVideo package ID is still pending. It also depends on #1607; this branch currently carries the same two Reason1 commits so the end-to-end validation is reproducible, and they can be dropped once #1607 lands.

Changes

  • Add Cosmos25DistilledScheduler with the official preconditioning, x0 conversion, fixed initial noise, and four-step schedule.
  • Select isolated distilled latent-preparation and denoising stages from packaged scheduler metadata, leaving the existing Cosmos Predict2.5 path unchanged.
  • Gate the initial scope to T2W, guidance scale 1, and 1-4 inference steps.
  • Add a converter for NVIDIA's monolithic base/distilled student checkpoint while reusing the existing Cosmos Predict2.5 tokenizer, VAE, and Reason1 components.
  • Add a runnable converted-model example, CPU contracts, pinned official scheduler parity, real-weight DiT parity, and validation notes.
cosmos25_distilled_full.mp4

Test plan and results

Spark / GB10, BF16 with Torch SDPA:

  • Scheduler unit tests: 7 passed.
  • Pinned official scheduler parity: 2 passed, non-skipped.
  • Conversion contracts: 7 passed.
  • Pipeline contracts: 9 passed.
  • Released 3.9 GB student checkpoint converted to a clean package: 685 student tensors, no training counters; production strict load passed.
  • Official-vs-FastVideo student DiT parity passed: first-block relative mean error 0.000655, final relative mean error 0.038397, final mean absolute error 0.037414.
  • Small one-step 256x448x9 T2W smoke passed; 2.19 seconds after model load.
  • Decoded-frame contract passed: 9 RGB frames, first shape (256, 448, 3).
  • Full four-step 704x1280x77 generation passed in 143.53 seconds after model load and passed visual inspection.

Local static validation:

  • git diff --check: passed.
  • codespell, PyMarkdown, and filename hooks: passed.
  • The lightweight Mac environment could not collect the Python suites because torchvision is not installed; the same suites and GPU gates above passed in the FastVideo environment on Spark.

Scope and limitations

  • T2W only. This PR does not claim distilled V2W, rolling generation, or real-time latency.
  • The validated configuration is BF16 + Torch SDPA on GB10.
  • Until a converted model is published, users must run the included conversion script and pass the local output directory to the example.
  • No SSIM baseline exists for this new distilled path; the full output received a manual visual quality check.

Checklist

  • Existing full-step Cosmos Predict2.5 routing remains unchanged.
  • New behavior is covered by scheduler, conversion, pipeline, and reference-parity tests.
  • Documentation and the compatibility-matrix packaging note are updated.
  • Relevant pre-commit documentation hooks pass.
  • Publish and register the converted model package before marking ready for final review.
  • Drop the duplicated Reason1 commits after [bugfix] reason1: handle BatchEncoding from apply_chat_template #1607 merges.

Cosmos-Predict2.5 2B text encoding crashes on load because
`apply_chat_template(tokenize=True)` returns a transformers `BatchEncoding`
-- a `collections.UserDict`, i.e. a `Mapping` but NOT a `dict` -- which the
`isinstance(tokenizer_output, dict)` check missed, so the id extraction fell
through to `raise RuntimeError("Unexpected chat_template output type")`.

Match on `Mapping` instead (every `dict` is a `Mapping`, so existing
plain-dict and list outputs are unchanged) and lift the normalization into a
tested `_normalize_chat_template_ids` helper. Add weight-free parametrized
regression tests over every shape apply_chat_template can return.
Address review: the helper documents a flat list[int] contract, but a nested
list with batch>1 slipped through the len==1 unwrap guard and was returned
as-is, violating the contract and breaking downstream padding. Raise on
batch>1 instead of silently returning a nested list; add tests.
@mergify mergify Bot added type: new-model New model support scope: inference Inference pipeline, serving, CLI scope: infra CI, tests, Docker, build scope: docs Documentation scope: model Model architecture (DiTs, encoders, VAEs) labels Aug 27, 2026
@mergify

mergify Bot commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Merge Protections

🔴 1 of 1 protections blocking · waiting on 👀 reviews and 🤖 CI

Protection Waiting on
🔴 PR merge requirements 👀 reviews and 🤖 CI

🔴 PR merge requirements

Waiting for

  • #approved-reviews-by>=1
  • check-success=fastcheck-passed
  • check-success=full-suite-passed
  • check-success~=pre-commit
This rule is failing.
  • #approved-reviews-by>=1
  • check-success=fastcheck-passed
  • check-success=full-suite-passed
  • check-success~=pre-commit
  • title~=(?i)^\[(feat|feature|bugfix|fix|refactor|perf|ci|doc|docs|misc|chore|kernel|new.?model|skill|skills|infra)\]

@Mister-Raggs Mister-Raggs changed the title [New Model] Add Cosmos Predict2.5 2B distilled T2W inference [new-model] Add Cosmos Predict2.5 2B distilled T2W inference Aug 27, 2026
@Mister-Raggs
Mister-Raggs marked this pull request as ready for review August 27, 2026 20:54
Copilot AI lite review requested due to automatic review settings August 27, 2026 20:54

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

scope: docs Documentation scope: inference Inference pipeline, serving, CLI scope: infra CI, tests, Docker, build scope: model Model architecture (DiTs, encoders, VAEs) type: new-model New model support

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants