# 技術スタック (Tech Stack)

## 概要 (Overview)

舌領域セグメンテーション済み画像から舌色 5 分類を推定するモデルを，手元の Windows で実装し，研究室の GPU サーバで学習する．臨床データは手元 PC に置かないため，**手元は合成データでの実装確認のみ**とし，実データを触るコードはすべてサーバ上で動かす．

## 言語・実行環境 (Language & Runtime)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| 言語 | Python | TIASjudge・SmTIAS-LightSim と揃える |
| Python バージョン | 3.12（`.python-version` で固定） | 既存 2 プロジェクトと同一．サーバにも導入済み |
| パッケージマネージャ | **uv**（Astral 製） | 既存プロジェクトと同じ．`uv.lock` をコミットして再現性を担保する |
| 手元 OS | Windows 11 | 実装・合成データでの動作確認のみ（GPU なし） |
| 学習環境 | 研究室 GPU サーバ（Ubuntu 22.04・RTX A6000） | uv・Python 3.12 導入済み |

## 機械学習フレームワーク (ML Framework)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| 学習フレームワーク | **PyTorch 2.x** | 研究用途の標準．事前学習モデルの入手性が高い |
| モデル | **timm**（PyTorch Image Models） | ConvNeXt・EfficientNet・ViT 等を設定 1 行で差し替えて比較できる |
| 学習ループ | 自前で記述（Lightning 等の高水準ラッパは使わない） | 患者単位分割・クラス不均衡対策を明示的に制御したいため．規模が小さく抽象化の利得が薄い |
| データ拡張 | `torchvision.transforms.v2` | 依存を増やさない．足りなければ albumentations を後から追加する |

※ 具体的なモデル（ConvNeXt-Tiny 等）・入力解像度・学習設定は仕様設計フェーズ（`SPEC_01`）で決める．本ファイルでは土台のみ確定する．

## データ処理・評価 (Data Processing & Evaluation)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| 画像 IO | Pillow | 学習時の読み込み．軽量 |
| 数値計算 | NumPy | — |
| 舌のセグメンテーション | onnxruntime・opencv-python-headless | DeepTIAS 2.7 の検出モデル（ONNX に変換）と ResUNet（ONNX）を CPU で推論し，大津の 2 値化・連結成分などの後処理を行う（SPEC_04）．開発用の依存に `onnx`（テスト用のダミーモデルの生成）．検出モデルの変換だけは TensorFlow・tf2onnx を一時的に使う（本体の依存に入れない） |
| 評価指標 | scikit-learn | 混同行列・macro F1・クラス別 recall・患者単位の層化分割 |
| 図の出力 | matplotlib | 学習曲線・混同行列を PNG で出力する（サーバ上で描画し，画像ファイルだけ回収する） |
| ルールベース比較 | TIASjudge の `core/` ロジックを移植または参照 | ベースライン算出用．OpenCV が必要になった場合はサーバに GUI が無いため `opencv-python-headless` を使う |

## 設定と実験記録 (Configuration & Experiment Tracking)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| 設定ファイル | **YAML ＋ pydantic**（スキーマ検証） | SmTIAS-LightSim と同じ流儀．`configs/*.yaml` に実験条件を置く |
| 実験記録 | **軽量自作**（外部サービスを使わない） | `runs/<実験ID>/` に `config.yaml`・`metrics.json`・`history.csv`・`confusion_matrix.png`・チェックポイントを書き出す |
| 手元への回収 | 指標・図・ログのみ（画像・ラベルは回収しない） | 個人情報を含む可能性のあるものを持ち帰らないため |

採用理由: 依存が増えず，**外部送信がゼロ**で，臨床データ由来の情報の流出経路を作らない．実験の比較はファイルを並べるだけで足りる規模である．

## リモート実行 (Remote Execution)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| リモート実行ツール | **自作 CLI**（SmTIAS-LightSim の `sm-remote` を移植） | コード送信・ジョブ実行・結果回収・GPU 空き確認 |
| 転送方式 | tar over ssh | Windows に rsync が無いため（LightSim と同じ判断） |
| 実行 | サーバ上の tmux 内で `uv run` | 接続が切れても学習が続く |
| SSH | Windows 標準 OpenSSH | 学外からは研究室 PC を ProxyJump の踏み台にする |
| データ | サーバ常設（コードのみ毎回転送） | 一度だけコピーし，以降は再転送しない |
| 認証情報 | サーバに GitHub の認証情報を置かない | コードは常に手元から送る |

## 開発ツール (Development Tools)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| テスト | pytest | 合成データで動くテストのみ（臨床データに依存するテストは書かない） |
| lint / format | ruff | Python の標準的な選択．規約は規約整備フェーズで定める |
| CI | **使わない** | ローカルで pytest・ruff を回す．必要になれば後から GitHub Actions を追加する |
| 依存更新 | Dependabot（`uv` エコシステム） | 週 1 回．CI が無いので更新 PR はローカル検証で確認する |

## CPU / GPU の依存差 (CPU / GPU Dependencies)

**Linux（両サーバ）は PyTorch 公式の CUDA 12.6 版（cu126）**，**Windows（手元）は PyPI の CPU 版**を使う．`pyproject.toml` の `[tool.uv.sources]` で，`torch`・`torchvision` の取得元を `sys_platform == 'linux'` のときだけ cu126 インデックスに向けている．

- 経緯: 当初は PyPI の wheel をそのまま使い，Linux では CUDA 13 版（cu130）が入っていた．Newton（ドライバ 595・CUDA 13.2 対応）では動いたが，**Archimedes はドライバ 535（CUDA 12.2 まで）のため cu130 版では GPU が使えなかった**（2026-09-27 に判明）
- cu126 版は CUDA のマイナーバージョン互換により 12.2 のドライバでも動く．Archimedes で行列積・畳み込みの逆伝播まで，Newton でも CUDA の動作を確認した（torch は 2.14.0 のまま）
- **両サーバで同じ torch ビルドになる**ため，どちらのサーバで学習しても条件がそろう
- 将来 torch を上げるときは，cu126 版が提供され続けているか（`https://download.pytorch.org/whl/cu126/torch/`）と，Archimedes のドライバ（535）で動くかを確認する

## 採用しなかった選択肢 (Rejected Alternatives)

| 候補 | 却下理由 |
| --- | --- |
| Weights & Biases | 学習指標を外部サービスへ送信する．臨床データを扱う研究では審査・規約との整合確認が必要で，得られる利便性に対して手続きの負担が大きい |
| MLflow | サーバでサービスを立ててポート転送で見る運用コストが，本プロジェクトの実験数に対して過大 |
| torchvision のみ | 事前学習モデルの選択肢が狭く，「どの系統のモデルが向くか」の比較がしにくい |
| PyTorch Lightning・Keras 等の高水準ラッパ | 患者単位分割・クラス不均衡対策を明示的に制御したい．学習ループが小さいため抽象化の利得が薄い |
| GitHub Actions での CI | 現時点では 1 人開発でローカル実行で足りる．データを使うテストは CI で回せない |

## 未確定事項 (Open Items)

- モデルアーキテクチャ・入力解像度・学習設定（仕様設計フェーズで決定）
- サーバ上のデータ配置パスとディレクトリ構成（環境構築フェーズで決定）
- TIASjudge のルールベース診断を「移植」するか「別リポジトリを参照」するか（ベースライン実装時に決定）
- 学習済みモデルの配布形式（ONNX 等．モデルの見込みが立ってから決定）