技術スタック (Tech Stack)

概要 (Overview)

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

項目	採用	備考
言語	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 導入済み

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

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

項目	採用	備考
画像 IO	Pillow	学習時の読み込み．軽量
数値計算	NumPy	—
評価指標	scikit-learn	混同行列・macro F1・クラス別 recall・患者単位の層化分割
図の出力	matplotlib	学習曲線・混同行列を PNG で出力する（サーバ上で描画し，画像ファイルだけ回収する）
ルールベース比較	TIASjudge の `core/` ロジックを移植または参照	ベースライン算出用．OpenCV が必要になった場合はサーバに GUI が無いため `opencv-python-headless` を使う

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

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

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

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

torch を PyPI からそのまま依存に入れると，Linux では CUDA 付きの wheel，Windows では CPU 版の wheel が選ばれるため，同一の pyproject.toml で「手元 = CPU，サーバ = GPU」が成立する見込みである．

サーバでの初回 uv sync 後に torch.cuda.is_available() が True になることを確認する（環境構築手順に含める）
想定どおりにならない場合は PyTorch 公式インデックスを [tool.uv.sources] で指定する方式に切り替える

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