1

.gitattributes

@@ -0,0 +1 @@
+*.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,293 @@
+# 處理結果檔案（不需要版本控制）
+backend/results/*
+backend/uploads/*
+
+# AI 模型檔案（檔案太大，需要另外下載）
+# inswapper_128.onnx 檔案 529MB，超過 GitHub 100MB 限制
+backend/models/inswapper_128.onnx
+backend/models/*.pth
+backend/models/*.pt
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+*.lnk
+
+# Linux
+*~
+
+# Docker
+.dockerignore
+
+# Node.js (如果有前端建置工具)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage
+.grunt
+
+# Bower dependency directory
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons
+build/Release
+
+# Dependency directories
+jspm_packages/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+public
+
+# Storybook build outputs
+.out
+.storybook-out
+storybook-static
+
+# Temporary folders
+tmp/
+temp/
+
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# 專案特定的臨時檔案
+*.tmp
+*.temp
+*.bak
+*.swp
+*.swo
+
+# 測試檔案
+test_images/
+test_results/
+
+
+myenv/

Dockerfile

@@ -0,0 +1,39 @@
+# 使用官方 Python 3.11 slim 版本作為基礎映像
+FROM python:3.11-slim
+
+# 設定工作目錄
+WORKDIR /app
+
+# 安裝系統依賴
+RUN apt-get update && apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libsm6 \
+    libxext6 \
+    libxrender-dev \
+    libgomp1 \
+    wget \
+    build-essential \
+    g++ \
+    cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+# 複製 requirements.txt 並安裝 Python 依賴
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 創建模型目錄（模型檔案由 docker-compose.yml 中的 model-downloader 服務下載）
+RUN mkdir -p /app/{models,results,uploads}
+
+# 由於使用 volume 掛載，不需要 COPY 後端代碼
+# 後端代碼會通過 docker-compose.yml 中的 volume 掛載
+
+# 設定環境變數
+ENV PYTHONPATH=/app
+ENV ENVIRONMENT=development
+
+# 暴露端口
+EXPOSE 3001
+
+# 啟動命令（會被 docker-compose.yml 中的 command 覆蓋）
+CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "3001", "--reload"]

README.md

@@ -0,0 +1,13 @@
+---
+title: SwapFace
+emoji: ⚡
+colorFrom: gray
+colorTo: pink
+sdk: gradio
+sdk_version: 5.34.2
+app_file: app.py
+pinned: false
+short_description: 換臉
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

README2.md

@@ -0,0 +1,97 @@
+# 🎭 AI 頭像工作室 (Gradio 版)
+
+這是一個使用 Gradio 和 InsightFace 技術建立的 AI 換臉應用程式。專案經過簡化，移除了前後端分離的複雜架構，改用單一的 Gradio 應用程式，使其更容易在本地端執行、打包成 Docker 映像檔，或部署到 Hugging Face Spaces。
+
+## ✨ 功能
+
+- **互動式介面**: 使用 Gradio 建立，操作直觀，無需前端開發知識。
+- **自訂換臉**: 上傳您的照片和目標風格照片，一鍵生成換臉結果。
+- **預設模板**: 提供多個預設模板，方便快速體驗。
+- **多人臉支援**: 支援對圖片中的多張人臉進行選擇性替換。
+- **自動模型下載**: 首次執行時，應用程式會自動下載所需的 AI 模型。
+
+## 📂 專案結構
+
+專案已簡化為適合 Gradio 應用的結構：
+
+```
+swapFace/
+├── Dockerfile          # 用於建立 Docker 映像檔
+├── app.py              # 主要的 Gradio 應用程式
+├── requirements.txt    # Python 依賴
+├── README.md           # 就是您正在看的這個檔案
+├── core/               # 核心 AI 處理邏輯
+│   ├── __init__.py
+│   ├── config.py
+│   └── face_processor.py
+└── models/             # 存放 AI 模型和圖片模板
+    └── templates/
+        ├── step01.jpg
+        └── ...
+```
+
+---
+
+## 🚀 如何執行
+
+您可以選擇兩種方式來執行此應用程式：**1. 在本地端直接執行** 或 **2. 使用 Docker**。
+
+### 方案一：在本地端直接執行 (推薦給開發者)
+
+1.  **環境準備**:
+    建議在 Python 虛擬環境中進行操作。
+    ```bash
+    # 建立虛擬環境
+    python3 -m venv venv
+
+    # 啟用虛擬環境 (macOS/Linux)
+    source venv/bin/activate
+    # (Windows)
+    # venv\Scripts\activate
+    ```
+
+2.  **安裝依賴**:
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+3.  **啟動應用**:
+    ```bash
+    python app.py
+    ```
+
+    應用程式啟動後，會顯示一個本地 URL (例如 `http://127.0.0.1:7860`)。在瀏覽器中打開此連結即可開始使用。
+
+    **⚠️ 注意**: 首次啟動時，程式會自動從網路下載約 530MB 的 AI 模型 (`inswapper_128.onnx`) 到 `models` 目錄下，請耐心等待。這只需要執行一次。
+
+### 方案二：使用 Docker 執行 (推薦用於部署或隔離環境)
+
+確保您的電腦上已經安裝了 [Docker](https://www.docker.com/products/docker-desktop/)。
+
+1.  **建立 Docker 映像檔**:
+    在專案根目錄下（與 `Dockerfile` 同層級），執行以下指令：
+    ```bash
+    # -t 後面是您為映像檔取的名稱，例如 'ai-avatar-studio'
+    docker build -t ai-avatar-studio .
+    ```
+
+2.  **執行 Docker 容器**:
+    映像檔建立成功後，使用以下指令來啟動容器：
+    ```bash
+    # -p 7860:7860 將您本機的 7860 連接埠映射到容器的 7860 連接埠
+    # --rm 會在容器停止後自動刪除，保持系統乾淨
+    docker run --rm -p 7860:7860 ai-avatar-studio
+    ```
+
+3.  **訪問應用**:
+    容器啟動後，同樣會先下載模型（如果映像檔中沒有的話）。完成後，在瀏覽器中打開 `http://localhost:7860` 即可使用。
+
+---
+
+## 🤗 部署到 Hugging Face Spaces
+
+這個專案結構也非常適合直接部署到 Hugging Face Spaces。
+
+1.  在 Hugging Face 上建立一個新的 Space，並選擇 **Gradio** 作為 SDK。
+2.  將專案中的所有檔案（**除了 `Dockerfile`**）上傳到 Space 的 Git 儲存庫。
+3.  Hugging Face 會自動處理環境安裝和應用啟動。大功告成！

app.py

@@ -0,0 +1,215 @@
+import gradio as gr
+import cv2
+import numpy as np
+from PIL import Image
+from pathlib import Path
+
+# 導入臉部處理器
+from core.face_processor import FaceProcessor
+
+# --- 初始化模型 ---
+face_processor = None
+try:
+    print("🚀 正在初始化 AI 模型，請稍候...")
+    face_processor = FaceProcessor()
+    print("✅ AI 模型載入成功！")
+except Exception as e:
+    print(f"❌ 模型載入失敗: {e}")
+    print("   如果看到下載錯誤，請參考 README.md 中的手動下載指南。")
+    face_processor = None
+
+# --- Gradio 介面 ---
+def create_examples():
+    """檢查範例圖片是否存在，如果存在則建立範例列表"""
+    example_list = []
+    template_dir = Path(__file__).parent / 'models' / 'templates'
+    
+    # 檢查範例圖片 step01.jpg 和 step02.jpg 是否存在
+    source_example_path = template_dir / 'step01.jpg'
+    target_example_path = template_dir / 'step02.jpg'
+
+    if source_example_path.exists() and target_example_path.exists():
+        print("✅ 找到範例圖片，正在建立 Gradio 範例...")
+        example_list.append([
+            str(source_example_path),
+            str(target_example_path),
+            "0", # 臉部索引
+            None # 模板
+        ])
+    else:
+        print("⚠️  未找到範例圖片（例如 models/templates/step01.jpg），Gradio 將不會顯示範例。")
+        print(f"   - 檢查路徑: {source_example_path}")
+        print(f"   - 檢查路徑: {target_example_path}")
+
+    return example_list
+
+# 建立範例
+examples = create_examples()
+
+# 取得模板圖片列表
+def get_template_files():
+    template_dir = Path(__file__).parent / "models" / "templates"
+    try:
+        templates = [str(p) for p in template_dir.glob("*.jpg")]
+        print(f"✅ 成功載入 {len(templates)} 個模板。")
+        return templates
+    except FileNotFoundError:
+        print("⚠️  找不到模板資料夾 'models/templates'，模板選擇功能將無法使用。")
+        return []
+    except Exception as e:
+        print(f"❌ 載入模板時發生錯誤: {e}")
+        return []
+
+def swap_face_gradio(source_image, target_image, face_index_str, template_choice):
+    """Gradio 的主處理函數"""
+    if face_processor is None:
+        raise gr.Error("AI 模型未能成功載入，無法處理請求。請檢查後台日誌。")
+
+    print(f"ℹ️ 開始處理... 來源臉孔索引: {face_index_str}")
+
+    try:
+        # --- 1. 參數驗證和準備 ---
+        if source_image is None:
+            raise gr.Error("請務必上傳來源圖片。")
+
+        # 如果選擇了模板，目標圖片變成模板
+        if template_choice and template_choice != "無":
+            print(f"   -> 使用模板: {template_choice}")
+            target_image = np.array(Image.open(template_choice))
+        elif target_image is None:
+            raise gr.Error("請上傳目標圖片，或選擇一個模板。")
+
+        try:
+            face_index = int(face_index_str)
+            if face_index < 0:
+                raise ValueError
+        except (ValueError, TypeError):
+            raise gr.Error("臉部索引必須是一個大於等於 0 的整數。")
+
+        # --- 2. 圖片格式轉換 ---
+        # Gradio 提供 RGB 格式，insightface 需要 BGR 格式
+        source_bgr = cv2.cvtColor(source_image, cv2.COLOR_RGB2BGR)
+        target_bgr = cv2.cvtColor(target_image, cv2.COLOR_RGB2BGR)
+
+        # --- 3. 執行換臉 --- 
+        result_bgr = face_processor.swap_face(
+            source_bgr,
+            target_bgr,
+            face_index
+        )
+
+        # --- 4. 處理結果 ---
+        if result_bgr is None:
+            raise gr.Error("換臉失敗，可能是因為無法在圖片中偵測到足夠的臉部。")
+
+        # 轉回 RGB 格式供 Gradio 顯示
+        result_rgb = cv2.cvtColor(result_bgr, cv2.COLOR_BGR2RGB)
+        print("✅ 處理完成！")
+        return result_rgb
+
+    except ValueError as ve:
+        print(f"❌ 處理時發生錯誤: {ve}")
+        raise gr.Error(str(ve))
+    except Exception as e:
+        import traceback
+        error_details = traceback.format_exc()
+        print(f"❌ 發生未預期的錯誤: {e}")
+        print(f"詳細錯誤堆疊:\n{error_details}")
+        raise gr.Error(f"錯誤: {str(e)}")
+
+# --- 建立 Gradio 介面 ---
+with gr.Blocks(
+    title="換臉 by DAVID888",
+    theme=gr.themes.Soft(),
+    css=".gradio-container {max-width: 1000px !important}"
+) as demo:
+    
+    gr.HTML("""
+        <div style="text-align: center; font-family: 'Arial', sans-serif; color: #333;">
+            <h1 style="color: #2c3e50;">換臉工具</h1>
+            <p style="font-size: 1.1em;">上傳一張包含臉部的<b>來源圖片</b>和一張<b>目標圖片</b>，或從下方選擇一個<b>模板</b>作為目標，即可進行換臉。</p>
+            <p style="font-size: 0.9em; color: #7f8c8d;">如果來源圖片中有多張臉，請在「來源臉部索引」中���定要替換的臉部（從 0 開始）。</p>
+        </div>
+    """)
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            source_image = gr.Image(
+                label="來源圖片 (您的臉部)",
+                type="numpy",
+                height=300
+            )
+            face_index_input = gr.Textbox(
+                label="來源臉部索引",
+                value="0",
+                placeholder="如果有多張臉，指定要使用的臉部（從 0 開始）",
+                info="0=第一張臉, 1=第二張臉, 以此類推"
+            )
+
+        with gr.Column(scale=1):
+            target_image = gr.Image(
+                label="目標圖片 (要換到的目標)",
+                type="numpy", 
+                height=300
+            )
+            
+            # 模板選擇 (如果有可用模板)
+            template_files = get_template_files()
+            if template_files:
+                template_choice = gr.Dropdown(
+                    choices=["無"] + template_files,
+                    value="無",
+                    label="或選擇一個模板",
+                    info="選擇模板會覆蓋上方的目標圖片"
+                )
+            else:
+                template_choice = gr.Dropdown(
+                    choices=["無"],
+                    value="無",
+                    label="模板 (無可用模板)",
+                    interactive=False
+                )
+
+    # 處理按鈕
+    swap_button = gr.Button(
+        "🚀 開始換臉",
+        variant="primary",
+        size="lg"
+    )
+
+    # 結果顯示
+    result_image = gr.Image(
+        label="換臉結果",
+        type="numpy",
+        height=400
+    )
+
+    # 範例 (如果有的話)
+    if examples:
+        gr.Examples(
+            examples=examples,
+            inputs=[source_image, target_image, face_index_input, template_choice],
+            label="點擊範例快速開始",
+            examples_per_page=3
+        )
+
+    # 綁定處理函數
+    swap_button.click(
+        fn=swap_face_gradio,
+        inputs=[
+            source_image,
+            target_image, 
+            face_index_input,
+            template_choice
+        ],
+        outputs=result_image,
+        api_name="face_swap"
+    )
+
+# --- 啟動應用 ---
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0", 
+        server_port=7860, 
+        share=True
+    )

core/config.py

@@ -0,0 +1,87 @@
+"""
+應用配置檔案
+"""
+import os
+from pathlib import Path
+
+# 基礎路徑 (現在是專案根目錄)
+BASE_DIR = Path(__file__).parent.parent
+MODELS_DIR = BASE_DIR / "models"
+RESULTS_DIR = BASE_DIR / "results" # Gradio 可能不太需要這個了
+
+# AI 模型配置
+MODEL_CONFIG = {
+    "FACE_ANALYSIS_MODEL": "buffalo_l",
+    "FACE_SWAP_MODEL": "inswapper_128.onnx",
+    "DETECTION_SIZE": (640, 640),
+    "CTX_ID": 0,  # CPU: -1, GPU: 0
+}
+
+# 模板配置
+TEMPLATE_CONFIG = {
+    "TEMPLATES": {
+        "1": {
+            "id": "1",
+            "name": "模板 1",
+            "description": "預設模板",
+            "path": "./models/templates/step01.jpg"
+        },
+        "2": {
+            "id": "2", 
+            "name": "模板 2",
+            "description": "預設模板",
+            "path": "./models/templates/step02.jpg"
+        },
+        "3": {
+            "id": "3",
+            "name": "模板 3", 
+            "description": "預設模板",
+            "path": "./models/templates/step03.jpg"
+        },
+        "4": {
+            "id": "4",
+            "name": "模板 4",
+            "description": "預設模板", 
+            "path": "./models/templates/step04.jpg"
+        },
+        "5": {
+            "id": "5",
+            "name": "模板 5",
+            "description": "預設模板",
+            "path": "./models/templates/step05.jpg"
+        },
+        "6": {
+            "id": "6",
+            "name": "模板 6",
+            "description": "預設模板",
+            "path": "./models/templates/step06.jpg"
+        }
+    }
+}
+
+def get_model_path(model_name: str) -> Path:
+    """獲取模型檔案路徑"""
+    # Hugging Face Spaces 會將模型快取在 /data，但我們的邏輯是下載到 models/
+    local_model_path = MODELS_DIR / model_name
+    if local_model_path.exists():
+        return local_model_path
+    # 如果本地沒有，face_processor 會嘗試下載
+    return local_model_path
+
+def get_template_path(template_id: str) -> Path:
+    """獲取模板圖片路徑"""
+    template = TEMPLATE_CONFIG["TEMPLATES"].get(template_id)
+    if not template:
+        raise ValueError(f"Template {template_id} not found")
+    
+    template_path = template["path"]
+    # 將相對於專案根目錄的路徑轉換為絕對路徑
+    if template_path.startswith("./"):
+        return BASE_DIR / template_path[2:]
+    return Path(template_path)
+
+def ensure_directories():
+    """確保必要的目錄存在"""
+    # 確保模型和模板目錄存在，以便下載和存取
+    (MODELS_DIR / "templates").mkdir(parents=True, exist_ok=True)
+

core/face_processor.py

@@ -0,0 +1,169 @@
+"""
+臉部處理核心模組
+"""
+import cv2
+import numpy as np
+from PIL import Image
+import insightface
+from insightface.app import FaceAnalysis
+import onnxruntime
+from pathlib import Path
+import urllib.request
+import os
+
+class FaceProcessor:
+    """臉部處理器，封裝了所有 AI 模型"""
+    def __init__(self):
+        self.swapper = None
+        self.face_analyzer = None
+        self._initialize_models()
+
+    def _ensure_model_downloaded(self, root_dir: Path, model_name: str, url: str):
+        """
+        確保指定的模型檔案存在於 models 資料夾中。
+        如果不存在，則從提供的 URL 下載。
+        """
+        model_dir = root_dir / 'models'
+        model_path = model_dir / model_name
+
+        model_dir.mkdir(parents=True, exist_ok=True)
+
+        if model_path.exists():
+            print(f"INFO:core.face_processor:找到本地模型: {model_path}，將跳過下載。")
+            return
+
+        print(f"INFO:core.face_processor:在本地找不到模型，將從以下 URL 下載：")
+        print(f"   -> URL: {url}")
+        print(f"   -> 目標路徑: {model_path}")
+
+        try:
+            response = urllib.request.urlopen(url)
+            total_length = response.getheader('content-length')
+            
+            with open(model_path, 'wb') as f:
+                if total_length is None:
+                    f.write(response.read())
+                    print("INFO:core.face_processor:模型下載完成。")
+                else:
+                    dl = 0
+                    total_length = int(total_length)
+                    for data in response:
+                        dl += len(data)
+                        f.write(data)
+                        done = int(50 * dl / total_length)
+                        print(f"\r   [ {'=' * done}{' ' * (50-done)} ] {dl * 100 / total_length:.2f}%", end='')
+            print("\nINFO:core.face_processor:模型下載完成。")
+
+        except Exception as e:
+            print(f"\nERROR:core.face_processor:下載模型時發生錯誤。")
+            if model_path.exists():
+                os.remove(model_path)
+            print(f"   請檢查您的網路連線，或嘗試手動從以下 URL 下載模型：")
+            print(f"   {url}")
+            print(f"   並將其放置在 '{model_path.parent}' 資料夾中。")
+            raise RuntimeError(f"模型下載失敗: {url}") from e
+
+    def _initialize_models(self):
+        """初始化所有需要的模型"""
+        try:
+            print("INFO:core.face_processor:正在初始化 AI 模型...")
+            onnxruntime.set_default_logger_severity(3)
+            
+            root_dir = Path(__file__).parent.parent
+            models_dir = root_dir / 'models'
+            models_dir.mkdir(exist_ok=True) # 確保 models 資料夾存在
+
+            providers = onnxruntime.get_available_providers()
+            if 'CUDAExecutionProvider' in providers:
+                print("INFO:core.face_processor:檢測到 CUDA，將使用 GPU。")
+            else:
+                print("INFO:core.face_processor:未檢測到 CUDA，將使用 CPU。")
+                if 'CoreMLExecutionProvider' in providers:
+                    providers.insert(0, 'CoreMLExecutionProvider')
+
+            # --- 載入臉部分析模型 (buffalo_l) ---
+            print(f"INFO:core.face_processor:正在檢查臉部分析模型 'buffalo_l'...")
+            buffalo_l_path = models_dir / 'buffalo_l'
+            print(f"   -> 預期路徑: {buffalo_l_path}")
+
+            if not buffalo_l_path.is_dir() or not any(buffalo_l_path.iterdir()):
+                 print("WARNING:core.face_processor:未在預期路徑找到 'buffalo_l' 模型資料夾，或該資料夾為空。")
+                 print("   -> 程式將嘗試從網路下載。若要手動放置，請將解壓縮後的 'buffalo_l' 資料夾完整放入 'models' 目錄中。")
+            else:
+                 print("INFO:core.face_processor:成功找到本地 'buffalo_l' 模型資料夾。")
+
+            # insightface 會在 root 目錄下尋找 'models' 資料夾，所以 root 應設為專案根目錄
+            self.face_analyzer = FaceAnalysis(name='buffalo_l', root=str(root_dir), providers=providers)
+            self.face_analyzer.prepare(ctx_id=0, det_size=(640, 640))
+
+            # --- 載入換臉模型 (inswapper_128.onnx) ---
+            model_name = "inswapper_128.onnx"
+            model_url = "https://huggingface.co/xingren23/comfyflow-models/resolve/976de8449674de379b02c144d0b3cfa2b61482f2/insightface/inswapper_128.onnx?download=true"
+            
+            self._ensure_model_downloaded(root_dir, model_name, model_url)
+
+            model_path = root_dir / 'models' / model_name
+            print(f"INFO:core.face_processor:準備從本地路徑載入模型: {model_path}")
+            
+            self.swapper = insightface.model_zoo.get_model(
+                str(model_path),
+                download=False,
+                download_zip=False
+            )
+            print("INFO:core.face_processor:AI 模型載入完成！")
+
+        except Exception as e:
+            print(f"ERROR:core.face_processor:模型初始化失敗：{e}")
+            raise RuntimeError(f"無法初始化 AI 模型：{e}") from e
+
+    def get_faces(self, image):
+        """從圖片中偵測所有臉部"""
+        try:
+            faces = self.face_analyzer.get(image)
+            if faces:
+                print(f"INFO:core.face_processor:偵測到 {len(faces)} 張臉部")
+            else:
+                print("WARNING:core.face_processor:在來源圖片中未偵測到任何臉部。")
+            return faces
+        except Exception as e:
+            print(f"ERROR:core.face_processor:臉部偵測失敗：{e}")
+            return []
+
+    def swap_face(self, source_img, target_img, face_index=0):
+        """
+        在來源和目標圖片之間交換臉部。
+        :param source_img: 來源圖片 (包含要使用的臉部)
+        :param target_img: 目標圖片 (要將臉部換到這張圖上)
+        :param face_index: 要從來源圖片中使用的臉部索引 (預設為第 0 張)
+        :return: 換臉後的圖片
+        """
+        try:
+            source_faces = self.get_faces(source_img)
+            if not source_faces:
+                raise ValueError("在來源圖片中找不到任何臉部，無法進行換臉。")
+            
+            if face_index >= len(source_faces):
+                raise ValueError(f"指定的臉部索引 {face_index} 超出範圍，來源圖片只有 {len(source_faces)} 張臉。")
+
+            target_faces = self.get_faces(target_img)
+            if not target_faces:
+                print("WARNING:core.face_processor:在目標圖片中未偵測到臉部，將直接在原圖上操作。")
+                # 如果目標沒有臉，某些模型可能允許直接返回，或我們可以選擇返回原圖
+                # 在此案例中，我們讓 swapper 決定如何處理
+
+            source_face = source_faces[face_index]
+            
+            # 執行換臉
+            # INSwapper.get() 的正確用法：get(target_img, target_face, source_face, paste_back=True)
+            # 如果目標圖片沒有臉部，我們使用 source_face 作為 target_face
+            target_face = target_faces[0] if target_faces else source_face
+            result_img = self.swapper.get(target_img, target_face, source_face, paste_back=True)
+            print("INFO:core.face_processor:換臉處理完成")
+            return result_img
+
+        except ValueError as ve:
+            print(f"ERROR:core.face_processor:{ve}")
+            raise
+        except Exception as e:
+            print(f"ERROR:core.face_processor:換臉處理失敗：{e}")
+            raise RuntimeError("換臉過程中發生未預期的錯誤") from e

requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+insightface==0.7.3
+onnxruntime==1.16.3
+opencv-python==4.8.1.78
+pillow==10.1.0
+numpy==1.24.4
+gradio==4.16.0