docs(docs): add the Exporting weights guide, from a checkpoint to a float or quantized file

apps/docs/astro.config.mjs

@@ -158,6 +158,7 @@ export default defineConfig({
                   label: 'Guides',
                   items: [
                     { label: 'Error handling', slug: 'zoo/error-handling' },
+                    { label: 'Exporting weights', slug: 'zoo/exporting-weights' },
                     {
                       label: 'Migrating from transformers.js',
                       slug: 'zoo/migrating-from-transformers-js',

apps/docs/src/components/QuantFile.astro

@@ -0,0 +1,89 @@
+---
+/** What a quantized safetensors file holds and how the loader reads each
+ *  entry: the header label, an int8 weight with its F16 scales, and the float
+ *  tensors around them. Names are all-MiniLM-L6-v2's, shortened; the floats
+ *  are F16 as `--f16` stores them. */
+const rows = [
+  { name: '…word_embeddings.weight', dtype: 'F16', shape: '[30522, 384]', loads: 'float' },
+  { name: '…query.weight', dtype: 'I8', shape: '[384, 384]', loads: 'int8 weight', quant: true },
+  { name: '…query.weight_scale', dtype: 'F16', shape: '[384, 12]', loads: 'its scales', quant: true },
+  { name: '…query.bias', dtype: 'F16', shape: '[384]', loads: 'float' },
+  { name: '…LayerNorm.weight', dtype: 'F16', shape: '[384]', loads: 'float' },
+];
+const rowHeight = 30;
+const top = 84;
+const height = top + rows.length * rowHeight + 14;
+---
+
+<svg
+  class="quant-file"
+  viewBox={`0 0 400 ${height}`}
+  role="img"
+  aria-label="A quantized file: the runntime.quant header label, then tensors. F16 tensors load as float, an I8 weight loads as an int8 weight and takes its F16 weight_scale with it."
+>
+  <rect class="file" x="0.5" y="0.5" width="399" height={height - 1} rx="6"></rect>
+  <text class="header" x="12" y="22">__metadata__ runntime.quant =</text>
+  <text class="header strong" x="12" y="42">{'{'}"version":1,"bits":8,</text>
+  <text class="header strong" x="12" y="60">"groupSize":32,"scheme":"symmetric"{'}'}</text>
+  <line class="rule" x1="0" y1="72" x2="400" y2="72"></line>
+  {
+    rows.map((row, i) => {
+      const y = top + i * rowHeight + 12;
+      return (
+        <g class={row.quant ? 'row quant' : 'row'}>
+          {row.quant && (
+            <rect class="band" x="6" y={y - 20} width="388" height={rowHeight} rx="3" />
+          )}
+          <text class="name" x="12" y={y}>
+            {row.name}
+          </text>
+          <text class="dtype" x="212" y={y}>
+            {row.dtype} {row.shape}
+          </text>
+          <text class="loads" x="392" y={y} text-anchor="end">
+            {row.loads}
+          </text>
+        </g>
+      );
+    })
+  }
+</svg>
+
+<style>
+  .quant-file {
+    display: block;
+    height: auto;
+    margin: 1.5rem auto;
+    max-width: 30rem;
+    width: 100%;
+  }
+
+  .file {
+    fill: var(--surface-raised);
+    stroke: var(--border-strong);
+  }
+
+  .rule {
+    stroke: var(--border-strong);
+  }
+
+  .band {
+    fill: var(--surface-quiet);
+  }
+
+  text {
+    fill: var(--text-muted);
+    font-family: var(--__sl-font-mono, monospace);
+    font-size: 13px;
+  }
+
+  .strong,
+  .quant .name,
+  .quant .loads {
+    fill: var(--text-primary);
+  }
+
+  .loads {
+    font-family: var(--__sl-font, sans-serif);
+  }
+</style>

apps/docs/src/components/WeightsPath.astro

@@ -0,0 +1,105 @@
+---
+/** The path of a weights file, from a checkpoint to the GPU: six numbered
+ *  steps in two rows, one column at phone width. */
+const steps = [
+  { title: 'Checkpoint', detail: 'PyTorch or Hugging Face' },
+  { title: 'Export', detail: 'model.safetensors, F32 / F16 / BF16' },
+  { title: 'Quantize', detail: 'runntime quantize, int8 or int4. Optional.' },
+  { title: 'Host', detail: 'any static file server' },
+  { title: 'modelPath', detail: 'create<Task>({ modelPath })' },
+  { title: 'Load', detail: 'header, 8 MB chunks, cache, GPU upload' },
+];
+---
+
+<ol class="weights-path" aria-label="From a checkpoint to the GPU">
+  {
+    steps.map((step) => (
+      <li>
+        <span class="weights-path-title">{step.title}</span>
+        <span class="weights-path-detail">{step.detail}</span>
+      </li>
+    ))
+  }
+</ol>
+
+<style>
+  .weights-path {
+    counter-reset: step;
+    display: grid;
+    gap: 1.75rem 2rem;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    list-style: none;
+    margin: 1.5rem 0;
+    padding: 0;
+  }
+
+  .weights-path li {
+    background: var(--surface-raised);
+    border: 1px solid var(--border-strong);
+    border-radius: 0.5rem;
+    counter-increment: step;
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    margin: 0;
+    min-height: 5rem;
+    padding: 0.75rem 0.875rem;
+    position: relative;
+  }
+
+  /* The step number, in the top right corner. */
+  .weights-path li::before {
+    color: var(--text-faint);
+    content: counter(step);
+    font-family: var(--__sl-font-mono, monospace);
+    font-size: 0.75rem;
+    position: absolute;
+    right: 0.75rem;
+    top: 0.625rem;
+  }
+
+  /* The arrow to the next step, between the boxes. The third box ends a
+   * row, so it gets none: the numbers carry the order to the next row. */
+  .weights-path li:not(:last-child):not(:nth-child(3))::after {
+    color: var(--text-faint);
+    content: '→';
+    font-size: 1.125rem;
+    line-height: 1;
+    position: absolute;
+    right: -1.5rem;
+    top: 50%;
+    transform: translateY(-50%);
+  }
+
+  .weights-path-title {
+    color: var(--text-primary);
+    font-weight: 600;
+  }
+
+  .weights-path-detail {
+    color: var(--text-muted);
+    font-family: var(--__sl-font-mono, monospace);
+    font-size: 0.75rem;
+    line-height: 1.4;
+  }
+
+  @media (max-width: 40rem) {
+    .weights-path {
+      gap: 1.75rem;
+      grid-template-columns: minmax(0, 1fr);
+    }
+
+    .weights-path li:not(:last-child)::after {
+      bottom: -1.5rem;
+      color: var(--text-faint);
+      content: '↓';
+      font-size: 1.125rem;
+      left: 50%;
+      line-height: 1;
+      position: absolute;
+      right: auto;
+      top: auto;
+      transform: translateX(-50%);
+    }
+  }
+</style>

apps/docs/src/content/docs/zoo/embedding.mdx

@@ -194,7 +194,8 @@ await createEmbedder({
 ```
 
 - **modelPath** - the weights, a `model.safetensors` file. The model is
-  read from the file.
+  read from the file. To make your own, see
+  [Exporting weights](/zoo/exporting-weights/).
 - **visionPath** - the weights for images and video. `null` skips the
   download, and images and video become an error.
 - **audioPath** - the same for audio.