Loading a Model

Getting Started

TokenPrint supports three model paths: a PyTorch model loaded by the backend (via Hugging Face), a GGUF binary file parsed client-side in the browser, and the in-browser GPT-2 engine that runs generation entirely in the browser.

Hugging Face model (backend)

The backend loads a model on startup using the MODEL_NAME environment variable. The default is Qwen/Qwen2.5-0.5B-Instruct.

bash

MODEL_NAME=meta-llama/Llama-3.2-3B-Instruct \
  python -m uvicorn app.main:app --app-dir . --port 8000 --reload

Any model architecture supported by the backend is available. The frontend detects the architecture from GET /model-info and selects the correct formula set (RMSNorm vs LayerNorm, SwiGLU vs GELU, GQA vs MHA).

Note

The Model Explorer modal in the top navigation bar lists curated models with parameter counts, VRAM estimates, and instrumentation capability flags.

GGUF drag-and-drop (client-side)

Drag a .gguf file onto the 3D canvas in Architecture mode. The browser reads the binary header and parses tensor metadata without sending the file to the backend.

Two tested GGUF models (from the verification report):

Model	Architecture	Parameters	Tensors	Quantization
Qwen3 8B	`qwen3`	8.19B	399	Q4_K
Llama 3.2 3B	`llama`	3.21B	255	Q4_K

The GGUF path produces the same data shape as GET /architecture with "source": "gguf" and extra fields for quantization type and GGUF version.

Warning

GGUF mode only supports Architecture visualization (drag-and-drop diff/compare). However, generation without the backend is possible via the in-browser GPT-2 engine — see Browser GPT-2. Walkthrough and Debugger modes require the backend with a PyTorch model loaded.

Browser GPT-2 (no backend)

Instead of loading a file, you can switch Generation mode to the Browser GPT-2 engine (WebGPU or CPU/WASM). It downloads a pinnedXenova/gpt2 model (~500 MB, cached) and runs real greedy generation entirely in the browser. No backend is required for this path.

The backend can also serve a dedicated GGUF execution engine over the /gguf/* API for running quantized llama.cpp models server-side — see API Reference.