docs: align Safetensors README with GGUF HQ tiers and document distinct quantization provenance

README.md

@@ -33,10 +33,10 @@ It is packaged as a standard Hugging Face repository containing packed Safetenso
 * **Upstream Model:** [`google/embeddinggemma-2`](https://huggingface.co/google/embeddinggemma-2)
 * **Pinned Upstream Commit:** `914f7f89142e33e77833254d9c9b90c3cef7303b`
 * **Base Architecture:** `EmbeddingGemma2ForSequenceClassification` / `EmbeddingGemma2TextModel`
-* **Model Size:** 1.24 GB total directory (packed `model.safetensors`: 1,236 MB / 1.21 GiB)
+* **Model File Size:** `model.safetensors`: **1,296,471,072 bytes / 1,296.47 MB / 1,236.41 MiB**. The pinned BF16 original model file is 1,488,915,288 bytes / 1,488.92 MB / 1,419.94 MiB: **12.93% smaller on disk**. This compares model files, not total directories or measured runtime memory.
 * **Verification Status:** Public Hub access verified; local release smoke test passed; packaged for Transformers & SentenceTransformers.
-* **Quantization Framework:** [AutoRound](https://github.com/intel/auto-round) (v0.8+)
-* **Quantization Scheme:** W4A16 Symmetric (`group_size=128`, 100 tuning iterations, sign gradient descent with Hessian approximation)
+* **Quantization Framework:** [AutoRound](https://github.com/intel/auto-round) **0.16.0**, as recorded in the published `quantization_config.json`.
+* **Quantization Scheme:** W4A16 symmetric (`bits=4`, `group_size=128`, `iters=100`); recorded packing format `auto_round:auto_gptq`.
 * **Release Decision:** **RELEASE GO** (Early community release based on empirical fidelity retention)
 
 ---
@@ -63,7 +63,18 @@ All evaluations were conducted against an unquantized **bfloat16 reference** acr
 
 The candidate was evaluated against strict quality criteria:
 * **Empirical Gate Result:** **RELEASE GO / Early Community Release**
-* **Gate Context:** The initial theoretical target of $\ge 0.99$ Mean Cosine Similarity and $\ge 95\%$ Top-5 Retrieval Agreement was not fully reached in every dimension (achieved: **0.9878** Mean Cosine, **87.6%** Top-5 Agreement). However, with **99.0% Top-1 Agreement**, **100.0% Recall@5**, and **0.9781 Spearman Correlation**, the model demonstrates outstanding retrieval fidelity and semantic stability without a single NaN or Inf anomaly.
+* **Gate Context:** The initial theoretical target of $\ge 0.99$ Mean Cosine Similarity and $\ge 95\%$ Top-5 Retrieval Agreement was not fully reached in every dimension (achieved: **0.9878** Mean Cosine, **87.6%** Top-5 Agreement). However, with **99.0% Top-1 Agreement**, **100.0% Recall@5**, and **0.9781 Spearman Correlation**, these benchmark results show retained retrieval success alongside measurable BF16-fidelity loss; no NaN or Inf anomaly was observed.
+
+
+The companion [GGUF HQ releases](https://huggingface.co/webmp3/Sakura-EmbeddingGemma-2-AutoRound-GGUF#side-by-side-comparison--same-bf16-benchmark-768d) achieve higher reported BF16 fidelity on the same existing BF16 reference and text/code benchmark. They are separate quantization runs; their results do **not** change this Safetensors model's release-gate outcome.
+
+| GGUF companion tier | MiB | Combined Mean Cosine (768d) | Combined Spearman (768d) | Text Top-5 | Text/Code Recall@5 |
+|---|---:|---:|---:|---:|---|
+| Q4 HQ | 169.79 | 0.99400270 | 0.98857239 | 90.00% | 100% / 100% |
+| Q5 HQ — recommended balance | 199.88 | 0.99828082 | 0.99664205 | 95.40% | 100% / 100% |
+| Q6 HQ | 231.75 | 0.99940187 | 0.99879852 | 96.80% | 100% / 100% |
+
+Values are quoted from the GGUF README's [Side-by-Side Comparison](https://huggingface.co/webmp3/Sakura-EmbeddingGemma-2-AutoRound-GGUF#side-by-side-comparison--same-bf16-benchmark-768d). **Aggregation differs:** this Safetensors section reports alignment over 200 text query/document vectors; the GGUF combined Mean Cosine/Spearman include all 300 text-and-code vectors. Text Top-5 uses the 100-pair text retrieval benchmark in both. These are not identically aggregated mean scores, and no all-metric comparison with Unsloth is implied.
 
 ### MRL (Matryoshka Representation Learning) Dimensions
 
@@ -91,9 +102,29 @@ EmbeddingGemma 2 supports dimension truncation followed by L2-renormalization. T
 | Distribution / Format | Runtime Compatibility | Direct Transformers / ST Support | Notes |
 |---|---|---|---|
 | **Sakura AutoRound W4A16** *(This repo)* | **Python, PyTorch, Transformers, SentenceTransformers** | **Yes (Plug-and-play)** | Runs directly in existing Python AI pipelines without needing custom binary builds. |
-| **GGUF Community Releases** (`unsloth`, `ggml-org`) | `llama.cpp` | No (requires llama-server or bindings) | During this release test, the downloaded community GGUF could not be loaded with the older local llama.cpp build used for evaluation (`unknown model architecture`). Current llama.cpp versions include dedicated Gemma embedding support, so this should not be interpreted as a general llama.cpp limitation. |
+| **GGUF Community Releases** (`unsloth`, `ggml-org`) | `llama.cpp` | No (requires llama-server or bindings) | EmbeddingGemma 2 support is upstream in llama.cpp via [PR #30054](https://github.com/ggml-org/llama.cpp/pull/30054), merged **2026-10-06**. The earlier `unknown model architecture` result came from an older local build; use a build that includes this support. Community GGUF controls have since been loaded and benchmarked with a supported build. |
 | **ONNX Community Releases** (`onnx-community`) | ONNX Runtime / Transformers.js | No (ONNX graph format) | Modular multi-graph export tailored for WebGPU/JavaScript execution. |
-| **Sakura AutoRound GGUF** *(Companion)* | `llama.cpp` | Via llama-server / bindings | GGUF runtime variant: [webmp3/Sakura-EmbeddingGemma-2-AutoRound-GGUF](https://huggingface.co/webmp3/Sakura-EmbeddingGemma-2-AutoRound-GGUF) |
+| **Sakura AutoRound GGUF HQ** *(Companion)* | `llama.cpp` | Via llama-server / bindings | [Q4 HQ **169.79 MiB**, Q5 HQ **199.88 MiB** (recommended balance), Q6 HQ **231.75 MiB**](https://huggingface.co/webmp3/Sakura-EmbeddingGemma-2-AutoRound-GGUF). This Safetensors/ST package is for native Python pipelines; the standalone text GGUF variants are for llama.cpp. |
+
+---
+
+### Safetensors vs. GGUF HQ: separate quantization runs
+
+**These are separate optimization runs, not two exports of one quantized state.** The published Safetensors `quantization_config.json` records a different scheme and iteration count from the preserved GGUF cal256 build configurations/logs. Both use AutoRound **0.16.0** and the same base model, but that does not imply identical optimized weights or calibration.
+
+| Setting | This Safetensors W4A16 release | GGUF HQ cal256 runs |
+|---|---|---|
+| Transformer weight types | 4-bit symmetric W4A16 | Q4_K/Q5_K/Q6_K base with 48 Q8_0 block-PLE linears |
+| Weight grouping | Group size **128** | Q4_K/Q5_K: **32** weights per subgroup, 8 subgroups per 256-weight superblock; Q6_K: **16**, 16 subgroups per 256-weight superblock. Q8_0 uses 32-weight blocks. |
+| Iterations | **100**, published configuration | **50**, saved build configurations/logs |
+| Calibration selection | Existing W4A16 pipeline selects up to **64** entries from `calibration/calib_data.json` at seqlen 128; exact historical input content is not independently established | **256** synthetic retrieval samples: 48 EN queries, 48 EN docs, 48 DE queries, 48 DE docs, 32 code queries and 32 code snippets; zero exact benchmark overlap |
+| Optimization/export path | AutoRound W4A16; published packing format `auto_round:auto_gptq`; Safetensors for Transformers/ST | Native AutoRound **SignRoundV2** (`enable_alg_ext=True`), matching GGUF optimized-state packing, then selected embedding-path precision overrides |
+| AutoRound version | **0.16.0**, published configuration | **0.16.0**, preserved builds |
+| Scope | Full multimodal checkpoint, vision/audio and sensitive components retained in BF16 | Standalone text GGUF; CPU/native llama.cpp runtime |
+
+**Historical evidence limit:** the Safetensors model's local SHA256 matches the published weight file, and its local configuration matches the published configuration. The W4A16 pipeline script and saved benchmark report are available, but no immutable historical calibration-input hash/sample manifest or complete W4A16 training log was found in the inspected release records. Therefore, the exact historical 64 texts and their realized selection cannot be certified from those records alone. The script's 64-sample selection is reported as pipeline configuration, not as a recovered immutable run manifest. Exact historical Transformers/SentenceTransformers versions were not recorded in the published quantization configuration.
+
+The GGUF cal256 runs do retain explicit sample count, calibration SHA256 `b65d22bad14722ab02d316ddae2ea6f860b92c94669f5717321b66e81abb91b8`, resolved per-layer configuration, native optimized-state packing evidence and training logs. These differences are enough to rule out a shared optimized quantization state. Public GGUF settings and runtime provenance are linked from the companion README; the inspected W4A16 pipeline settings are summarized here without claiming historical inputs that were not preserved.
 
 ---
 
@@ -161,7 +192,7 @@ with torch.no_grad():
 
 ## Limitations & Honest Disclosure
 
-1. **Text Precision:** The 216 linear layers of the text backbone are quantized to 4-bit weights (`torch_zp` / GPTQ-style packed format). While memory footprint is significantly reduced (~1.24 GB vs ~5.5 GB for full BF16), low-bit weights inherently involve quantization approximations.
+1. **Text Precision and File Size:** The 216 text-backbone linear layers use 4-bit packed weights. `model.safetensors` is 1,296,471,072 bytes (1,296.47 MB / 1,236.41 MiB), compared with 1,488,915,288 bytes (1,488.92 MB / 1,419.94 MiB) for the [pinned full BF16 original](https://huggingface.co/google/embeddinggemma-2/blob/914f7f89142e33e77833254d9c9b90c3cef7303b/model.safetensors). The **12.93% model-file saving is modest**: token embeddings and multimodal towers remain BF16. These on-disk measurements do not establish a runtime-memory reduction; the former ~5.5 GB BF16 comparison is not supported by the checked model files.
 2. **Multimodal Towers:** The vision and audio towers remain in 16-bit precision. If you do not use vision or audio inputs, memory consumption can be minimized by only loading the text language model.
 3. **Execution Device:** Optimal execution requires modern CPU (AVX-512 / VNNI) or GPU environments supporting accelerated bfloat16 and packed int4 kernels.