使い方・解説

modelmapでLLMの構造を図にする【GPUメモリに収まるかも判定】

#modelmap#Hugging Face#LLM#オープンソース

modelmapでできること

modelmapはモデルの性能を測るのではなく、中身の構造を見るためのツールです。 入力・出力・提供形態などの基本仕様は次のとおりです。

modelmapの基本仕様

事柄 内容
入力 Hugging FaceのモデルID（公開リポジトリ全般）
出力 階層グラフ・順伝播アニメーション・GPU適合判定
重みの取得 なし（config.json約2KBのみ）
ライセンス MIT
提供形態 ウェブ（modelmap.cc）／CLI／REST API／Python／MCP
実装言語 Python（WebはReact）
リポジトリ作成 2026年8月14日

modelmapはモデルIDを貼るだけで図が出る

modelmapの入力フィールドにモデルIDを貼り付けると、そのモデルのネットワーク全体が地図のような図で表示されます。 開発者のlizhaoliu氏はネットワークの図を「生きた地図」と呼んでいます。図は個々の射影（projection）まで展開でき、埋め込みからロジットまでトークンが流れる様子もアニメーションで追えるとのこと。

同じ画面には、ローカルでLLMを使う人が毎週のように気にする「GPUのメモリに収まるか」の判定も表示されます。modelmapはHugging Faceの公開リポジトリ全般を読み込め、対応するモデルの種類は次のとおりです。

  • 密なLLM
  • MoE（複数の専門家モデルを切り替える構成）
  • T5やBARTのようなエンコーダ・デコーダ
  • Whisperのような音声モデル
  • BERTやViT
  • 視覚言語モデル

config.jsonだけでLLMのアーキテクチャ図とモデル構造を可視化

modelmapは約2KBのconfig.jsonだけを取得し、モデルの重みは一切ダウンロードされません。 重みが無くても構造を描ける理由は、PyTorchのmetaデバイス（実データを持たない仮想的な配置先）の上でモデルの構造だけを組み立てているからです。modelmapはそのうえでフックを仕掛けた疑似的な順伝播を実行し、実際の実行順とテンソル形状を記録します。

重みを読み込まないので、8Bのモデルでも671Bのモデルでも所要時間は同じ数秒で、生成されるグラフもgzipで約10KBです。数百GBの重みを落とさずに構造だけチェックできるので、ローカルでLLMを動作させる検討の前段としても使うことができます。

"Paste a Hugging Face model id. Get a living map of the network — explorable down to every projection, animated so you can watch a token flow from embedding to logits — and the answer to the question you re-ask every week: <strong>will it fit on my GPU?</strong>"／"<strong>No weights are ever downloaded.</strong> modelmap fetches config.json (~2 KB), instantiates the model on PyTorch's meta device, runs a hooked fake forward pass to capture real execution order and tensor shapes, and serves the result as a compact hierarchical graph."／"An 8B or 671B model costs the same few seconds; the graph ships as ~10 KB gzipped."（README 冒頭）— modelmap 公式リポジトリより
公式情報を見る →

GPUのメモリに収まるかをチェックする方法

GPU適合判定は、モデルIDを貼って手持ちのGPUを選ぶと始まります。 GPU適合判定はトップページでいちばん目立つ位置にあり、判定までは3ステップです。

GPU適合判定の流れ

段階 操作
1 Hugging FaceのモデルID（例Qwen/Qwen3-8B）を貼る
2 「will it fit on」の一覧で手持ちGPUを選択する
3 重み・KVキャッシュ・活性化の内訳が地図の上に表示される
modelmapのトップページ。Hugging FaceのモデルIDを探す検索ボックスの下に「will it fit on」の行があり、GPUの選択メニュー（H100 80GB）とモデルIDの入力フィールドが横に配置されている
「will it fit on」の左でGPUを選択し、右の入力フィールドにモデルIDを入れると判定が始まります。modelmap

対応GPUにはどの機種があるか

公式のトップページには13機種が一覧で表示されます。 選ぶことができるのは次のGPUです。

  • H100 80GB
  • H200 141GB
  • A100 80GB
  • A100 40GB
  • L40S 48GB
  • L4 24GB
  • A10G 24GB
  • RTX 4090 24GB
  • RTX 3090 24GB
  • RTX 5090 32GB
  • MI300X 192GB
  • B200 180GB
  • T4 16GB

選択できるGPUはデータセンター向け上位機から個人向けRTX 3090、推論向け小型機のT4まで幅があります。RTX 4090や5090を選べば、自宅PCのGPUでもモデルがメモリに収まるかどうかを確認できます。

適合判定はどの3つの合計で行われるのか

判定は、重み（weights）・KVキャッシュ・活性化（activations）という3つの値を合計して行われます。また、3つの数値は構造図の上に重ねて表示されるとのこと。

重みだけならメモリに収まるのに、コンテキスト長（モデルが一度に読み込める入力の長さ）を伸ばすとKVキャッシュでメモリが溢れることはよくあります。modelmapは3つの内訳を分けて表示するので、どこでメモリが足りなくなるのかを確認できます。

Qwen3-8Bのconfig.jsonから重みとKVキャッシュを求めると、RTX 4090（24GB）にはBF16で最大長の40,960トークンまで収まる見込みです。 計算には、Hugging Faceで公開されている層の数36・KVヘッド8・ヘッドの次元128と、パラメータ数8,190,735,360を使いました（2026-11-06に取得）。

KVキャッシュは1トークンあたり「2（キーと値）×36層×8ヘッド×128次元×2バイト」で約147KBになり、コンテキストに比例して増加します。最大長の40,960トークンでは、KVキャッシュだけで約6.0GBです。

Qwen3-8Bの重み＋KVキャッシュ（活性化は含まない、sakutto.ai編集部による試算）

コンテキスト長 KVキャッシュ BF16の重みと合計 8bitの重みと合計 4bitの重みと合計
8,192 1.2GB 17.6GB 9.4GB 5.3GB
32,768 4.8GB 21.2GB 13.0GB 8.9GB
40,960（設定上の最大） 6.0GB 22.4GB 14.2GB 10.1GB

BF16の重みだけで16.4GBあるため、24GBのGPUで最大長まで使うと、残りは活性化と実行環境の分として約1.6GBしかありません。modelmapにモデルIDQwen/Qwen3-8Bを入力し、表示された内訳を上に掲げた試算と見比べることで、活性化に見込まれている量を確認することができます。

modelmapには系列長・バッチ・データ型を変更できるwhat-ifバーがあり、値を変更するとその場で再計算されます。CLI側のplanコマンドでは、GPU枚数・パイプライン並列の段数・系列長を指定した検証もできます。

"Paste a Hugging Face model id. See the whole network, watch a forward pass, and find out whether it fits on your GPU — no weights downloaded."／"will it fit on ／ H100 80GB ／ H200 141GB ／ A100 80GB ／ A100 40GB ／ L40S 48GB ／ L4 24GB ／ A10G 24GB ／ RTX 4090 24GB ／ RTX 3090 24GB ／ RTX 5090 32GB ／ MI300X 192GB ／ B200 180GB ／ T4 16GB"／"weights + KV cache + activations on the map itself · try Qwen3-8B or DeepSeek-V3.1"（トップページ・2026-08-26 に実描画して取得）— modelmap 公式サイトより
公式情報を見る →
"head_dim": 128／"max_position_embeddings": 40960／"num_hidden_layers": 36／"num_key_value_heads": 8／"torch_dtype": "bfloat16"（2026-11-06 取得。パラメータ数 8,190,735,360 は同リポジトリの Hugging Face API の safetensors 集計値）— Hugging Face より
公式情報を見る →

アーキテクチャを図で読む表示モード

modelmapには、表示モードがExplore・Flow・Compare・Liveと4つあります。 各モードで表示される内容と使いどころは次のとおりです。

表示モードの使い分け

モード 表示される内容 使いどころ
Explore モジュールツリーの階層地図。層はdecoder block ×36のように畳まれる 構造を俯瞰したい
Flow 実行順にパルスが走る順伝播アニメーション。HUDが形状と説明を出す 処理の流れを掴みたい
Compare 2モデルをパスと役割で対応づけた差分表示 世代間の変更点を知りたい
Live ブラウザ内で本物の推論。アテンションヘッドとロジットレンズ 挙動を実際に見たい

Exploreモードで構造ツリーはどう表示されるのか

Exploreモードはズームと折りたたみができるモジュールツリーを表示し、繰り返される層はスタックに畳まれるので235BのMoEでも約10ノードとして開きます。また、MoEではexperts ×128のようにエキスパートも1つのノードにまとめて表示されるとのこと。

コストレンズという切り替えもあり、パラメータ・計算量・メモリ・KV・VRAMの観点で地図を色分けし直せます。ノードをクリックすると詳細を確認できます。表示される内容は次のとおりです。

  • クラス名
  • パラメータ数（絶対値と全体比）
  • データ型
  • 重みの形状
  • 追跡された入出力形状
  • 子要素のパラメータ・ツリーマップ
  • 定義元のソース行へのリンク

Flowモードの順伝播アニメーション

Flowモードは追跡した順伝播をそのまま再生します。 繰り返しの層は「layer 12 / 36」というカウンタで圧縮され、8Bモデルの全再生でおよそ12秒とのこと。琥珀色のパルスが実行順にグラフを走り、HUDが各ステップを実際の形状と平易な説明で解説します。

ブロックを展開すると、パルスはその内部も実行順に走ります。ブロック内のnorm → attention → 加算 → norm → MLP → 加算、アテンション機構のQ/K/V → スコア → softmax → 結合といった細部が、そのモデルの設定と追跡結果から描かれます。

Compareモードは2モデルの差分をどう表示するのか

Compareモードは、/compare/A...B形式のURLで2つのモデルを並べて表示します。モジュールはまずパスで対応づけられ、合わない部分は役割で対応づけられるとのこと。パン・ズーム・展開・選択は2モデル間で連動する仕組みです。

変わっていないモジュールは薄い色で、変わったものは琥珀色の輪郭で表示され、追加と削除は+と−の記号で示されます。ベースモデルとファインチューン版を比較すると、modelmapは「構造の変化なし」と表示します。 一方でQwen2.5-7BとQwen3-8Bを比較すると、q/kの正規化・バイアスの削除・FFN・層数の違いが表示されるとのこと。

要約ストリップでは、2モデルの数値が同時に表示されます。比較できる数値は次のとおりです。

  • パラメータ数
  • 層数
  • ヘッド数
  • KVヘッド数
  • 隠れ次元
  • FFN
  • 語彙
  • コンテキスト
  • トークンあたりの計算量とKV

ブラウザで推論が動作するライブモード

ライブモードでは小さいモデルに限って本物の推論がブラウザ内で動作します。 対象はllama系とgpt2系のうち、単一ファイルのsafetensorsが700MB以下のものに限られるとのこと。重みはブラウザが取得し、Web Workerの中でCPU推論を回します。サーバー側は重みをダウンロードしません。

デフォルトは9MBのTinyLLama-v0で1トークンあたり約4ミリ秒。ローカルで小さなモデルを触る前の下見としても使うことができます。プロンプトを打つと次の3つが表示されます。

  • 次トークンが出る本当の確率
  • ヘッドごとのアテンションヒートマップ
  • 層ごとに予測が鋭くなっていく様子を見せるロジットレンズ
"<strong>Explore mode</strong> — a zoomable, collapsible map of the module tree. Repeated layers collapse into stacks (decoder block ×36, experts ×128) so a 235B MoE opens as ~10 nodes"／"Repeat stacks compress with a layer 12 / 36 counter (~12 s for a full 8B replay)."／"Base vs fine-tune reports no structural change; Qwen2.5-7B vs Qwen3-8B calls out q/k norms, dropped biases, ffn, layers."／"<strong>⚡ Live mode</strong> — for small models (llama-family / gpt2, single-file safetensors ≤ 700 MB) the browser downloads the weights and runs *real inference* on your CPU in a Web Worker"／"TinyLLama-v0 (9 MB, ~4 ms/token) is the instant default; SmolLM2-135M and distilgpt2 also run."（README / What you get 節）— modelmap 公式リポジトリより
公式情報を見る →

CLI・API・MCPからの使い方

modelmapはブラウザのほか、PCのコマンドラインやエージェントからも使うことができます。 主なコマンドは次のとおりです。

主なコマンド

コマンド 用途
uv run modelmap サーバーを起動してブラウザを開く
uv run modelmap dump Qwen/Qwen3-8B -f md グラフをJSON / CSV / Markdown / DOTで書き出す
uv run modelmap cost Qwen/Qwen3-8B-GGUF:Q4_K_M 量子化版の主要数値を出す
uv run modelmap plan Qwen/Qwen3-8B --gpus 2 --gpu-memory 24 --pp 2 -T 32768 指定条件でメモリに収まるか検証する
uv run modelmap diff Qwen/Qwen2.5-7B Qwen/Qwen3-8B 2モデルの差分を出す
uv run modelmap mcp MCPサーバーとして起動する

ローカルで起動するにはどのコマンドを実行するのか

インストールせずに1回だけ試すならuvxを使います。 2.5GBあるCUDA版のホイールは入れずにCPU版のPyTorchだけを指定して入れ、起動後はブラウザでhttp://127.0.0.1:7860が開く仕組みです。

uvx --index https://download.pytorch.org/whl/cpu modelmap

ローカルのチェックポイントはディレクトリでも.safetensorsでも.ggufでも開け、社内で作ったファインチューン版の構造をそのまま確認できます。コンテナ構成は、非rootかつ読み取り専用ルートファイルシステムで動作するように用意されています。

MCPサーバーとしての公開

uv run modelmap mcpでMCPサーバーとして立てると、Claude CodeやCursorからmodelmapの機能を呼べるようになります。MCP（Model Context Protocol）は、エージェントが外部のツールと連携するための規約です。

MCP経由なら、「このモデルはこのGPUのメモリに収まるか」を調べる作業をエージェントに任せることができます。同じ機能はREST APIやPythonからも呼び出せるので、ご自身のスクリプトにも組み込めます。ローカルのLLMにツールを呼び出させる仕組みとしては、LM Studioのスキル対応も参考になるでしょう。

"# one-off, nothing to install (pins the CPU torch wheel instead of the 2.5 GB CUDA one) uvx --index https://download.pytorch.org/whl/cpu modelmap # opens http://127.0.0.1:7860"／"uv run modelmap ./my-finetune # …opening a local checkpoint (dir, .safetensors or .gguf)"／"uv run modelmap mcp # MCP server for Claude Code / Cursor (pip install 'modelmap[mcp]')"／"# container (non-root, read-only rootfs, capabilities dropped) docker compose up --build"（README / Run it 節）— modelmap 公式リポジトリより
公式情報を見る →

導入前の制約は初回約30秒の待ちと個人開発の若さ

導入前に押さえたい制約は、初回の待ち時間・ライブモードの対象・プロジェクトの成熟度などです。 便利な一方でできないことと待たされる状況もはっきりしています。

導入前に確認したい制約

制約 内容
初回の待ち時間 未キャッシュのモデルはコールドスタート時に約30秒
ライブモードの対象 llama系・gpt2系で単一ファイルsafetensors 700MB以下のみ
trust_remote_code必須のリポジトリ デフォルトで拒否。ローカルのPCでdumpして.graph.jsonを投入する
ゲート付きリポジトリ トークンを追加すれば利用可。トークンはブラウザ内のみに保存
プロジェクトの成熟度 2026年8月14日作成の個人リポジトリ

モデル構造の可視化ツールは初回のLLMアーキテクチャ図に約30秒

キャッシュにあるモデルはすぐに開き、キャッシュにないモデルを初めて開くとおよそ30秒かかります。 待ち時間が出るのはコールドスタート状態のインスタンスで、公開デモがGoogle Cloud Runの無料枠で動作しているためです。

急ぐならローカル環境で起動するほうが確実です。serve --warmオプションを指定して起動すると、ギャラリーのモデルをあらかじめ読み込んでおけます。

modelmapは個人開発でLLM構造の下調べ向き

リポジトリは2026年8月14日に作られ、2026年10月11日時点の最終更新は9月10日でした。ライセンスはMITで実装言語はPythonです。公式リポジトリには次の資料とテストが揃っています。

  • 設計ドキュメント
  • REST・Python・CLI・MCPのAPI仕様
  • デプロイ手順
  • 拡張方法
  • E2Eテスト

完成度は高いものの、公開から日が浅く開発者1人で作っているプロジェクトであることは押さえておくといいでしょう。 業務の基盤に据えるより、導入前の判断を早めるためのツールとして使うのが現状に合っています。

⚠️ なおtrust_remote_codeを必要とするリポジトリがデフォルトで拒否されるのは任意のPythonコードが実行されるためで、安全側に倒した妥当な設計です。どうしても見たい場合はローカルのマシンでmodelmap dump <id> --trust-remote-codeを実行して、生成された.graph.jsonをページ上に投入します。

"Structure comes from a meta-device instantiation; shapes come from a traced fake forward pass. Any public repo works — gated ones after you add a token."（トップページ末尾・2026-08-26 に実描画して取得）— modelmap 公式サイトより
公式情報を見る →
"architectures transformers can't instantiate, or repos requiring trust_remote_code (refused by default — it executes arbitrary Python), get a structural <strong>weights view</strong> rebuilt from safetensors headers alone."／"Gated repos work once you add a token (top bar → token; stored in your browser only, never cached server-side)."（README / Any public repo. 節）／"<strong>Live demo:</strong> https://modelmap.cc (free-tier Cloud Run: cached models are instant; the first uncached model on a cold instance takes ~30 s)."／"MIT — see [LICENSE](LICENSE)."（README / Live demo・License 節）— modelmap 公式リポジトリより
公式情報を見る →

構造とGPU適合を先に見る導入判断

modelmapはHugging FaceのモデルIDを貼るだけでネットワークの構造図と順伝播アニメーションを返し、手持ちGPUのメモリに収まるかどうかまで判定するツールです。また、重みを一切ダウンロードしないため、671Bのモデルでも数秒で開くのが特徴です。GPUは13機種から選ぶことができ、判定は重み・KVキャッシュ・活性化の合計で行われます。 表示モードには次の4種類があります。

  • 構造を見るExplore
  • 流れを追うFlow
  • 2モデルを比較するCompare
  • ブラウザ内で推論するLive

Liveで推論できるのは、700MB以下の小さいモデルに限られます。CLI・REST API・Python・MCPからも同じ機能を呼び出せるので、GPUのメモリに収まるかどうかを調べる作業をエージェントに任せることもできます。ライセンスはMITで公開デモは無料です。

ただし、リポジトリの作成は2026年8月14日で、まだ日が浅い個人プロジェクトです。業務に組み込むより、使うモデルを選ぶ前の下調べに使うのが今の完成度に合った使い方です。

FAQ

modelmapは無料で使うことができますか？
無料です。MITライセンスのOSSとして公開されています。公開デモのmodelmap.ccはGoogle Cloud Runの無料枠で動作しており、お使いのPC上でもコマンド1本で起動できます。
モデルの重みはダウンロードされますか？
されません。取得対象は2KBほどのconfig.jsonだけで、PyTorchのmetaデバイス上にモデルを組み立て、フックを仕掛けた疑似的な順伝播で実行順とテンソル形状を記録します。8Bでも671Bでも所要時間は同じ数秒です。
どのGPUで判定できますか？
画面上の一覧から選びます。メモリの大きい上位機は、H100 80GB・H200 141GB・A100 80GB/40GB・B200 180GB・MI300X 192GBです。そのほかに、L40S 48GB・L4 24GB・A10G 24GB・T4 16GBと、RTX 4090/3090 24GB・RTX 5090 32GBも選ぶことができます。判定は重み・KVキャッシュ・活性化の合計で行われます。
ブラウザの中で実際に推論を動作させることができますか？
小さいモデルなら動作します。対象はllama系とgpt2系のうち、単一ファイルのsafetensorsが700MB以下のものです。ブラウザが重みを取得してWeb Worker上のCPUで本物の推論を回します。デフォルトは9MBのTinyLLama-v0です。