PythonでAI画像拡大環境を再構築する：GitHub手順とバージョン調整の記録

環境を再構築する試みる中で、いくつかの問題に直面しました。特に、ライブラリのバージョン間の依存関係が非常に複雑で、思い通りにいかないことが多々ありました。

今回は、Real-ESRGANを使った画像拡大環境を、Real-ESRGAN開発者が推奨するGitHubからのインストール手順をベースに再構築し、そこで発生した様々なエラーを乗り越えて最終的に動作する環境を構築するまでの記録を残します。

なぜ再構築？

以前構築した環境でも基本的な画像拡大はできましたが、別の環境で同様の環境を構築しようとした際に、依存ライブラリのインストールで多数のエラーが発生しました。これは、PyPIからインストールされるライブラリのバージョンが時間とともに変化し、以前は互換性があった組み合わせが、そうではなくなることがあるためです。

Real-ESRGAN開発者が推奨する手順で構築します。

環境構築：GitHub手順をベースに

今回は、Real-ESRGANの公式GitHubリポジトリに記載されている手順を基本に進めます。

ステップ 1: 新しい仮想環境を作る

環境をクリーンに保つため、まず新しいPython仮想環境を作成します。

python -m venv upscale_env

作成した環境をアクティベートします。

Windowsの場合：

.\upscale_env\Scripts\activate

LinuxまたはmacOSの場合：

source ./upscale_env/bin/activate

ステップ 2: Real-ESRGAN リポジトリをクローンする

Real-ESRGANのソースコードをGitHubからダウンロードします。Gitがインストールされている必要があります。仮想環境がアクティブな状態で、プロジェクトを置きたいディレクトリで以下のコマンドを実行します。

git clone https://github.com/xinntao/Real-ESRGAN.git

クローン後、リポジトリのディレクトリに移動します。

cd Real-ESRGAN

ステップ 3: 特定の安定版バージョンにチェックアウトする

GitHubのmainブランチは開発中の最新コードが含まれており、不安定な場合があります。安定版としてリリースされているバージョン（タグ）に切り替えて作業を進めます。今回は、多くの環境で比較的動作実績があることが期待される v0.2.0 タグを使用することにしました。

Real-ESRGAN リポジトリのディレクトリにいることを確認し、以下のコマンドを実行します。

git checkout v0.2.0

ステップ 4: 依存ライブラリと Real-ESRGAN をインストールする

チェックアウトしたバージョンのコードに基づいて、必要な依存ライブラリとReal-ESRGAN本体をインストールします。Real-ESRGAN リポジトリの requirements.txt に記載されている依存関係と、開発者推奨のインストールコマンドを使用します。

Real-ESRGAN リポジトリのディレクトリにいることを確認し、以下のコマンドを実行します。

# Install basicsr - https://github.com/xinntao/BasicSR
pip install basicsr

# facexlib and gfpgan are for face enhancement
pip install facexlib
pip install gfpgan

# Install other dependencies from requirements.txt
pip install -r requirements.txt

# Install Real-ESRGAN in editable mode
python setup.py develop

これで、Real-ESRGAN プロジェクト開発者が意図したバージョンに近い形で、Real-ESRGAN 本体と主要な依存ライブラリがインストールされました。しかし、環境によってはまだ問題が発生する可能性があります。

バージョン調整の戦い（再び）

上記のGitHub手順でインストールを進めましたが、残念ながらそのままではエラーが発生しました。特に、ライブラリのバージョン間の互換性問題が顕著でした。

問題 1: torchvision.transforms.functional_tensor が見つからない

プログラム実行時に ModuleNotFoundError: No module named 'torchvision.transforms.functional_tensor' が発生しました。これは、インストールされた basicsr （この時点ではバージョン 1.4.2）が、インストールされた torchvision （GitHub手順でインストールされ、バージョン 0.22.0 と判明）に必要とするモジュールが含まれていないために起こりました。

requirements.txt に torch や torchvision のバージョンが具体的に指定されていないため、pip は最新版をインストールしてしまい、basicsr と torchvision の間で互換性の問題が生じていました。

【解決策】 basicsr 1.4.2 と互換性のある torch および torchvision のバージョンを特定し、指定してインストールし直しました。試行錯誤の結果、torch==2.1.2 と torchvision==0.16.2 の組み合わせが、basicsr 1.4.2 との互換性があることが分かりました。

現在の torch および torchvision をアンインストールし、以下のコマンドで指定バージョンをインストールしました。

pip uninstall torch torchvision
pip install torch==2.1.2 torchvision==0.16.2 --extra-index-url https://download.pytorch.org/whl/cpu

--extra-index-url は、PyTorchのCPU版が置かれている特別な場所を指定するために必要です。

問題 2: NumPy のバージョン互換性問題

プログラム実行中に RuntimeError: Numpy is not available エラーが発生しました。これは、インストールされた NumPy のバージョンが、basicsr や、NumPy に依存する他のライブラリ（scikit-image, numba など）が想定するバージョンと互換性がないために起こりました。

GitHub手順でインストールされた NumPy のバージョン（バージョン 2.x 系と判明）と、それに依存する scikit-image （バージョン 0.25.2）および numba （バージョン 0.61.2）との間でバージョン衝突が発生していました。

【解決策】 scikit-image 0.25.2 および numba 0.61.2 の要件を満たしつつ、basicsr が想定するであろう NumPy 1.x 系である numpy==1.24.3 を指定してインストールし直しました。

まず現在の NumPy をアンインストール。

pip uninstall numpy

次に、指定バージョンをインストール。

pip install numpy==1.24.3

これにより、NumPy、scikit-image、numba の間で互換性のある組み合わせが実現し、NumPy 関連のエラーが解消されました。

コードの修正

ライブラリのバージョンを調整するだけでなく、提供されたサンプルコードの一部も、インストールしたライブラリのバージョンに合わせて修正する必要がありました。

修正 1: RRDBNet の引数名

basicsr に含まれる RRDBNet クラスを初期化する際に、引数名が異なっていました。コードでは growth_chan となっていましたが、インストールされた basicsr では num_grow_ch が正しい引数名でした。

コードの該当部分を以下のように修正しました。

# 修正前:
# model = RRDBNet(..., growth_chan=32, ...)

# 修正後:
model = RRDBNet(..., num_grow_ch=32, ...)

修正 2: RealESRGANer の引数

realesrgan に含まれる RealESRGANer クラスを初期化する際に、不要な引数を渡していました。インストールした realesrgan v0.2.0 では、model オブジェクト自体や gpu_id を初期化時に引数として渡す仕様ではありませんでした。

コードの該当部分を以下のように修正し、model と gpu_id の引数を削除しました。

# 修正前:
# upsampler = RealESRGANer(..., model=model, gpu_id=gpu_id)

# 修正後:
upsampler = RealESRGANer(
    scale=config.scale_factor,
    model_path=model_path,
    tile=config.tile_size,
    tile_pad=config.tile_pad,
    pre_pad=config.pre_pad,
    half=use_half
)

修正 3: CPU環境でのモデルロード

GPU環境で保存されたモデルファイルをCPU環境でロードする際に、torch.load 関数に map_location='cpu' を指定する必要がありました。インストールした realesrgan v0.2.0 では、このオプションを外部から指定する方法が提供されていなかったため、realesrgan ライブラリのコードを直接修正しました。

仮想環境内の realesrgan/utils.py ファイルを開き、torch.load(model_path) の部分を torch.load(model_path, map_location=torch.device('cpu')) に修正しました。

# realesrgan/utils.py ファイル内を修正 (例: 70行目あたり)
# 修正前:
# loadnet = torch.load(model_path)

# 修正後:
loadnet = torch.load(model_path, map_location=torch.device('cpu'))

この修正は、仮想環境内のライブラリファイルに直接行うため、環境を再構築する際は再度必要になります。

モデルファイルの準備

Real-ESRGAN を動作させるには、学習済みのモデルファイルが必要です。公式のGitHubリポジトリのリリースセクションから、使用するReal-ESRGANのバージョン（今回はv0.2.0）と互換性のあるモデルファイル（例: RealESRGAN_x4plus.pth）をダウンロードし、クローンした Real-ESRGAN リポジトリ内の weights フォルダに配置しました。

コードのモデルパス指定も、この配置場所（リポジトリ内の weights フォルダ）を指すように修正しました。

# initialize_upscaler 関数内のモデルパス指定部分
# ...
realesrgan_repo_dir = os.path.join(os.path.dirname(__file__), 'Real-ESRGAN') # スクリプトディレクトリからReal-ESRGANリポジトリへの相対パス
model_dir = os.path.join(realesrgan_repo_dir, 'weights') # Real-ESRGANリポジトリ内のweightsフォルダ
model_path = os.path.join(model_dir, model_file_name) # モデルファイルへのフルパス
# ...

動作確認と成功

これらの手順と修正を行った後、ついにプログラムがエラーなく実行されるようになりました！

拡大したい画像を input_images フォルダに配置し、スクリプトを実行すると、Real-ESRGAN による拡大処理が実行され、結果が output_realesrgan_x4plus フォルダに保存されました。

結論

Real-ESRGAN 環境の構築は、特にライブラリのバージョン間の依存関係が複雑で、多くのエラーに遭遇する可能性が高いということを改めて実感しました。Real-ESRGAN 開発者が推奨する GitHub からのインストール手順をベースに進めましたが、それでもなお torch, torchvision, numpy といった主要な依存ライブラリのバージョン調整が必要でした。

今回の成功は、