Upload README.md with huggingface_hub

README.md

@@ -21,6 +21,8 @@ intra-block token dependency) and a **per-position confidence head** (accept-rat
 prediction). Trained with the [speculators](https://github.com/vllm-project/speculators)
 library.
 
+`main` is the final epoch-3 checkpoint (best validation).
+
 ## Model Specifications
 
 - **Base Model**: zai-org/GLM-5.2-FP8
@@ -32,22 +34,39 @@ library.
 
 ## Checkpoint series
 
-This repo publishes **per-epoch checkpoints** of a single 3-epoch run. `main` tracks
-the latest available epoch; each epoch is also a permanent revision.
+Per-epoch checkpoints of a single 3-epoch run. `main` = the final (epoch-3) checkpoint;
+each epoch is also a permanent revision.
 
 | revision | epoch | status |
 | --- | --- | --- |
 | `epoch-1` | 1 / 3 | ✅ available |
-| `epoch-2` | 2 / 3 | ✅ this checkpoint (= `main`) |
-| `epoch-3` | 3 / 3 | training |
+| `epoch-2` | 2 / 3 | ✅ available |
+| `epoch-3` | 3 / 3 | ✅ final (= `main`) |
 
 ```python
 from transformers import AutoModel
 model = AutoModel.from_pretrained(
-    "mgoin/GLM-5.2-speculator.dspark", revision="epoch-2", trust_remote_code=True
+    "mgoin/GLM-5.2-speculator.dspark", trust_remote_code=True  # or revision="epoch-3"
 )
 ```
 
+## Evaluation Results
+
+Validation metrics after epoch 3 (held-out split):
+
+| metric | value |
+| --- | --- |
+| **mean accepted length** | **3.967** |
+| full accuracy | 0.613 |
+| mean acceptance rate | 0.584 |
+| confidence abs error | 0.044 |
+
+Per-position acceptance (positions 1-7):
+`0.829 / 0.723 / 0.646 / 0.587 / 0.539 / 0.500 / 0.464`
+
+Epoch-over-epoch mean accepted length (train-set proxy for epochs 1-2, val for epoch 3):
+3.376 → 3.819 → **3.967 (val)**.
+
 ## Training Details
 
 The model was trained using the Speculators library on prompts from
@@ -133,12 +152,11 @@ Notes:
 - DSpark-specific flags: `--markov-rank`, `--enable-confidence-head`,
   `--confidence-head-with-markov`, `--confidence-head-alpha`. Dropping them (and
   using `--speculator-type dflash`) recovers a plain DFlash draft.
-- `--checkpoint-freq 0.2` writes sub-epoch checkpoints (~5 per epoch) for resumability.
 
 ## Deployment
 
-DSpark inference support is available on the vLLM nightly
-(`uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly`):
+DSpark inference support in vLLM is landing; once available, deploy with speculative
+decoding:
 
 ```bash
 vllm serve zai-org/GLM-5.2-FP8 \
@@ -146,58 +164,12 @@ vllm serve zai-org/GLM-5.2-FP8 \
     --max-model-len 16384 \
     --trust-remote-code \
     --speculative-config '{
-        "model": "RedHatAI/GLM-5.2-speculator.dspark",
+        "model": "mgoin/GLM-5.2-speculator.dspark",
         "num_speculative_tokens": 7,
-        "method": "dspark",
-        "draft_sample_method": "probabilistic"
+        "method": "dspark"
     }'
 ```
 
-## Evaluation Results
-
-Train-set metrics at the end of epoch 2 (per-epoch validation passes did not
-complete due to server restarts; per-dataset acceptance evaluation will accompany
-the final checkpoint):
-
-| metric | epoch 1 | epoch 2 |
-| --- | --- | --- |
-| mean accepted length | 3.376 | **3.819** |
-| full accuracy | 0.532 | 0.587 |
-| mean acceptance rate | 0.497 | 0.557 |
-
-Per-position accuracy (positions 1-7), epoch 2:
-`0.809 / 0.693 / 0.619 / 0.549 / 0.515 / 0.478 / 0.445`
-
-Still improving epoch-over-epoch (epoch 3 in training).
-
-### Acceptance length in vLLM (revision `epoch-2`)
-
-Measured end-to-end in vLLM speculative decoding (nightly
-`0.23.1rc1.dev709+g2b753ad20`), serving `zai-org/GLM-5.2-FP8` on 4xB300 with
-`num_speculative_tokens=7`, `draft_sample_method="probabilistic"`, greedy
-sampling, batch size 1, 64 single-turn chat prompts (32 `HumanEval` + 32
-`math_reasoning` from
-[`RedHatAI/speculator_benchmarks`](https://huggingface.co/datasets/RedHatAI/speculator_benchmarks)),
-1024 output tokens each. Acceptance is computed from vLLM's
-`spec_decode_num_accepted_tokens_per_pos` / `num_drafts` counter deltas.
-The earlier
-[`GLM-5.2-speculator.dspark-preview`](https://huggingface.co/RedHatAI/GLM-5.2-speculator.dspark-preview)
-is included for reference (measured on a 16-prompt subset of the same set).
-
-> This table is updated as later epochs are published; `main` currently
-> points to **`epoch-2`**.
-
-| Checkpoint | Pos 1 | Pos 2 | Pos 3 | Pos 4 | Pos 5 | Pos 6 | Pos 7 | Accept Len | Decode tok/s |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| `epoch-2` (= `main`) | 74.7% | 56.0% | 41.5% | 31.1% | 23.7% | 18.0% | 13.2% | **3.58** | **225** |
-| `epoch-1` | 74.7% | 55.4% | 40.2% | 29.5% | 21.5% | 15.4% | 10.9% | 3.48 | 219 |
-| `dspark-preview` | 57.5% | 31.7% | 15.4% | 7.4% | 3.3% | 1.5% | 0.7% | 2.18 | 139 |
-
-The epoch-2 gain comes from deeper draft positions (position-1 acceptance is
-unchanged), consistent with continued training. For reference, the same
-server without speculative decoding decodes at 102 tok/s (2.2x speedup for
-`epoch-2`).
-
 ## References
 
 - **DFlash**: Block Diffusion for Flash Speculative Decoding (arXiv:2602.06036) — the