autoresearch
autoresearch 総合ガイド：AIエージェントによる自律型機械学習研究
1. はじめに
1.1 autoresearchとは
autoresearchは、Andrej Karpathy（OpenAI共同創設者、元Tesla AI ディレクター）が2025年に公開した、AIエージェントによる自律的な機械学習研究フレームワークである。GitHubで68,000以上のスターを獲得し、AI研究の自動化における画期的なプロジェクトとして広く認知されている。
このプロジェクトの核心的なアイデアは極めてシンプルである：
「AIエージェントに小規模だが実際のLLM訓練環境を与え、一晩中自律的に実験させる」
研究者が夜間にシステムを起動し、翌朝には実験ログと（理想的には）改善されたモデルが手元に残るという、「寝ている間にAIが研究を進める」というビジョンを実現している。
1.2 登場の背景
従来の機械学習研究では、以下のようなサイクルが一般的であった：
- 研究者が仮説を立てる
- コードを手動で修正する
- 実験を実行し、結果を待つ
- 結果を分析し、次の仮説を考える
- 1-4を繰り返す
このプロセスには多大な人的労力と時間がかかり、特にハイパーパラメータの探索やアーキテクチャの微調整といった反復的な作業は、研究者の創造的な時間を圧迫していた。
autoresearchは、このサイクル全体をAIエージェントに委任することで、以下の革新を実現した：
- 24時間無休の実験: 研究者の労働時間に依存しない
- 系統的な探索: 人間のバイアスに左右されない実験設計
- 即座の判断: 結果に基づく自動的な取捨選択
- 完全な記録: すべての実験がログとして残る
1.3 オープンソースと哲学
autoresearchはMITライセンスで公開されており、誰でも自由に利用・改変・再配布が可能である。Karpathyの教育的な姿勢が反映されており、コードは意図的にシンプルに保たれている。この「教育と実用の両立」という設計哲学は、彼の過去のプロジェクト（nanoGPT、minbpe等）と一貫している。
1.4 本記事の構成
本記事では、autoresearchの全容を以下の構成で解説する：
| セクション | 内容 |
|---|---|
| 第2章 | 設計思想とアーキテクチャの全体像 |
| 第3章 | コアファイルの詳細解説 |
| 第4章 | 実験ループの仕組み |
| 第5章 | GPTモデルアーキテクチャ |
| 第6章 | 最適化戦略（Muon + AdamW） |
| 第7章 | 評価指標とデータパイプライン |
| 第8章 | セットアップと実行方法 |
| 第9章 | program.mdによるエージェント制御 |
| 第10章 | 派生プロジェクト（エコシステム） |
| 第11章 | AutoResearchClaw（論文自動生成） |
| 第12章 | Codex Autoresearch |
| 第13章 | MLXポート（Apple Silicon対応） |
| 第14章 | 応用シナリオとベストプラクティス |
| 第15章 | まとめと今後の展望 |
2. 設計思想とアーキテクチャの全体像
2.1 設計原則
autoresearchは、以下の5つの設計原則に基づいて構築されている：
原則1：単一の変更対象（Single Modification Point）
AIエージェントが変更できるファイルはtrain.pyのみに限定されている。この制約により：
- 差分（diff）が常にレビュー可能な規模に収まる
- 予期しない副作用が最小化される
- 実験の再現性が保証される
変更可能: train.py （モデル、最適化、ハイパーパラメータ）
変更不可: prepare.py （データ準備、評価関数、ユーティリティ）
人間が編集: program.md （エージェントへの指示）
原則2：固定時間予算（Fixed Time Budget）
すべての実験は厳密に5分間で実行される。ハードウェアの性能差はモデルサイズやバッチサイズの調整で吸収し、実行時間は一定に保つ。
TIME_BUDGET = 300 # 秒（5分間）
1時間あたり約12実験 = 一晩（8時間）で約96実験
この設計により：
- 実験同士の公平な比較が可能
- 暴走した実験が他のリソースを消費しない
- 計画的な実験スケジュールが立てやすい
原則3：単一指標での最適化
最適化対象は**val_bpb（validation bits per byte）**の一点に絞られている。複数の指標間のトレードオフをエージェントに判断させるのではなく、明確な単一目標を与えることで：
- エージェントの判断が単純化される
- 改善の有無が明確に判定できる
- 語彙サイズに依存しない公平な比較が可能
原則4：自己完結型（Self-Contained）
依存関係はPyTorchと最小限のライブラリのみ。単一GPU、単一ファイル、単一指標。複雑なインフラストラクチャは不要。
原則5：シンプリシティ優先
コードの複雑化を伴う限界的な改善よりも、コードの削除による同等の結果が優先される。これはエージェントにも人間にも共通する原則として、program.mdに明示されている。
2.2 全体アーキテクチャ
┌─────────────────────────────────────────────────────────┐
│ autoresearch システム │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ program.md │ │ train.py │ │ prepare.py │ │
│ │ (指示書) │ │ (実験対象) │ │ (固定基盤) │ │
│ │ │ │ │ │ │ │
│ │ ・研究方針 │───▶│ ・GPTモデル │◀───│ ・データ準備 │ │
│ │ ・制約条件 │ │ ・最適化器 │ │ ・トークナイザ│ │
│ │ ・実験手順 │ │ ・訓練ループ │ │ ・評価関数 │ │
│ │ ・記録規則 │ │ ・ハイパラ │ │ ・データローダ│ │
│ └─────────────┘ └──────┬───────┘ └─────────────┘ │
│ │ │
│ ┌──────▼───────┐ │
│ │ AIエージェント │ │
│ │ (Claude/Codex) │ │
│ │ │ │
│ │ 1. コード変更 │ │
│ │ 2. 実験実行 │ │
│ │ 3. 結果評価 │ │
│ │ 4. 取捨選択 │ │
│ │ 5. 繰り返し │ │
│ └──────┬───────┘ │
│ │ │
│ ┌──────▼───────┐ │
│ │ results.tsv │ │
│ │ (実験記録) │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
2.3 Gitベースの実験管理
autoresearchは、Gitを実験管理の中核として活用する：
main ─────────────────────────────────────────
\
autoresearch/<tag> ──●──●──●──●──●──
↑ ↑ ↑ ↑ ↑
実験 実験 実験 実験 実験
#1 #2 #3 #4 #5
✓ ✗ ✓ ✓ ✗
(保持)(復元)(保持)(保持)(復元)
- 各実験はコミットとして記録される
- 改善が見られた実験は保持（コミットを維持）
- 改善が見られなかった実験はリバート（前のコミットに復元）
- すべての実験結果は
results.tsvに記録される（リバートされた実験も含む）
2.4 時間配分の設計
一つの実験サイクルにおける典型的な時間配分：
| フェーズ | 所要時間 | 内容 |
|---|---|---|
| コード分析 | 10-30秒 | エージェントが現在のtrain.pyを読み解く |
| 変更実施 | 10-30秒 | エージェントがコードを修正 |
| 実験実行 | 300秒（固定） | 訓練の実行とメトリクス計測 |
| 結果評価 | 5-10秒 | ログからメトリクスを抽出・評価 |
| 記録・判断 | 5-10秒 | results.tsvへの記録、Git操作 |
| 合計 | 約6-7分 | 1時間あたり約9-10実験 |
3. コアファイルの詳細解説
3.1 prepare.py：固定基盤
prepare.pyはエージェントが一切変更できない「聖域」であり、データの準備から評価まで、実験の基盤となるすべての機能を提供する。
3.1.1 定数定義
MAX_SEQ_LEN = 2048 # 最大シーケンス長
TIME_BUDGET = 300 # 実験時間（秒）
VOCAB_SIZE = 8192 # 語彙サイズ（BPEトークン数）
これらの定数は全実験で共通であり、公平な比較を保証する。
3.1.2 データダウンロード
def download_single_shard(args):
"""Hugging Faceからparquetシャードをダウンロード"""
# リトライロジック付き
# ダウンロード済みシャードのスキップ
pass
def download_data():
"""マルチプロセスでの並列ダウンロード"""
# 既存ダウンロードの追跡で重複回避
pass
データセットはHugging Face上のparquetフォーマットで提供され、マルチプロセスで効率的にダウンロードされる。
3.1.3 トークナイザ訓練
def train_tokenizer():
"""BPEトークナイザの訓練"""
# rustbpeライブラリを使用
# 語彙サイズ: 8,192トークン
# GPT-4スタイルのBPE分割パターン
# tiktokenフォーマットに変換
# トークンIDからバイト長へのルックアップテーブル構築
pass
トークナイザは8,192トークンという比較的小さな語彙サイズを使用する。これは実験の高速性を優先した設計である。
3.1.4 データローダ
def make_dataloader():
"""Best-fitパッキングによるデータローダ"""
# ドキュメントをBOSトークンで連結
# パディングを最小化
# 100%のバッチ利用率を実現
pass
Best-fitパッキングは、autoresearchの重要な技術的工夫の一つである。通常のデータローダでは、異なる長さの文書をバッチ化する際にパディング（余白埋め）が発生し、計算資源が無駄になる。Best-fitパッキングでは：
- 文書をBOS（Begin of Sequence）トークンで連結
- シーケンス長（2048トークン）に収まるよう最適に詰め込む
- パディングなしで100%の利用率を達成
3.1.5 評価関数
def evaluate_bpb(model, dataloader):
"""Bits Per Byte (BPB) の計算"""
# nats_per_byte = total_loss / total_bytes
# bpb = nats_per_byte / log(2)
# 特殊トークンは計算から除外
return val_bpb
BPB（Bits Per Byte） は語彙サイズに依存しない評価指標であり、異なるトークナイザやアーキテクチャ間での公平な比較を可能にする。計算式は以下の通り：
val_bpb = (合計損失 / 合計バイト数) / ln(2)
3.2 train.py：実験の中心
train.pyはエージェントが自由に修正できる唯一のファイルであり、以下のコンポーネントを含む：
3.2.1 モデル設定
@dataclass
class GPTConfig:
max_seq_len: int = 2048 # 最大シーケンス長
vocab_size: int = 8192 # 語彙サイズ
n_layer: int = 8 # Transformerレイヤー数
n_head: int = 8 # アテンションヘッド数
n_kv_head: int = 4 # KVヘッド数（GQA）
n_embd: int = 512 # 埋め込み次元
window_pattern: str = "SSSL" # ウィンドウパターン
3.2.2 訓練ハイパーパラメータ
DEPTH = 8 # Transformerレイヤー数
ASPECT_RATIO = 64 # model_dim = depth × aspect_ratio
TOTAL_BATCH_SIZE = 2**19 # ~524Kトークン/ステップ
EMBEDDING_LR = 0.6 # 埋め込み層学習率
MATRIX_LR = 0.04 # 行列パラメータ学習率
WARMDOWN_RATIO = 0.5 # 学習率スケジュール終盤比率
3.2.3 訓練ループの構造
# 疑似コード
for step in range(total_steps):
# 1. 勾配累積
for micro_step in range(grad_accum_steps):
batch = next(dataloader)
with torch.autocast('cuda', dtype=torch.bfloat16):
loss = model(batch)
loss.backward()
# 2. 学習率スケジューリング
lr = get_learning_rate(step, total_steps)
optimizer.step(lr)
optimizer.zero_grad()
# 3. メトリクス記録
log_metrics(step, loss, mfu)
# 4. 時間制約チェック
if elapsed > TIME_BUDGET:
break
# 5. 最終評価
val_bpb = evaluate_bpb(model, val_dataloader)
print(f"val_bpb: {val_bpb}")
print(f"peak_vram_mb: {peak_vram}")
3.3 program.md：エージェントへの指示書
program.mdは人間がエージェントに対して研究方針を伝えるためのMarkdownファイルである。
3.3.1 program.mdの構造
# 研究プログラム
## 目標
val_bpbを最小化する
## 制約
- train.pyのみ変更可能
- prepare.pyは変更不可
- 新しい依存パッケージのインストール不可
- evaluate_bpb関数の改変不可
## 実験手順
1. autoresearch/<tag>ブランチを作成
2. キャッシュデータの存在を確認
3. results.tsvヘッダを初期化
4. 以下を繰り返す：
a. train.pyを修正
b. uv run train.py > run.log 2>&1 を実行
c. ログからメトリクスを抽出
d. results.tsvに記録
e. 改善ならコミット、そうでなければリバート
## 出力メトリクス
- val_bpb: 検証BPB（最適化対象）
- peak_vram_mb: ピークVRAM使用量
- training_seconds: 訓練時間
- num_params_M: パラメータ数（百万単位）
- mfu_percent: MFU（Model Flops Utilization）
## 運用原則
- 継続の許可を求めない（完全自律）
- シンプルさを優先する
- 限界的な改善のためのコード複雑化を避ける
4. 実験ループの仕組み
4.1 実験ライフサイクル
autoresearchの核心は「修正→実行→評価→判断」の自律的なループである。このセクションでは、各フェーズの詳細を解説する。
フェーズ1：初期化
# 1. 実験ブランチの作成
git checkout -b autoresearch/experiment-v1
# 2. キャッシュデータの確認
ls ~/.cache/autoresearch/
# data/ - ダウンロード済みデータシャード
# tokenizer/ - 訓練済みBPEトークナイザ
# 3. results.tsvの初期化
echo "commit\tval_bpb\tpeak_vram_mb\ttraining_seconds\tnum_params_M\tmfu_percent\tstatus\tdescription" > results.tsv
フェーズ2：コード修正
エージェントはtrain.pyを分析し、改善の仮説に基づいてコードを変更する。典型的な変更例：
# 例1: レイヤー数の変更
DEPTH = 8 → DEPTH = 10
# 例2: アテンションヘッドの構成変更
n_head: int = 8 → n_head: int = 12
n_kv_head: int = 4 → n_kv_head: int = 4 # GQA比率の変更
# 例3: 学習率の調整
EMBEDDING_LR = 0.6 → EMBEDDING_LR = 0.45
MATRIX_LR = 0.04 → MATRIX_LR = 0.035
# 例4: ウィンドウパターンの変更
window_pattern: str = "SSSL" → window_pattern: str = "SSSSL"
# 例5: モデルアーキテクチャの根本的変更
# RoPEパラメータの調整、ゲーティング機構の追加など
フェーズ3：実験実行
uv run train.py > run.log 2>&1
実行中の出力例：
step 1 | loss 9.3142 | lr 0.0001 | mfu 42.3% | 1234ms
step 2 | loss 8.7651 | lr 0.0002 | mfu 43.1% | 1198ms
...
step 500 | loss 3.2847 | lr 0.0400 | mfu 44.8% | 1201ms
...
training complete (300.0s)
val_bpb: 1.8234
peak_vram_mb: 23456
training_seconds: 300
num_params_M: 124.5
mfu_percent: 44.8
フェーズ4：結果抽出
# ログからメトリクスを抽出
grep "^val_bpb:\|^peak_vram_mb:" run.log
出力：
val_bpb: 1.8234
peak_vram_mb: 23456
フェーズ5：判断と記録
# results.tsvへの記録
echo "abc1234\t1.8234\t23456\t300\t124.5\t44.8\tIMPROVED\tIncreased depth to 10" >> results.tsv
# 改善した場合：コミットして保持
git add train.py
git commit -m "Experiment: Increased depth to 10, val_bpb 1.8234 (improved from 1.8567)"
# 改善しなかった場合：リバート
git checkout -- train.py
4.2 判断ロジックの詳細
エージェントの判断基準は明確である：
if 新しいval_bpb < 前回のベストval_bpb:
→ 改善: 変更を保持（コミット）
→ ステータス: "IMPROVED"
else:
→ 非改善: 変更をリバート
→ ステータス: "REVERTED"
特殊ケース:
if 実験がエラーで終了:
→ ステータス: "ERROR"
→ 変更をリバート
if NaN/Infが発生:
→ ステータス: "DIVERGED"
→ 変更をリバート
4.3 results.tsvの構造
実験結果は以下の形式でTSVファイルに記録される：
commit val_bpb peak_vram_mb training_seconds num_params_M mfu_percent status description
a1b2c3d 2.6670 18234 300 85.3 42.1 BASELINE Initial baseline
e4f5g6h 2.4512 19456 300 85.3 43.2 IMPROVED Added RoPE scaling
i7j8k9l 2.5100 22345 300 124.5 38.7 REVERTED Doubled model size (too large)
m0n1o2p 2.3890 19567 300 85.3 43.5 IMPROVED Adjusted LR schedule
このTSVファイルは以下の目的で活用される：
- エージェントが過去の実験結果を参照し、戦略を立てる
- 人間が実験の進捗を確認する
- 成功した変更と失敗した変更のパターンを分析する
4.4 自律性の設計
autoresearchにおける重要な設計決定の一つが「完全自律」の原則である：
❌ 「次の実験を実行してもよいですか？」 → 聞かない
❌ 「このアプローチで問題ないですか？」 → 聞かない
✅ 結果が出たら即座に次の実験に移行 → 自動的に続行
✅ ユーザーが手動で中断するまで実行 → 無限ループ
この設計により、研究者は：
- 夜間に実験を開始し、翌朝結果を確認できる
- エージェントの判断を信頼し、介入の必要がない
- 1時間あたり約9-12の実験を自動的に実行できる
4.5 典型的な実験戦略
エージェントが採用する典型的な実験戦略をいくつか紹介する：
戦略1：ハイパーパラメータスイープ
実験1: DEPTH=8, ASPECT_RATIO=64 → ベースライン
実験2: DEPTH=10, ASPECT_RATIO=64 → レイヤー増加
実験3: DEPTH=8, ASPECT_RATIO=80 → 幅の拡大
実験4: DEPTH=6, ASPECT_RATIO=96 → 浅く広いモデル
戦略2：段階的改善
実験1: 学習率を0.6→0.5に調整 → 改善
実験2: さらに0.5→0.45に微調整 → 改善
実験3: ウォームダウン比率を変更 → 改善
実験4: バッチサイズを増加 → 悪化→リバート
戦略3：アーキテクチャ探索
実験1: GQAのKVヘッド数を変更
実験2: ウィンドウパターンを実験
実験3: ゲーティング機構の追加
実験4: Rotary Embeddingのパラメータ調整
5. GPTモデルアーキテクチャ
5.1 アーキテクチャの概要
autoresearchで使用されるGPTモデルは、標準的なTransformerデコーダをベースに、いくつかの先進的な技術を組み込んでいる。
入力トークン
│
▼
┌─────────────┐
│ Token Embed │ 語彙サイズ 8,192 × 埋め込み次元 512
└──────┬──────┘
│
▼
┌──────────────────────┐
│ Transformer Block ×8 │
│ │
│ ┌────────────────┐ │
│ │ Layer Norm │ │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Causal Self- │ │
│ │ Attention │ │
│ │ (Flash Attn 3) │ │
│ │ + GQA │ │
│ │ + RoPE │ │
│ │ + Sliding Win │ │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Layer Norm │ │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Feed Forward │ │
│ │ Network │ │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Value Embed │ │
│ │ + Gating │ │
│ └───────┬────────┘ │
└──────────┼──────────┘
│
▼
┌─────────────┐
│ Layer Norm │
└──────┬──────┘
│
▼
┌─────────────┐
│ LM Head │ → ロジット（8,192次元）
└─────────────┘
5.2 Flash Attention 3
Flash Attention 3は、GPUメモリの階層構造を活用した高効率なアテンション計算カーネルである。
# 標準的なアテンション（O(n²)メモリ）
attention_scores = Q @ K.T / sqrt(d_k) # (seq_len × seq_len) の行列
attention_weights = softmax(attention_scores)
output = attention_weights @ V
# Flash Attention 3（O(n)メモリ）
# - タイルベースの計算でHBMアクセスを最小化
# - SRAMを最大活用
# - 完全な数値的等価性を維持
output = flash_attention_3(Q, K, V, causal=True)
Flash Attention 3の利点：
- メモリ効率: アテンション行列全体をメモリに保持しない
- 速度: HBM（高帯域メモリ）へのアクセスを最小化
- 精度: 標準アテンションと数値的に等価
5.3 Grouped Query Attention（GQA）
GQAは、Multi-Head Attention（MHA）とMulti-Query Attention（MQA）の中間に位置する効率的なアテンション手法である。
Multi-Head Attention (MHA):
Q heads: [Q1] [Q2] [Q3] [Q4] [Q5] [Q6] [Q7] [Q8]
K heads: [K1] [K2] [K3] [K4] [K5] [K6] [K7] [K8]
V heads: [V1] [V2] [V3] [V4] [V5] [V6] [V7] [V8]
→ 8つのQ、K、Vそれぞれに個別のヘッド
Grouped Query Attention (GQA, n_kv_head=4):
Q heads: [Q1] [Q2] [Q3] [Q4] [Q5] [Q6] [Q7] [Q8]
K heads: [K1 ] [K2 ] [K3 ] [K4 ]
V heads: [V1 ] [V2 ] [V3 ] [V4 ]
→ 8つのQヘッドが4つのKVヘッドを共有
Multi-Query Attention (MQA):
Q heads: [Q1] [Q2] [Q3] [Q4] [Q5] [Q6] [Q7] [Q8]
K heads: [K1 ]
V heads: [V1 ]
→ すべてのQヘッドが1つのKVヘッドを共有
autoresearchではn_head=8, n_kv_head=4がデフォルトで、2:1のGQA比率を使用。これにより：
- MHAと比較してKVキャッシュのメモリ使用量が50%削減
- MQAと比較して表現力を維持
- 推論速度と品質のバランスが最適化
5.4 Rotary Position Embeddings（RoPE）
RoPE（回転位置埋め込み）は、位置情報を回転行列として埋め込みベクトルにエンコードする手法である。
# RoPEの基本原理
def apply_rope(x, freqs):
"""
x: (batch, seq_len, n_head, head_dim)
freqs: (seq_len, head_dim // 2)
"""
# 隣接する次元をペアにして2D回転を適用
x_pairs = x.reshape(..., head_dim // 2, 2)
cos = torch.cos(freqs)
sin = torch.sin(freqs)
# 回転の適用
x_rotated = torch.stack([
x_pairs[..., 0] * cos - x_pairs[..., 1] * sin,
x_pairs[..., 0] * sin + x_pairs[..., 1] * cos
], dim=-1)
return x_rotated.reshape(x.shape)
RoPEの利点：
- 相対位置: 位置の絶対値ではなく、トークン間の相対距離を自然にエンコード
- 長さの外挿: 訓練時より長いシーケンスへの一定の汎化能力
- 計算効率: 追加パラメータなしで位置情報を埋め込み
5.5 スライディングウィンドウアテンション
autoresearchでは、window_patternパラメータによって各レイヤーのアテンションウィンドウを制御する。
window_pattern = "SSSL"
S = Sliding Window（局所的なウィンドウ）
L = Long-range（全シーケンスへのアテンション）
レイヤー1: [S] 局所的なパターンに注目（例：128トークン幅）
レイヤー2: [S] 局所的なパターンに注目
レイヤー3: [S] 局所的なパターンに注目
レイヤー4: [L] 全シーケンスを見渡す
レイヤー5: [S] 局所的なパターンに注目
レイヤー6: [S] 局所的なパターンに注目
レイヤー7: [S] 局所的なパターンに注目
レイヤー8: [L] 全シーケンスを見渡す
この設計の意図：
- 計算効率: 大部分のレイヤーでウィンドウアテンションを使用し、計算量を削減
- 長距離依存: 定期的にフルアテンションレイヤーを挟み、遠方の情報も統合
- 柔軟性: パターンを変更することで、タスクに応じた最適化が可能
5.6 Value Embeddings with Input-Dependent Gating
ResFormerスタイルのValue Embeddingとゲーティング機構は、モデルの表現力を向上させる追加コンポーネントである。
class ValueEmbedding(nn.Module):
def __init__(self, n_embd):
self.value_embed = nn.Embedding(vocab_size, n_embd)
self.gate = nn.Linear(n_embd, n_embd)
def forward(self, x, input_ids):
# 入力トークンに依存したゲーティング
v_embed = self.value_embed(input_ids)
gate_signal = torch.sigmoid(self.gate(x))
return x + gate_signal * v_embed
この機構により：
- 入力トークンの元の情報が残差接続を通じて保持される
- ゲーティングにより、文脈に応じて情報の流れが動的に制御される
- 深いネットワークでの勾配消失を軽減
6. 最適化戦略：MuonAdamW
6.1 デュアルオプティマイザの設計
autoresearchは、MuonAdamWという二重最適化器を採用している。これは、パラメータの種類に応じて異なる最適化アルゴリズムを適用するハイブリッド手法である。
パラメータの分類と最適化器の割り当て:
┌─────────────────────────────┬───────────────┐
│ パラメータ種別 │ 最適化器 │
├─────────────────────────────┼───────────────┤
│ LM Head（出力層） │ AdamW │
│ Token Embeddings（埋め込み層）│ AdamW │
│ Layer-wise Scalars（スカラー）│ AdamW │
│ 2D Matrix Parameters（行列） │ Muon │
└─────────────────────────────┴───────────────┘
6.2 AdamWグループ
AdamWは、重み減衰（Weight Decay）を正規化手法として組み込んだAdamの改良版である。
# AdamWの更新則
m_t = β1 * m_{t-1} + (1 - β1) * g_t # 1次モーメント
v_t = β2 * v_{t-1} + (1 - β2) * g_t² # 2次モーメント
m̂_t = m_t / (1 - β1^t) # バイアス補正
v̂_t = v_t / (1 - β2^t) # バイアス補正
θ_t = θ_{t-1} - lr * (m̂_t / (√v̂_t + ε) + λ * θ_{t-1})
autoresearchにおけるAdamWの特別な設定：
# 学習率スケーリング
# モデル次元に基づく逆平方根スケーリング
lr_scale = (model_dim / 768) ** (-0.5)
# 埋め込み層: EMBEDDING_LR = 0.6
# LM Head: 同じスケーリング
# スカラーパラメータ: 層ごとの個別学習率
6.3 Muonオプティマイザ
Muon（Momentum with Unitarization and Nesterov）は、2D行列パラメータに特化した最適化器である。通常のSGDやAdamとは根本的に異なるアプローチを取る。
6.3.1 Polar Express直交化
Muonの核心技術は、勾配更新を直交行列の近傍に保つPolar Expressアルゴリズムである。
def polar_express(G, steps=5):
"""
Newton法による極分解
G = U * S * V^T （SVD）
U * V^T を近似する（直交成分の抽出）
"""
X = G
for _ in range(steps):
X = 1.5 * X - 0.5 * X @ X.T @ X # Newton反復
return X
直交化の利点：
- 重みの方向のみを更新し、スケールを保持
- 勾配消失・爆発を本質的に防止
- パラメータ空間の効率的な探索
6.3.2 Nesterovモメンタム
# Nesterovモメンタムの実装
# モメンタム係数: 0.85 → 0.95（300ステップかけてランプアップ）
momentum = 0.85 + (0.95 - 0.85) * min(step / 300, 1.0)
# 標準モメンタム vs Nesterov
# 標準: v_t = μ * v_{t-1} + g_t, θ_t = θ_{t-1} - lr * v_t
# Nesterov: θ_lookahead = θ_{t-1} - lr * μ * v_{t-1}
# g_t = ∇f(θ_lookahead)
# v_t = μ * v_{t-1} + g_t
# θ_t = θ_{t-1} - lr * v_t
Nesterovモメンタムの利点：
- 「先読み」により、過剰な更新を事前に検知
- 収束速度の改善
- 振動の抑制
6.3.3 NorMuon分散削減
# NorMuon: 適応的なスケーリング
# パラメータごとの更新量を正規化
# 勾配の分散に基づく自動スケーリング
def normmon_scale(grad, param):
variance = grad.var()
return grad / (variance.sqrt() + eps)
6.3.4 Cautious Weight Decay
# パラメータ-勾配の整合性チェック
# 勾配と同方向のパラメータのみに減衰を適用
alignment = (param * grad).sum()
if alignment > 0:
param -= weight_decay * param # 減衰を適用
else:
pass # 減衰をスキップ
6.4 学習率スケジュール
autoresearchは、以下の学習率スケジュールを使用する：
学習率
↑
│ ╱───────────────────╲
│ ╱ ╲
│ ╱ ╲
│ ╱ ╲
│ ╱ ╲
│╱ ╲
┼──────────────────────────────→ ステップ
0 ウォームアップ 定常状態 ウォームダウン
(短い) (大部分) (WARMDOWN_RATIO=0.5)
def get_learning_rate(step, total_steps, warmdown_ratio=0.5):
warmup_steps = 100
warmdown_start = int(total_steps * (1 - warmdown_ratio))
if step < warmup_steps:
# 線形ウォームアップ
return base_lr * step / warmup_steps
elif step < warmdown_start:
# 定常状態
return base_lr
else:
# コサインウォームダウン
progress = (step - warmdown_start) / (total_steps - warmdown_start)
return base_lr * 0.5 * (1 + math.cos(math.pi * progress))
6.5 勾配累積
TOTAL_BATCH_SIZE = 2**19 # ~524,288 トークン
# GPUメモリに収まるマイクロバッチサイズを計算
micro_batch_size = calculate_max_micro_batch(gpu_memory)
grad_accum_steps = TOTAL_BATCH_SIZE // (micro_batch_size * MAX_SEQ_LEN)
# 勾配累積ループ
for micro_step in range(grad_accum_steps):
batch = next(dataloader)
with torch.autocast('cuda', dtype=torch.bfloat16):
loss = model(batch) / grad_accum_steps # スケーリング
loss.backward() # 勾配を累積
optimizer.step()
optimizer.zero_grad()
6.6 その他の訓練技術
torch.compileによる最適化
model = torch.compile(model) # グラフレベルの最適化
bfloat16混合精度
with torch.autocast('cuda', dtype=torch.bfloat16):
output = model(input)
# bfloat16: 指数部8bit + 仮数部7bit
# float16比でダイナミックレンジが広く、Loss scalingが不要
GCの管理
# Python GCのストール防止
gc.disable() # 訓練中はGCを無効化
# 定期的に手動GCを実行
if step % 100 == 0:
gc.collect()
7. 評価指標とデータパイプライン
7.1 val_bpb（Validation Bits Per Byte）
7.1.1 BPBの定義
BPB（Bits Per Byte）は、モデルがテキストデータを「どれだけ効率的に圧縮できるか」を測定する指標である。
BPB = (合計クロスエントロピー損失) / (合計バイト数) / ln(2)
具体的には：
- 各トークンの予測に対するクロスエントロピー損失を計算
- それをバイト単位のテキスト長で割る
- 自然対数から2を底とする対数に変換（bits）
7.1.2 なぜBPBを使うのか
指標の比較:
| 指標 | 語彙依存 | 比較公平性 | 解釈のしやすさ |
|-------------------|----------|-----------|---------------|
| Cross-Entropy | ✗ | ✗ | △（nats） |
| Perplexity | ✗ | ✗ | △（指数的） |
| Bits Per Token | ✗ | ✗ | ○ |
| Bits Per Byte | ✓不依存 | ✓公平 | ◎（直感的） |
語彙サイズ8,192のモデルと32,000のモデルは同じテキストに対するトークン数が異なるため、トークン単位の指標では比較できない。BPBはバイト単位であるため、語彙サイズに依存しない公平な比較が可能である。
7.1.3 BPBの解釈
BPB値の目安:
8.0 → ランダム予測（情報なし）
3.0 → 基本的な言語パターンを学習
2.0 → 良好な言語モデル
1.5 → 高品質な言語モデル
1.0 → テキスト圧縮の理論的限界に近い
autoresearchでの典型的な進歩:
ベースライン: 2.667
最適化後: 1.808 （公開実験）
長時間実行: 1.295 （M4 Maxでの拡張実験）
7.1.4 evaluate_bpb関数の実装
@torch.no_grad()
def evaluate_bpb(model, dataloader, num_batches=50):
"""
検証データでのBPBを計算する。
特殊トークン（BOS等）はバイト数計算から除外される。
"""
model.eval()
total_loss = 0.0
total_bytes = 0
for i, batch in enumerate(dataloader):
if i >= num_batches:
break
logits = model(batch['input_ids'])
# クロスエントロピー損失の計算
loss = F.cross_entropy(
logits.view(-1, vocab_size),
batch['labels'].view(-1),
reduction='sum'
)
total_loss += loss.item()
# バイト数の計算（特殊トークンを除外）
for token_id in batch['labels'].view(-1):
if token_id >= 0: # パディングでない
total_bytes += get_token_bytes(token_id)
bpb = (total_loss / total_bytes) / math.log(2)
model.train()
return bpb
7.2 Model Flops Utilization（MFU）
MFUは、GPU の理論上の最大計算能力に対して、実際にどれだけ活用されているかを示す指標である。
MFU = 実際のFLOPS / 理論上の最大FLOPS × 100%
H100の場合:
理論最大（bfloat16）: ~989 TFLOPS
typical MFU: 40-50%（autoresearch）
# MFUの計算
def compute_mfu(model_params, batch_size, seq_len, elapsed_time, gpu_peak_flops):
# Transformerの近似FLOPS = 6 * N * B * T
# N: パラメータ数, B: バッチサイズ, T: シーケンス長
flops_per_step = 6 * model_params * batch_size * seq_len
achieved_flops = flops_per_step / elapsed_time
mfu = achieved_flops / gpu_peak_flops * 100
return mfu
7.3 その他の記録メトリクス
# 各実験で記録されるメトリクス
metrics = {
"val_bpb": 1.8234, # 最適化対象
"peak_vram_mb": 23456, # ピークGPUメモリ使用量
"training_seconds": 300, # 訓練時間
"num_params_M": 124.5, # パラメータ数（百万単位）
"mfu_percent": 44.8 # MFU
}
7.4 データセット
7.4.1 データソース
autoresearchはHugging Face上のテキストデータセットを使用する。データはparquet形式のシャードとして配布され、並列ダウンロードに対応している。
~/.cache/autoresearch/
├── data/
│ ├── shard_0000.parquet
│ ├── shard_0001.parquet
│ ├── ...
│ └── shard_0099.parquet
└── tokenizer/
├── tokenizer.model
├── tokenizer.tiktoken
└── token_bytes_lookup.bin
7.4.2 トークナイザ
# BPEトークナイザの設定
vocab_size = 8192 # 語彙サイズ
split_pattern = GPT4_PATTERN # GPT-4スタイルの分割パターン
# 訓練プロセス
# 1. rustbpeライブラリで高速BPE訓練
# 2. tiktoken互換フォーマットに変換
# 3. トークンID→バイト長のルックアップテーブル生成
8,192という小さな語彙サイズの選択理由：
- 訓練の高速化: 出力層（LM Head）のパラメータが少ない
- メモリ効率: 埋め込みテーブルが小さい
- BPBへの影響なし: BPBは語彙サイズに依存しない
- 実験の公平性: 全実験で同じトークナイザを使用
7.4.3 Best-Fitパッキング
通常のバッチ化:
[Doc1 ██████████░░░░░] (パディングあり)
[Doc2 ████░░░░░░░░░░░] (パディングあり)
[Doc3 ████████████░░░] (パディングあり)
利用率: ~60%
Best-Fitパッキング:
[BOS Doc1 ██████████ BOS Doc3_part1 ████] (パディングなし)
[BOS Doc2 ████ BOS Doc3_part2 ████████] (パディングなし)
利用率: 100%
Best-Fitパッキングのアルゴリズム：
- 各ドキュメントの先頭にBOSトークンを追加
- ドキュメントを長さでソート
- ビンパッキングアルゴリズムでシーケンス長（2048）に最適に詰め込む
- パディングが発生しない100%の利用率を実現
8. セットアップと実行方法
8.1 動作要件
ハードウェア要件
| 項目 | 推奨 | 最低 |
|---|---|---|
| GPU | NVIDIA H100 | CUDA対応GPU |
| VRAM | 80GB | 16GB+ |
| CPU | 任意 | 4コア以上 |
| RAM | 64GB+ | 16GB+ |
| ストレージ | 100GB+ SSD | 50GB+ |
ソフトウェア要件
| 項目 | バージョン |
|---|---|
| Python | 3.10以上 |
| uv | 最新版 |
| CUDA | 12.0以上（NVIDIA GPU使用時） |
| Git | 任意のバージョン |
| OS | Linux推奨（Windowsフォークあり） |
8.2 インストール手順
ステップ1：uvのインストール
# uvパッケージマネージャのインストール
curl -LsSf https://astral.sh/uv/install.sh | sh
# インストール確認
uv --version
uvはRust製の高速Pythonパッケージマネージャで、pipの10-100倍の速度で依存関係を解決する。
ステップ2：リポジトリのクローン
git clone https://github.com/karpathy/autoresearch.git
cd autoresearch
ステップ3：依存関係の同期
uv sync
これにより、pyproject.tomlに定義されたすべての依存関係が仮想環境にインストールされる。
ステップ4：データ準備（初回のみ）
uv run prepare.py
このコマンドは以下を実行する（約2分）：
- Hugging Faceからデータシャードをダウンロード
- BPEトークナイザを訓練
- トークンバイト長ルックアップテーブルを生成
- すべてを
~/.cache/autoresearch/にキャッシュ
ステップ5：ベースライン実験の実行
uv run train.py
約5分で完了し、ベースラインのval_bpb値が出力される。
8.3 AIエージェントとの連携
Claude Codeでの実行
# Claude Codeを起動し、autoresearchディレクトリで実行
cd autoresearch
claude
# Claude Codeのプロンプトで以下を入力
> program.mdを読んで、新しい実験を開始してください
OpenAI Codexでの実行
# Codexをautoresearchディレクトリで起動
codex --model o4-mini "program.mdを参照して自律実験を開始"
汎用的なエージェント連携
どのAIエージェントでも、以下の手順で連携可能：
- エージェントに
program.mdを読ませる - 「新しい実験を開始して」と指示する
- エージェントが自律的に実験ループを実行
8.4 実行例：一晩の自律実験
# ターミナル1: 実験の開始
cd autoresearch
claude "program.mdを読んで、autoresearch/overnight-v1ブランチで
自律実験を開始してください。改善が見られなくても
継続してください。"
# ターミナル2: リアルタイム監視（オプション）
watch -n 60 "tail -5 results.tsv | column -t -s $'\t'"
# 翌朝の確認
cat results.tsv | column -t -s $'\t'
git log --oneline autoresearch/overnight-v1
8.5 結果の確認方法
# 全実験結果の表示
column -t -s $'\t' results.tsv
# ベスト結果の抽出
sort -t$'\t' -k2 -n results.tsv | head -5
# 改善された実験のみ表示
grep "IMPROVED" results.tsv | column -t -s $'\t'
# val_bpbの推移をプロット（Pythonワンライナー）
python3 -c "
import csv
with open('results.tsv') as f:
reader = csv.DictReader(f, delimiter='\t')
for row in reader:
bpb = float(row['val_bpb'])
bar = '█' * int((3.0 - bpb) * 30)
print(f'{row[\"status\"]:10s} {bpb:.4f} {bar}')
"
8.6 カスタマイズ
データセットの変更
prepare.pyのデータソースURLを変更することで、異なるデータセットで実験可能（ただしprepare.pyの変更は本来の設計思想から逸脱する）。
時間予算の変更
# prepare.py内
TIME_BUDGET = 300 # デフォルト: 5分
TIME_BUDGET = 600 # 10分に延長（より大きなモデル向け）
TIME_BUDGET = 120 # 2分に短縮（高速イテレーション向け）
GPU別の推奨設定
| GPU | VRAM | 推奨DEPTH | 推奨ASPECT_RATIO | 概算パラメータ数 |
|---|---|---|---|---|
| H100 | 80GB | 8-12 | 64-96 | 85M-250M |
| A100 | 40GB | 6-8 | 48-64 | 40M-85M |
| RTX 4090 | 24GB | 4-6 | 32-48 | 15M-40M |
| RTX 3090 | 24GB | 4-6 | 32-48 | 15M-40M |
9. program.mdによるエージェント制御
9.1 program.mdの役割
program.mdは、autoresearchにおける「人間とAIの接点」である。研究者はこのファイルを通じて：
- 研究の方向性を定義する
- 制約条件を明示する
- 実験手順を指定する
- 記録フォーマットを規定する
これは従来の設定ファイル（YAML/JSON）とは異なり、自然言語のMarkdownで記述される。エージェントはこれを「読んで理解する」ことで、指示に従って行動する。
9.2 program.mdの詳細構造
# Autoresearch Program
## Overview
あなたはLLM訓練の自律研究エージェントです。
train.pyを修正し、val_bpb（低いほど良い）を改善する実験を
繰り返し実行してください。
## Files
- `prepare.py`: データ準備と評価関数（変更禁止）
- `train.py`: モデルとトレーニングコード（変更可能）
- `program.md`: この指示書（参照のみ）
## Constraints
1. train.pyのみ変更可能
2. prepare.pyのevaluate_bpb関数を改変しない
3. 新しいpipパッケージをインストールしない
4. 実行時間はTIME_BUDGET（300秒）以内
## Experiment Procedure
### Initialization
1. ブランチを作成: `git checkout -b autoresearch/<tag>`
2. データキャッシュの確認: `ls ~/.cache/autoresearch/`
3. results.tsvの初期化
### Loop
以下を無限に繰り返す（ユーザーの中断まで）:
1. 現在のtrain.pyを分析
2. 改善仮説を立てる
3. train.pyを修正
4. 実行: `uv run train.py > run.log 2>&1`
5. メトリクス抽出: `grep "^val_bpb:\|^peak_vram_mb:" run.log`
6. results.tsvに記録
7. val_bpbが改善した場合:
- git commit -m "Experiment: <description>, val_bpb <value>"
8. val_bpbが悪化した場合:
- git checkout -- train.py
- ステータスをREVERTEDとして記録
9. ステップ1に戻る
### Important Principles
- **NEVER** ask for permission to continue
- Prefer simplicity over complexity
- If code deletion achieves equal results, prefer deletion
- Log ALL experiments, including failures
9.3 program.mdのカスタマイズ例
例1：特定の研究方向に焦点を当てる
## Research Focus
今回の実験セッションでは、以下に焦点を当ててください：
- アテンション機構の改善のみを探索
- モデルサイズは現在の規模（~85M params）を維持
- ウィンドウパターンの最適な組み合わせを見つける
- GQAのKVヘッド数は2, 4, 8のいずれかを試す
例2：探索範囲を制限する
## Constraints (Additional)
- DEPTH は 6-10 の範囲内
- ASPECT_RATIO は 48-96 の範囲内
- TOTAL_BATCH_SIZE は変更しない
- 学習率は現在値の±50%の範囲で調整
- アーキテクチャの根本的な変更は避ける
例3：段階的な実験を指示する
## Experiment Plan
以下の順序で段階的に実験してください：
### Phase 1: ベースライン確認（1実験）
現在のtrain.pyをそのまま実行し、ベースラインを記録
### Phase 2: ハイパーパラメータ調整（5実験）
学習率、バッチサイズ、ウォームダウン比率を個別に調整
### Phase 3: アーキテクチャ探索（5実験）
Phase 2の最良設定をベースに、モデル構造を変更
### Phase 4: 最終微調整（5実験）
Phase 3の最良設定をベースに、微調整を実施
例4：安全性を強化する
## Safety Measures
- VRAM使用量が60GB（75%）を超える実験は避ける
- NaN検出時は即座にリバート
- 3回連続でREVERTEDになった場合、別のアプローチに切り替える
- パラメータ数が200Mを超えないようにする
9.4 エージェントとprogram.mdの対話パターン
┌──────────────────────────────────────────────────────┐
│ 研究者の作業フロー │
│ │
│ 朝: program.mdを書く / 修正する │
│ │ │
│ ▼ │
│ エージェント起動: "program.mdを読んで実験を開始して" │
│ │ │
│ ▼ │
│ ┌──── 自律実験ループ（8-12時間） ────┐ │
│ │ program.md → 解釈 → 実験 → 判断 │ │
│ │ ↑ │ │ │
│ │ └────────────────────┘ │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 翌朝: results.tsvを確認、GitログをレビューData │
│ │ │
│ ▼ │
│ program.mdを更新して次のセッションの方向性を設定 │
└──────────────────────────────────────────────────────┘
10. 派生プロジェクト（エコシステム）
10.1 エコシステムの全体像
autoresearchの公開以降、そのコンセプトは急速に拡大し、多様な派生プロジェクトが生まれた。
autoresearch (Karpathy)
"単一GPU自律ML研究"
│
┌────────────────┼────────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ プラット │ │ 機能拡張 │ │ 応用領域 │
│ フォーム │ │ │ │ │
│ 移植 │ │ │ │ │
├───────────┤ ├───────────┤ ├───────────┤
│ MLXポート │ │ AutoRe- │ │ Codex │
│ (Apple) │ │ searchClaw│ │ Autore- │
│ │ │ (論文生成) │ │ search │
│ Windows版 │ │ │ │ (汎用) │
│ (jsegov) │ │ Claude │ │ │
│ │ │ Skill版 │ │ │
│ AMD版 │ │ │ │ │
│ (andyluo7) │ │ │ │ │
└───────────┘ └───────────┘ └───────────┘
10.2 主要な派生プロジェクト一覧
| プロジェクト | 作者 | 特徴 | ターゲット |
|---|---|---|---|
| autoresearch | karpathy | オリジナル、NVIDIA GPU | ML研究者 |
| autoresearch-mlx | trevin-creator | Apple Silicon対応 | Mac開発者 |
| AutoResearchClaw | aiming-lab | 23段階の論文自動生成 | 学術研究者 |
| codex-autoresearch | leo-lilinxiao | 汎用コード最適化 | ソフトウェア開発者 |
| autoresearch-windows | jsegov | Windows対応 | Windows開発者 |
| autoresearch-amd | andyluo7 | AMD GPU対応 | AMD GPU所有者 |
10.3 コンセプトの一般化
autoresearchの「修正→実行→評価→判断」のループは、ML研究に限らず、より広い領域に一般化可能である：
一般化されたautoresearchパターン:
1. 目標の定義（定量的な指標）
2. 変更可能なコードの特定
3. 固定された評価基準
4. 自律的な反復ループ
a. コードの分析
b. 改善仮説の生成
c. コードの修正
d. 実行と評価
e. 結果に基づく取捨選択
5. 全実験の記録
応用例：
- パフォーマンス最適化: レスポンスタイムを指標に、コードを自動改善
- テスト改善: カバレッジを指標に、テストケースを自動生成
- コンパイラ最適化: バイナリサイズや実行速度を指標に、コンパイル設定を探索
- データパイプライン最適化: スループットを指標に、パイプライン構成を自動調整
11. AutoResearchClaw：AIによる完全自動論文生成
11.1 概要
AutoResearchClawは、aiming-labが開発した、アイデアから学術論文までを完全自動で生成するシステムである。autoresearchの「自律的な実験ループ」というコンセプトを、学術研究のワークフロー全体に拡張している。
入力: 「研究トピック」（一文）
↓
23段階のパイプライン
↓
出力: 会議投稿品質の論文（LaTeX + BibTeX + 実験コード + 査読）
11.2 23段階パイプライン
AutoResearchClawのパイプラインは8つのフェーズに分かれた23のステージで構成される：
Phase A: スコーピング（トピック初期化）
├── Stage 1: トピック分析
├── Stage 2: 研究課題の分解
└── Stage 3: スコープ定義
Phase B: 文献探索
├── Stage 4: 論文収集（OpenAlex, Semantic Scholar, arXiv）
├── Stage 5: 重複排除・関連性スクリーニング ★ゲート1
└── Stage 6: メタデータ統合
Phase C: 知識合成
├── Stage 7: 知見クラスタリング
├── Stage 8: ギャップ特定・仮説生成
└── Stage 9: マルチエージェント議論 ★ゲート2
Phase D: 実験設計
├── Stage 10: ハードウェア検知・リソース推定
├── Stage 11: 実験計画策定
└── Stage 12: コード生成ルーティング
Phase E: 実験実行
├── Stage 13: サンドボックス実行
├── Stage 14: 自己修復ループ（最大10回）
└── Stage 15: 結果検証
Phase F: 分析と判断
├── Stage 16: 多角的結果分析
├── Stage 17: 自律判断（PROCEED/REFINE/PIVOT）
└── Stage 18: 知見の構造化
Phase G: 論文執筆
├── Stage 19: セクション別ドラフト（NeurIPS/ICML/ICLR形式）
├── Stage 20: 査読（マルチエージェント） ★ゲート3
└── Stage 21: 修正・改善
Phase H: 最終化
├── Stage 22: 品質ゲート・引用検証
└── Stage 23: LaTeX出力・アーカイブ
11.3 マルチエージェントシステム
AutoResearchClawは、専門化された複数のエージェントで構成される：
┌─────────────────────────────────────────┐
│ AutoResearchClaw │
│ │
│ ┌────────────┐ ┌─────────────────┐ │
│ │ CodeAgent │ │ BenchmarkAgent │ │
│ │ コード生成 │ │ 実験実行・管理 │ │
│ │ AST検証 │ │ 結果収集 │ │
│ └────────────┘ └─────────────────┘ │
│ │
│ ┌────────────┐ ┌─────────────────┐ │
│ │ FigureAgent│ │ ReviewAgent │ │
│ │ 図表生成 │ │ 査読シミュレーション│ │
│ │ 統計注釈 │ │ 多角的フィードバック│ │
│ └────────────┘ └─────────────────┘ │
└─────────────────────────────────────────┘
11.4 4層引用検証システム
学術論文における「幻覚引用」（存在しない論文の引用）を防止するため、4層の検証システムを実装：
Layer 1: arXiv ID検証
arxiv.org/abs/2301.12345 → arXivレジストリで照合
Layer 2: DOIクロスリファレンス
DOI → CrossRef/DataCiteで照合
Layer 3: Semantic Scholar タイトルマッチング
論文タイトル → メタデータ照合
Layer 4: LLM関連性スコアリング
引用文脈 → 収集論文との関連性評価
結果: 幻覚引用は論文生成前に自動除去
11.5 Human-in-the-Loopモード
┌──────────────────────────────────────────┐
│ 協調モード一覧 │
├──────────┬───────────────────────────────┤
│ Full Auto│ 介入なし（従来動作） │
│ Gate Only│ 3つの重要ゲートで確認 │
│ │ (Stage 5, 9, 20) │
│Checkpoint│ フェーズ境界でポーズ │
│ Co-Pilot │ Stage 7-8, 9, 16-17で深い協業 │
│Step-by- │ 全ステージでポーズ │
│ Step │ │
│ Custom │ ステージごとの個別ポリシー │
└──────────┴───────────────────────────────┘
SmartPause: 信頼度スコアが閾値を下回った場合に自動的に人間の入力を要求する機能。
11.6 設定例
# config.yaml
project:
name: "attention-mechanism-research"
research:
topic: "Novel attention mechanisms for long-context language models"
llm:
provider: "anthropic" # "openai", "anthropic", "acp"
model: "claude-sonnet-4-20250514"
experiment:
mode: "sandbox"
python_path: "/usr/bin/python3"
max_iterations: 10
timeout_seconds: 3600
copilot:
mode: "gate_only" # ゲートのみで介入
openclaw_bridge:
enabled: false # Discord/Telegram統合は無効
11.7 出力成果物
artifacts/rc-20250615-143022-a1b2c3/deliverables/
├── paper_draft.md # フル論文（Markdown）
├── paper.tex # 会議フォーマットLaTeX
├── references.bib # 自動剪定BibTeX
├── verification_report.json # 引用検証レポート
├── experiment_runs/ # 実験コードと結果
│ ├── run_001/
│ ├── run_002/
│ └── ...
├── charts/ # 自動生成図表
│ ├── comparison.png
│ └── ablation.png
└── reviews.md # マルチエージェント査読
12. Codex Autoresearch：汎用コード最適化フレームワーク
12.1 概要
Codex Autoresearchは、Karpathyのautoresearchパターンをコード最適化全般に一般化したフレームワークである。ML訓練に限定されず、あらゆる定量的指標を持つコード改善に適用できる。
12.2 コアサイクル
┌─────────────────────────────────────────────┐
│ Codex Autoresearch サイクル │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Modify │────▶│ Verify │ │
│ │ コード変更 │ │ 検証実行 │ │
│ └──────────┘ └────┬─────┘ │
│ ▲ │ │
│ │ ┌────▼─────┐ │
│ │ │ 改善? │ │
│ │ └────┬─────┘ │
│ │ Yes │ No │
│ │ ┌────────┼────────┐ │
│ │ │ │ │
│ │ ┌────▼─────┐ ┌─────▼────┐ │
│ │ │ Retain │ │ Discard │ │
│ │ │ 変更保持 │ │ 変更破棄 │ │
│ │ └────┬─────┘ └─────┬────┘ │
│ │ │ │ │
│ └────────┴────────────────┘ │
│ Repeat │
└─────────────────────────────────────────────┘
12.3 自動構成
Codex Autoresearchの特徴的な機能として、ユーザーの自然言語リクエストからパラメータを自動推論する機能がある：
ユーザー入力: "APIのレスポンスタイムを改善して"
自動推論結果:
├── Goal: レスポンスタイムの短縮
├── Scope: src/api/ 配下のファイル
├── Metric: 平均レスポンスタイム（ms）
├── Direction: 低いほど良い（minimize）
└── Verification: 既存のベンチマークスクリプトを使用
ユーザー入力: "テストカバレッジを上げて"
自動推論結果:
├── Goal: テストカバレッジの向上
├── Scope: tests/ 配下 + src/ 配下
├── Metric: カバレッジ率（%）
├── Direction: 高いほど良い（maximize）
└── Verification: pytest --cov を使用
12.4 インテリジェントエスカレーション
行き詰まった際の段階的な戦略変更メカニズム：
失敗回数 アクション
────────── ──────────────────────
1-2回 同じアプローチで微調整
3回 アプローチの洗練（refinement）
4回 同上
5回 戦略のピボット（pivot）
6-7回 同上
8回 外部情報の検索
9回 同上
10回 人間への報告（stuck状態）
# エスカレーションロジック（疑似コード）
class EscalationManager:
def __init__(self):
self.consecutive_failures = 0
self.pivot_count = 0
def on_failure(self):
self.consecutive_failures += 1
if self.consecutive_failures >= 3 and self.consecutive_failures < 5:
return "REFINE" # アプローチの洗練
elif self.consecutive_failures >= 5:
self.pivot_count += 1
self.consecutive_failures = 0
if self.pivot_count >= 2:
return "SEARCH_EXTERNAL" # 外部検索
elif self.pivot_count >= 3:
return "REPORT_HUMAN" # 人間に報告
return "PIVOT" # 戦略ピボット
def on_success(self):
self.consecutive_failures = 0
12.5 results.tsvによる実験追跡
commit metric_value delta status description
a1b2c3d 234.5 - BASELINE Initial measurement
e4f5g6h 198.2 -36.3 IMPROVED Optimized database query
i7j8k9l 245.1 +46.9 REVERTED Added caching (slower due to overhead)
m0n1o2p 187.4 -10.8 IMPROVED Connection pooling
q3r4s5t 191.2 +3.8 REVERTED Async refactor (marginal regression)
12.6 7つの動作モード
| モード | 用途 | 自動検出キーワード |
|---|---|---|
| loop | 継続的な改善ループ | "improve", "optimize" |
| plan | 計画策定 | "plan", "design" |
| debug | デバッグ | "debug", "why", "investigate" |
| fix | バグ修正 | "fix", "repair", "broken" |
| security | セキュリティ分析 | "secure", "vulnerability" |
| ship | リリース準備 | "ship", "release", "deploy" |
| exec | CI/CD統合（JSON出力） | プログラム的呼び出し |
12.7 高度な機能
クロスラン学習
# 過去の実験セッションから学習
# what_worked.json に蓄積された知見を参照
{
"pattern": "connection_pooling",
"avg_improvement": -15.2,
"success_rate": 0.85,
"applicable_contexts": ["database", "api", "network"]
}
並列仮説テスト
# Gitワークツリーを活用した並列実験
git worktree add ../experiment-a -b experiment-a
git worktree add ../experiment-b -b experiment-b
# 各ワークツリーで独立した実験を並行実行
13. autoresearch-mlx：Apple Silicon対応
13.1 概要
autoresearch-mlxは、Karpathyのautoresearchフレームワークをapple Silicon Mac上でネイティブに動作するよう再設計したポートである。PyTorchとCUDAへの依存を完全に排除し、AppleのMLXフレームワークを使用する。
13.2 技術的な違い
┌────────────────────┬──────────────────┬──────────────────┐
│ 項目 │ オリジナル │ MLXポート │
├────────────────────┼──────────────────┼──────────────────┤
│ フレームワーク │ PyTorch │ MLX │
│ GPU │ NVIDIA CUDA │ Apple GPU │
│ メモリモデル │ 専用VRAM │ ユニファイドメモリ│
│ オプティマイザ │ Muon + AdamW │ AdamW中心 │
│ 評価トークン数 │ 標準 │ 高速化のため削減 │
│ 実行時間/実験 │ ~5分 │ ~6-7分 │
│ MFUレポート │ H100基準 │ プレースホルダー │
│ ライセンス │ MIT │ MIT │
└────────────────────┴──────────────────┴──────────────────┘
13.3 ユニファイドメモリの利点
Apple Siliconのユニファイドメモリアーキテクチャは、従来のCPU-GPU分離アーキテクチャとは根本的に異なる：
従来のアーキテクチャ（NVIDIA）:
┌──────────┐ PCIe ┌──────────┐
│ CPU RAM │◀──────────▶│ GPU VRAM │
│ (64GB) │ データ転送 │ (80GB) │
└──────────┘ └──────────┘
※ CPU-GPU間のデータ転送がボトルネック
Apple Silicon ユニファイドメモリ:
┌────────────────────────────────┐
│ ユニファイドメモリ │
│ (128GB等) │
│ │
│ CPU ←→ GPU ←→ Neural Engine │
│ （データ転送なし） │
└────────────────────────────────┘
※ すべてのプロセッサが同じメモリを直接参照
13.4 セットアップ手順
# 1. リポジトリのクローン
git clone https://github.com/trevin-creator/autoresearch-mlx.git
cd autoresearch-mlx
# 2. 依存関係のインストール
uv sync
# 3. データ準備（初回のみ）
uv run prepare.py
# 4. ベースライン実験
uv run train.py
13.5 実験結果
MLXポートでの公開実験結果：
実験結果の推移:
val_bpb
↑
2.667 ████████████████████████████████████ ベースライン
2.400 ████████████████████████████████
2.100 ████████████████████████████
1.808 ██████████████████████████ 公開最良結果
1.500 █████████████████████
1.295 ████████████████████ M4 Max拡張実験
└──────────────────────────────────→ 実験番号
主な知見：
- 小さく高速なモデルが勝つ: 固定時間予算内では、大きなモデルよりも小さく高速に回るモデルの方がval_bpbが良い
- M4 Max性能: M4 MaxシステムでのMLXポートはval_bpb 1.295を達成
- コンシューマー向けハードウェア: H100なしでも有意義な研究が可能
13.6 GPU別パフォーマンス比較
| Mac | チップ | メモリ | 典型的val_bpb | 実験時間 |
|---|---|---|---|---|
| MacBook Air | M2 | 16GB | ~2.1 | ~8分 |
| MacBook Pro | M3 Pro | 36GB | ~1.9 | ~7分 |
| MacBook Pro | M4 Max | 128GB | ~1.3 | ~6分 |
| Mac Studio | M2 Ultra | 192GB | ~1.5 | ~6分 |
14. 応用シナリオとベストプラクティス
14.1 応用シナリオ
シナリオ1：学術研究での活用
ユースケース: 新しいアテンション機構の探索
1. program.mdで研究方向を定義
"アテンション機構のバリエーションを探索する。
既知のアプローチ（Linear Attention, Sparse Attention等）
の組み合わせや改良を自動的に試す。"
2. 一晩で96回の実験を実行
→ 24の異なるアテンション構成を4つの学習率で評価
3. 翌朝、results.tsvを分析
→ 上位5つの設定を特定
→ 大規模な検証実験に移行
シナリオ2：プロダクションモデルの最適化
ユースケース: 推論速度とモデル品質のトレードオフ探索
1. カスタム指標を設定
evaluate関数を修正して、品質と速度の加重平均を計算：
score = val_bpb + 0.1 * (latency_ms / 100)
2. モデルサイズと構成の自動探索
→ より少ないレイヤーで同等品質を達成する構成を発見
3. 本番デプロイ候補の選定
シナリオ3：教育目的での活用
ユースケース: Transformerアーキテクチャの理解
1. 各コンポーネントの影響を定量化
- アテンションヘッド数: 4 vs 8 vs 16
- GQAのKVヘッド比率: 1:1 vs 2:1 vs 4:1
- ウィンドウパターン: "SSSS" vs "SSSL" vs "SLSL"
2. 視覚化
results.tsvから各パラメータとval_bpbの関係をプロット
3. 実験レポートの作成
14.2 ベストプラクティス
実験設計のベストプラクティス
DO:
✅ 一度に一つの変数のみ変更する（制御実験）
✅ ベースラインを必ず最初に記録する
✅ 成功した変更を積み重ねる（段階的改善）
✅ 結果をこまめに確認する（暴走防止）
DON'T:
❌ 複数の変更を同時に行う（原因特定が困難）
❌ ベースラインなしで実験を開始する
❌ 大幅な変更を一度に行う（発散リスク）
❌ results.tsvを手動で編集する
program.md作成のベストプラクティス
DO:
✅ 明確な目標を設定する（「val_bpbを1.5以下にする」）
✅ 制約条件を明示する（VRAMの上限、パラメータ数の上限）
✅ 段階的な実験計画を示す
✅ 失敗時の代替戦略を含める
DON'T:
❌ 曖昧な指示を出す（「モデルを良くして」）
❌ 矛盾する制約を設定する
❌ エージェントの自律性を制限しすぎる
❌ 100以上の詳細な指示を列挙する（情報過多）
リソース管理のベストプラクティス
メモリ管理:
- GPUメモリの75%を上限とする
- OOMエラー発生時の自動リカバリ手順を含める
- バッチサイズの段階的調整を許可する
ストレージ管理:
- チェックポイントの自動削除ポリシーを設定
- run.logのローテーション
- Gitブランチの定期的な整理
電力管理（長時間実行時）:
- UPS（無停電電源装置）の使用を推奨
- 中断からの自動復帰手順を文書化
14.3 トラブルシューティング
よくある問題と解決策
| 問題 | 原因 | 解決策 |
|---|---|---|
| OOM（メモリ不足） | モデルが大きすぎる | DEPTH/ASPECT_RATIOを減らす |
| NaN発生 | 学習率が高すぎる | 学習率を50%に下げる |
| val_bpbが改善しない | 局所最適に捕まった | 大胆なアーキテクチャ変更を試す |
| 実験時間の超過 | モデルが大きすぎる | バッチサイズまたはモデルサイズを削減 |
| Gitコンフリクト | 並行編集 | ブランチを分離する |
| prepare.pyのエラー | ネットワーク問題 | データキャッシュを確認・再ダウンロード |
デバッグチェックリスト
# 1. データキャッシュの確認
ls -la ~/.cache/autoresearch/
# 2. GPU状態の確認
nvidia-smi # NVIDIA
# または
system_profiler SPDisplaysDataType # Mac
# 3. 前回の実行ログ確認
tail -50 run.log
# 4. Git状態の確認
git status
git log --oneline -5
# 5. results.tsvの最新エントリ
tail -3 results.tsv | column -t -s $'\t'
15. まとめと今後の展望
15.1 autoresearchの意義
autoresearchは、AI研究の方法論に根本的な転換をもたらした：
- 研究の民主化: 高価な計算リソースがなくても、効率的な実験が可能
- 生産性の革命: 人間が寝ている間にも研究が進む
- 実験の体系化: すべての試行錯誤が記録され、再現可能
- 教育的価値: シンプルなコードベースがML研究の学習を促進
15.2 技術的な貢献
| 貢献分野 | 内容 |
|---|---|
| 自律エージェント設計 | 制約ベースの自律実験ループパターン |
| 最適化手法 | MuonAdamWデュアルオプティマイザの実用化 |
| 評価指標 | BPBによる公平なモデル比較手法 |
| データ処理 | Best-Fitパッキングによる100%データ利用 |
| ソフトウェア設計 | program.mdによる自然言語エージェント制御 |
15.3 エコシステムの広がり
2025年3月: autoresearch公開
↓
2025年4月: MLXポート、Windows/AMDフォーク登場
↓
2025年5月: AutoResearchClaw（論文自動生成）
↓
2025年6月: Codex Autoresearch（汎用コード最適化）
↓
現在: 多数の派生プロジェクトが活発に開発中
15.4 今後の展望
autoresearchのコンセプトは、以下の方向で進化が期待される：
マルチGPU対応
現在: 単一GPU（H100等）
将来: 複数GPUでの並列実験
→ 異なる仮説を同時に検証
→ より大規模なモデルでの実験
マルチモダリティ
現在: テキスト（LLM訓練）のみ
将来: 画像、音声、マルチモーダルモデルへの拡張
→ Vision Transformer の自動最適化
→ 音声認識モデルの自動改善
メタ学習
現在: 各実験セッションは独立
将来: 過去の実験結果からの学習
→ 「この種の変更は効果がある」パターンの蓄積
→ 実験戦略の自動進化
分散コラボレーション
現在: 個人利用
将来: チームでの共同実験
→ 実験結果の共有プラットフォーム
→ コミュニティベースのブレークスルー発見
15.5 結びの言葉
autoresearchは、「AIが人間の代わりに研究する」という壮大なビジョンの最初の一歩である。Andrej Karpathyの設計哲学—シンプルさ、自己完結性、教育的価値—は、このフレームワークのあらゆる側面に反映されている。
現時点ではML訓練の最適化に焦点を当てているが、そのパターンは「修正→実行→評価→判断」という普遍的なサイクルであり、ソフトウェア開発、科学研究、さらには創造的な作業にまで応用可能である。
autoresearchが示した道筋は、AIと人間の新しい協調関係の始まりを告げるものであり、今後の発展が大いに期待される。
参考リソース
| リソース | URL |
|---|---|
| autoresearch（オリジナル） | https://github.com/karpathy/autoresearch |
| AutoResearchClaw | https://github.com/aiming-lab/AutoResearchClaw |
| Codex Autoresearch | https://github.com/leo-lilinxiao/codex-autoresearch |
| autoresearch-mlx | https://github.com/trevin-creator/autoresearch-mlx |
| MLX Framework | https://github.com/ml-explore/mlx |
| Flash Attention | https://github.com/Dao-AILab/flash-attention |
| uv Package Manager | https://github.com/astral-sh/uv |