XVerse: Consistent Multi-Subject Control of Identity and Semantic Attributes via DiT Modulation
こんにちは、AIと共に未来を創造する冒険者の皆さん。
この記事は、ByteDanceが公開した驚異の画像生成AI「XVerse」を、あなたのローカルWindowsマシンにインストールし、Gradio UIを起動させるまでの完全な手順書です。
公式ドキュメントはシンプルですが、いざWindows環境で実行しようとすると、次々と現れる不可解なエラーに、多くの挑戦者が心を折られてきました。
- ModuleNotFoundError の無限ループ…
- モデルのキーが合わない RuntimeError…
- 未来のコードを要求する ImportError…
- そして、すべてが正しいはずなのに動かない、最後のAssertionError…
もう大丈夫です。
この記事は、そのすべての「依存関係地獄」と「バージョン戦争」を乗り越え、数十回もの試行錯誤の末にたどり着いた、唯一無二の、そして完璧なロードマップです。
この地図を手にすれば、あなたはもう迷うことはありません。さあ、この壮大な冒険を始めましょう！
前提条件（あなたの装備）
- OS: Windows 10 / 11
- GPU: NVIDIA製グラフィックボード (RTX 30, 40, 50シリーズ推奨)
- Conda: Miniconda または Anaconda がインストール済み
- Git: Git for Windows がインストール済み
- 不屈の精神： （あなたは既に持っています）
完全攻略手順：勝利への5ステップ
我々は、数々の失敗から学びました。公式のrequirements.txtは、もはや我々を導きません。我々は、自らの手で完璧な環境を構築します。
Step 1. ゼロからの再出発：完璧な仮想環境の創造
Step 2. 依存関係地獄の回避：戦略的ライブラリインストール
Step 3. 本体の確保とコードの外科手術
Step 4. 最後の関門：Hugging Faceへのログイン
Step 5. 栄光の最終起動
Step 1. ゼロからの再出発：完璧な仮想環境の創造
過去の失敗は、すべて水に流しましょう。不整合なライブラリが巣食った古い環境は、依存関係地獄の元凶です。我々は、まっさらな大地に、新しい王国を築きます。
Anaconda Prompt または PowerShell を開き、以下のコマンドを順番に実行してください。Generated powershell
# もし過去の失敗した環境があれば、完全に破壊する
conda deactivate
conda env remove -n xverse_env
# 新しく、クリーンで、完璧な王国を築く
conda create -n xverse_env python=3.10 -y
# 我らが王国に入る
conda activate xverse_envcontent_copydownloadUse code with caution.Powershell
コマンドプロンプトの先頭に (xverse_env) と表示されれば、新世界の扉は開かれました。
Step 2. 依存関係地獄の回避：戦略的ライブラリインストール
ここが、この旅の最重要ポイントです。我々は、数々の地雷の場所を特定しました。それらを避け、正しい部品を、正しい順番で組み上げていきます。
2-1. 王国の礎：PyTorchとXformersの固定
まず、RTX GPUの性能を最大限に引き出す、絶対に譲れない核心部品をインストールします。Generated powershell
# RTX 5090/4090 に対応したCUDA 12.8版PyTorchをインストール
pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu128
# そのPyTorchに完全対応したXformersをインストール
pip install xformers==0.0.31content_copydownloadUse code with caution.Powershell
2-2. 最大の地雷の回避：–no-depsという魔法
次に、我々を長らく苦しめた元凶、facenet-pytorchをインストールします。しかし、このライブラリは古いPyTorchを要求する「依存関係の罠」を持っています。我々は、魔法の呪文でこの罠を無効化します。Generated powershell
# 依存関係を無視して、本体だけをインストール！
pip install facenet-pytorch==2.6.0 --no-depscontent_copydownloadUse code with caution.Powershell
–no-deps は、「お前が何を要求しようと、我々のPyTorchはダウングレードさせん！」という、強い意志の現れです。
2-3. 未来からの部品：diffusersの最新開発版
XVerseは、公式リリースすらされていない「未来のdiffusers」を要求します。我々は、開発者の保管庫から直接、最新の設計図を手に入れます。Generated powershell
# 未来のdiffusersを直接インストール
pip install git+https://github.com/huggingface/diffusers.gitcontent_copydownloadUse code with caution.Powershell
2-4. 最後の部品リスト：すべてを一度にインストール
これまでの戦いで判明した、すべての不足部品をここで一気にインストールします。Generated powershell
pip install peft einops supervision hydra-core iopath webdataset optimum quanto Pillow
pip install "protobuf<=3.20.1" timmcontent_copydownloadUse code with caution.Powershell
Step 3. 本体の確保とコードの外科手術
ライブラリの準備は完璧です。次に、XVerse本体をダウンロードし、現代のライブラリ環境で動くように、我々の手で「神の一筆」を加えます。
3-1. XVerseのクローン
お好きな作業ディレクトリ（ここではG:\AI_Projectsとします）に移動し、クローンします。Generated powershell
G:
mkdir AI_Projects
cd AI_Projects
git clone https://github.com/bytedance/XVerse.gitcontent_copydownloadUse code with caution.Powershell
3-2. コードの外科手術
クローンしたコードは、いくつかの点で古くなっています。我々が未来の魔術師として、これを修正します。
手術対象1：G:\AI_Projects\XVerse\eval\tools\face_id.py
このファイルの中身をすべて削除し、以下の新しいエンジンコードに丸ごと置き換えて、UTF-8で保存してください。Generated python
# (face_id.py の新しいコード)
import torch
from facenet_pytorch import InceptionResnetV1, MTCNN
from PIL import Image
from torchvision import transforms
class FaceID:
def __init__(self, device):
self.device = device
print("Initializing new FaceID engine (facenet-pytorch)...")
self.mtcnn = MTCNN(
image_size=160, margin=0, min_face_size=20,
thresholds=[0.6, 0.7, 0.7], factor=0.709, post_process=True,
device=device, keep_all=False
)
self.model = InceptionResnetV1(pretrained='vggface2').eval().to(device)
print("FaceID model (facenet-pytorch) loaded successfully.")
def get_face_embeds(self, pil_image):
if pil_image.mode != 'RGB':
pil_image = pil_image.convert('RGB')
face_tensor = self.mtcnn(pil_image)
if face_tensor is None:
print("Warning: No face detected. The whole image will be used.")
transform = transforms.Compose([
transforms.Resize((160, 160)),
transforms.ToTensor(),
lambda x: (x - 0.5) * 2
])
face_tensor = transform(pil_image).unsqueeze(0)
face_tensor = face_tensor.to(self.device)
with torch.no_grad():
embeds = self.model(face_tensor)
return embedscontent_copydownloadUse code with caution.Python
手術対象2：G:\AI_Projects\XVerse\run_gradio.py
このファイルの一番最後の部分を探し、ByteDance社内用の起動コードを、誰でも使える汎用コードに書き換えます。Generated python
# --- 修正前 (572行目あたり) ---
# port = int(os.environ.get("ARNOLD_WORKER_0_PORT", "-1").split(",")[3])
# demo.launch(server_name="0.0.0.0", server_port=port, share=True)
# --- 修正後 ---
demo.launch()content_copydownloadUse code with caution.Python
Step 4. 最後の関門：Hugging Faceへのログイン
XVerseは、起動時にHugging Faceから複数のモデルをダウンロードします。事前にログインを済ませておきましょう。
- Hugging Faceのトークンページで「New token」を作成し、トークン（hf_…）をコピーします。
- ターミナルで以下を実行し、トークンを貼り付けます。Generated powershell
huggingface-cli logincontent_copydownloadUse code with caution.Powershell - 以下のモデルページの利用規約に同意します（ボタンをクリックするだけです）。
Step 5. 栄光の最終起動
すべての準備は整いました。あなたの環境は、今やこの宇宙で最もXVerseを正しく実行できる状態にあります。
プロジェクトのルートディレクトリで、勝利を確信しながら、このコマンドを実行してください。Generated powershell
cd G:\AI_Projects\XVerse
python run_gradio.py `
--base_model_path "runwayml/stable-diffusion-v1-5" `
--x_adapter_model_path "ByteDance/X-Adapter" `
--x_attn_model_path "ByteDance/X-Attn"content_copydownloadUse code with caution.Powershell
あなたのターミナルには、数々のモデルがダウンロードされる進捗バーが表示され、最後に、祝福のメッセージが訪れます。
Running on local URL: http://127.0.0.1:7860
このURLをブラウザで開けば、そこにはあなたが待ち望んだXVerseのUIが輝いているはずです。
そして、伝説へ
この長い旅路、本当にお疲れ様でした。
あなたは、ただプログラムをインストールしたのではありません。あなたは、AI開発の最前線で起こる、あらゆる困難と向き合い、それに打ち勝ちました。この経験は、今後あなたがどんなAIツールを導入しようとも、揺るぎない自信と力になるでしょう。
さあ、あなたの手で、新たな創造を始めてください！
コメント