Upload README.md

README.md

@@ -1,112 +1,139 @@
-# 画像分類デモ — 2015 vs 2025 実装比較
+---
+title: Image Classification 2015 vs 2025
+emoji: 🔍
+colorFrom: green
+colorTo: gray
+sdk: gradio
+sdk_version: 4.36.0
+app_file: app.py
+pinned: false
+python_version: "3.10"
+suggested_hardware: cpu-basic
+---
+
+# Image Classification Demo — 2015 vs 2025
+**画像分類デモ — 2015 vs 2025 実装比較**
 
-同じ機能（画像 → カテゴリ予測）を **2 世代の実装**で並べて見比べるための教材・デモアプリです。
+A Gradio app that demonstrates how dramatically machine learning implementation
+complexity has changed over a decade — using the same task (image → category
+prediction) as a benchmark.
 
-推論は 2025 実装（HuggingFace ViT）が担い、2015 実装（Theano CNN）は
-実装コードを参照表示します。
+同じタスク（画像 → カテゴリ予測）を使って、10年間で機械学習の実装コストが
+いかに変化したかを比較する Gradio デモアプリです。
 
 ---
 
-## 実装比較サマリー
+## What This App Does / このアプリについて
 
-| 項目 | 2015（Theano + NumPy） | 2025（HuggingFace Transformers） |
-|---|---|---|
-| **実装行数** | 約 130 行 | 5 行 |
-| **モデル** | 手書き CNN | ViT-Base（事前学習済） |
-| **前処理** | 手動実装（正規化・CHW変換） | 自動 |
-| **学習** | SGD・ループ・勾配計算を手動記述 | 不要（Fine-tuning は別途） |
-| **精度目安** | ~70 % (CIFAR-10) | ~81 % (ImageNet) |
-| **コンパイル** | Theano グラフ最適化（数十秒） | 不要 |
-| **Python 対応** | Python 3.8 以下 | Python 3.10〜3.12 |
+Upload any image and get a top-5 category prediction from a pre-trained
+Vision Transformer (ViT). Alongside the result, the app shows the code
+required to build the same classifier in **2015 (Theano + NumPy, ~130 lines)**
+versus **2025 (HuggingFace Transformers, 5 lines)**.
 
-> 約 **26 倍**のコード量の差で、同じ推論機能を実現できるようになりました。
+画像をアップロードすると、事前学習済み ViT による上位5件の予測結果を表示します。
+あわせて、**2015年（Theano + NumPy、約130行）** と **2025年（HuggingFace Transformers、5行）**
+の実装コードを左右に並べて比較します。
 
 ---
 
-## ファイル構成
+## Implementation Comparison / 実装比較
 
-```
-imgclf_app/
-├── app.py            # Gradio Web アプリ（エントリポイント）
-├── model_2025.py     # 2025 実装：HuggingFace pipeline（5 行）
-├── model_2015.py     # 2015 実装：Theano CNN（参照用ドキュメント）
-├── requirements.txt  # 依存パッケージ
-└── README.md         # このファイル
-```
+| Item / 項目 | 2015 (Theano + NumPy) | 2025 (HuggingFace) |
+|---|---|---|
+| **Lines of code** / 実装行数 | ~130 lines | 5 lines |
+| **Model** / モデル | Hand-written CNN / 手書き CNN | ViT-Base (pre-trained) / 事前学習済み |
+| **Preprocessing** / 前処理 | Manual / 手動実装 | Automatic / 自動 |
+| **Training** / 学習 | SGD written by hand / 手動記述 | Not required / 不要 |
+| **Accuracy** / 精度目安 | ~70 % (CIFAR-10) | ~81 % (ImageNet) |
+| **Compile step** / コンパイル | Tens of seconds / 数十秒 | Not required / 不要 |
 
 ---
 
-## セットアップ
-
-### 1. リポジトリを取得
+## File Structure / ファイル構成
 
-```bash
-git clone <this-repo>
-cd imgclf_app
 ```
-
-### 2. 仮想環境を作成して依存をインストール
-
-```bash
-python -m venv .venv
-source .venv/bin/activate        # Windows: .venv\Scripts\activate
-pip install -r requirements.txt
+.
+├── app.py            # Gradio app — entry point / エントリポイント
+├── model_2025.py     # 2025 implementation: HuggingFace pipeline (5 lines)
+│                     # 2025 実装：HuggingFace pipeline（5 行）
+├── model_2015.py     # 2015 implementation: Theano CNN (reference / 参照用)
+├── requirements.txt  # Dependencies / 依存パッケージ
+└── README.md         # This file / このファイル
 ```
 
-> **GPU を使う場合**（任意）：`torch` を CUDA 版に差し替えると推論が高速になります。
-> ```bash
-> pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
-> ```
+---
 
-### 3. 起動
+## Running Locally / ローカルでの起動
 
 ```bash
+# 1. Clone / クローン
+git clone https://huggingface.co/spaces/<your-username>/image-classification-2015-vs-2025
+cd image-classification-2015-vs-2025
+
+# 2. Install dependencies / 依存をインストール
+pip install -r requirements.txt
+
+# 3. Launch / 起動
 python app.py
+# → http://localhost:7860
 ```
 
-ブラウザで `http://localhost:7860` を開きます。
-初回起動時に HuggingFace Hub から ViT モデル（約 330 MB）がダウンロードされます。
+> **Note / 注意:** On first launch, the ViT model (~330 MB) is downloaded from
+> Hugging Face Hub automatically and cached in `~/.cache/huggingface/`.
+>
+> 初回起動時に ViT モデル（約330 MB）が HuggingFace Hub から自動ダウンロードされ、
+> `~/.cache/huggingface/` にキャッシュされます。
 
 ---
 
-## 使い方
+## Hardware / 動作環境
+
+This Space runs on **CPU Basic** (free tier — no GPU required).
+ViT-Base inference on CPU typically takes **2–5 seconds** per image.
+
+このSpaceは **CPU Basic**（無料枠）で動作します。GPU は不要です。
+CPU 上での ViT-Base 推論は 1 枚あたり **2〜5秒** 程度です。
 
-1. 左側の画像アップロードエリアに画像をドロップ（または選択）
-2. **▶ 分類を実行** をクリック（または画像変更で自動実行）
-3. 予測結果（カテゴリ名とスコア上位 5 件）が表示される
-4. 右側で 2015 / 2025 のコードを並べて確認
+| Resource | Spec |
+|---|---|
+| Hardware | CPU Basic (2 vCPU / 16 GB RAM) |
+| GPU | None / なし |
+| Storage | Ephemeral (model cached via HF Hub) |
 
 ---
 
-## 2015 実装（`model_2015.py`）について
+## About the 2015 Implementation / 2015年実装について
 
-`model_2015.py` は **Python 3.8 + Theano 1.0** 環境でのみ動作します。
-現在は Theano の開発が停止されており、Python 3.9 以降では動作しません。
-このファイルは**実装コストの比較・教育目的**のドキュメントとして収録しています。
+`model_2015.py` is **reference documentation only** — it requires Python 3.8
+and Theano 1.0, which are no longer maintained and incompatible with Python 3.9+.
+The file is included to illustrate the implementation burden of the era.
 
-2015 年当時は以下をすべて手書きで実装する必要がありました。
+`model_2015.py` は **参照用ドキュメント** です。Python 3.8 と Theano 1.0 が必要で、
+現在はメンテナンスされておらず Python 3.9 以降では動作しません。
+当時の実装コストを示す資料として収録しています。
 
-- 重みの初期化（各層の `W`, `b`）
-- シンボルグラフ（`conv2d` → `pool` → `flatten` → `softmax`）
-- 損失関数・勾配計算・SGD 更新則
-- Theano 関数のコンパイル
-- 画像前処理（正規化・次元変換）
-- 学習ループ（バッチ分割・epoch 管理）
-- モデルの保存・読み込み
+What had to be hand-written in 2015 / 2015年当時に手書きが必要だったもの:
+- Weight initialization for each layer / 各層の重み初期化
+- Symbolic computation graph (conv → pool → softmax) / シンボルグラフ
+- Loss function, gradient computation, SGD update rules / 損失・勾配・SGD更新則
+- Theano function compilation / Theano 関数のコンパイル
+- Image preprocessing (normalization, CHW transpose) / 画像前処理
+- Training loop with manual batch splitting / 手動バッチ分割・学習ループ
+- Model save / load / モデルの保存・読み込み
 
 ---
 
-## 技術スタック
+## Tech Stack / 技術スタック
 
-| ライブラリ | バージョン | 用途 |
+| Library | Version | Purpose / 用途 |
 |---|---|---|
-| `transformers` | ≥ 4.40 | ViT モデル・pipeline |
-| `torch` | ≥ 2.2 | 推論バックエンド |
-| `Pillow` | ≥ 10.0 | 画像入出力 |
+| `transformers` | ≥ 4.40 | ViT model & pipeline |
+| `torch` | ≥ 2.2 | Inference backend / 推論バックエンド |
+| `Pillow` | ≥ 10.0 | Image I/O / 画像入出力 |
 | `gradio` | ≥ 4.36 | Web UI |
 
 ---
 
-## ライセンス
+## License / ライセンス
 
 MIT