chenfengxu714/StreamDiffusionV2

StreamDiffusionV2 – ディフュージョンによるリアルタイム動画生成

何であるか – StreamDiffusionV2 は、ディフュージョンベースの動画生成を ストリーミング プロセスとして実行できるオープンソースライブラリです。完全な動画が生成されるのを待つ代わりに、システムは短い動画チャンクをリアルタイムで処理し、各新しいチャンクが既に完了した作業を再利用できるように、ローリングKVキャッシュを維持します。単一GPU、マルチGPUパイプライン並列、およびインタラクティブな使用向けの軽量Web 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 Web 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 モードで1回の呼び出しで実行可能：

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）は環境変数でも指定可能。

Webデモ – 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 – ディフュージョンによるリアルタイム動画生成

関連