【Stable Diffusion】SD3/SD3.5モデルのローカル環境構築手順とよくあるエラー解決法

問題の概要：SD3/SD3.5モデルのローカル実行環境構築で発生する課題

Stability AIが発表した次世代モデル、Stable Diffusion 3 (SD3) および SD3.5 は、テキスト描画能力の飛躍的向上などで大きな注目を集めています。しかし、これらの最新モデルをローカルPCで実行しようとすると、従来のSD1.5やSDXLとは異なるアーキテクチャと要件のため、環境構築の段階で様々なエラーに直面することがあります。

具体的には、「モデルファイルの読み込み失敗」、「Transformerアーキテクチャ関連のインポートエラー」、「メモリ不足（VRAM/ RAM）」、「互換性のないライブラリバージョンによる実行時エラー」などが頻発します。これらのエラーは、単に公式リポジトリをクローンしてモデルをダウンロードするだけでは解決が難しく、適切な依存関係の構築と環境設定が不可欠です。

原因の解説：なぜSD3/SD3.5の環境構築は難しいのか？

SD3/SD3.5のローカル実行が従来モデルより複雑な主な原因は以下の3点です。

1. アーキテクチャの大幅な変更

SD3は、これまでのU-Netをベースとした拡散モデルから、Diffusion Transformer (DiT) をベースとしたMM-DiTアーキテクチャに移行しています。この根本的な変更により、モデルをロードし実行するための推論コード（`pipeline`や`model`の読み込み方法）が刷新され、従来のコミュニティツール（如：Automatic1111 WebUI）との直接的な互換性が失われています。

2. 厳格な依存関係

新しい`transformers`、`diffusers`、`torch`の特定バージョンが要求されます。特に、SD3.5の正式な実装が`diffusers`ライブラリに統合されたのは比較的最近であるため、バージョンを厳密に合わせないと「`AttributeError: ‘Flax…’`」や「`KeyError: ‘expected keys …’`」といったモデル読み込みエラーの原因となります。

3. 高いハードウェア要件

モデルパラメータ数が増大し、推論に必要なVRAMがSDXLよりもさらに多くなっています。特にフルモデル（8Bパラメータなど）の実行には、16GB以上のVRAMが推奨されるため、リソース不足による`CUDA out of memory`エラーが発生しやすくなっています。

解決方法：ステップバイステップでのローカル環境構築手順

ここでは、最も一般的な方法である、Hugging Faceの`diffusers`ライブラリを使用したPython環境での構築手順を説明します。

ステップ1: 前提環境のセットアップ

Python 3.8〜3.10、および適切なバージョンのPyTorch（CUDA対応）がインストールされていることを確認します。Anacondaやvenvでの仮想環境の使用を強く推奨します。

# 仮想環境の作成と有効化（condaの場合）
conda create -n sd3 python=3.10 -y
conda activate sd3

# PyTorchのインストール（CUDA 12.1の例）
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

ステップ2: 必要なライブラリのインストール

SD3/SD3.5実行に必要なライブラリを、互換性のあるバージョンでインストールします。バージョンの組み合わせが重要です。

# コアライブラリのインストール
pip install diffusers==0.28.0
pip install transformers==4.40.0
pip install accelerate>=0.30.0

# 画像処理・表示用の補助ライブラリ
pip install pillow matplotlib
pip install invisible_watermark  # 透かし検出用（オプション）

ステップ3: Hugging Face Hubへのログインとモデル取得

SD3.5などのモデルは、Hugging Face Hubで公開されています。アクセストークンが必要な場合があるため、ログインを行います。

# ターミナルでログイン（アクセストークンを入力）
huggingface-cli login

# または、Pythonスクリプト内で環境変数を設定
import os
os.environ["HF_TOKEN"] = "your_huggingface_token_here"

ステップ4: 推論スクリプトの作成と実行

以下のようなPythonスクリプトを作成し、SD3.5 Medium（推奨）を実行します。

import torch
from diffusers import StableDiffusion3Pipeline

# パイプラインのロード（モデルは初回実行時に自動ダウンロード）
pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-medium",
    torch_dtype=torch.float16,  # メモリ節約のため半精度を使用
)
pipe = pipe.to("cuda")

# プロンプトを指定して画像生成
prompt = "A majestic lion standing on a cliff, sunset, photorealistic"
negative_prompt = "blurry, low quality, deformed"

image = pipe(
    prompt,
    negative_prompt=negative_prompt,
    num_inference_steps=28,
    guidance_scale=7.0,
).images[0]

# 画像の保存
image.save("sd35_output.png")
print("画像生成が完了しました！")

よくあるエラーとその解決策

エラー1: 「`Could not find model …`」または「`404 Client Error …`」

エラーメッセージ例: 404 Client Error: Repository Not Found for url: https://huggingface.co/stabilityai/stable-diffusion-3.5-medium/resolve/main/model_index.json

原因と解決策: モデル名が間違っているか、アクセス権限が必要です。SD3.5の正しいリポジトリ名はstabilityai/stable-diffusion-3.5-medium（または-large, -turbo）です。また、SD3（8Bなど）は現在、研究目的での申請が必要な場合があります。Hugging Face Hubの該当モデルページでアクセス方法を確認してください。

エラー2: 「`OutOfMemoryError: CUDA out of memory`」

原因と解決策: VRAM不足です。以下の対策を試してください。

# 1. 画像サイズを小さくする（デフォルトは1024x1024）
image = pipe(..., height=768, width=768).images[0]

# 2. CPUオフロードとメモリ最適化を有効化（推論は遅くなる）
pipe.enable_model_cpu_offload()
pipe.enable_attention_slicing()

# 3. より軽量なモデルを選択する（例: SD3.5-Turbo）

エラー3: 「`AttributeError: ‘Flax…’` や `KeyError` がモデル読み込み時に発生」

原因と解決策:</strong diffusers と transformers のバージョン不一致がほぼ確実です。前述のステップ2に記載のバージョンに厳密にダウングレードし、キャッシュをクリアして再試行してください。

# パッケージのアンインストールと再インストール
pip uninstall diffusers transformers -y
pip install diffusers==0.28.0 transformers==4.40.0

# Hugging Faceのモデルキャッシュを削除（必要に応じて）
# キャッシュディレクトリは通常 ~/.cache/huggingface/hub にあります