NVLabs/Sana 詳細教學

對 NVlabs/Sana 從「定位」到「跑起來」到「整合進其他工作流」的完整 onboarding。 補充 inbox/2026-05-22-github-NVlabs-Sana.md（gh-save metadata），請搭配閱讀。

1. 專案定位

SANA 是 NVIDIA Labs × MIT Han Lab 主導的高效 diffusion (擴散模型) 全家桶，目標：

• 效率：比 FLUX-12B 模型小 20×、快 100×；4 bit 量化版可在 < 8 GB GPU VRAM 上跑
• 覆蓋面：text-to-image（最高 4K）、text-to-video（720p、1 min）、controllable world model、RL post-training
• 開源：Apache 2.0，整套訓練 + 推理 + 量化 + ComfyUI / Diffusers / SGLang 整合

核心技術 (Key Techniques)：

會議發表 (publication track)：

• SANA：ICLR 2025 Oral
• SANA-1.5：ICML 2025
• SANA-Sprint：ICCV 2025 Highlight
• SANA-Video：ICLR 2026 Oral

重要連結：

• 📚 完整 docs
• 🤗 HuggingFace collection
• 線上 Demo
• BibTeX (arXiv 2410.10629)

2. 安裝指南

2.1 環境需求

2.2 一鍵安裝（推薦）

1git clone https://github.com/NVlabs/Sana.git
2cd Sana
3./environment_setup.sh sana   # 建 conda env `sana` + 裝所有依賴

environment_setup.sh 做的事：

1. conda create -n sana python=3.11（若已存在則 reuse）
2. conda install -c nvidia cuda-toolkit=12.8
3. pip install -U pip wheel，再 pip install "setuptools<80"（避開 mmcv 1.7.2 的 pkg_resources 問題）
4. 從 pyproject.toml 安裝主依賴（含 torch 2.9.1 cu128 wheels）
5. 特殊 wheel（mmcv 1.7.2 / flash-attn 等）走特定 flag 編譯

環境變數 hint：CI 環境可設 SKIP_ENV_SETUP=true 跳過 setup。

2.3 Docker 方式

1# Dockerfile 已內含 CUDA + Python + 套件
2docker build -t sana:latest .
3docker run --gpus all -it -v $(pwd):/workspace sana:latest

2.4 用 diffusers 最小化安裝（推理用）

只想跑推理、不想 build mmcv / flash-attn？走純 diffusers：

1pip install -U "diffusers>=0.37.0" transformers accelerate

然後直接呼叫 SanaPipeline（見 §4.1）。

2.5 Mermaid：安裝流程

flowchart TD
    Start([git clone Sana]) --> CheckEnv{有 conda?}
    CheckEnv -->|有| RunSetup[bash environment_setup.sh sana]
    CheckEnv -->|無 / 用 Docker| BuildDocker[docker build .]
    RunSetup --> CreateEnv[conda create py=3.11
+ cuda-toolkit 12.8]
    CreateEnv --> InstallPip[pip install pyproject.toml deps
+ torch 2.9.1 cu128 wheels]
    InstallPip --> SpecialWheels[特殊 wheel: mmcv 1.7.2 / flash-attn / Pi3]
    SpecialWheels --> Verify[python -c 'import sana; print OK']
    BuildDocker --> Verify
    Verify --> Done([可以開始推理 / 訓練])

3. 核心架構解析

3.1 Repo top-level 結構

 1Sana/
 2├── sana/                  # 套件入口（pyproject 註冊 `sana-run` / `sana-upload`）
 3│   ├── cli/              # CLI 入口（run.py / upload2hf.py）
 4│   └── tools/            # download.py / hf_utils.py
 5├── diffusion/            # 模型核心
 6│   ├── model/            # Linear DiT、DC-AE、scheduler、qwen 文字編碼器
 7│   │   ├── nets/         # 主網路結構
 8│   │   ├── dc_ae/        # Deep Compression AutoEncoder
 9│   │   ├── longsana/     # Long video 模組
10│   │   ├── wan/, wan2_2/ # Wan 系列整合
11│   │   └── ...
12│   ├── scheduler/        # Flow Euler / DPM / IDDPM / LCM / sCM
13│   ├── data/             # WebDataset 多解析度載入
14│   ├── guiders/          # guidance scale 控制
15│   ├── post_training/    # Sol-RL 後訓練
16│   └── refiner/          # LTX-VAE refiner（影片上 2K 用）
17├── scripts/              # 推理 + benchmark 入口
18├── train_scripts/        # 訓練腳本（DDP / FSDP / multi-scale）
19├── train_video_scripts/  # 影片訓練
20├── inference_video_scripts/ # 影片推理
21├── configs/              # YAML 設定（sana / sana_1-5 / sana_sprint / sana_video / sana_wm / sol_rl）
22├── tools/                # 資料轉換 / fid / clip-score / image-reward / inference scaling
23├── app/                  # Gradio demo（含 4bit 版）
24├── docs/                 # mkdocs 文件 source
25├── CIs/                  # CI 配置 + lint
26├── pyproject.toml        # 主依賴（Python 3.11+ / torch 2.9.1 / cu128）
27├── environment_setup.sh  # conda + 特殊 wheel 安裝
28└── Dockerfile            # GPU image

3.2 系統架構圖

flowchart LR
    subgraph Input["輸入"]
        Prompt[文字 prompt
e.g. 'cyberpunk cat']
    end

    subgraph Encoder["編碼層"]
        TextEnc[Decoder-only LLM
text encoder
e.g. Qwen / Gemma]
    end

    subgraph Core["Linear DiT 核心"]
        DiT[Linear Attention
Diffusion Transformer]
        Sched[Flow Euler /
DPM-Solver /
sCM]
    end

    subgraph Decoder["解碼層"]
        DCAE[DC-AE
32× decoder]
    end

    subgraph Output["輸出"]
        Img[1024 / 2K / 4K image]
        Vid[720p 1-min video]
    end

    Prompt --> TextEnc
    TextEnc -->|text embedding| DiT
    Sched <--> DiT
    DiT -->|latent| DCAE
    DCAE --> Img
    DCAE --> Vid

    classDef core fill:#e3f2fd,stroke:#1976d2
    class DiT,Sched core

3.3 子模型家族與差別

選型 quickguide：

• 想試水 → SANA-1.5 1.6B（diffusers 整合最佳）
• 即時 / 互動 → SANA-Sprint
• 影片 → SANA-Video
• 量化部署 → SANA 0.6B 4bit（VRAM < 8 GB）
• 訓練 / fine-tune → SANA-1.5 + Sol-RL post-training

4. Helper Scripts 詳細用法

4.1 推理（Python / diffusers）

最短工作範例：

 1import torch
 2from diffusers import SanaPipeline
 3
 4pipe = SanaPipeline.from_pretrained(
 5    "Efficient-Large-Model/SANA1.5_1.6B_1024px_diffusers",
 6    torch_dtype=torch.bfloat16,
 7)
 8pipe.to("cuda")
 9
10# VAE 和 text encoder 也轉 bf16 省 VRAM
11pipe.vae.to(torch.bfloat16)
12pipe.text_encoder.to(torch.bfloat16)
13
14prompt = 'a cyberpunk cat with a neon sign that says "Sana"'
15image = pipe(
16    prompt=prompt,
17    height=1024, width=1024,
18    guidance_scale=4.5,
19    num_inference_steps=20,
20    generator=torch.Generator(device="cuda").manual_seed(42),
21)[0]
22
23image[0].save("sana.png")

需要 diffusers >= 0.37.0。

4.2 推理（repo 內 scripts）

對 1024px 走原生 pipeline：

 1# 純命令列推理
 2bash scripts/infer_run_inference.sh \
 3    configs/sana_config/1024ms/Sana_1600M_img1024.yaml \
 4    "Efficient-Large-Model/Sana_1600M_1024px_diffusers" \
 5    "a cyberpunk cat with a neon sign"
 6
 7# Sana-Sprint（少步推理）
 8python scripts/inference_sana_sprint.py \
 9    --config configs/sana_sprint_config/1024ms/SanaSprint_1600M_1024px.yaml \
10    --image_size 1024 \
11    --txt "a cyberpunk cat"

4.3 訓練

DDP 模式：

1bash train_scripts/train.sh \
2    configs/sana_config/1024ms/Sana_1600M_img1024.yaml \
3    --tracker_pattern "exp_name"

FSDP（大模型 SANA-1.5 4.8B）：

1bash train_scripts/train_fsdp.sh \
2    configs/sana1-5_config/1024ms/Sana_4800M_img1024_fsdp.yaml

Multi-scale WebDataset（TAR 流式訓練）：

1bash train_scripts/train_multiscale.sh \
2    configs/sana_config/multiscale/Sana_1600M_multiscale_webdataset.yaml

4.4 Benchmark / Metrics

 1# GenEval（text-image alignment）
 2bash scripts/bash_run_inference_metric_geneval.sh
 3
 4# DPG（dense prompt grounding）
 5bash scripts/bash_run_inference_metric_dpg.sh
 6
 7# ImageReward（人類偏好 proxy）
 8bash scripts/bash_run_inference_metric_imagereward.sh
 9
10# FID（distribution distance）— 走 tools/metrics/pytorch-fid

4.5 量化 / 4bit 部署

走 SVDQuant + Nunchaku：

1# 8 GB GPU VRAM 跑 1024px
2bash app/run_app_4bit.sh

4.6 Gradio Demo

1python app/app_sana.py            # 主 demo
2python app/app_sana_4bit.py       # 4bit 版（< 8 GB VRAM）
3python app/app_sana_sprint.py     # Sprint（少步）

預設綁 0.0.0.0:7860，建議 --server-name 127.0.0.1 改為本機限定。

5. 應用場景

6. 資安掃描報告

對 scripts/ tools/ sana/ app/ 跑 grep -nE 'eval\\(|exec\\(|os\\.system|subprocess.*shell=True|pickle\\.load|input\\(|requests\\.|urllib|api_key|secret'：

🔴 高風險

無。

🟡 中風險

🟢 低風險（無實質安全問題）

• urllib.request.urlretrieve 在 tools/controlnet/annotator/hed/__init__.py:76 — 下載 ControlNet HED checkpoint，URL 是 hard-coded github raw / hf；建議補 SHA-256 verify
• model.eval() 是 PyTorch nn.Module.eval()（無關 Python eval()）— 安全
• 大量 # http://www.apache.org/licenses/LICENSE-2.0 是 license header — 安全
• requests / http 模式無發現（除了 license header）

結論

🟡 中風險，本機開發環境安全；若把 inference scripts 包進 web API 對外開放，必須先把上述 4 個 eval() 改成 ast.literal_eval 或加參數驗證，否則 CLI 參數 = RCE。

7. FAQ

Q1: 為什麼必須 Python 3.11，不能用 3.10？ A: triton 3.5 的 @triton.jit 透過 inspect.getsource() 取 kernel 原始碼，再用 regex ^def\s+\w+\s*\( match；在 Python 3.10 的 inspect 行為下，被 decorator 包過的 kernel 回傳的字串會從 decorator 之後開始，導致 regex match 失敗。3.11 行為才對齊。

Q2: 為什麼必須 CUDA 12.8？ A: torch 2.9.1 + xformers 0.0.33 + triton 3.5 是套件版本鎖定；自編 flash-attn / Pi3 wheel 時 nvcc 必須對齊 torch wheel 的 CUDA major.minor。

Q3: 8 GB VRAM 真的能跑 1024px？ A: 走 4 bit (SVDQuant + Nunchaku) 路線可以；FP16 / BF16 純 SANA-0.6B 也接近邊緣。視 batch size / VAE 是否 offload 到 CPU。

Q4: 商業使用 OK 嗎？ A: code base Apache 2.0（2025-01-11 改的）。但個別 model weight（HuggingFace）可能有自己的 license（CC-NC 等）— 用 HuggingFace 上 model card 為準。

Q5: 跟 FLUX 比，SANA 弱點在哪？ A: 文字渲染 / 細節密度上 FLUX-12B 通常還是領先（畢竟 20× 參數）；SANA 強在效率與部署，弱在「最高峰質感」。

Q6: 已有 diffusers 環境，需要再裝一遍嗎？ A: 不需要。diffusers >= 0.37.0 已內建 SanaPipeline / SanaPAGPipeline / SanaVideoPipeline，最短安裝 = pip install -U diffusers transformers accelerate。原生 repo 只在需要訓練 / 評測 / 4bit 量化時才裝。

Q7: 為什麼有那麼多子專案（SANA / SANA-1.5 / Sprint / Video / WM / Sol-RL）？ A: SANA 是「基礎模型」；其他都是衍生路線：1.5=擴量、Sprint=蒸餾、Video=擴到影片、WM=世界模型、Sol-RL=後訓練。共用 Linear DiT + DC-AE 核心。

8. 進階技巧

8.1 多解析度訓練（multi-scale WebDataset）

訓練不同 aspect ratio 同時：

1# configs/sana_config/multiscale/...yaml
2data:
3    type: multiscale_webdataset
4    paths:
5      - /data/laion-aesthetic-1024.tar
6      - /data/laion-aesthetic-2048.tar
7    aspect_ratios: [0.5, 0.67, 1.0, 1.5, 2.0]

WebDataset TAR 格式比 HuggingFace dataset 更省 IO，適合 100 M+ 樣本。

8.2 Inference-time scaling

SANA-1.5 提供「跑更多 step / 用更大 cfg → 質感升」的 trade-off 曲線：

1# configs/sana1-5_config/.../inference_scaling.yaml
2inference:
3    num_inference_steps_grid: [20, 28, 40]
4    guidance_scale_grid: [4.5, 5.5, 7.0]

跑全 grid 取 best by GenEval。

8.3 ControlNet

1python scripts/inference.py \
2    --config configs/sana_controlnet_config/.../sana_controlnet.yaml \
3    --controlnet_pretrained Efficient-Large-Model/Sana_1600M_ControlNet_Canny \
4    --txt "a photo of a horse" \
5    --controlnet_image asset/controlnet/horse_canny.png

8.4 LoRA / DreamBooth fine-tune

走 diffusers examples/dreambooth/：

1accelerate launch examples/dreambooth/train_dreambooth_lora_sana.py \
2    --pretrained_model_name_or_path="Efficient-Large-Model/SANA1.5_1.6B_1024px_diffusers" \
3    --instance_data_dir=/data/my-character/ \
4    --output_dir=lora-out/ \
5    --rank=16 --max_train_steps=1000

8.5 Sol-RL post-training

1bash train_scripts/sol_rl/train.sh \
2    configs/sol_rl/sana_solrl.yaml \
3    --reward_service "hpsv2"

支援 reward services（hpsv2 / imagereward / 自訂）。

8.6 部署 SGLang

走 OpenAI-compatible API server：

1python -m sglang.launch_server \
2    --model-path Efficient-Large-Model/SANA1.5_1.6B_1024px_diffusers \
3    --port 30000

然後客戶端 openai SDK 直接打 http://localhost:30000/v1/images/generations。

9. 整合進其他工作流

9.1 ComfyUI

裝 lawrence-cj/ComfyUI_ExtraModels，模型放 ComfyUI/models/sana/。提供 SANA / SANA-1.5 / SANA-Sprint 三套 workflow JSON。

9.2 HuggingFace Spaces

直接 deploy app/app_sana.py：

1# spaces config
2sdk: gradio
3python_version: 3.11
4hardware: l40s-large  # 推薦

或 4bit 版：app/app_sana_4bit.py，可在 t4-small 跑。

9.3 Cosmos-RL（多 backbone RL）

詳見 Cosmos-RL × SANA 整合 doc。可以對 SANA / FLUX.1 / SD3.5 同一介面跑 RL。

9.4 自家研究 pipeline 整合 checklist

1. 環境：用 SANA 自帶 conda env，避免污染主環境
2. 權重快取：設 HF_HOME=/data/hf_cache 避免每個 user 各自下載
3. inference API 化：寫一層 FastAPI wrapper，先把 §6 提到的 eval() 改成 ast.literal_eval
4. 量化選擇：production → 4bit (Nunchaku)；training → BF16
5. Monitoring：wandb 內建支援；接 prometheus 從 /metrics 取 GPU util / latency

10. 重點摘要 Checklist

• 確認 Python 3.11 + CUDA 12.8（不可改）
• 推理只想用 diffusers → pip install "diffusers>=0.37.0" 即可
• 訓練或 4bit → 走 environment_setup.sh sana
• 商用 → check code Apache 2.0 + 個別 weight license
• 部署到 web API → 必須先修 eval()（§6 中風險）
• 選型：Sprint 即時 / 1.5 質感 / Video 影片 / WM 世界模型 / Sol-RL 後訓練
• 4K 推理需 22 GB VRAM；< 8 GB → 走 4bit / Nunchaku
• 訓練資料量大 → WebDataset TAR + multiscale
• 想 fine-tune → 用 diffusers DreamBooth LoRA（最快）

11. 進一步閱讀

Generated 2026-05-22 by gh-tutorial-qd skill — paired with inbox/2026-05-22-github-NVlabs-Sana.md.