# Dengeki プロジェクト方針（v0）

最終更新: 2026-02-22

本ドキュメントは、`docs/dengeki.md` を前提に、実装開始前に合意した「技術スタック」「リポジトリ構造」「v0（まず正しく学習を回す）方針」をまとめたもの。

## 1. 目的

- 目標は、将棋AIの探索不要型（Search-less）学習基盤を段階的に構築すること。
- v0では「強さ最大化」より先に、Phase1-3 の学習ループが破綻せず動作することを最優先とする。
- 推論時（本番）は MCTS を使わず、モデルの forward のみで着手する。

## 2. 技術スタック（決定）

- 言語/環境: Python 3.11+, `uv`
- 学習基盤: PyTorch 2.x（CUDA）, `torchrun`（将来のDDP拡張）
- 将棋処理: `cshogi`
- 探索トレース抽出: `yaneurapy` + 改造版やねうら王
- データ形式: `pyarrow` + Parquet
- 設定管理: Hydra
- ログ/可視化: TensorBoard（必須）, W&B（任意）
- 品質管理: `pytest`, `ruff`, `mypy`

補足: 現在の `pyproject.toml` には `torch`, `cshogi`, `pyarrow`, `yaneurapy` が含まれているため、v0の基盤依存は整合している。

## 3. 推奨プロジェクト構造

```text
Dengeki/
  configs/
    data/
    model/
    train/
    eval/
    runtime/
  docs/
    dengeki.md
    project_blueprint_v0.md
  src/dengeki/
    core/
      types.py
      constants.py
      action_encoding.py
      legal_mask.py
    env/
      shogi_env.py
      feature_builder.py
    engine/
      yaneuraou_client.py
      yaneurapy_bridge.py
      trace_tokenizer.py
    data/
      schema.py
      writer.py
      reader.py
      replay_buffer.py
    models/
      spatial_encoder.py
      mamba_decoder.py
      heads.py
      sms_net.py
    losses/
      policy_value.py
      dynamics.py
      search_trace.py
      ppo.py
    train/
      phase1_generate.py
      phase2_distill.py
      phase3_searchless_rl.py
      loop.py
    eval/
      elo.py
      internal_trace_metrics.py
      ablation.py
    inference/
      searchless_policy.py
      usi_server.py
    utils/
      seed.py
      logging.py
      checkpoint.py
  scripts/
    run_phase1.py
    run_phase2.py
    run_phase3.py
    run_eval.py
  tests/
    unit/
    integration/
  data/
    raw/
    interim/
    processed/
  artifacts/
    checkpoints/
    logs/
    reports/
```

## 4. 設計原則

- 学習を3フェーズで責務分離する。
  - Phase1: 教師探索（MCTS）つきデータ生成
  - Phase2: 探索トレース蒸留 + 世界モデル学習
  - Phase3: 探索レス自己対局RL（PPO系）
- データ契約（スキーマ）を先に固定し、途中で壊さない。
- 推論系は searchless 専用として独立させる。

## 5. 懸念点（実装前に明示）

- 改造版やねうら王・`yaneurapy` のライセンス/配布条件
- USI連携時の探索木トレース抽出粒度の固定
- Action encoding（例: `9x9x122`）の早期凍結
- Parquetスキーマのバージョン管理
- 評価ベースライン（比較相手/設定）の事前定義
- 内部探索トークン語彙の設計（粗すぎ/細かすぎのトレードオフ）
- 再現性（seed, split, checkpoint互換）ルールの固定

## 6. ユーザー回答に基づく v0 方針確定

- 優先順位: まず「正しく学習できること」の確認
- ローカル計算資源: RTX 4070 12GB を24時間利用可能
- クラウド計算資源: RTX 5090 複数機 / A6000 利用可能（ただし v0後に拡張）
- トレース粒度: 初期は最小構成で安定性優先

## 7. v0 実行戦略（12GB最適化）

- まずは単機 RTX4070 で完結する小型構成で立ち上げる。
- モデルは小型SMS-Net（例: hidden 256, block 6-8）。
- mixed precision（bf16/fp16）+ gradient accumulation を前提にする。
- コンテキスト長/探索トークン長は短く開始し、学習成立後に拡張する。

### 7.1 v0 モデル簡略化

- 空間エンコーダ: 軽量Res系（Ryfc要素は最小限）
- 系列部: 小型Mamba（1-2段）
- 出力: `policy`, `value`, `search_trace`
- `dynamics loss` は小さめ重みで開始（例: 0.05-0.1）

### 7.2 v0 データ契約（初期）

最小必須列:

- `schema_version`
- `state_features`
- `legal_mask`
- `action`
- `value_target`
- `return_to_go`
- `search_trace_tokens`
- `next_state_features`（任意）

保存形式: Parquet（train/valid は生成時に固定分割）

実装注記（2026-02-22）:

- `cshogi-src/src/cshogi.h` の `__dlshogi_make_move_label` に合わせ、`action_dim=2187` を採用。
- 根拠は `(MOVE_DIRECTION_NUM=20 + hand_piece=7) * 9 * 9 = 2187`。

### 7.3 v0 探索トレース粒度

初期は軽量に限定:

- `selected_move`
- `pv_topk`
- `root_visit_topk`
- `root_value`

注: ノード全展開ログは v0 では収集しない。

## 8. v0 成功条件（受け入れ基準）

- Phase1 で探索トレース付きデータを安定生成できる
- Phase2 で `policy/value/search_trace` の損失が低下傾向を示す
- `illegal move rate = 0%`
- 100-200局の簡易対局でランダム/単純方策に勝ち越す
- 24h連続学習で NaN, 発散, deadlock が発生しない

## 9. スケール移行条件（v1以降）

以下を満たしたらクラウドへ拡張する:

- v0成功条件を満たす
- データスキーマが凍結されている
- 推論（searchless）が安定完走する

拡張順序:

1. データ量拡張
2. モデル幅/深さ拡張
3. 長コンテキスト化

---

本ドキュメントは v0 の実装基準として扱う。設計変更時は差分を追記し、`schema_version` と合わせて更新する。
