Skip to content

feat(ggml): add TurboQuant Q4_T (flat 4-bit, block_size=256)#23617

Closed
Chun-Yi-Wu wants to merge 1 commit into
ggml-org:masterfrom
Chun-Yi-Wu:feat/turboquant-q4t
Closed

feat(ggml): add TurboQuant Q4_T (flat 4-bit, block_size=256)#23617
Chun-Yi-Wu wants to merge 1 commit into
ggml-org:masterfrom
Chun-Yi-Wu:feat/turboquant-q4t

Conversation

@Chun-Yi-Wu

Copy link
Copy Markdown
Phase 1 — Core ggml type system:
- Add GGML_TYPE_Q4_T = 43 enum in ggml.h, bump COUNT to 44
- Define QK_T=256 and block_q4_t struct (d[FP16] + qs[128 nibbles], 130 byte s)
- Register type_traits[] entry with dequantize_row_q4_t / quantize_row_q4_t_ ref
- Implement dequantize_row_q4_t(): same formula as Q4_0, block size 256
- Implement quantize_row_q4_t_ref() and quantize_row_q4_t() scalar CPU impl
- Add validation case in ggml_validate_row_data() for type safety

Phase 2 — CPU backend:
- Add type_traits_cpu[] entry with vec_dot = ggml_vec_dot_q4_t_q8_0
- Implement ggml_vec_dot_q4_t_q8_0_generic() kernel (handles QK_T=256 blocks mapped to Q8_0 keys, fixing NaN in dot product test)

Phase 3 — CLI wiring:
- Add LLAMA_FTYPE_MOSTLY_Q4_T enum in llama.h (value 41)
- Wire ftype->ggml_type mapping in llama-quant.cpp (Q4_T -> GGML_TYPE_Q4_T)
- Register Q4_T string option in quantize.cpp QUANT_OPTIONS array

Phase 4 — End-to-end validation:
- Add tensor fallback: Q4_T -> Q4_0 for tensors with ncols not divisible by 256
- Full pipeline verified: f32->Q4_T quantization, GGUF load, and inference t est

Spec: flat block layout, same dequant as Q4_0 ((nibble-8)*d), ~4.06 bpw,
QK_T=256 blocks. Compatible with existing Q8_K matmul via vec_dot dispatch.

Tests: test-backend-ops OK, test-gguf 71/71 OK, test-quantize-fns Q4_T OK

Overview

Additional information

Requirements

    Phase 1 — Core ggml type system:
    - Add GGML_TYPE_Q4_T = 43 enum in ggml.h, bump COUNT to 44
    - Define QK_T=256 and block_q4_t struct (d[FP16] + qs[128 nibbles], 130 byte
s)
    - Register type_traits[] entry with dequantize_row_q4_t / quantize_row_q4_t_
ref
    - Implement dequantize_row_q4_t(): same formula as Q4_0, block size 256
    - Implement quantize_row_q4_t_ref() and quantize_row_q4_t() scalar CPU impl
    - Add validation case in ggml_validate_row_data() for type safety

    Phase 2 — CPU backend:
    - Add type_traits_cpu[] entry with vec_dot = ggml_vec_dot_q4_t_q8_0
    - Implement ggml_vec_dot_q4_t_q8_0_generic() kernel (handles QK_T=256 blocks
      mapped to Q8_0 keys, fixing NaN in dot product test)

    Phase 3 — CLI wiring:
    - Add LLAMA_FTYPE_MOSTLY_Q4_T enum in llama.h (value 41)
    - Wire ftype->ggml_type mapping in llama-quant.cpp (Q4_T -> GGML_TYPE_Q4_T)
    - Register Q4_T string option in quantize.cpp QUANT_OPTIONS array

    Phase 4 — End-to-end validation:
    - Add tensor fallback: Q4_T -> Q4_0 for tensors with ncols not divisible by
256
    - Full pipeline verified: f32->Q4_T quantization, GGUF load, and inference t
est

    Spec: flat block layout, same dequant as Q4_0 ((nibble-8)*d), ~4.06 bpw,
    QK_T=256 blocks. Compatible with existing Q8_K matmul via vec_dot dispatch.

    Tests: test-backend-ops OK, test-gguf 71/71 OK, test-quantize-fns Q4_T OK
@Chun-Yi-Wu Chun-Yi-Wu requested a review from ggerganov as a code owner May 24, 2026 14:37
@github-actions github-actions Bot added examples ggml changes relating to the ggml tensor library for machine learning labels May 24, 2026
@Chun-Yi-Wu Chun-Yi-Wu closed this May 24, 2026
@ggml-gh-bot

ggml-gh-bot Bot commented May 24, 2026

Copy link
Copy Markdown

Hi @Chun-Yi-Wu, thanks for your contribution!

Per our contribution guidelines, the automated PR checker found the following issue(s) that need your attention:

  • AI-generated content: This project does not accept PRs, descriptions or commit messages that are fully or predominantly AI-generated. If you have used AI to assist you in writing code, please make sure to disclose that explicitly.

Please note that maintainers reserve the right to make final decisions on PRs. If you believe there is a mistake, please comment below.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

examples ggml changes relating to the ggml tensor library for machine learning

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants