zxell.ai ロードマップ(清書版 v2)

作成日: 2026-08-12(改訂: 2026-09-05 = 10 章、2026-10-04 = 11 章)原本: ロードマップ整理資料(2026-08-10)本書は原本に、その後の決定事項(review01〜08 の往復)とフェーズ0 実測値を反映して清書したもの。

1. プロジェクト目的と成功基準

1.1 目的(3 層)

モデル層: ニュースコーパス(英独仏日・約 800 万記事)を学習した言語モデルをイチから作る(事前学習済みモデルは使わない。モデルは自前実装、PyTorch 等の基盤利用は許容 — 確定)。
分散層: 低スペックなクライアント複数台に処理を分散させ、ハイエンド GPU なしで学習を成立させる。
知見層: 「どのくらいの知能になったか」を体験・計測し、データ量 × 計算量 × 分散方式 → 能力の関係を定量的な知見として得る。

成果物は「モデルそのもの」だけでなく 「低予算・分散環境でどこまで到達できるかの定量的知見」。比較対象(単一マシンベースライン)と計測方法を最初から設計に組み込む。

1.2 成功基準

区分	指標	目標イメージ
モデル能力	検証パープレキシティ(言語別)	単一マシン学習の同規模モデル比で劣化 10% 以内
モデル能力	要約品質(ROUGE-L / BERTScore + 人手)	記事+付属要約(description)ペアで定量評価
モデル能力	コーパス内事実の QA	自作 QA セットで正答率を計測
分散効率	台数スケーリング	台数に対するスループット曲線を取得
分散効率	通信量 / 学習トークン	同期式データ並列比 1/100 以下
運用	離脱耐性	任意クライアントが落ちても学習継続
可視化	運用ダッシュボード	タスク・クライアント・損失・スループットを表示(管理者用)

2. 確定事項(決定ログ)

review01〜08 で確定した方針。以後の設計はこれを前提とする。

#	項目	決定内容	出典
1	法務方針	closed 運用(クライアントは自己管理端末に限定)/ 配布はトークン化・シャッフル・パック済みシャードのみ / 法的整理まで不特定多数の募集はしない	review01
2	初期クライアント	Windows 2 台(NVIDIA GeForce GTX 1050, VRAM 2GB × 2)。進捗を見て追加検討	review01, 08
3	中央サーバ	自前(現マシン)。`https://api.zxell.ai` で公開済み(省略: 公開経路の構成)	review04〜08
4	モデル規模	S(≈30M)/ M(≈125M)/ L(≈500M)の 3 段階。最終目標は L: 500M	review01
5	画像	第 1 期は学習対象外(棚卸しのみ実施済み。第 2 期候補)	review01, 03
6	公開範囲	コードのみ公開(GitHub `zxell-ai/zxell` を public 化予定)。学習可視化・重み・データは管理者/開発者用	review01, 08
7	リポジトリ構成	モノレポ。`zxell_server/` + `zxell_client/`(予定)。非公開フォルダは Git 管理外	review02, 08
8	データソース	MySQL の `feed_items` を直接読む(スナップショットは取らない)。content_alive/content_locked は無視して全件対象	review03, phase0
9	フィールドの使い方	本文=content_text、要約=description、言語=feed_channels.language 先頭 2 文字。title は varchar(100) 切り詰めのまま使用	review03
10	重複除去	主キー = link(補助 = guid。guid は 21.6% 空欄)	review03, phase0
11	日本語の扱い	自然比率で全言語混合 + 日本語のみ title+description+content_text を連結(他言語は content_text のみ)	phase0
12	ストレージ	(省略: サーバ上の保存場所)	review02, phase0, 2026-10-02
13	認証	クライアント登録は承認制(pending→approved)。`/api/status` 含む全 API に認証	review02, 03
14	公開範囲	コード+開発記録(編集版)を公開(review01 の「コードのみ」から拡大)。開発記録は reviews を原文尊重・削るだけで編集し、サーバ運用・障害対応・セキュリティ情報・コーパスの詳細・個人的事情を省く。法務は決定事項のみ。重み・データ統計・ダッシュボードは非公開のまま。公開先 https://zxell.ai/devlog/	devlog_publish_plan.md, 2026-10-02
15	トークナイザ	SentencePiece BPE・語彙 48k を採用(64k はトークン数を 3% 減らすだけで、S モデルの埋め込みが 33% 太る)	review13, 19
16	train/val/test の分割	言語別・記事数ベース: 各言語の新しい側から test 8,000 記事、その直前 val 3,000 記事、残りを train(全言語共通の日付で切ると val/test が日本語だけになるため)	review20
17	シャード	1 シャード = 5,000 万トークン固定(uint16 で約 100MB)。train は記事単位でシャッフルしてから切る(どのシャードも言語比率が全体とほぼ同じ)	review22
18	フェーズ 1→2 の段取り	フェーズ 1 = RTX 3060 単独の S ベースライン(比較の物差し。シャード取得は API 経由)→ フェーズ 2 = 同じ S を API 配布で 3060 + 1050 の FedAvg	review22

3. 定量前提(フェーズ0 実測で更新)

3.1 コーパス実測値(2026-08-11 棚卸し。詳細: フェーズ0 データ棚卸しレポート)

総記事 7,986,288 件 / link 重複除去後の実効 約 757 万件
本文 26.2G 文字(重複除去後 ≈ 24.8G 文字)
トークン概算 ≈ 6.5G(65 億)トークン(欧文 ≈4 字/トークン、和文 ≈1 字/トークン)
言語構成: en 49.9% / de 25.5% / fr 14.0% / ja 10.6%(ただし文字数では ja は 1.5%。本文が平均 472 字と短いため)
本文欠損は全体 1% 未満と良好。category は ja 100%・en 57% 欠損(分類系タスクは de/fr 中心)
link/guid に改行 11,069 件・タブ 301 件 → 前処理で正規化必須

原本の見積り(実効 6〜9B トークン)は 6.5B で実測確定。作業仮説からの修正は不要。

3.2 トークン数 → モデル規模

Chinchilla 則(パラメータ ≒ トークン ÷ 20)では 6.5B トークンの計算最適は ≈300M。
最終目標 L: 500M は計算最適よりやや大きいが、複数エポック(2〜3 周)は小規模データでは一般的であり許容範囲。方針(3 サイズ)は維持:

サイズ	パラメータ	構成(目安)	ctx	役割
S	≈30M	6 層 / d=384 / 6 head	1024	パイプライン検証・スモーク・教材化
M	≈125M	12 層 / d=768 / 12 head	1024	分散方式の比較実験の主力
L	≈500M	24 層 / d=1280 / 20 head	2048	最終ターゲット(全データ)

語彙 48k〜64k の多言語 BPE、埋め込みと LM Head は重み共有。

3.3 計算量の再試算(GTX 1050 2GB × 2 台前提)【原本から下方修正】

GTX 1050 は FP32 ピーク ≈1.8 TFLOPS・Tensor Core なし。MFU 30% として実効 ≈0.5 TFLOPS/台(原本の想定「実効 4 TFLOPS のミドル GPU」の約 1/8)。学習 FLOPs ≒ 6 × パラメータ × トークン。

モデル	トークン	総FLOPs	2 台(実効 1 TFLOPS 合算)
S: 30M	3B	5.4e17	約 6 日
M: 125M	6.5B	4.9e18	約 57 日
L: 500M	6.5B	2.0e19	約 230 日(非現実的)

さらに VRAM 2GB の制約:

S(30M): fp16 + AdamW でも余裕。現有 2 台の主力ターゲット。
M(125M): 重み+optimizer 状態で 2GB をほぼ使い切る。勾配チェックポインティング + 8bit optimizer(または optimizer 状態の CPU 退避)+ 小バッチ勾配蓄積で「載るが遅い」。
L(500M): 2GB では学習不可(推論は fp16 ≈1GB で可)。

結論: 現有 2 台では S を完走させ分散方式の実証まで行う。M の本格比較実験・L の本番学習は GPU クライアントの増強(VRAM 6GB 以上を数台)が前提。これは原本 2.3 の結論「L は分散なしでは非現実的」をさらに強めるもので、フェーズ 3→4 のゲート条件に台数を明記する(6 章)。

3.4 通信量

500M の勾配 fp16 ≈1GB。同期式データ並列は家庭用回線で不成立(原本どおり)。ローカル H ステップ → 差分(擬似勾配)低頻度送信 + 8bit 量子化 + Top-k スパース化で 1/100〜1/500 に圧縮し、30〜60 分に 1 回の同期で運用する方針を維持。

4. アーキテクチャ

4.1 全体構成(ハブ&スポーク。稼働中の実体で更新)

[中央サーバ]  https://api.zxell.ai
  (省略: 公開経路の構成)
  ├─ コーディネータ API(FastAPI): 登録承認 / タスク払い出し(リース) / 結果受領
  ├─ パラメータサーバ: weight_versions(checksum 付き)+ 外側最適化(実装予定)
  ├─ ストレージ(シャード・重み・成果物 Δ)
  ├─ PostgreSQL 16: clients / tasks / results / weight_versions
  └─ ダッシュボード(実装予定。/api/status ベース・管理キー式)

[クライアント](当面 Windows 2 台・GTX 1050 2GB)
  ├─ GPU ワーカー: 重み GET → シャード GET → ローカル H ステップ → Δ を POST
  └─ CPU ワーカー: preprocess / eval / verify タスク

4.2 サーバ実装状況(原本 3.6 の 8 項目 → 全項目実装・コミット済み)

リース付き払い出し(FOR UPDATE SKIP LOCKED、期限切れ自動再キュー、max_attempts)、結果永続化(metrics JSON + 成果物ファイル)、承認制クライアント認証(X-API-Key)+ 管理 API(X-Admin-Key)、環境変数設定(pydantic-settings・必須化)、Pydantic v2、重みバージョン管理・配布、シャード配布。タスク種別は preprocess / train / eval / verify。 train の結果には base_weight_version 必須(ステイルネス対策の前提)。実 PostgreSQL でスモークテスト 15 項目 + 認証ヘッダ欠落 2 項目に合格済み。

4.3 分散学習方式(原本 3.2 の推奨を維持)

DiLoCo 型(Local SGD + 外側 Nesterov モーメンタム)を本命とし、段階導入する: FedAvg(単純平均)で MVP → 外側最適化 → Δ 圧縮(8bit / Top-k)。方式の差し替えによる品質変化そのものが本プロジェクトの知見となる。非 IID 対策(シャードのランダム割当で全クライアントが全言語を見る)、ステイルネス対策(基準重みバージョン添付・減衰・破棄)も原本どおり。

4.4 クライアント v1(次の実装対象)

対象環境: Windows ネイティブ(Python + PyTorch CUDA)。GTX 1050(Pascal, sm_61)は現行 PyTorch の CUDA ビルドでサポート内。
ループ: 登録 → 承認待ちポーリング → タスク取得 → 処理 → 結果提出。リトライ・リース期限内の心拍を実装(省略: 回線に関する補足)。
初回登録時に簡易ベンチ(GPU/CPU・VRAM・回線)を自己申告し、タスク種別と H を調整。
結果検証(Δ ノルム外れ値検知 → 抜き打ち二重計算 → 信頼スコア)はフェーズ 3 で実装。

5. データパイプライン(フェーズ0 の発見を反映)

正規化: link/guid の改行・タブ除去(実測 1.1 万件)、文字コード正規化、HTML 残骸確認。
重複除去: link 主キー(重複 5.3%)、guid 補助。MinHash/SimHash の近似重複除去は通信社配信の重複対策としてフェーズ 1 で効果を計測してから採否を決める。
日本語の連結: ja のみ title + description + content_text を連結(確定事項 11)。
トークン化 → シャーディング: 多言語 BPE(48k〜64k)→ 固定長パック(1024/2048)→ 数十〜数百 MB のシャード + checksum + メタデータ(言語構成・トークン数)。置き場所: サーバのストレージ。
分割: 時系列を考慮(最終数か月をテストに回し「新しい記事の要約」評価を自然に行う)。
前処理自体を preprocess タスクとして分散させ、分散基盤の最初の実運用テストとする。

省略: サーバのディスクに関する注意(サーバ運用)

6. フェーズ計画(作成時点の現在地: フェーズ0 完了。最新は 11 章)

フェーズ 0: 定量把握と法務整理 — ✅ 完了(2026-08-11)

データ棚卸し完了(phase0_inventory.md)。法務方針は closed 運用で確定(確定事項 1)。
サーバ改修・公開(https://api.zxell.ai)(省略: 運用の詳細)まで完了(前倒し)。

フェーズ 1: 単一マシンベースライン(3〜6 週間)← 次はここ

トークナイザ学習(多言語 BPE 48k〜64k、日本語圧縮効率の検証込み)
前処理パイプライン v1(5 章)→ シャード生成
S モデル(30M)を単一 GPU(GTX 1050)で学習し、損失曲線・生成品質のベースラインを記録
評価ハーネス(パープレキシティ・ROUGE・QA 雛形)
判断ポイント: S がまともな文を生成し、評価が自動で回ること
※ 実行環境注: ベースラインはクライアント予定機(Windows/GTX 1050)上で実施。サーバ機は GPU なしのため、学習はクライアント側・集約はサーバ側の役割分担が最初から必要

フェーズ 2: 分散基盤 MVP(4〜8 週間)

クライアント v1(4.4)/ 運用ダッシュボード v1(管理キー式)
FedAvg による S モデルの分散学習を 2 台で成功させる
判断ポイント: 1 台落としても学習継続、単一マシン学習と同等の損失に到達

フェーズ 3: 低通信方式の実装と比較実験(4〜8 週間)

DiLoCo 型(外側 Nesterov)+ Δ 圧縮(8bit / Top-k)、検証機構(外れ値・検算・信頼スコア)
M モデルで方式比較 → 中間レポート
判断ポイント: 通信 1/100 で品質劣化 10% 以内、かつ VRAM 6GB+ の GPU クライアントを数台確保できる見込みが立つこと(3.3 の再試算による追加ゲート)

フェーズ 4: 本番学習と体験系(6〜12 週間)

L モデル(500M)の全データ分散学習(チェックポイント定期保存)
要約 SFT(記事+description ペア)、推論 API・デモ UI、QA 評価、チェックポイント考古学、モデル内部可視化(Spreadsheets 系譜の体験 UI)
判断ポイント: 成功基準(1.2)の計測完了

フェーズ 5: 知見の公開と拡張判断

技術レポート(分散方式比較・スケーリング曲線・多言語の学び)
拡張判断: 参加者公募(法務整理済みなら)、画像対応(メイン画像は 9 割の記事に実在 — フェーズ0 実測)、ブラウザ(WebGPU)クライアント等

7. リスク(主要なもの。原本 5 章から現状に合わせ更新)

リスク	現状評価	対応
記事本文の再頒布(著作権)	closed 運用 + トークン化シャード配布で当面回避(確定)	open 化の際に再整理。コード公開はデータと分離済み
VRAM 2GB 制約	顕在化(3.3)。M 以上は現有機で困難	S で実証 → GPU 増強をフェーズ 3 ゲートに設定
非 IID・ステイルネス	未検証	シャードランダム割当・バージョン添付減衰(フェーズ 2〜3)
不正・故障クライアント	当面は自己管理端末のみで低リスク	検証機構はフェーズ 3 で実装
学習の発散(低頻度同期)	未検証	S/M でハイパラ探索してから L(段取り厳守)
再現性	—	シード・割当・Δ 履歴の完全ログ化

省略: 表の 2 行(回線とサーバのディスクに関するリスク)

8. 公開方針(確定事項 6 の具体化)

GitHub zxell-ai/zxell を public 化。公開対象はコードのみ: zxell_server/、zxell_client/(今後)、README(英語)、CLAUDE.md、LICENSE(GPL-3.0)。
非公開フォルダ(計画書・レビュー・レポート・生データ統計)は Git 管理外を維持(.gitignore に明記)。重み・シャード・DB は公開しない。
コミット履歴に実クレデンシャルが無いことは確認済み(初期コミットの DB URL はプレースホルダーのみ)。

9. 参考文献

DiLoCo / Local SGD / FedAvg / Branch-Train-Merge / Hivemind / Petals / BOINC / Chinchilla / nanoGPT / Spreadsheets are all you need(原本 8 章と同一)。

10. 2026-09-05 改訂: 新サーバ移行とクライアント体制の変更

10-1. 起きたこと(review16〜18 とその後)

旧サーバの RAM 物理故障(review17 で確定)→ AMD Ryzen 3 4300U / 16GB の新サーバへ移行完了。 memtest 4 パス合格。(省略: 復旧したサービスの一覧)
(省略: 旧サーバのディスク故障の詳細)稼働 MySQL は喪失した。ただしコーパス原本(2025-03-30 のバックアップ)はバックアップコピーが sha256 完全一致で生存。以後の正はこのファイル(+ 二重化コピー)。
確定事項 8(「MySQL を直接読む」)は失効。データソースは parse_dump.py によるスナップショット(検証つき JSONL)に一本化した。extract_sample.py もスナップショット読みに改修済み。

10-2. クライアント体制(確定事項 2 の更新)

RTX 3060(12GB, Ubuntu Server)+ GTX 1050(2GB, Windows)の 2 台。 (1050 の 1 台は退役し、代わりに 3060 を調達。3060 も memtest 済み)

学習対象	旧見積(1050×2)	新体制
S (30M)	約 6 日	3060 単独約 1 日 / 分散実験は 3060+1050
M (125M)	約 57 日(2GB に辛うじて載る)	3060 単独約 1 週間(1050 には載らない)
L (500M)	約 230 日(非現実的)	3060 単独約 1 か月 — 実現可能に

フェーズ 3 のゲート条件「VRAM 6GB+ のクライアント確保」は達成済み。 L(500M)の本番学習が現実のスケジュールに乗った。
分散実験の主戦場は S スケール(1050 の VRAM 制約)。3060:1050 は速度比 ~15:1・VRAM 比 6:1 の極端なヘテロ構成であり、「クライアントごとに局所ステップ数 H を変える DiLoCo」という現実の分散環境(BOINC 的)に近い研究題材になる。M/L は 3060 が学習主体、 1050 は S の分散実験 + eval/preprocess 担当。

10-3. フェーズ 1 の再構築状況(2026-09-05 時点)

故障 RAM 機の work/ 産物は全て破棄し、新サーバで作り直した:

スナップショット再生成: 7,969,236 件・書き込み後検証合格(統計は 8/13 実行と完全一致)
サンプル抽出・トークナイザ 48k/64k 学習・比較: 完了。採用は 48k(推定 6.14B トークン)。 chars/token は 8/13 の結果と小数第 3 位まで一致(数値の再現性を確認)
分割境界の実測: コーパスの pub_date は 2024-02-12 で終端(終盤は約 2,700 件/月に先細り)。 test = 2023-11-13 以降 / val = 2023-10-14 以降。test ≈ 7 千記事・val ≈ 2.7 千記事
全量トークン化+シャード化: 実行中

次: S(30M)モデル実装 → 3060 での単一 GPU ベースライン(フェーズ 1 完了判定)。

11. 2026-10-04 改訂: フェーズ 1 の前処理の確定と S モデルの実装

11-1. シャード v2 — 分割方式の変更と日本語の重複除去(2026-09-27、review19〜21)

9/5 に作った v1(125 シャード・6.152B トークン。全言語共通の時系列境界)は、val/test が 100% 日本語になっていた。原因は収集の終了時期の違い: en/de/fr は 2023-05-28 に同日で停止、ja だけ 2024-02-12 まで続いていた。 10-3 の境界(test = 2023-11-13 以降 / val = 2023-10-14 以降)は失効
分割を言語別・記事数ベースに変更(確定事項 16、compute_boundaries.py)。4 言語の val/test が同じ大きさで揃い、 train から失うのは言語あたり 0.3〜1.3%

言語	最終 pub_date	test 開始	val 開始
en	2023-05-28	2023-05-24	2023-05-23
de	2023-05-28	2023-05-21	2023-05-18
fr	2023-05-28	2023-05-13	2023-05-09
ja	2024-02-12	2023-11-21	2023-10-19

ja 連結の重複除去(textprep.compose_ja): title や description が本文の冒頭と重複していれば連結しない。 ja 記事の 87.5% で title が重複していた。ja の文字数 −12%、train トークンは 0.23B → 0.197B(約 −14%)
clean() に HTML タグ除去と文字実体参照の復号を追加(タグ入り本文は 0.005% と小規模)
v2 の結果(検証済み。抜き打ち sha256 一致・異常 0):

分割	シャード	トークン	記事数	言語構成(トークン)
train	122	6.068B	7,448,909	en 64.8% / de 21.9% / fr 10.0% / ja 3.2%
val	1	10.2M	11,129	en 61.2% / de 14.1% / fr 14.0% / ja 10.7%
test	1	27.2M	30,171	en 60.1% / de 14.7% / fr 14.3% / ja 10.9%
合計	124	6.106B	7,490,209

留意点: en/de/fr の val/test は期間が狭い(en の test は最後の 4 日間)。S モデルの評価で違和感が出たら、期間を広げて記事数上限でサンプリングする方式に改める

11-2. モデル本体の実装(2026-09-29、review22〜23)

zxell_model/ にモデル本体と学習・評価・生成コードを実装した(RMSNorm・RoPE・causal Self-Attention・SwiGLU・埋め込みと LM Head の重み共有。AdamW・warmup + cosine・bf16・チェックポイント/再開・言語別パープレキシティ評価)。

preset	層 / d_model / head / ctx	パラメータ	うち非埋め込み
S	6 / 384 / 6 / 1024	29.1M	10.6M
M	12 / 768 / 12 / 1024	121.8M	85.0M
L	24 / 1280 / 20 / 2048	537.3M	475.9M

サーバ機(CPU)での極小構成のスモーク(学習 → 再開 → 言語別 PPL 評価 → 生成)に合格
フェーズ 1 でもシャードは手元コピーではなく API(GET /api/shards/{name})で取得し、sha256 を照合する(fetch_shards.py)。配布経路を最初から通すため。実証済み
フェーズ 1 のベースラインは、6 章の記述(GTX 1050)から RTX 3060 での実施に変更

11-3. S ベースラインの計画とフェーズ 2 への段取り(確定事項 18)

項目	値
構成	S(29.1M)、batch 32 × ctx 1024 = 32,768 トークン/ステップ
学習量	90,000 ステップ ≈ 2.95B トークン(train の約半分)
所要(見込み)	RTX 3060 で約 1 日(約 35,000〜40,000 トークン/秒)
評価	500 ステップごとに val の言語別 PPL、終了時に val 全量。完了後に test

フェーズ 2 では同じ S を API 配布で 2 台(3060 + 1050)の FedAvg にかける。1 シャード(5,000 万トークン)の処理は 3060 で約 21 分、1050 で約 5 時間かかりリース(1 時間)を超えるため、1050 向けのタスクはシャードのトークン範囲で細かく切る。

11-4. 公開(確定事項 14 の実施)

2026-10-02: 開発記録(https://zxell.ai/devlog/)を公開
2026-10-04: フェーズ別まとめ資料(https://zxell.ai/reports/、英語・日本語)を作成。各コンポーネントの README を英語・日本語の 2 本立てに

11-5. 現在地(2026-10-04): フェーズ 1 進行中

フェーズ 1 の項目	状態
トークナイザ(48k)	完了
前処理パイプライン・シャード(v2)	完了
S/M/L モデルと学習・評価コード	完了(CPU スモーク合格)
評価ハーネス	言語別パープレキシティは実装済み。ROUGE・QA は未着手
S ベースライン学習(RTX 3060)	未着手(3060 機のセットアップ・クライアント登録から)

残り: 3060 機のセットアップ → S ベースライン学習(約 1 日)→ test の言語別 PPL と生成サンプルの確認 → フェーズ 1 の完了判定(「S がまともな文を生成し、評価が自動で回ること」)→ フェーズ 2(クライアントの train タスクを本物の局所学習に置き換え、2 台で FedAvg)。