Agenten's picture
Upload 2 files
5ea4b46 verified
Raw History Blame Contribute Delete
22.2 kB
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Compare open-weight AI model formats including Safetensors and GGUF. Learn about metadata, sharding, quantization, conversion and runtime compatibility.">
<meta name="theme-color" content="#07111f">
<title>Weight Format Explorer β€” Safetensors, GGUF, Metadata & Compatibility</title>
<style>
:root{
--bg:#07111f;--panel:#0d1b2d;--panel2:#10233a;--text:#edf7ff;--muted:#9fb4c8;
--line:#24445f;--cyan:#55d9ff;--blue:#6b8cff;--green:#79f2c0;--gold:#ffd580;
--red:#ff9c9c;--shadow:0 18px 60px rgba(0,0,0,.25)
}
*{box-sizing:border-box}
html{scroll-behavior:smooth}
body{
margin:0;color:var(--text);font:16px/1.65 Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
background:
radial-gradient(circle at 12% 0%,rgba(85,217,255,.12),transparent 28%),
radial-gradient(circle at 90% 12%,rgba(107,140,255,.13),transparent 26%),
var(--bg)
}
a{color:var(--cyan);text-decoration:none}
a:hover{text-decoration:underline}
.wrap{max-width:1180px;margin:auto;padding:0 22px}
.hero{padding:72px 0 35px}
.badge{display:inline-flex;align-items:center;gap:8px;padding:7px 12px;border:1px solid var(--line);border-radius:999px;background:rgba(13,27,45,.75);color:#c8efff;font-size:14px}
h1{font-size:clamp(42px,7vw,78px);line-height:1;letter-spacing:-.055em;margin:20px 0;max-width:980px}
.gradient{background:linear-gradient(90deg,var(--cyan),#b6c3ff);-webkit-background-clip:text;background-clip:text;color:transparent}
.lead{font-size:clamp(18px,2.2vw,24px);max-width:880px;color:#cbdbe8;margin:0 0 28px}
.cta{display:flex;gap:12px;flex-wrap:wrap}
.btn{display:inline-block;padding:11px 16px;border:1px solid var(--line);border-radius:12px;font-weight:750}
.btn.primary{border:0;color:white;background:linear-gradient(135deg,#157aa8,#5269df)}
.quick{display:grid;grid-template-columns:repeat(4,1fr);gap:14px;margin:32px 0 56px}
.card,.section{border:1px solid var(--line);background:linear-gradient(180deg,rgba(16,35,58,.93),rgba(10,25,42,.93));border-radius:20px;box-shadow:var(--shadow)}
.card{padding:18px}
.card strong{display:block;font-size:23px;color:#fff}
.card span,.muted{color:var(--muted)}
.section{padding:28px;margin:22px 0}
.eyebrow{text-transform:uppercase;letter-spacing:.14em;font-size:12px;color:var(--cyan);font-weight:850}
h2{font-size:clamp(28px,4vw,45px);letter-spacing:-.03em;margin:6px 0 10px}
h3{font-size:22px;margin:0 0 8px}
.grid2{display:grid;grid-template-columns:1fr 1fr;gap:18px}
.grid3{display:grid;grid-template-columns:repeat(3,1fr);gap:14px}
.callout{padding:15px 17px;border-left:4px solid var(--cyan);border-radius:9px;background:rgba(85,217,255,.06);margin:18px 0}
.warning{border-left-color:var(--gold);background:rgba(255,213,128,.06)}
.diagram{padding:22px;border:1px solid #2d5876;border-radius:17px;background:#091829;overflow:auto;margin:20px 0}
.flow{display:flex;gap:9px;align-items:center;min-width:900px}
.node{min-width:135px;padding:14px 12px;text-align:center;border:1px solid #34617d;background:#102842;border-radius:13px;font-weight:800}
.arrow{font-size:24px;color:var(--cyan)}
.tablewrap{overflow:auto}
table{width:100%;border-collapse:collapse;min-width:760px}
th,td{padding:13px;border-bottom:1px solid #23435e;text-align:left;vertical-align:top}
th{font-size:12px;text-transform:uppercase;letter-spacing:.07em;color:#c9efff}
.pill{display:inline-block;padding:5px 9px;margin:3px;border:1px solid #315b78;border-radius:999px;background:#102842;color:#c8ecff;font-size:13px}
.code{white-space:pre-wrap;padding:17px;border:1px solid #223f58;border-radius:14px;background:#06101c;color:#bfeeff;font:14px/1.6 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;overflow:auto}
.tabs{display:flex;gap:9px;flex-wrap:wrap;margin:16px 0}
.tab{cursor:pointer;border:1px solid #315b78;background:#0c2035;color:#d9f2ff;border-radius:999px;padding:8px 12px;font:inherit;font-weight:700}
.tab.active{background:linear-gradient(135deg,#177aa6,#4e66d8);border-color:transparent}
.answer{padding:18px;border:1px solid #315b78;border-radius:15px;background:#0a1c2f;min-height:112px}
.good{color:var(--green);font-weight:800}
.caution{color:var(--gold);font-weight:800}
.legend{display:flex;gap:12px;flex-wrap:wrap;color:var(--muted);font-size:13px}
.kv{display:grid;grid-template-columns:150px 1fr;gap:8px 16px;margin-top:15px}
.kv div:nth-child(odd){color:#c7edff;font-family:ui-monospace,monospace}
footer{padding:50px 0 68px;color:var(--muted)}
@media(max-width:820px){
.quick,.grid2,.grid3{grid-template-columns:1fr}
.hero{padding-top:48px}
.section{padding:20px}
.kv{grid-template-columns:1fr}
}
</style>
</head>
<body>
<div class="wrap">
<header class="hero">
<div class="badge">Open Weight Β· Format Explorer</div>
<h1>Safetensors, GGUF and the <span class="gradient">model format layer.</span></h1>
<p class="lead">Understand what a weight format is, how tensors and metadata are stored, why checkpoints are sharded, where quantization fits, and how formats connect to runtimes and hardware.</p>
<div class="cta">
<a class="btn primary" href="#comparison">Compare formats</a>
<a class="btn" href="https://huggingface.co/open-weight" target="_blank" rel="noopener">Open Weight organization β†—</a>
</div>
</header>
<div class="quick">
<div class="card"><strong>Safetensors</strong><span>Safe, efficient tensor serialization</span></div>
<div class="card"><strong>GGUF</strong><span>Model metadata + tensors for GGML workflows</span></div>
<div class="card"><strong>Sharding</strong><span>Large checkpoints split across files</span></div>
<div class="card"><strong>Compatibility</strong><span>Format + runtime + architecture</span></div>
</div>
<section class="section">
<div class="eyebrow">01 Β· Foundation</div>
<h2>What is a model weight format?</h2>
<p>A <strong>model weight format</strong> defines how learned tensors β€” and sometimes associated metadata β€” are serialized into files that software can store, distribute and load.</p>
<div class="callout"><strong>Important:</strong> a weight format is not the same thing as a model architecture, numerical precision, quantization method or inference runtime.</div>
<div class="diagram">
<div class="flow">
<div class="node">Architecture</div><div class="arrow">β‰ </div>
<div class="node">Weight format</div><div class="arrow">β‰ </div>
<div class="node">Precision</div><div class="arrow">β‰ </div>
<div class="node">Quantization</div><div class="arrow">β‰ </div>
<div class="node">Runtime</div><div class="arrow">β‰ </div>
<div class="node">Hardware</div>
</div>
</div>
</section>
<section class="section" id="comparison">
<div class="eyebrow">02 Β· Safetensors vs. GGUF</div>
<h2>Two formats, different design contexts</h2>
<div class="tablewrap">
<table>
<thead>
<tr><th>Dimension</th><th>Safetensors</th><th>GGUF</th></tr>
</thead>
<tbody>
<tr><td>Core role</td><td>Tensor serialization format</td><td>GGML model file format containing metadata and tensors</td></tr>
<tr><td>Typical ecosystem</td><td>Hugging Face / Transformers and many ML workflows</td><td>llama.cpp / GGML-oriented inference workflows</td></tr>
<tr><td>Safety design</td><td>Designed to avoid arbitrary code execution associated with pickle-style loading</td><td>Binary structured model format; security still depends on the complete loading stack</td></tr>
<tr><td>Metadata</td><td>Supports metadata alongside tensor information</td><td>Uses structured key-value metadata plus tensor descriptors</td></tr>
<tr><td>Quantized models</td><td>Can be used in multiple quantized workflows depending on framework/runtime</td><td>Explicitly supports many quantized GGML tensor types</td></tr>
<tr><td>Local inference</td><td>Possible with compatible runtimes</td><td>Commonly used for local llama.cpp inference</td></tr>
<tr><td>Server inference</td><td>Common across server-oriented ML stacks</td><td>Possible in supported runtimes; support and optimization vary</td></tr>
</tbody>
</table>
</div>
<p class="muted">This comparison describes common ecosystem usage, not a universal rule. Runtime support changes over time.</p>
</section>
<section class="section">
<div class="eyebrow">03 Β· Safetensors</div>
<h2>Safe and efficient tensor storage</h2>
<div class="grid2">
<div>
<p>Hugging Face describes <strong>Safetensors</strong> as a simple format for storing tensors safely while supporting fast loading, including zero-copy behavior in supported workflows.</p>
<p>It is widely used for model checkpoints distributed through the Hugging Face ecosystem.</p>
<span class="pill">Tensor serialization</span>
<span class="pill">Metadata</span>
<span class="pill">Fast loading</span>
<span class="pill">HF ecosystem</span>
</div>
<div class="code">model.safetensors
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Header / tensor metadata β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Tensor data β”‚
β”‚ ... β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜</div>
</div>
<p><a href="https://huggingface.co/docs/safetensors/" target="_blank" rel="noopener">Official Safetensors documentation β†—</a></p>
</section>
<section class="section">
<div class="eyebrow">04 Β· GGUF</div>
<h2>Metadata + tensors for GGML workflows</h2>
<div class="grid2">
<div>
<p>Hugging Face documents <strong>GGUF</strong> as a single-file format used to store models for inference with GGML, containing both model metadata and tensors. It supports many quantized data types.</p>
<p>The canonical llama.cpp implementation defines a GGUF structure with a header, key-value metadata, tensor descriptors and tensor data.</p>
<span class="pill">GGML</span>
<span class="pill">llama.cpp</span>
<span class="pill">Metadata</span>
<span class="pill">Quantized types</span>
</div>
<div class="code">GGUF
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Magic + version β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Key-value metadata β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Tensor descriptors β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Tensor data β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜</div>
</div>
<p><a href="https://huggingface.co/docs/transformers/main/quantization/gguf" target="_blank" rel="noopener">Transformers GGUF documentation β†—</a></p>
<p><a href="https://github.com/ggml-org/llama.cpp" target="_blank" rel="noopener">llama.cpp β†—</a></p>
</section>
<section class="section">
<div class="eyebrow">05 Β· Sharding</div>
<h2>Why Safetensors checkpoints may use many files</h2>
<p>Very large checkpoints are frequently <strong>sharded</strong>: the tensors are distributed across multiple files, with an index describing which tensor belongs to which shard.</p>
<div class="code">model-00001-of-00004.safetensors
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
model.safetensors.index.json</div>
<div class="callout">Sharding does not change the model architecture. It changes how a large checkpoint is packaged and loaded.</div>
</section>
<section class="section">
<div class="eyebrow">06 Β· Metadata</div>
<h2>Weights need context</h2>
<p>A collection of tensors is not enough for a reliable deployment. Software also needs enough information to interpret those tensors correctly.</p>
<div class="kv">
<div>architecture</div><div>How tensor names and shapes map to model structure.</div>
<div>tokenizer</div><div>How text or other inputs are converted into model tokens.</div>
<div>dtype</div><div>The numerical representation of stored parameters.</div>
<div>quantization</div><div>How lower-precision representations were produced.</div>
<div>revision</div><div>Which source checkpoint or repository state produced the artifact.</div>
<div>license</div><div>What use and redistribution terms apply.</div>
</div>
<p class="muted">Some metadata lives inside the weight file; some lives in adjacent configuration, tokenizer or repository files. The exact arrangement depends on format and ecosystem.</p>
</section>
<section class="section">
<div class="eyebrow">07 Β· Quantization</div>
<h2>Format and quantization are different layers</h2>
<p>Quantization changes how values are represented. A file format determines how data is serialized. They are related but not interchangeable concepts.</p>
<div class="diagram">
<div class="flow" style="min-width:760px">
<div class="node">Model tensors</div><div class="arrow">β†’</div>
<div class="node">Precision / quantization</div><div class="arrow">β†’</div>
<div class="node">Serialization format</div><div class="arrow">β†’</div>
<div class="node">Runtime loader</div><div class="arrow">β†’</div>
<div class="node">Hardware</div>
</div>
</div>
<p class="muted">For example, GGUF supports many quantized GGML data types, while Safetensors can store tensors used by multiple framework-specific quantization approaches.</p>
</section>
<section class="section">
<div class="eyebrow">08 Β· Conversion</div>
<h2>What happens when a model is converted?</h2>
<div class="code">Source checkpoint
↓
Read configuration + tokenizer + tensors
↓
Map tensor names / structure
↓
Optional quantization
↓
Write target format + metadata
↓
Validate output
↓
Run inference checks</div>
<p>llama.cpp provides conversion tooling for supported architectures, including workflows that convert Hugging Face checkpoints into GGUF.</p>
<div class="callout warning"><strong>Conversion is not just renaming a file extension.</strong> Architecture support, tensor mapping, tokenizer metadata and quantization choices must all be compatible.</div>
</section>
<section class="section">
<div class="eyebrow">09 Β· Compatibility</div>
<h2>The format is only useful if the runtime can load it</h2>
<div class="tablewrap">
<table>
<thead><tr><th>Runtime / workflow</th><th>Safetensors</th><th>GGUF</th><th>Important nuance</th></tr></thead>
<tbody>
<tr><td>Transformers</td><td><span class="good">Native ecosystem fit</span></td><td>Supported for documented GGUF loading workflows</td><td>Feature support depends on architecture and current Transformers implementation.</td></tr>
<tr><td>llama.cpp</td><td>Conversion typically required</td><td><span class="good">Primary format</span></td><td>llama.cpp requires supported models to be in GGUF for its standard model-loading workflow.</td></tr>
<tr><td>vLLM</td><td><span class="good">Common loading path</span></td><td><span class="caution">Experimental / plugin-based</span></td><td>Current vLLM documentation describes GGUF support as highly experimental and under-optimized.</td></tr>
<tr><td>Local desktop workflows</td><td>Depends on application/runtime</td><td>Common in llama.cpp-based tools</td><td>Application support matters more than the filename alone.</td></tr>
</tbody>
</table>
</div>
<p class="muted">Compatibility should always be checked against the current runtime version and the specific model architecture.</p>
</section>
<section class="section">
<div class="eyebrow">10 Β· Decision helper</div>
<h2>Which direction fits your workflow?</h2>
<p>Choose a scenario. The answer is a workflow starting point β€” not a universal rule.</p>
<div class="tabs">
<button class="tab active" data-answer="hf">Hugging Face / Transformers</button>
<button class="tab" data-answer="local">llama.cpp / local AI</button>
<button class="tab" data-answer="server">Server inference</button>
<button class="tab" data-answer="portable">Consumer hardware</button>
</div>
<div class="answer" id="answer">
<strong>Start with Safetensors.</strong>
<p class="muted">It is a natural fit for many Hugging Face / Transformers checkpoint workflows. Then choose precision or quantization according to your framework and deployment target.</p>
</div>
</section>
<section class="section">
<div class="eyebrow">11 Β· Common mistakes</div>
<h2>Five concepts people often mix up</h2>
<div class="grid3">
<div class="card"><h3>Format β‰  architecture</h3><p class="muted">A Transformer architecture can be distributed in different weight formats.</p></div>
<div class="card"><h3>Format β‰  quantization</h3><p class="muted">INT4 describes numerical representation, not by itself a universal file format.</p></div>
<div class="card"><h3>Weights β‰  tokenizer</h3><p class="muted">Tokenization artifacts are separate from the learned tensor values.</p></div>
<div class="card"><h3>Extension β‰  compatibility</h3><p class="muted">A runtime also needs support for the architecture and tensor representation.</p></div>
<div class="card"><h3>Conversion β‰  zero risk</h3><p class="muted">Converted artifacts should be validated against the source model.</p></div>
<div class="card"><h3>Open weights β‰  open source</h3><p class="muted">Weight access does not automatically open training data, code or usage rights.</p></div>
</div>
</section>
<section class="section">
<div class="eyebrow">12 Β· Quick reference</div>
<h2>Format-selection checklist</h2>
<div class="tablewrap">
<table>
<thead><tr><th>Question</th><th>Why it matters</th></tr></thead>
<tbody>
<tr><td>Which runtime will load the model?</td><td>Runtime support determines which formats and architectures are practical.</td></tr>
<tr><td>Which hardware is the target?</td><td>CPU, GPU and Apple Silicon workflows can favor different runtimes and quantizations.</td></tr>
<tr><td>Is this for training or inference?</td><td>Training, fine-tuning and optimized local inference have different needs.</td></tr>
<tr><td>Do you need quantization?</td><td>Quantization affects memory, quality and compatibility.</td></tr>
<tr><td>Is the model architecture supported?</td><td>A valid file format does not guarantee runtime support for the architecture.</td></tr>
<tr><td>Can the artifact be traced to its source?</td><td>Provenance matters for reproducibility and security.</td></tr>
</tbody>
</table>
</div>
</section>
<section class="section">
<div class="eyebrow">Next</div>
<h2>Continue the Open Weight series</h2>
<div class="grid3">
<div class="card"><h3>Open Weight Explorer</h3><p class="muted">The fundamentals of tensors, weights, precision and deployment.</p></div>
<div class="card"><h3>Quantization Explorer</h3><p class="muted">FP16, BF16, FP8, INT8, INT4 and practical trade-offs.</p></div>
<div class="card"><h3>Model Portability Explorer</h3><p class="muted">Formats, runtimes, hardware and compatibility.</p></div>
</div>
</section>
<section class="section">
<div class="eyebrow">Primary sources</div>
<h2>Technical references</h2>
<p><a href="https://huggingface.co/docs/safetensors/" target="_blank" rel="noopener">Hugging Face β€” Safetensors β†—</a></p>
<p><a href="https://huggingface.co/docs/transformers/main/quantization/gguf" target="_blank" rel="noopener">Hugging Face Transformers β€” GGUF β†—</a></p>
<p><a href="https://github.com/ggml-org/llama.cpp" target="_blank" rel="noopener">ggml-org / llama.cpp β†—</a></p>
<p><a href="https://docs.vllm.ai/en/latest/features/quantization/gguf/" target="_blank" rel="noopener">vLLM β€” GGUF β†—</a></p>
</section>
<footer>
<strong style="color:white">Open Weight</strong><br>
Open weights. Portable models. Deployable AI.<br><br>
Collaboration: open-weight AI, model infrastructure, inference, deployment, research and ecosystem partnerships.<br>
Contact: <a href="mailto:agenten@magenta.de">agenten@magenta.de</a>
</footer>
</div>
<script>
const answers = {
hf: `<strong>Start with Safetensors.</strong><p class="muted">It is a natural fit for many Hugging Face / Transformers checkpoint workflows. Then choose precision or quantization according to your framework and deployment target.</p>`,
local: `<strong>GGUF is a strong starting point.</strong><p class="muted">llama.cpp uses GGUF for supported model-loading workflows, and the format is common in local and quantized inference ecosystems.</p>`,
server: `<strong>Check the serving runtime first.</strong><p class="muted">Safetensors is common across server-oriented ML stacks. GGUF support exists in some runtimes, but support and optimization can differ substantially.</p>`,
portable: `<strong>Choose the runtime before the file.</strong><p class="muted">For llama.cpp-based consumer-hardware workflows, GGUF is common. For other runtimes, verify architecture, quantization and hardware support before converting.</p>`
};
document.querySelectorAll('.tab').forEach(btn=>{
btn.addEventListener('click',()=>{
document.querySelectorAll('.tab').forEach(x=>x.classList.remove('active'));
btn.classList.add('active');
document.getElementById('answer').innerHTML=answers[btn.dataset.answer];
});
});
</script>
</body>
</html>