Image Offline Distillation

公開画像モデルからのオフライン知識蒸留を体験するための、小さな GitHub-ready template です。

このプロジェクトはシンプルな full-stack 構成を保っています:

Backend: FastAPI + PyTorch + torchvision
Frontend: Expo / React Native Web
Container: Docker Compose
No Makefile

このリポジトリで学べること

この repository は大規模な diffusion model を train するものではありません。public image classifier を使って offline distillation pattern を学ぶためのものです:

public ImageNet teacher model
  -> run once on images
  -> save teacher logits
  -> train a small CNN student from cached logits
  -> compare teacher/student agreement

Default teacher は public ImageNet weights を持つ torchvision.models.resnet18 です。resnet50 または mobilenet_v3_large も使用できます。

Student は同じ 1000 個の ImageNet logits を output する tiny CNN です。Teacher の softened probability distribution を模倣するように train されます。

なぜ offline distillation なのか

重要な artifact は次の file です:

artifacts/teacher_logits_train.pt

この file が作成された後は、teacher model を再度 call せずに student を train できます。

Dataset modes

Dataset	Purpose
`fake`	Smoke test。実画像は不要です。
`cifar10`	CIFAR-10 を download し、ImageNet input size に resize します。
`image_folder`	`data/images` 配下にある独自の unlabeled images を使用します。

Real experiment では、images をここに置きます:

data/images/

Nested folders も使用できます。Labels は不要です。

Start

docker compose down -v
docker compose down -v
docker compose up --build

Frontend service は Docker の network_mode: host と Expo Web を使用するため、expo start --web --localhost --port 8081 に host browser からアクセスできます。これは Linux Docker environments 向けです。

Open:

Frontend: http://localhost:8081
Frontend direct Metro: http://localhost:8081
Backend:  http://localhost:8000/docs

Frontend note

Frontend は Expo-based のままです。Docker は expo export --platform web を実行し、exported web build を 0.0.0.0:19006 で serve します。これにより、web build では Expo を使い続けながら、interactive Expo dev server に伴う Docker networking problems を回避できます。

Run from API

curl -X POST http://localhost:8000/api/v1/distillation/run-all   -H 'Content-Type: application/json'   -d '{
    "teacher": "resnet18",
    "dataset": "fake",
    "samples": 128,
    "batch_size": 16,
    "epochs": 2,
    "learning_rate": 0.001,
    "temperature": 3.0,
    "device": "cpu"
  }'

Run from CLI

docker compose run --rm backend python /app/cli.py run-all   --teacher resnet18   --dataset fake   --samples 128   --batch-size 16   --epochs 2   --temperature 3.0   --device cpu

独自の image folder を使う場合:

docker compose run --rm backend python /app/cli.py run-all   --teacher resnet18   --dataset image_folder   --samples 256   --epochs 3   --device cpu

Outputs

artifacts/
├── teacher_logits_train.pt
├── teacher_cache_metadata.json
├── student_model.pt
└── report.json

report.json には次が含まれます:

teacher_student_top1_agreement
distillation_kl
student_parameters
training loss history

Tests

docker compose -f docker-compose.test.yml run --rm backend_test
docker compose -f docker-compose.yml -f docker-compose.test.yml run --rm frontend_test

Diffusion models についての notes

Stable Diffusion のような text-to-image diffusion models を distill するのは、より重い task です。通常は latent-space objectives、scheduler changes、multi-step teacher sampling、GPU-heavy training が必要になります。

この repository は最初の stage です。public image models を使って offline logits-cache pattern を学びます。これが動作した後の next step は、LCM-LoRA または teacher latent predictions を使った diffusion-specific branch を作成することです。