minimind — ゼロから自作して学ぶ超軽量LLMの学習・実装フレームワーク
jingyaogong/minimind
★ 66,080 ・ Python ・ Apache-2.0
概要
minimind は、個人の手元にある一般的なGPU環境を利用して、ゼロから超小型の大規模言語モデル(LLM)を構築・学習できるように設計されたオープンソースプロジェクトです。最新の主線モデルである「minimind-3」では、パラメータ規模を約64M(MoE版で約198M、アクティブ64M)という極小サイズに抑えることで、学習にかかる時間と計算コストを大幅に削減しています。
既存の多くの解説やツールは、transformers や peft、trl といった高度に抽象化されたライブラリを介して既存モデルのファインチューニングを行う手法が中心です。それに対し、minimind はブラックボックス化された高層APIに頼らず、PyTorchのコードベースから直接モデルアーキテクチャや訓練ロジックを実装しています。LLMが実際にどのようなコードとデータパイプラインによってゼロから構築され、対話や推論、強化学習を経て動作していくのかを、自分の手でコードを追体験しながら深く理解したい開発者や学生に向いています。
主な特徴
- PyTorchネイティブによるフルスクラッチ実装 モデル構造の定義をはじめ、LoRA、RLHF(DPO)、RLAIF(PPO / GRPO / CISPO)などの主要アルゴリズムをサードパーティ製ラッパーに依存せずPyTorchのみで記述しており、内部動作を直接把握できます。
- 極めて軽量なモデル規模 GPT-3と比較して約2,700分の1とされる約64Mパラメータ(Dense版)を主線としており、単一の個人用GPU(NVIDIA RTX 3090など)でも事前学習やSFT(教師あり微調整)を短時間で実行可能です。
- 包括的な学習パイプラインを網羅 データクレンジング、事前学習(Pretrain)、指示微調整(Full SFT / LoRA)、モデル蒸留、RLHF/RLAIF、ツール呼び出し(Tool Use)、そしてマルチターン推論環境を想定したAgentic RLまでの一連の訓練スクリプトを同梱しています。
- 最新アーキテクチャ・機能への追従
Qwen3 / Qwen3-MoEの構成に合わせた設計を採用し、
タグを用いた適応的思考(Adaptive Thinking)やタグによるツール呼び出し、YaRNによるRoPE長文外挿に対応しています。 - 主要な推論エコシステムとの連携 Hugging FaceのTransformers形式への変換やエクスポートに対応するほか、llama.cpp、vLLM、Ollamaなどの軽量・高速推論エンジン、OpenAI API互換のサービング、StreamlitによるチャットWebUIにも対応しています。
使い方
1. 環境構築
リポジトリをクローンし、必要な依存関係をインストールします。Python 3.10環境などが推奨されています。
git clone --depth 1 https://github.com/jingyaogong/minimind
cd minimind && pip install -r requirements.txt
2. 推論の実行
公開されている事前学習済みモデルを取得してCLIから対話推論をテストできます。
# モデルのダウンロード(例: Hugging Faceから取得する場合)
git clone https://huggingface.co/jingyaogong/minimind-3
# CLIによる推論の実行
python eval_llm.py --load_from ./minimind-3
Streamlitを利用したWeb UIも用意されています。
cd scripts && streamlit run web_demo.py
3. モデルの学習(ゼロからの訓練)
学習を行う場合は、所定のデータセット(pretrain_t2t_mini.jsonl や sft_t2t_mini.jsonl など)を ./dataset 配下に配置します。すべてのスクリプトは --from_resume 1 引数を付与することで中断したチェックポイントからの自動復帰に対応しています。
事前学習(Pretrain)の実行:
cd trainer && python train_pretrain.py
教師あり微調整(Full SFT)の実行:
cd trainer && python train_full_sft.py
学習が完了すると、重みファイルが ./out/ 配下に出力されます。
技術的なポイント
- アーキテクチャ設計 Dense構成の「minimind-3」(約64M)と、Mixture of Experts構成の「minimind-3-moe」(約198M、アクティブ64M)が提供されています。初期版からアップデートを重ねており、Qwen3系列の生態系に合わせたトークナイザーやレイヤー構成が採用されています。
- 脱フレームワークによる自作アルゴリズム PEFTなどの抽象ライブラリを介さずに自前実装されたLoRA微調整スクリプトや、PPO、GRPO、CISPOといったRLAIF/強化学習アルゴリズムがコードとして直接含まれています。強化学習パイプラインではロールアウトエンジン(rollout engine)が分離されており、生成バックエンドを柔軟に切り替えられる工夫がなされています。
- トークナイザーと特殊トークンの扱い
BPEおよびByteLevelをベースにしたトークナイザーが用意され、
や、`` などのメタタグがあらかじめ設計されています。これにより、推論時の思考過程の出力制御や外部ツールとの連携がテンプレート単位で統合されています。 - 分散学習と運用補助機能 単一GPUでの実行だけでなく、DDP(Distributed Data Parallel)やDeepSpeedを用いたマルチGPU訓練をサポートしています。また、訓練状況の可視化ツールとしてW&B(Weights & Biases)およびSwanLabに対応し、GPU数の増減を伴う再開でもステップ調整を自動で行うチェックポイント管理機能が備わっています。
注意点
- ライセンス 本プロジェクトは Apache-2.0 ライセンスの下で公開されています。
- ハードウェアと実行環境 READMEの検証環境としては、Ubuntu 20.04、CUDA 12.2、NVIDIA GeForce RTX 3090が記載されています。PyTorchのバックエンドとしてCPUやApple Silicon(MPS)でも実行自体は可能とされていますが、計算速度や互換性に大きな差が生じる旨が注記されています。
- 過去バージョンとの互換性 2025年4月の更新において、パラメータ命名規則の整理やRoPE位置エンコーディングの調整が行われたため、それ以前の旧版(minimind-v1等)の重みを直接ロードすることはサポート外(非推奨)となっています。
- モデルの利用用途 パラメータサイズが26M〜64M程度と非常にコンパクトであるため、大規模な商用基底モデルのような広範な知識保持や高度な推論を目的としたものではありません。あくまで「LLMの内部構造と全学習ステップを自分の手で理解・実験するための教育・検証用モデル」として活用することが前提となります。
まとめ
minimind は、モデル定義から事前学習、微調整、強化学習、エージェント機能までをPyTorchコードで徹底的に自作した、実践志向のLLM学習プロジェクトです。高価な計算資源を大量に確保できない環境でも、個人のGPUを使って短時間・低コストで言語モデル構築の全体像を深く学ぶことができます。





