Wan2.2

Wan2.2

Wan2.2는 Wan 계열을 timestep 전문화된 Mixture-of-Experts(MoE) 모델과 통합 5B TI2V 체크포인트로 확장합니다. 시네마틱 구도, 조명, 복잡한 모션을 목표로 하면서 텍스트-투-비디오, 이미지-투-비디오, 하이브리드 텍스트/이미지 컨디셔닝을 지원합니다.

출처: 문서

본문

<DiffusionModelTags tags={["video", "T2V / I2V / TI2V", "MoE", "720p @ 24 fps", "cinematic motion"]} />

1. 모델 소개 (Model Introduction)

Wan2.2는 Wan 계열을 timestep 전문화된 Mixture-of-Experts(MoE) 모델과 통합 5B TI2V 체크포인트로 확장합니다. 시네마틱 구도, 조명, 복잡한 모션을 목표로 하면서 텍스트-투-비디오, 이미지-투-비디오, 하이브리드 텍스트/이미지 컨디셔닝을 지원합니다.

최대 T2V 또는 I2V 용량에는 A14B MoE 체크포인트를, 더 작은 통합 720p-at-24-fps 경로에는 5B TI2V 모델을 선택하세요. MoE는 총 용량 대비 활성 연산을 줄이지만 전문가 가중치 로딩의 메모리 비용은 제거하지 않으므로 하드웨어 선택이 여전히 중요합니다.

Wan2.2 TI2V 5B 체크포인트는 이미지-투-비디오 생성에 사용될 때 현재 알려진 품질 문제가 있습니다. I2V 품질이 우선이라면 `Wan-AI/Wan2.2-I2V-A14B-Diffusers`를 사용하세요.

2. SGLang-diffusion 설치 (Installation)

SGLang-diffusion은 여러 설치 방법을 제공합니다. 하드웨어 플랫폼과 요구사항에 따라 가장 적합한 방법을 선택할 수 있습니다.

설치 지침은 공식 SGLang-diffusion 설치 가이드를 참조하세요.

3. 모델 배포 (Model Deployment)

이 섹션은 다양한 하드웨어 플랫폼과 사용 사례에 최적화된 배포 구성을 제공합니다.

3.1 기본 구성 (Basic Configuration)

Wan2.2 시리즈는 다양한 하드웨어 플랫폼에 최적화된 다양한 크기, 아키텍처, 입력 타입의 모델을 제공합니다. 권장 시작 구성은 하드웨어와 모델 크기에 따라 다릅니다.

대화형 명령 생성기 (Interactive Command Generator): 아래 구성 선택기를 사용해 하드웨어 플랫폼과 모델 크기에 적합한 배포 명령을 자동 생성하세요. SGLang은 NVIDIA B200, H200, AMD MI300X, MI325X, MI355X GPU와 Ascend A2/A3 Series NPU에서 Wan2.2 서빙을 지원합니다.

3.2 구성 팁 (Configuration Tips)

가속 기능과 런타임 요구사항은 성능 최적화를 참조하세요.

  • --vae-path: 커스텀 VAE 모델 또는 HuggingFace 모델 ID 경로(예: fal/FLUX.2-Tiny-AutoEncoder). 지정하지 않으면 메인 모델 경로에서 VAE를 로드.
  • --num-gpus {NUM_GPUS}: 사용할 GPU 수
  • --tp-size {TP_SIZE}: 텐서 병렬 크기(인코더 전용. 텍스트 인코더 오프로드가 활성화되면 1보다 크면 안 됩니다. 레이어별 오프로드 + 프리페치가 더 빠르기 때문)
  • --sp-degree {SP_SIZE}: 시퀀스 병렬 크기(보통 GPU 수와 일치해야 함)
  • --ulysses-degree {ULYSSES_DEGREE}: USP에서 DeepSpeed-Ulysses 스타일 SP의 정도
  • --ring-degree {RING_DEGREE}: USP에서 ring attention 스타일 SP의 정도

4. 모델 호출 (Model Invocation)

4.1 기본 사용법 (Basic Usage)

더 많은 API 사용법과 요청 예시는 SGLang Diffusion OpenAI API를 참조하세요.

4.1.1 서버 시작 후 요청 보내기

sglang serve --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers --port 3000

curl http://127.0.0.1:3000/v1/images/generations \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > example.png) \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
    "prompt": "A cute baby sea otter",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

4.1.2 서버 시작 없이 비디오 생성

SERVER_ARGS=(
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers
  --text-encoder-cpu-offload
  --pin-cpu-memory
  --num-gpus 4
  --ulysses-degree=2
  --enable-cfg-parallel
)

SAMPLING_ARGS=(
  --prompt "A curious raccoon"
  --save-output
  --output-path outputs
  --output-file-name "A curious raccoon.mp4"
)

sglang generate "${SERVER_ARGS[@]}" "${SAMPLING_ARGS[@]}"

4.2 고급 사용법 (Advanced Usage)

4.2.1 Cache-DiT 가속 (Cache-DiT Acceleration)

SGLang은 Diffusion Transformer(DiT)용 캐싱 가속 엔진인 Cache-DiT를 통합해 최소 품질 손실로 최대 7.4배 추론 속도 향상을 얻을 수 있습니다. SGLANG_CACHE_DIT_ENABLED=True로 활성화할 수 있습니다. 자세한 내용은 SGLang Cache-DiT 문서를 참조하세요.

기본 사용법 (Basic Usage)

SGLANG_CACHE_DIT_ENABLED=true sglang serve --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers

고급 사용법 (Advanced Usage)

  • DBCache 파라미터: DBCache는 블록 수준 캐싱 동작을 제어합니다:
파라미터 (Parameter) 환경 변수 (Env Variable) 기본값 (Default) 설명 (Description)
Fn SGLANG_CACHE_DIT_FN 1 항상 계산할 첫 블록 수
Bn SGLANG_CACHE_DIT_BN 0 항상 계산할 마지막 블록 수
W SGLANG_CACHE_DIT_WARMUP 4 캐싱이 시작되기 전 워밍업 스텝
R SGLANG_CACHE_DIT_RDT 0.24 잔차 차이 임계값
MC SGLANG_CACHE_DIT_MC 3 최대 연속 캐시 스텝 수
  • TaylorSeer 구성: TaylorSeer는 Taylor 전개를 사용해 캐싱 정확도를 개선합니다:
파라미터 (Parameter) 환경 변수 (Env Variable) 기본값 (Default) 설명 (Description)
Enable SGLANG_CACHE_DIT_TAYLORSEER false TaylorSeer 교정기 활성화
Order SGLANG_CACHE_DIT_TS_ORDER 1 Taylor 전개 차수 (1 또는 2)

결합 구성 예시:

SGLANG_CACHE_DIT_ENABLED=true \
SGLANG_CACHE_DIT_FN=2 \
SGLANG_CACHE_DIT_BN=1 \
SGLANG_CACHE_DIT_WARMUP=4 \
SGLANG_CACHE_DIT_RDT=0.4 \
SGLANG_CACHE_DIT_MC=4 \
SGLANG_CACHE_DIT_TAYLORSEER=true \
SGLANG_CACHE_DIT_TS_ORDER=2 \
sglang serve --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers

4.2.2 GPU 최적화 (GPU Optimization)

  • --dit-cpu-offload: DiT 추론에 CPU 오프로드 사용. FSDP로 메모리가 부족하면 활성화.
  • --text-encoder-cpu-offload: 텍스트 인코더 추론에 CPU 오프로드 사용. FSDP로 메모리가 부족하면 활성화.
  • --image-encoder-cpu-offload: 이미지 인코더 추론에 CPU 오프로드 사용. FSDP로 메모리가 부족하면 활성화.
  • --vae-cpu-offload: VAE에 CPU 오프로드 사용. 메모리가 부족하면 활성화.
  • --pin-cpu-memory: CPU 오프로드를 위한 메모리 고정. "CUDA error: invalid argument"가 발생할 때만 임시 해결책으로 추가.

4.2.3 지원 LoRA 레지스트리 (Supported LoRA Registry)

원본 모델 (origin model) 지원 LoRA (supported LoRA)
Wan-AI/Wan2.2-I2V-A14B-Diffusers lightx2v/Wan2.2-Distill-Loras
Wan-AI/Wan2.2-T2V-A14B-Diffusers Cseti/wan2.2-14B-Arcane_Jinx-lora-v1

예시:

sglang serve --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers --port 3000 \
    --lora-path Cseti/wan2.2-14B-Arcane_Jinx-lora-v1

5. 벤치마크 (Benchmark)

테스트 환경:

  • 하드웨어: NVIDIA B200 GPU (1x)
  • 모델: Wan-AI/Wan2.2-T2V-A14B-Diffusers
  • sglang diffusion 버전: 0.5.6.post2

5.1 속도 향상 벤치마크 (Speedup Benchmark)

5.1.1 비디오 생성 (Generate a video)

**서버 명령 (Server Command):** 
```shell Command theme={null}
sglang serve --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers
```

**벤치마크 명령 (Benchmark Command):**

```shell Command theme={null}
python3 -m sglang.multimodal_gen.benchmarks.bench_serving \
    --dataset vbench --task text-to-video --num-prompts 1 --max-concurrency 1
```

**결과 (Result):**

```text Output theme={null}
================= Serving Benchmark Result =================
Model:                                   Wan-AI/Wan2.2-T2V-A14B-Diffusers
Dataset:                                 vbench
Task:                                    text-to-video
--------------------------------------------------
Benchmark duration (s):                  630.43
Request rate:                            inf
Max request concurrency:                 1
Successful requests:                     1/1
--------------------------------------------------
Request throughput (req/s):              0.00
Latency Mean (s):                        630.4277
Latency Median (s):                      630.4277
Latency P99 (s):                         630.4277
--------------------------------------------------
Peak Memory Max (MB):                    62627.41
Peak Memory Mean (MB):                   62627.41
Peak Memory Median (MB):                 62627.41

============================================================
```
**서버 명령 (Server Command):** 
```shell Command theme={null}
#One A3 Series card has 2 npu chips. Using four A3 Series cards in benchmarking
sglang serve \
  --model-path /models/Wan-AI/Wan2.2-T2V-A14B-Diffusers/ \
  --tp-size 2 \
  --sp-degree 4 \
  --num-gpus 8 \
  --attention-backend laser_attn
```

**벤치마크 명령 (Benchmark Command):**

```shell Command theme={null}
python -m sglang.multimodal_gen.benchmarks.bench_serving \
  --dataset vbench \
  --task text-to-video \
  --num-prompts 1 \
  --max-concurrency 1
```

**결과 (Result):**

```text Output theme={null}
================= Serving Benchmark Result =================
Task:                                         text-to-video
Model:                                        Wan-AI/Wan2.2-T2V-A14B-Diffusers/
Dataset:                                      vbench
--------------------------------------------------
Benchmark duration (s):                       214.50
Request rate:                                 inf
Max request concurrency:                      1
Successful requests:                          1/1
Completed outputs:                            1
Outputs per prompt:                           1
--------------------------------------------------
Request throughput (req/s):                   0.00
Output throughput (outputs/s):                0.00
Latency Mean (s):                             214.50
Latency Median (s):                           214.50
Latency P90 (s):                              214.50
Latency P95 (s):                              214.50
Latency P99 (s):                              214.50
--------------------------------------------------
Peak Memory Max (MB):                         46692.00
Peak Memory Mean (MB):                        46692.00
Peak Memory Median (MB):                      46692.00
------------------------------------------------------------
```

5.1.2 고동시성 비디오 생성 (Generate videos with high concurrency)

**서버 명령 (Server Command):** 
```shell Command theme={null}
SGLANG_CACHE_DIT_ENABLED=true \
SGLANG_CACHE_DIT_FN=2 \
SGLANG_CACHE_DIT_BN=1 \
SGLANG_CACHE_DIT_WARMUP=4 \
SGLANG_CACHE_DIT_RDT=0.4 \
SGLANG_CACHE_DIT_MC=4 \
SGLANG_CACHE_DIT_TAYLORSEER=true \
SGLANG_CACHE_DIT_TS_ORDER=2 \
sglang serve --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers
```

**벤치마크 명령 (Benchmark Command):**

```shell Command theme={null}
python3 -m sglang.multimodal_gen.benchmarks.bench_serving \
    --dataset vbench --task text-to-video --num-prompts 20 --max-concurrency 20
```

**결과 (Result):**

```text Output theme={null}
================= Serving Benchmark Result =================
Model:                                   Wan-AI/Wan2.2-T2V-A14B-Diffusers
Dataset:                                 vbench
Task:                                    text-to-video
--------------------------------------------------
Benchmark duration (s):                  5163.21
Request rate:                            inf
Max request concurrency:                 20
Successful requests:                     20/20
--------------------------------------------------
Request throughput (req/s):              0.00
Latency Mean (s):                        2739.7695
Latency Median (s):                      2742.0673
Latency P99 (s):                         5121.6331
--------------------------------------------------
Peak Memory Max (MB):                    72523.56
Peak Memory Mean (MB):                   70253.34
Peak Memory Median (MB):                 70824.46

============================================================
```
**서버 명령 (Server Command):** 
```shell Command theme={null}
#One A3 Series card has 2 npu chips. Using four A3 Series cards in benchmarking
SGLANG_CACHE_DIT_FN=2 \
SGLANG_CACHE_DIT_BN=1 \
SGLANG_CACHE_DIT_WARMUP=4 \
SGLANG_CACHE_DIT_RDT=0.4 \
SGLANG_CACHE_DIT_MC=4 \
SGLANG_CACHE_DIT_TAYLORSEER=true \
SGLANG_CACHE_DIT_TS_ORDER=2 \
SGLANG_CACHE_DIT_ENABLED=true sglang serve \
  --model-path /models/Wan-AI/Wan2.2-T2V-A14B-Diffusers/ \
  --tp-size 2 \
  --sp-degree 4 \
  --num-gpus 8 \
  --attention-backend laser_attn
```

**벤치마크 명령 (Benchmark Command):**

```shell Command theme={null}
python -m sglang.multimodal_gen.benchmarks.bench_serving \
  --dataset vbench \
  --task text-to-video \
  --num-prompts 20 \
  --max-concurrency 20
```

**결과 (Result):**

```text Output theme={null}
================= Serving Benchmark Result =================
Task:                                         text-to-video
Model:                                        Wan-AI/Wan2.2-T2V-A14B-Diffusers/
Dataset:                                      vbench
--------------------------------------------------
Benchmark duration (s):                       4384.65
Request rate:                                 inf
Max request concurrency:                      20
Successful requests:                          20/20
Completed outputs:                            20
Outputs per prompt:                           1
--------------------------------------------------
Request throughput (req/s):                   0.00
Output throughput (outputs/s):                0.00
Latency Mean (s):                             2304.17
Latency Median (s):                           2297.69
Latency P90 (s):                              3972.32
Latency P95 (s):                              4178.99
Latency P99 (s):                              4343.52
--------------------------------------------------
Peak Memory Max (MB):                         46692.00
Peak Memory Mean (MB):                        46691.90
Peak Memory Median (MB):                      46692.00
------------------------------------------------------------
```

6. ComfyUI에서 실행 (Run in ComfyUI)

더 알아보기 (Learn more)