StreamDiffusion：Windows 平台建置與初次驗證

現在還要在 Windows 上建 StreamDiffusion，真正會把人卡住的通常是版本。官方 README 目前仍以 Python 3.10、PyTorch 2.1.0，以及 CUDA 11.8 或 12.1 這組合來說明安裝流程。這組先站穩，後面才有餘裕去談 NDI、OSC，或把它接進 TouchDesigner 與 Unity。

如果只是想快速跑一次官方範例，照 README 直接用 pip install streamdiffusion[tensorrt] 就可以了。不過此系列接下來會自己改傳輸流程，也會直接動到 utils/wrapper.py 這條路，所以本文採用「自己建 Python 專案，再把 StreamDiffusion 的核心程式放進來」的做法。這不是唯一的安裝方式，但後續維護會比較清楚。

StreamDiffusion 的目標就是把影像生成推到足夠即時，讓它能進入互動系統之中。

先把版本策略講清楚

在動手安裝之前，先把這篇的版本基準講清楚，後面比較不會一路猜。

• Python：3.10。
• PyTorch：2.1.0。
• CUDA 對應的 PyTorch Wheel：cu118 或 cu121。
• StreamDiffusion 安裝來源：GitHub 主線或 PyPI 穩定版都可以，但本文採用 GitHub 專案內容來整理自己的開發環境。

PyTorch 官網現在已經列出更新的 CUDA 組合，像是 12.4、12.6。但 StreamDiffusion README 目前仍明確列的是 torch==2.1.0 搭配 cu118 或 cu121。如果現在的目的只是先把系統建起來，我會建議先走文件還有明確寫出的組合，不要一開始就把變數放大。

以本文使用的 SD Turbo、512x512 生成尺寸來看，實務上我會建議顯示卡至少有 8GB VRAM，系統記憶體至少 16GB。再低仍然有機會跑起來，只是速度和穩定性都會變得很難看。

安裝 CUDA

如果電腦已經有能正常工作的 NVIDIA 驅動與 CUDA 環境，先確認版本即可。請開啟命令提示字元，輸入：

1nvcc --version

如果指令能正常顯示版本，代表電腦裡已經有 CUDA Toolkit。只要你的環境能對應到後面要安裝的 cu118 或 cu121 PyTorch Wheel，就可以繼續往下做。

如果指令失敗，再去安裝 CUDA Toolkit。這裡不用執著追最新版本，先以本文後面要使用的 cu121 路線為主即可。Windows 端只要先把這一層穩定下來，後面比較不會出現「PyTorch 裝好了但模型跑不起來」這種看起來很像玄學的狀況。

安裝 uv 與 Python 3.10

本文延續這個系列一貫的做法，用 uv 來管理 Python 環境。原因很簡單：它在 Windows 上建立虛擬環境和同步套件都夠快，之後要重建專案也比較乾淨。

先安裝 uv：

1powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

如果當前的命令列還沒有抓到 uv，可以把安裝路徑補進 PATH：

1SET PATH=%PATH%;%UserProfile%\.local\bin

接著安裝 Python 3.10：

1uv python install 3.10

我刻意不把小版本寫死成 3.10.17 這類數字，原因很單純：StreamDiffusion 官方要求的是 3.10 系列，而 uv 會抓到可用的 3.10 版。這樣後面不用因為 Python patch 版變動，再回頭重改整篇文章。

建立可編輯的 StreamDiffusion 專案

這一段的重點，在於建立一個後面方便自己改的工作目錄。

先建立資料夾，用 VS Code 開啟，然後在終端機輸入：

1uv init
2uv venv --python 3.10

這一步完成後，資料夾內會出現 main.py、pyproject.toml 等檔案。之後我們主要會改這兩個地方。

取得 StreamDiffusion 的核心程式

官方 README 對一般使用者建議直接安裝套件；但這個系列後面會自己接傳輸流程，所以我還是會把核心程式攤開來放在專案裡。做法不複雜，就是先 clone，再把我們真的會動到的資料夾抽出來。

1git clone https://github.com/cumulo-autumn/StreamDiffusion.git

下載完成後，專案裡會多一個 StreamDiffusion 資料夾。接著把 src/streamdiffusion 與 utils 移到目前專案根目錄：

1powershell Rename-Item -Path "StreamDiffusion" "StreamDiffusion_Bak"
2powershell Move-Item -Path "StreamDiffusion_Bak\\src\\streamdiffusion" "streamdiffusion"
3powershell Move-Item -Path "StreamDiffusion_Bak\\utils" "utils"
4powershell Remove-Item -Recurse -Force "StreamDiffusion_Bak"

這樣整理完之後，我們自己的專案根目錄就會直接看到 streamdiffusion 與 utils 兩個資料夾。之後無論是改 Wrapper、補 NDI、補 OSC，結構都比較直。

安裝 PyTorch 與依賴套件

這裡是整篇最容易被版本拖下水的地方，所以我直接用文件中還有明確記錄的組合來整理。

設定 PyTorch 的來源

請先打開 pyproject.toml，把以下內容補到檔案後面。本文以 cu121 為基準：

 1[[tool.uv.index]]
 2name = "pytorch-cu121"
 3url = "https://download.pytorch.org/whl/cu121"
 4explicit = true
 5
 6[tool.uv.sources]
 7torch = [
 8  { index = "pytorch-cu121", marker = "sys_platform == 'win32'" },
 9]
10torchvision = [
11  { index = "pytorch-cu121", marker = "sys_platform == 'win32'" },
12]

PyTorch 官網現在確實有更新的 CUDA Wheel，但因為本文是照 StreamDiffusion README 的安裝基準來建，先用 cu121 反而比較省事。

對齊 StreamDiffusion 的依賴版本

接著，把 dependencies 改成下面這組版本。這份列表是以 StreamDiffusion 當前 setup.py 的依賴為主，再補上 torch 與 torchvision：

 1dependencies = [
 2    "accelerate",
 3    "colored",
 4    "cuda-python",
 5    "diffusers==0.24.0",
 6    "fire",
 7    "omegaconf",
 8    "onnx==1.15.0",
 9    "onnxruntime==1.16.3",
10    "protobuf==3.20.2",
11    "pywin32>=310",
12    "torch",
13    "torchvision==0.16.0",
14    "transformers",
15    "xformers"
16]

原本那種「自己一路加到能跑」的 dependency 列法，在當下可能有效，但時間一拉長就很容易和官方程式實際依賴脫節。這裡直接對齊 setup.py，後面踩雷的機率會低很多。

最後執行同步：

1uv sync

走到這裡，環境基本上就算建立完成了。

先用 Img2Img 做第一次驗證

我會先用 Img2Img 驗證，因為它能同時檢查模型、影像前處理和輸出是否都正常。

先自行準備一張圖片放到專案根目錄，檔名命名成 image.png。

接著把 main.py 改成下面這段：

 1from utils.wrapper import StreamDiffusionWrapper
 2
 3
 4def main():
 5    stream = StreamDiffusionWrapper(
 6        model_id_or_path="stabilityai/sd-turbo",
 7        t_index_list=[24, 32],
 8        width=512,
 9        height=512,
10        acceleration="xformers",
11        mode="img2img"
12    )
13    stream.prepare(prompt="cat, detailed, fantasy, 8k")
14
15    input_image = stream.preprocess_image("image.png")
16
17    for _ in range(stream.batch_size - 1):
18        stream(image=input_image)
19
20    output = stream(image=input_image)
21    output.save("result.png")
22
23
24if __name__ == "__main__":
25    main()

執行程式：

1uv run main.py

第一次跑會先下載模型，所以需要等一下。只要最後專案裡能正常生成 result.png，代表這條路已經通了。

再用 Txt2Img 補第二次驗證

Img2Img 通了之後，再用 Txt2Img 補一次驗證，主要是確認文字生成這條路也沒問題。

把 main.py 改成下面這段：

 1from utils.wrapper import StreamDiffusionWrapper
 2
 3
 4def main():
 5    stream = StreamDiffusionWrapper(
 6        model_id_or_path="stabilityai/sd-turbo",
 7        t_index_list=[0, 24, 32],
 8        width=512,
 9        height=512,
10        cfg_type="none",
11        acceleration="xformers",
12        mode="txt2img"
13    )
14    stream.prepare(prompt="cat, detailed, fantasy, 8k")
15
16    for _ in range(stream.batch_size - 1):
17        stream()
18
19    output = stream()
20    output.save("result.png")
21
22
23if __name__ == "__main__":
24    main()

一樣執行：

1uv run main.py

如果 result.png 正常產生，代表 Windows 上的 StreamDiffusion 核心功能已經可以用了。後面我們再把這個「本來只能改程式碼、重新執行」的生成流程，改造成可以被外部系統即時控制的版本。

FAQ

為什麼本文不用最新的 PyTorch 與 CUDA 組合？

因為 StreamDiffusion README 目前仍明確記載 torch==2.1.0 與 cu118、cu121 這條安裝路徑。PyTorch 官網確實已經提供更新的 Wheel，但如果現在的目標是先把 StreamDiffusion 穩定跑起來，先跟文件還有寫出來的版本走，風險會低很多。

為什麼不直接照官方 README 用 pip install streamdiffusion[tensorrt]？

如果只是要跑官方範例，直接裝套件沒有問題。本文之所以改成把 streamdiffusion 和 utils 放進自己的專案，是因為後面我們要自己接 NDI、OSC，也會改 Wrapper。這時把核心程式攤開來會比較好維護。

總結

Windows 上的 StreamDiffusion 建置，真正要先處理的是版本組合，而不是先急著找範例。本文把基準收斂到官方文件目前仍明確記載的 Python 3.10、PyTorch 2.1.0 與 CUDA 11.8 或 12.1，再用 uv 整理成本地可編輯的專案，最後用 Img2Img 與 Txt2Img 各做一次驗證。只要這一層穩了，後面要把它接進互動系統，工作量才會落在「設計流程」而不是「救環境」。

本文提到的版本與安裝基準，請參考：

• StreamDiffusion README
• PyTorch Previous Versions
• uv Installation

作者

Ted Liou

現職 Unity C# 工程師，主要分享 Unity、C# 與 Vibe Coding 相關技術教學。

GitHub