Debian 13 原生 Python 安裝與使用 CodeFormer 修復臉部照片與影片教學

目前人工智慧（AI）已有越來越多的應用，而 CodeFormer 是一種人工智慧數位臉部修復工具，一般可以在其官網上傳照片（https://huggingface.co/spaces/sczhou/CodeFormer），它會修復後讓你下載，但傳過一次曠日費時。還好它是開源軟體，於是將其安裝到自己的電腦中，便可以批次處理。不過事涉大量運算，有獨顯速度會快些，沒有的就只能用 CPU 硬解。如果原稿臉部夠大張（最好 512×512 像素以上），其還原程度相當不錯，有針對臉部一般修復、精細修復、上色、破碎還原等功能，個人覺得蠻自然傳神的。

因為自己筆電沒有太高檔 GPU，且 Debian 12 時使用 Anaconda3 來處理在 Debian 13 時卻失效，常常說空間不足、安裝 CUDA 相依性錯誤等問題，重灌系統好幾次，於是改變作法，打掉重做，用原生 Python 來執行。

---

在 Debian 13 中安裝 Nvidia GPU 驅動

若使用 Nvidia GTX 1060 等顯卡，想讓 CodeFormer 利用 GPU 加速運算，需要先安裝 Nvidia 官方驅動與 CUDA 開發環境。注意！核心要使用 Debian 標準版核心以免編譯失敗。

1. 更新系統並安裝基礎工具

sudo apt update
sudo apt upgrade
sudo apt install linux-headers-amd64 python3.13-venv
sudo apt install -y build-essential dkms

2. 安裝 Nvidia 官方驅動

sudo apt install nvidia-detect nvidia-driver firmware-misc-nonfree
sudo reboot
（如果失敗，編輯 /etc/apt/sources.list 在套件庫中加入 contrib non-free 如下：
deb http://free.nchc.org.tw/debian/ trixie main non-free-firmware contrib non-free） 

3. 驗證驅動安裝是否成功

nvidia-smi

---

Debian 13 原生 Python 安裝與 CodeFormer 執行流程

Step 1: 安裝系統依賴

sudo apt install -y git python3-pip python3-venv build-essential cmake \
libgl1 libglib2.0-0 libffi-dev libbz2-dev libreadline-dev libsqlite3-dev \
libncurses5-dev libgdbm-dev liblzma-dev tk-dev libssl-dev uuid-dev

Step 2: 安裝 pyenv 管理 Python

# 安裝pyenv依賴
sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
libsqlite3-dev libncurses5-dev xz-utils tk-dev libffi-dev liblzma-dev

# 安裝 pyenv
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init -)"\nfi' >> ~/.bashrc
exec "$SHELL"

# 使用 pyenv 安裝 Python 3.10.9
pyenv install 3.10.9
pyenv global 3.10.9

# 建立虛擬環境並啟用
python -m venv ~/codeformer_env
source ~/codeformer_env/bin/activate

# 安裝Pytorch
使用GPU（配合Nvidia 1060挑選適合的版本）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 --cache-dir=$HOME/tmp
或是使用CPU
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu --cache-dir=$HOME/tmp

Step 3: 下載 CodeFormer 並安裝依賴

pip install --upgrade pip
git clone https://github.com/sczhou/CodeFormer.git ~/CodeFormer
cd ~/CodeFormer
export TMPDIR=$HOME/tmp
pip install -r requirements.txt --cache-dir=$HOME/tmp
python basicsr/setup.py develop
pip install dlib ffmpeg-python --cache-dir=$HOME/tmp
python scripts/download_pretrained_models.py facelib
python scripts/download_pretrained_models.py CodeFormer

Step 4: 使用批次處理腳本

將以下腳本存成 /usr/local/bin/aiphoto，調整裡面路徑符合個人環境：

#!/bin/bash

INPUT_DIR="$(pwd)"
CURRENT_DIR_NAME="$(basename "$INPUT_DIR")"
USER_HOME="$HOME"
TEMP_OUTPUT_DIR="$USER_HOME/aiphoto"
FINAL_OUTPUT_DIR="$INPUT_DIR/ai_$CURRENT_DIR_NAME"

mkdir -p "$TEMP_OUTPUT_DIR"
mkdir -p "$FINAL_OUTPUT_DIR"
cd "$HOME/CodeFormer"
source "$HOME/codeformer_env/bin/activate"
clear

echo "=============================================="
echo " CodeFormer 批次處理操作介面 "
echo "=============================================="
echo "原始圖片資料夾：$INPUT_DIR"
echo "暫存輸出資料夾（使用者目錄）：$TEMP_OUTPUT_DIR"
echo "最終輸出資料夾（原始目錄下）：$FINAL_OUTPUT_DIR"
echo

echo "請選擇處理模式："
echo " [1] 僅修復"
echo " [2] 利用 Real-ESRGAN 強化背景區域"
echo " [3] 以 Real-ESRGAN 進一步提升修復後的人臉細節"
echo " [4] 彩色化黑白或褪色照片"
echo " [5] 人臉修補（裁切並對齊的人臉）"
echo " [0] 離開程式"
read -p "請輸入選項數字（0-5，0離開）: " choice

if [[ "$choice" =~ ^[1-3]$ ]]; then
  read -p "請輸入權重值 (例如 0.7 或 1.0，建議 0.7~1.0): " weight
  if ! [[ "$weight" =~ ^0*(\.([0-9]+))?$|^1(\.0*)?$ ]]; then
    echo "錯誤：權重請輸入介於 0 與 1 之間的數字"
    deactivate
    exit 1
  fi
fi

case $choice in
  0)
    echo "離開程式。"
    deactivate
    exit 0
    ;;
  1)
    echo "執行選項 1：僅使用權重 ${weight} 修復"
    python inference_codeformer.py -w "$weight" --input_path "$INPUT_DIR" --output_path "$TEMP_OUTPUT_DIR"
    ;;
  2)
    echo "執行選項 2：使用權重 ${weight} 並利用 Real-ESRGAN 強化背景區域"
    python inference_codeformer.py -w "$weight" --bg_upsampler realesrgan --input_path "$INPUT_DIR" --output_path "$TEMP_OUTPUT_DIR"
    ;;
  3)
    echo "執行選項 3：使用權重 ${weight} 並以 Real-ESRGAN 進一步提升修復後的人臉細節"
    python inference_codeformer.py -w "$weight" --face_upsample --bg_upsampler realesrgan --input_path "$INPUT_DIR" --output_path "$TEMP_OUTPUT_DIR"
    ;;
  4)
    echo "執行選項 4：彩色化黑白或褪色照片"
    python inference_colorization.py --input_path "$INPUT_DIR" --output_path "$TEMP_OUTPUT_DIR"
    ;;
  5)
    echo "執行選項 5：人臉修補（裁切並對齊的人臉）"
    python inference_inpainting.py --input_path "$INPUT_DIR" --output_path "$TEMP_OUTPUT_DIR"
    ;;
  *)
    echo "無效選項，請重新執行並選擇有效選項。"
    deactivate
    exit 1
    ;;
esac

if [ "$choice" -eq 4 ] || [ "$choice" -eq 5 ]; then
  # 彩色化與人臉修補結果直接搬移 TEMP_OUTPUT_DIR 所有檔案
  echo "搬移處理結果到最終資料夾 $FINAL_OUTPUT_DIR"
  mv -v "$TEMP_OUTPUT_DIR"/* "$FINAL_OUTPUT_DIR"/
else
  # 其他功能結果位於 TEMP_OUTPUT_DIR/final_results
  if [ -d "$TEMP_OUTPUT_DIR/final_results" ]; then
    echo "搬移處理結果到最終資料夾 $FINAL_OUTPUT_DIR"
    mv -v "$TEMP_OUTPUT_DIR/final_results/"*.png "$FINAL_OUTPUT_DIR"/
  else
    echo "找不到 $TEMP_OUTPUT_DIR/final_results 目錄，無法搬移結果"
  fi
fi

echo "原始圖片保留於 $INPUT_DIR ，處理結果已搬移至 $FINAL_OUTPUT_DIR"

#刪除暫存檔

rm -Rf $HOME/aiphoto/*

deactivate

Step 5: 執行腳本

sudo chmod +x /usr/local/bin/aiphoto

要處理照片、影片時在該目錄開啟終端機，並執行 aiphoto 即可，
處理完會將優化照片放在該目錄下之「ai_當前目錄」。 

---