architecture-design

アーキテクチャ設計 - ML プロジェクトテンプレート

このスキルでは、テンプレート構造に基づく機械学習プロジェクトの標準的なコードアーキテクチャを定義します。コードを変更または拡張する際は、一貫性を保つためにこれらのパターンに従ってください。

概要

このプロジェクトは、関心事を明確に分離した、モジュール式で拡張性の高いアーキテクチャを採用しています。各モジュール（data、model、trainer、analysis）は、柔軟性を最大限に高めるため、ファクトリーとレジストリのパターンを使用して独立して構成されています。

使用する場面

次の場合にこのスキルを使用してください：

• @register_dataset が必要な新しい Dataset クラスを作成するとき
• @register_model が必要な新しい Model クラスを作成するとき
• __init__.py にファクトリーの配線を含む新しいモジュールディレクトリを作成するとき
• ML プロジェクトの構造をゼロから初期化するとき
• Augmentation、CollateFunction、Metrics などの新しいコンポーネントタイプを追加するとき

使用しない場面

次の場合はこのスキルを使用しないでください：

• 既存の関数やメソッドを変更するとき
• 既存のコードのバグを修正するとき
• ヘルパー関数やユーティリティを追加するとき
• 新しい登録可能なコンポーネントを追加せずにリファクタリングするとき
• 1 つのファイルに簡単なコード変更を行うとき
• 設定ファイルを変更するとき
• 既存のコードを読んだり理解したりするとき

重要な判断基準：タスクで @register_* デコレーターやファクトリーパターンが必要ない場合は、このスキルを使用しないでください。

コア設計パターン

ファクトリーパターン

各モジュールでは、インスタンスを動的に作成するファクトリーを使用します：

# Example from data_module/dataset/__init__.py
DATASET_FACTORY: Dict = {}

def DatasetFactory(data_name: str):
    dataset = DATASET_FACTORY.get(data_name, None)
    if dataset is None:
        print(f"{data_name} dataset is not implementation, use simple dataset")
        dataset = DATASET_FACTORY.get('simple')
    return dataset

詳しいガイダンスについては、references/factory_pattern.md を参照してください。

レジストリパターン

コンポーネントはデコレーターを介して自身を登録します：

# Example from data_module/dataset/simple_dataset.py
@register_dataset("simple")
class SimpleDataset(Dataset):
    def __init__(self, data):
        self.data = data

詳しいガイダンスについては、references/registry_pattern.md を参照してください。

自動インポートパターン

モジュールがサブモジュールを自動的に検出してインポートします：

# Example from data_module/dataset/__init__.py
models_dir = os.path.dirname(__file__)
import_modules(models_dir, "src.data_module.dataset")

詳しいガイダンスについては、references/auto_import.md を参照してください。

ディレクトリ構造

project/
├── run/
│   ├── pipeline/            # Main workflow scripts
│   │   ├── training/        # Training pipelines
│   │   ├── prepare_data/    # Data preparation pipelines
│   │   └── analysis/        # Analysis pipelines
│   └── conf/                # Hydra configuration files
│       ├── training/        # Training configs
│       ├── dataset/         # Dataset configs
│       ├── model/           # Model configs
│       ├── prepare_data/    # Data prep configs
│       └── analysis/        # Analysis configs
│
├── src/
│   ├── data_module/         # Data processing module
│   │   ├── dataset/         # Dataset implementations
│   │   ├── augmentation/    # Data augmentation
│   │   ├── collate_fn/      # Collate functions
│   │   ├── compute_metrics/ # Metrics computation
│   │   ├── prepare_data/    # Data preparation logic
│   │   ├── data_func/       # Data utility functions
│   │   └── utils.py         # Module-specific utilities
│   │
│   ├── model_module/        # Model implementations
│   │   ├── brain_decoder/   # Brain decoder models
│   │   └── model/           # Alternative model location
│   │
│   ├── trainer_module/      # Training logic
│   ├── analysis_module/     # Analysis and evaluation
│   ├── llm/                 # LLM-related code
│   └── utils/               # Shared utilities
│
├── data/
│   ├── raw/                 # Original, immutable data
│   ├── processed/           # Cleaned, transformed data
│   └── external/            # Third-party data
│
├── outputs/
│   ├── logs/                # Training and evaluation logs
│   ├── checkpoints/         # Model checkpoints
│   ├── tables/              # Result tables
│   └── figures/             # Plots and visualizations
│
├── pyproject.toml           # Project configuration
├── uv.lock                  # Dependency lock file
├── TODO.md                  # Task tracking
├── README.md                # Project documentation
└── .gitignore               # Git ignore rules

ファイルの説明を含む詳しいディレクトリ構造については、references/structure.md を参照してください。

モジュール構成

新しい Dataset の作成

新しいデータセットを追加する場合：

1. src/data_module/dataset/ にファイルを作成します
2. @register_dataset("name") デコレーターを使用します
3. torch.utils.data.Dataset を継承します
4. __init__、__len__、__getitem__ を実装します

from torch.utils.data import Dataset
from typing import Dict
import torch
from src.data_module.dataset import register_dataset

@register_dataset("custom")
class CustomDataset(Dataset):
    def __init__(self, data):
        self.data = data

    def __len__(self):
        return len(self.data)

    def __getitem__(self, i: int) -> Dict[str, torch.Tensor]:
        return self.data[i]

新しい Model の作成

重要：Model では設定駆動パターンを使用します

新しいモデルを追加する場合：

1. src/model_module/model/ または適切なモジュールのサブディレクトリにファイルを作成します
2. @register_model('ModelName') デコレーターを使用します
3. __init__ が受け取るのは cfg パラメーターのみです。すべてのハイパーパラメーターは設定から取得します
4. forward() は辞書を返します：{"loss": loss, "labels": labels, "logits": logits}
5. self.training を使用して、トレーニングモードと推論モードを処理します

from src.model_module.brain_decoder import register_model

@register_model('MyModel')
class MyModel(nn.Module):
    def __init__(self, cfg):
        super().__init__()
        self.cfg = cfg
        self.task = cfg.dataset.task

        # ALL parameters from cfg
        self.hidden_dim = cfg.model.hidden_dim
        self.output_dim = cfg.dataset.target_size[cfg.dataset.task]

    def forward(self, x, labels=None, **kwargs):
        if self.training:
            # Training logic
            pass
        else:
            # Inference logic
            pass

        return {"loss": loss, "labels": labels, "logits": logits}

データ拡張の追加

データ拡張を追加する場合：

1. src/data_module/augmentation/ にファイルを作成します
2. 変換関数を実装します
3. 必要に応じてファクトリーに登録します

コードスタイルのガイドライン

包括的なスタイルガイドラインについては、references/code_style.md を参照してください。

主な原則：

• 関数シグネチャには必ず型ヒントを使用します
• インポート順序に従います：標準ライブラリ → サードパーティ → ローカル
• モジュールの __init__.py ファイルにはファクトリー／レジストリのロジックを記述します
• Model クラスは設定駆動にする必要があります

設定管理

このプロジェクトでは設定管理に Hydra を使用します：

• 設定ファイルは run/conf/ にモジュールごとに整理します
• 各ステージ（トレーニング、分析）には独自の設定構造があります
• すべての設定に YAML ファイルを使用します

このプロジェクトで作業する場合

コードを変更する前に

1. 該当モジュールのファクトリー／レジストリパターンを読みます
2. 一貫性を保つため、既存の実装を確認します
3. 確立されたディレクトリ構造に従います
4. 新しいコンポーネントには登録デコレーターを使用します

新機能の追加

1. 機能が属するモジュールを特定します
2. 類似の機能が存在するか確認します
3. 新しいコンポーネントタイプを作成する場合は、ファクトリー／レジストリパターンに従います
4. 必要に応じて設定ファイルを追加します
5. ドキュメントを更新します

コードレビューチェックリスト

• ファクトリー／レジストリパターンを適切に使用している
• モジュールのディレクトリ構成に従っている
• 適切な型注釈が付いている
• インポートの順序が正しい
• 登録デコレーターを使用している
• 必要に応じて設定ファイルを追加している

追加リソース

参考ファイル

詳細については、以下を参照してください。

• references/structure.md - ファイルの説明を含む詳細なディレクトリ構成
• references/factory_pattern.md - ファクトリーパターンの詳細な説明
• references/registry_pattern.md - レジストリパターンの詳細な説明
• references/auto_import.md - 自動インポートパターンの詳細な説明
• references/code_style.md - 包括的なコードスタイルガイドライン

サンプルファイル

examples/ にある動作するサンプル：

• examples/custom_dataset.py - カスタムデータセットの実装
• examples/custom_model.py - カスタムモデルの実装
• examples/augmentation_example.py - データ拡張のサンプル
• examples/config_example.yaml - 設定ファイルのサンプル
• examples/pipeline_example.sh - パイプラインスクリプトのサンプル