SkinTokens GGUF — BF16 hi/lo split (X3 precision)

BF16-weight GGUF checkpoints for V-Sekai-fire/skin-tokens-ggml, derived from the project's own published F32 GGUF weights (LocalAI-io/SkinTokens-GGUF).

What it is for

The project's F16 weights corrupt to NaN during inference on Vulkan coopmat2 GPUs (confirmed on an RTX 4090) — upstream ggml-vulkan has no F16-weight/F32-activation matmul pipeline on coopmat2 hardware at all, so it silently forces a lossy F32→F16 reformat regardless of the requested precision. Plain BF16 weights avoid the crash (BF16 keeps F32's exponent range) but lose real accuracy on their own (confirmed: a reference humanoid mesh goes from TokenRig's correct 24 predicted joints down to 90 with plain BF16 truncation).

Each matrix tensor here is instead split into two BF16 tensors — name (hi) and name.lo (lo) — following XLA's ALG_DOT_BF16_BF16_F32_X3 trick (the same technique behind see-through-verify's triple-bf16 precision ladder and V-Sekai-fire/contract-ggml-rd's bf16 kernels): hi + lo reconstructs the original F32 value to within ~2e-4 relative error, and summing the hi/lo cross terms at inference time recovers near-F32 matmul accuracy using only native bf16xbf16 Vulkan hardware — no custom shaders needed. Measured on the same reference mesh: 24 predicted joints (exact match to F32), 19 distinct bones used (exact match), weight distribution within 0.01% of the F32 run.

Norm/embedding/sensitive tensors are kept plain F32, matching the project's own convert_to_gguf.py "sensitive" set.

Provenance

Derived from LocalAI-io/SkinTokens-GGUF's F32/ checkpoints (mesh-encoder.gguf, tokenrig.gguf, skin-vae.gguf), which are themselves converted from the upstream VAST-AI-Research/SkinTokens release. scripts/f32_to_bf16x3_gguf.py in this repo is the exact converter used (reads an F32 GGUF, writes the hi/lo split; a simpler scripts/f32_to_bf16_gguf.py for a plain bf16-only variant is included too, for comparison/debugging).

Loading these requires the matching skin-tokens-ggml code change (internal.hpp's mul_mat_x3 helper, linear()/rows_linear() detecting the .lo companion tensor): merged into main via PR #33 (commit 0fccf15).

Use

hf download chibifire/skintokens-ggml-bf16x3 --local-dir models/SkinTokens-GGUF/BF16X3
skintokens-cli rig models/SkinTokens-GGUF/BF16X3 character.glb character-rigged.glb --device vulkan

Licence

The upstream SkinTokens code and weights are MIT (see V-Sekai-fire/skin-tokens-ggml's NOTICE). This repo's own derivation (the F32→BF16-hi/lo split itself) is distributed under the same MIT terms as the upstream weights it is derived from; see the upstream NOTICE for the full chain of attribution.