L LLM Labo Mini Transformer Lab

Planned Implementation Plan

この計画は、ChatGPT Hands-on Path で Planned としている章を、実装可能なPR単位に分けたものです。

目的は、商用 ChatGPT と同等の性能を作ることではありません。小さな CPU 実験で、ChatGPT級システムに必要な処理の境界を順番に実装し、何が model weight の問題で、何が runtime / data / evaluation / safety の問題なのかを体感できる状態にすることです。

実装原則

  • 各章は docs/ の解説、src/mini_transformer_lab/ の実装、CLI、テストを同じPRで追加する。
  • 各PRは CPU smoke test で完走するサイズに保つ。
  • Runnable now に変える条件は、コマンド、ソース、テスト、公開ページ導線が揃うこと。
  • heavy dependency は避ける。検索やembeddingは、最初は bag-of-words / cosine などの軽い実装で仕組みを見せる。
  • LLM/AI Expert Reviewer は、P1/P2 が残っている章を Runnable now に上げない。

全体マイルストーン

MilestonePlanned chapters到達状態
M1: Data foundationData pipelinedataset の品質、分割、混合、contamination を見られる
M2: Chat model bridgeChat runtime、Instruction dataset、Minimal SFT、Preference / alignmentbase LM と assistant behavior の違いを実験できる
M3: Reasoning and retrievalModel-backed reasoning、RAG + evalmodel 出力、外部 verifier、外部文書検索を分けて扱える
M4: Agent product layerTool use、Agent loop、Serving / observabilitytool 権限、実行ループ、API、ログ、評価を接続できる

M1: Data pipeline

対象: Status: Runnable now の data pipeline

追加するユーザー体験:

Terminal window
uv run mini-transformer-prepare-data --input data/natural/tiny.txt --output-dir runs/data-natural --dedupe --splits 0.8,0.1,0.1
uv run mini-transformer-mixture-report --natural data/natural/tiny.txt --code data/code/tiny.py.txt --ratio 0.7,0.3
uv run mini-transformer-contamination-check --train runs/data-natural/train.txt --eval data/eval/tiny_prompts.txt

追加予定ファイル:

  • src/mini_transformer_lab/data_pipeline.py
  • src/mini_transformer_lab/dataset_mixture.py
  • data/eval/tiny_prompts.txt
  • tests/test_data_pipeline.py
  • docs/DATA_PIPELINE_HANDS_ON.md

完了条件:

  • raw text を train/valid/test に分割できる。
  • 重複行を除外できる。
  • natural / code の混合比をレポートできる。
  • eval prompt の training contamination を検出できる。
  • docs/CHATGPT_HANDS_ON_PATH.md の data pipeline を Runnable now に更新できる。

実装状態:

  • mini-transformer-prepare-data
  • mini-transformer-mixture-report
  • mini-transformer-contamination-check
  • Data Pipeline Hands-on

何に影響するか:

  • validation loss の信頼性。
  • code / natural language の出力傾向。
  • 暗記と汎化の見分け方。
  • 評価データが混ざったときに「良く見える」危険の理解。

M2-1: Chat template / runtime

対象: Status: Planned の chat template と chat runtime

追加するユーザー体験:

Terminal window
uv run mini-transformer-chat --run runs/natural-char --system "簡潔に答える assistant です" --user "Transformerとは?"
uv run mini-transformer-chat --run runs/natural-char --history runs/chat-history.jsonl --max-context 128

追加予定ファイル:

  • src/mini_transformer_lab/chat_template.py
  • src/mini_transformer_lab/chat_runtime.py
  • src/mini_transformer_lab/chat.py
  • tests/test_chat_template.py
  • tests/test_chat_runtime.py
  • docs/CHAT_RUNTIME_HANDS_ON.md

完了条件:

  • system / user / assistant role を1つの prompt text に直列化できる。
  • message history を保持できる。
  • context length を超える履歴を切り詰められる。
  • system prompt が model weight ではなく input structure であることをドキュメントで明示する。

何に影響するか:

  • 会話の一貫性。
  • system / user / assistant の役割理解。
  • context window による忘却。
  • tool result や検索結果を untrusted text として扱う準備。

M2-2: Instruction dataset

対象: Status: Planned の instruction tuning 用の最小データ

追加するユーザー体験:

Terminal window
uv run mini-transformer-show-instructions --file data/instruction/tiny.jsonl
uv run mini-transformer-render-chat-dataset --file data/instruction/tiny.jsonl --template simple

追加予定ファイル:

  • data/instruction/tiny.jsonl
  • src/mini_transformer_lab/instruction_data.py
  • tests/test_instruction_data.py
  • docs/INSTRUCTION_DATA_HANDS_ON.md

完了条件:

  • prompt -> response の JSONL dataset を読める。
  • chat template に変換できる。
  • assistant response 部分の token span を特定できる。
  • base pretraining data と instruction data の違いを説明できる。

何に影響するか:

  • 「続きを書くmodel」と「指示に答えるassistant」の違い。
  • loss をどの token にかけるか。
  • system / user / assistant 形式の意味。

M2-3: Minimal SFT

対象: Status: Planned の Minimal SFT

追加するユーザー体験:

Terminal window
uv run mini-transformer-train-sft --dataset data/instruction/tiny.jsonl --tokenizer char --steps 120 --output-dir runs/sft-char
uv run mini-transformer-chat --run runs/sft-char --user "挨拶して"

追加予定ファイル:

  • src/mini_transformer_lab/train_sft.py
  • src/mini_transformer_lab/sft_loss.py
  • tests/test_sft_loss.py
  • docs/SFT_HANDS_ON.md

完了条件:

  • assistant response token だけを loss 対象にできる。
  • pretraining checkpoint から追加学習できる。
  • tiny dataset でも base model と SFT model の出力差を観察できる。
  • 過学習しやすいことを validation と生成例で示す。

何に影響するか:

  • 指示追従の基礎。
  • prompt engineering と training objective の区別。
  • 小さい dataset の過学習リスク。

M2-4: Preference / alignment

対象: Status: Planned の preference / alignment

追加するユーザー体験:

Terminal window
uv run mini-transformer-show-preferences --file data/preference/tiny_pairs.jsonl
uv run mini-transformer-train-preference --file data/preference/tiny_pairs.jsonl --output-dir runs/preference-scorer
uv run mini-transformer-rank-responses --prompt "危険な依頼をされたら?" --candidates data/preference/sample_candidates.jsonl

追加予定ファイル:

  • data/preference/tiny_pairs.jsonl
  • src/mini_transformer_lab/preference_data.py
  • src/mini_transformer_lab/preference_scorer.py
  • src/mini_transformer_lab/preference_cli.py
  • tests/test_preference_data.py
  • tests/test_preference_scorer.py
  • docs/PREFERENCE_ALIGNMENT_HANDS_ON.md

完了条件:

  • chosen / rejected response pair を扱える。
  • helpful / harmless / honest の観点を toy label として持てる。
  • DPO風または scorer ranking の最小実装を説明できる。
  • SFT と preference/alignment が別段階であることを明確にできる。

何に影響するか:

  • assistant behavior の好ましさ。
  • refusal と通常回答の境界。
  • 安全性を prompt 文言だけでなく data / objective / eval として扱う理解。

M3-1: Model-backed reasoning

対象: Status: Planned の Model-backed reasoning

追加するユーザー体験:

Terminal window
uv run mini-transformer-reason-with-model --run runs/sft-char --prompt "8 * 6 - 5" --samples 5 --verifier arithmetic

追加予定ファイル:

  • src/mini_transformer_lab/model_reasoning.py
  • src/mini_transformer_lab/verifiers.py
  • tests/test_model_reasoning.py
  • docs/MODEL_REASONING_HANDS_ON.md

完了条件:

  • model が複数候補を生成する。
  • external verifier が候補を採点する。
  • 既存の deterministic controller simulator と model-backed reasoning の違いを明示する。
  • reasoning effort が samples / max tokens / verifier passes にどう対応するかを説明する。

何に影響するか:

  • latency。
  • token budget。
  • 正答率と候補数の関係。
  • model の内部推論と外部 controller の区別。

M3-2: RAG + eval

対象: Status: Planned の RAG + eval

追加するユーザー体験:

Terminal window
uv run mini-transformer-index-docs --docs data/docs/tiny_knowledge.md --output-dir runs/rag-index
uv run mini-transformer-rag-answer --index runs/rag-index --question "このlabの目的は?"
uv run mini-transformer-rag-eval --index runs/rag-index --questions data/eval/rag_questions.jsonl

追加予定ファイル:

  • data/docs/tiny_knowledge.md
  • data/eval/rag_questions.jsonl
  • src/mini_transformer_lab/rag_index.py
  • src/mini_transformer_lab/retrieval.py
  • src/mini_transformer_lab/rag_answer.py
  • src/mini_transformer_lab/rag_eval.py
  • tests/test_retrieval.py
  • tests/test_rag_eval.py
  • docs/RAG_HANDS_ON.md

完了条件:

  • document chunking ができる。
  • bag-of-words / cosine の軽量検索ができる。
  • retrieved chunk を chat context に入れられる。
  • retrieval precision / recall と grounding mismatch を小さく測れる。
  • retrieved text を instruction ではなく untrusted context として扱う。

何に影響するか:

  • model weight にない情報を扱う方法。
  • retrieval quality と回答品質の関係。
  • prompt injection への境界設計。
  • citation と grounding の信頼性。

M4-1: Tool use

対象: Status: Planned の Tool use

追加するユーザー体験:

Terminal window
uv run mini-transformer-tool-call --tool calculator --input '{"expression":"8*6-5"}'
uv run mini-transformer-tool-demo --prompt "8 * 6 - 5 を計算して" --allow-tool calculator

追加予定ファイル:

  • src/mini_transformer_lab/tools.py
  • src/mini_transformer_lab/tool_schema.py
  • src/mini_transformer_lab/tool_runtime.py
  • tests/test_tool_schema.py
  • tests/test_tool_runtime.py
  • docs/TOOL_USE_HANDS_ON.md

完了条件:

  • tool schema を定義できる。
  • model text から tool call 候補を検査できる。
  • schema validation、allowlist、timeout、read-only / side-effectful の区別を実装できる。
  • tool result を命令ではなく observation として戻せる。

何に影響するか:

  • model capability と外部権限の分離。
  • prompt injection 耐性。
  • side effect の安全管理。
  • agent loop の基礎。

M4-2: Agent loop

対象: Status: Planned の Agent loop

追加するユーザー体験:

Terminal window
uv run mini-transformer-agent --task "tiny docsから目的を調べて要約" --tools retrieve,calculator --max-steps 4

追加予定ファイル:

  • src/mini_transformer_lab/agent_loop.py
  • src/mini_transformer_lab/agent_state.py
  • src/mini_transformer_lab/agent_trace.py
  • tests/test_agent_loop.py
  • docs/AGENT_LOOP_HANDS_ON.md

完了条件:

  • observe -> decide -> act -> observe の loop を持つ。
  • max steps、retry limit、timeout を持つ。
  • tool call、tool result、final answer を trace として保存できる。
  • side-effectful tool はデフォルト無効にする。

何に影響するか:

  • 単発回答と agent の違い。
  • loop が暴走するリスク。
  • trace によるdebugと評価。
  • MCPや外部tool連携へ進むための設計。

M4-3: Serving / observability

対象: Status: Planned の Serving / observability

追加するユーザー体験:

Terminal window
uv run mini-transformer-serve --run runs/sft-char --host 127.0.0.1 --port 8080
uv run mini-transformer-eval-suite --questions data/eval/tiny_chat_eval.jsonl --endpoint http://127.0.0.1:8080/chat
uv run mini-transformer-log-summary --log runs/server/events.jsonl

追加予定ファイル:

  • data/eval/tiny_chat_eval.jsonl
  • src/mini_transformer_lab/server.py
  • src/mini_transformer_lab/eval_suite.py
  • src/mini_transformer_lab/observability.py
  • tests/test_server.py
  • tests/test_eval_suite.py
  • docs/SERVING_OBSERVABILITY_HANDS_ON.md

完了条件:

  • local HTTP endpoint で chat request を受けられる。
  • streaming は最初は concept note とし、最小実装後に追加する。
  • request id、latency、tokens、tool calls、errors を JSONL log に残せる。
  • 固定質問セットで回答を比較できる。

何に影響するか:

  • product boundary。
  • latency と cost の見積もり。
  • failure analysis。
  • model / prompt / retrieval / tool / runtime のどこを直すべきかの切り分け。

PR順序

PR範囲主要コマンドReview gate
1Data pipelinemini-transformer-prepare-datacontamination と split が説明されている
2Chat runtimemini-transformer-chatrole と context truncation が明確
3Instruction dataset + SFTmini-transformer-train-sftresponse-only loss がテストされている
4Preference / alignmentmini-transformer-train-preferenceSFT と alignment を混同していない
5Model-backed reasoningmini-transformer-reason-with-modelcontroller simulator との違いが明確
6RAG + evalmini-transformer-rag-evalretrieval と grounding の評価がある
7Tool usemini-transformer-tool-demoschema validation と権限境界がある
8Agent loopmini-transformer-agentstep limit と trace がある
9Serving / observabilitymini-transformer-servelogs と eval suite がある

各PRの共通チェックリスト

  • devbox run lint
  • devbox run test
  • npm run site:build
  • 新CLIを追加した場合は devbox run build
  • 該当docsの公開ページまたは生成HTMLに導線がある
  • docs/CHATGPT_HANDS_ON_PATH.md の status が実態と一致している
  • .agents/llm-ai-expert-reviewer.md の観点で P1/P2 が残っていない