diff --git a/.kiro/steering/product.md b/.kiro/steering/product.md new file mode 100644 index 0000000..bd1d3cd --- /dev/null +++ b/.kiro/steering/product.md @@ -0,0 +1,25 @@ +# Product Overview + +nanochat は、単一の 8xH100 GPU ノードで約 $100 ~ $1000 の予算内で動作する、フルスタックの ChatGPT クローンです。Andrej Karpathy 氏による LLM101n コースのキャップストーンプロジェクトとして設計されています。 + +## Core Capabilities + +1. **End-to-End LLM パイプライン**: トークナイザ学習 → 事前学習 → 中間学習 → SFT → RL → 推論 → Web UI まで一貫して実行 +2. **ミニマル・ハッカブル**: 依存関係を最小限に抑え、単一のコードベースで全プロセスを実現 +3. **スケーラブル**: $100 (4時間) から $1000 (41時間) まで、予算に応じたモデルサイズ選択 +4. **評価レポート**: 自動生成される report.md で CORE, ARC, GSM8K, HumanEval, MMLU 等のベンチマーク結果を確認可能 + +## Target Use Cases + +- LLM の仕組みを学習したい研究者・学生 +- 自分だけの ChatGPT クローンを一から構築したいエンジニア +- マイクロモデルの限界と可能性を探求する実験 + +## Value Proposition + +- **完全な所有権**: 全プロセスを自分でコントロール・カスタマイズ可能 +- **教育的価値**: 複雑なフレームワークなしで LLM の全体像を理解 +- **実践的**: 実際に動作する ChatGPT 風 Web UI で対話可能 + +--- +_Focus on patterns and purpose, not exhaustive feature lists_ diff --git a/.kiro/steering/structure.md b/.kiro/steering/structure.md new file mode 100644 index 0000000..aeaac79 --- /dev/null +++ b/.kiro/steering/structure.md @@ -0,0 +1,80 @@ +# Project Structure + +## Organization Philosophy + +フラットで見通しの良い構造。機能別ディレクトリではなく、役割別にシンプルに分割。「フレームワーク」ではなく「ベースライン実装」として設計。 + +## Directory Patterns + +### nanochat/ (コアライブラリ) +**Location**: `/nanochat/` +**Purpose**: 学習・推論のコアロジック +**Examples**: +- `gpt.py` - GPT モデル定義 (Transformer アーキテクチャ) +- `tokenizer.py` - トークナイザ抽象化 +- `dataloader.py` - データローディング +- `engine.py` - 学習エンジン +- `muon.py`, `adamw.py` - オプティマイザ + +### scripts/ (実行スクリプト) +**Location**: `/scripts/` +**Purpose**: 学習・評価・推論の実行エントリーポイント +**Naming**: `{stage}_{action}.py` パターン +- `tok_train.py`, `tok_eval.py` - トークナイザ +- `base_train.py`, `base_eval.py`, `base_loss.py` - 事前学習 +- `mid_train.py` - 中間学習 +- `chat_sft.py`, `chat_rl.py`, `chat_eval.py` - ファインチューニング +- `chat_web.py`, `chat_cli.py` - 推論インターフェース + +### tasks/ (評価タスク) +**Location**: `/tasks/` +**Purpose**: ベンチマーク評価の実装 +**Examples**: `arc.py`, `gsm8k.py`, `humaneval.py`, `mmlu.py` + +### rustbpe/ (Rust トークナイザ) +**Location**: `/rustbpe/` +**Purpose**: 高速 BPE トークナイザ (Rust + PyO3) +**Structure**: Cargo プロジェクト形式 + +### dev/ (開発用) +**Location**: `/dev/` +**Purpose**: 開発用スクリプト、リソース + +### tests/ (テスト) +**Location**: `/tests/` +**Purpose**: pytest テスト + +## Naming Conventions + +- **Files**: snake_case (`chat_web.py`, `base_train.py`) +- **Classes**: PascalCase (`GPTConfig`, `CausalSelfAttention`) +- **Functions**: snake_case (`apply_rotary_emb`, `norm`) +- **Constants**: UPPER_SNAKE_CASE (`SPECIAL_TOKENS`, `SPLIT_PATTERN`) + +## Import Organization + +```python +# 標準ライブラリ +import os +import math + +# サードパーティ +import torch +import torch.nn as nn + +# プロジェクト内 +from nanochat.common import get_dist_info, print0 +from nanochat.gpt import GPT, GPTConfig +``` + +**Path Aliases**: なし (明示的な相対/絶対パスを使用) + +## Code Organization Principles + +1. **1ファイル1責務**: 各ファイルは単一の明確な目的を持つ +2. **設定より規約**: 設定ファイルの山ではなく、コード内で直接設定 +3. **最小限の抽象化**: 必要以上の抽象化レイヤーを作らない +4. **成果物の管理**: 中間ファイルは `~/.cache/nanochat/` に配置 + +--- +_Document patterns, not file trees. New files following patterns shouldn't require updates_ diff --git a/.kiro/steering/tech.md b/.kiro/steering/tech.md new file mode 100644 index 0000000..452d1a6 --- /dev/null +++ b/.kiro/steering/tech.md @@ -0,0 +1,62 @@ +# Technology Stack + +## Architecture + +単一ノード分散学習を前提とした PyTorch ベースの LLM 実装。シンプルさと可読性を重視し、巨大な設定オブジェクトやモデルファクトリは使用しない。 + +## Core Technologies + +- **Language**: Python 3.10+, Rust (トークナイザ) +- **Framework**: PyTorch 2.8+ (torchrun による分散学習) +- **Web**: FastAPI + Uvicorn (推論 API) +- **Build**: uv (パッケージ管理), maturin (Rust-Python バインディング) + +## Key Libraries + +- **datasets**: HuggingFace データセット +- **tiktoken / tokenizers**: トークナイザ推論 +- **rustbpe (内製)**: 高速 BPE トークナイザ学習 (Rust + PyO3) +- **wandb**: 実験ログ (オプション) + +## Development Standards + +### Type Safety +- 型ヒント推奨、厳密な型チェックは課さない +- シンプルさを優先 + +### Code Quality +- 依存関係最小限 (dependency-lite) +- if-then-else の山を避ける +- 巨大な設定オブジェクトを作らない + +### Testing +- pytest (基本的なテスト、特にトークナイザ) +- `python -m pytest tests/test_rustbpe.py -v -s` + +## Development Environment + +### Required Tools +- Python 3.10+ +- Rust (rustbpe ビルド用) +- uv (パッケージマネージャ) +- CUDA 対応 GPU (本番環境) + +### Common Commands +```bash +# Setup: uv sync --extra gpu && source .venv/bin/activate +# Full run: bash speedrun.sh +# Web UI: python -m scripts.chat_web +# Test: python -m pytest tests/ -v -s +``` + +## Key Technical Decisions + +1. **RoPE (Rotary Position Embedding)**: 絶対位置埋め込みの代わりに回転位置埋め込みを使用 +2. **QK Norm**: Attention の安定化のため Query/Key に正規化を適用 +3. **ReLU² Activation**: MLP で ReLU² を使用 +4. **Multi-Query Attention (MQA)**: 推論効率のための KV ヘッド共有 +5. **Untied Embeddings**: トークン埋め込みと lm_head は重みを共有しない +6. **No Bias**: 線形層にバイアスなし + +--- +_Document standards and patterns, not every dependency_