Download index.html from open-weight/weight-format-explorer: direct link, hf CLI and curl.
- Browser
- Download file 22.2 kB
-
https://huggingface.co/spaces/open-weight/weight-format-explorer/resolve/main/index.html
- Command line
-
hf download hf://spaces/open-weight/weight-format-explorer/index.html
-
curl -L -o index.html https://huggingface.co/spaces/open-weight/weight-format-explorer/resolve/main/index.html
22.2 kB
| <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> | |
| </script> | |
| </body> | |
| </html> | |