ml-model-structurelisted

# ML モデル構築・API開発の標準構造 機械学習モデルの学習コードと推論API(コンテナ)を、**版ごとに自己完結する構造**で配置するための基準。 連番スクリプト (`01_…` `10_…`) をプロジェクト直下にフラットに並べると「どれがデプロイ済みの正規コードか」 「どれが旧版・ボツ実験か」が判別できなくなる。本構造はこれを **版 (version) 単位の実体ディレクトリ** で解決し、 将来 v2/v3 を champion/challenger・shadow で**並行運用**しても破綻しないようにする。 ## 設計の核 (なぜこの形か) - **版ごとに自己完結**: 各版 `vN/` は独自の `features.py` / `train/` / `inference/` を持つ。 並行運用では特徴量ロジック自体が版ごとに進化するため、全版が単一の共通ライブラリを共有する設計は破綻する。 版を跨いだ共有 (`shared/`) や `current -> vN` の symlink は**作らない**。 - **版内 feature SSoT**: 同一版の学習 (`train/`)・推論 (`inference/`)・テストが **`vN/features.py` だけ** を参照する (import / Docker COPY)。train/serve skew (学習時と推論時で特徴量計算がずれる事故) は **版内で** 保証する。 版間は独立でよい — v3 が別ロジックでも v2 に影響しない。 - **「コードの並行」と「デプロイの並行」は別レイヤー**。デプロイ並行は推論基盤側 (SageMaker production/shadow variants・multi-model endpoint 等) で解決する。本構造が担うのは**コード層の独立**のみ。 - **本番版の所在は symlink でなく明示管理**。並行運用では「今の本番」が複数になり得るため、 本番版はエンドポイント名・環境変数・README の表で管理する。 ## 目標ディレクトリ構造 モデルプロジェクト 1 つ (例: `analysis/<yyyymmdd>_<name>/`) を版で分割する。 ``` <model-project>/ # 例: analysis/20260505_oac-prediction/ ├── v1/ # 退役版: read-only アーカイブ │ ├── train/ # 旧学習コード (features.py 非依存・自己完結) │ ├── *_report.md *.csv # 旧レポート・成果物 │ └── README.md # 「read-only。再実行非想定」を明記 ├── v2/ # 現役版: 自己完結の実体 (symlink なし) │ ├── features.py # ★版内 feature SSoT (学習・推論が共有) │ ├── train/ │ │ ├── 01_build_dataset.py