chenfengxu714/StreamDiffusionV2

StreamDiffusionV2 – 디퓨전을 이용한 실시간 동영상 생성

무엇인가요 – StreamDiffusionV2는 디퓨전 기반의 동영상 생성을 스트리밍 프로세스로 실행할 수 있는 오픈소스 라이브러리입니다. 전체 동영상을 생성하는 데 기다리는 대신, 시스템은 짧은 동영상 청크를 실시간으로 처리하고, 각 새로운 청크가 이미 수행된 작업을 재사용할 수 있도록 롤링 KV 캐시를 유지합니다. 단일 GPU, 다중 GPU 파이프라인 병렬, 그리고 인터랙티브 사용을 위한 가벼운 웹 UI를 지원합니다.

왜 중요한가요 – 전통적인 텍스트에서 동영상으로의 디퓨전 모델은 배치 기반이며 느립니다 (1초당 수분). StreamDiffusionV2는 다음을 통해 높은 프레임 레이트(실시간 또는 근접 실시간)를 달성합니다:

동영상을 겹치는 청크로 분할하고, 링 버퍼 KV 캐시를 통해 잠재 상태를 재사용.
각 청크당 유연한 노이즈 제거 단계 수를 허용 (속도와 품질의 트레이드오프).
선택적 가속 경로 제공: 빠른 TAEHV-VAE 디코더, Flash-Attention, TensorRT 지원.
단일 GPU에서부터 다중 GPU 파이프라인 병렬까지 확장 가능하며, 더 큰 시스템에서는 "schedule-block" 옵션으로 더 나은 처리량을 제공.

주요 구성 요소

구성 요소	역할
`StreamDiffusionV2Pipeline`	청크화, 인코딩, 노이즈 제거, 디코딩을 처리하는 고수준 Python API.
`run_v2v.sh`	오프라인 추론용 통합 CLI 진입점 (단일, 단일-wo, pipe).
`demo/`	인터랙티브 생성을 위한 최소한의 FastAPI/Gradio 웹 UI.
`streamv2v/`	파이프라인을 프로그래밍 방식으로 제어하는 방법을 보여주는 예제 스크립트.
KV-캐시 구현	인과적 DiT 백본의 주의 키/값을 저장하는 링 버퍼. 슬라이딩 윈도우 주의를 가능하게 함.

설치 – 패키지는 PyPI에 게시되어 있으며, 선택적 Flash-Attention 지원과 함께 설치 가능:

conda create -n streamdiffusionv2 python=3.10 -y
conda activate streamdiffusionv2
pip install streamdiffusionv2            # 핵심
pip install "streamdiffusionv2[flash-attn]"  # 더 빠른 주의 (CUDA 필요)
# 최신 NVIDIA Blackwell GPU용
pip install torch==2.11.0 torchvision==0.26.0

로컬 체크아웃을 원하는 경우 pip install . 도 동일하게 작동합니다.

모델 받기 – 이 라이브러리는 추론 코드만 제공합니다. 체크포인트를 다운로드해야 합니다:

# 1.3B 모델 (데모용 기본값)
huggingface-cli download --resume-download Wan-AI/Wan2.1-T2V-1.3B --local-dir wan_models/Wan2.1-T2V-1.3B
huggingface-cli download --resume-download jerryfeng/StreamDiffusionV2 --local-dir ./ckpts --include "wan_causal_dmd_v2v/*"

# 14B 모델 (더 높은 품질)
huggingface-cli download --resume-download Wan-AI/Wan2.1-T2V-14B --local-dir wan_models/Wan2.1-T2V-14B
huggingface-cli download --resume-download jerryfeng/StreamDiffusionV2 --local-dir ./ckpts --include "wan_causal_dmd_v2v_14b/*"

선택적으로 가벼운 TAEHV-VAE 디코더를 가져오기:

curl -L https://github.com/madebyollin/taehv/raw/main/taew2_1.pth -o ckpts/taew2_1.pth

간단한 Python 예제 (단일 GPU)

import numpy as np
from streamdiffusionv2 import (
    StreamDiffusionV2Pipeline,
    load_video,
    export_video,
)

pipe = StreamDiffusionV2Pipeline(
    checkpoint_folder="ckpts/wan_causal_dmd_v2v",
    mode="single",
)
pipe.prepare("A dog walks on the grass, realistic")

video = load_video("examples/original.mp4", height=480, width=832)
chunks = []
noise = pipe.noise_scale

for chunk in pipe.chunk_video(video):
    enc = pipe.encode_chunk(video, chunk, previous_noise_scale=noise,
                           initial_noise_scale=pipe.noise_scale)
    noise = enc.noise_scale
    den = pipe.denoise_chunk(enc)
    if den is None:
        continue
    chunks.append(pipe.decode_chunk(den))

out = np.concatenate(chunks, axis=0)
export_video(out, "outputs/python_single.mp4", fps=16)

동일한 파이프라인은 다중 GPU 추론용 pipeline 모드로 단일 호출로 실행 가능:

from streamdiffusionv2 import run_video_to_video
run_video_to_video(
    mode="pipe",
    checkpoint_folder="ckpts/wan_causal_dmd_v2v",
    video_path="examples/original.mp4",
    prompt="A dog walks on the grass, realistic",
    output_path="outputs/python_pipe.mp4",
    gpu_ids=[0,1],
    num_gpus=2,
)

CLI 사용법 – run_v2v.sh 스크립트는 동일한 단계를 추상화합니다:

# 단일 GPU 스트리밍
./run_v2v.sh single
# 스트리밍 배치 없이 단일 GPU (약간 다른 메모리 패턴)
./run_v2v.sh single-wo
# 다중 GPU 파이프라인
./run_v2v.sh pipe
# 프로파일링 활성화
./run_v2v.sh pipe --profile
# 빠른 TAEHV 디코더 활성화
./run_v2v.sh single --use_taehv

공통 플래그 (--config_path, --checkpoint_folder, --video_path, --prompt_file_path, --height, --width, --fps, --step, --use_taehv)는 환경 변수로도 제공 가능합니다.

웹 데모 – Node.js 18을 설치한 후, 다음 명령어로 UI를 시작하세요:

cd demo
USE_TAEHV=1 python -m streamdiffusionv2.web_demo   # 또는 제공된 시작 스크립트

그 후 브라우저에서 http://localhost:7860을 열어주세요.

학습 – 리포지토리는 CausVid 코드베이스를 기반으로 하는 별도의 user-study 브랜치를 포함하고 있습니다. 추론 시 사용되는 인과적 DiT 백본을 위한 학습 스크립트를 제공합니다.

로드맵 – 저자들은 동적 스케줄러, FP8 양자화, 더 깊은 TensorRT 통합과 같은 앞으로의 작업을 목록화하고 있습니다.

인용 – 연구에서 이 라이브러리를 사용할 경우, MLSys 2026 논문을 인용해 주세요 (README에 BibTeX 제공).

StreamDiffusionV2는 실시간 디퓨전 동영상 생성을 실험하거나 배포하고자 하는 누구에게나 프로덕션 준비된 툴킷을 제공하며, 간단한 Python API와 확장 가능한 다중 GPU 백엔드를 모두 제공합니다.

chenfengxu714/StreamDiffusionV2

StreamDiffusionV2 – 디퓨전을 이용한 실시간 동영상 생성

관련