hipEngine
hipEngine is a ROCm-native local LLM inference engine designed from the ground up for AMD RDNA GPUs (starting with gfx1100, gfx1151). It pairs a small purpose-built Python host with a complete suite of custom-tuned HIP kernels developed through 100+ iterations of profiling and tuning.
hipEngine has lightweight dependencies with no PyTorch required for fully supported GPUs and models.
Core principles
- HIP-first, not CUDA-ported. Kernels directly target AMD hardware like gfx1100/RDNA3 with wave32, vec8 FMA, and the actual cache hierarchy.
- Torch-free runtime.
import torchis not on the hot path. The runtime owns a thinhipengine.Tensorover raw HIP/CUDA device pointers and driveshipblasLt,hipGraph, AOTriton, and JIT builds throughctypes. Torch appears only as an optional dlpack bridge behind thehipengine[torch]extra (~125 MiB install including the vendored AOTriton subset vs ~2 GiB with torch). - Multi-backend from day one. Kernels live under
kernels/hip_gfx1100/,kernels/hip_gfx1151/,kernels/cuda_sm86/,kernels/cpu_reference/as peer trees. - Four-axis plugin registry. Kernels are keyed by
(backend, layer, quant, variant). Models, quant schemes, and layers are plugins. Noif backend == "..."orif quant == "..."branches in dispatch / engine / model code. - Fused + unfused coexist. Every fused composite
(
rmsnorm+rotate,gate_combine_residual, …) has a numerically-equivalent unfused chain registered under its primitives, used as both fallback and correctness baseline. - Evidence-backed performance. Every performance claim ships with
model + quant + workload shape + hardware + exact command + correctness gate
(KL ≤ 0.05, top-1 ≥ 90% vs
kernels/cpu_reference/). Seedocs/BENCHMARK.mdandbenchmarks/README.md.
Status
v0.3.0 alpha. The runtime hot path is torch-free by construction, and the
first two 35B-class model-loading surfaces are available on gfx1100 and gfx1151:
shisa-ai/Qwen3.6-35B-A3B-PARO-packed
(19.07 GiB, 4.68 bpw) in packed
ParoQuant format, plus Qwen3.6 GGUF
Q4_K_M / Q4_K_S files through the resident GGUF path. Older benchmark
artifacts may still show the historical
Qwen3.6-35B-A3B-PARO-full4096-e5-packed name or local MTP-BF16 assembly path;
those rows use the same packed PARO architecture and remain the evidence for the
numbers below.
- Model-aware
backend="auto"/quant="auto"defaults select the registered PARO or GGUF route without environment-variable setup. Direct generation now supports exact token-id prompts, detailed outputs, logprobs, structured finish details, and backend execution telemetry. - PARO and GGUF support ordinary sampling controls including top-k/min-p, penalties, logit bias, suppression, deterministic seeds, EOS/min-token policy, token stops, and multi-token stops. Covered PARO shapes use a native GPU sampler; unsupported shapes use an explicit host fallback.
- The OpenAI-compatible server includes capability/readiness discovery, token and context diagnostics, exact usage accounting, request batching, deadlines, cancellation, opt-in Prometheus metrics, and detailed streaming metadata.
- Local-agent support includes OpenAI-style tools, Qwen thinking controls, structured-output result validation, deterministic continuation handles, and app-local transcript sessions with fork, rollback, snapshot, and overflow policies.
- Qwen3.6 GGUF models with NextN tensors expose detailed MTP generation and a guarded explicit non-streaming server route. Dense PARO DFlash and the shared speculative proposal/verify/commit infrastructure are available as retained runtime and benchmark paths.
- PARO BF16 KV has retained W7900 evidence through 128K under the 24 GiB gate. The 256K INT8 layout also fits physically, but fails the required Qwen3.6 long-rollout quality gate and is not a supported or usable route. Current capacity, throughput, speculative-decode, and concurrency evidence is reported below with separate gfx1100/gfx1151 provenance and correctness gates.
This remains an alpha, single-GPU release. Production PARO native c>1 decode
is disabled pending independent-c1 correctness, app-local sessions do not reuse
resident KV, structured outputs are not grammar-constrained decoding, and the
server MTP route is explicit-only. See the API limitations
and concurrency status for the exact
boundaries.
Hardware targets
| Backend | Hardware | Status |
|---|---|---|
cpu_reference |
Any CPU, numpy | Correctness oracle; CI without GPU |
hip_gfx1100 |
AMD Radeon Pro W7900 / RX 7900 XTX (RDNA3) | Active backend |
hip_gfx1151 |
AMD Ryzen AI MAX+ 395 / Radeon 8060S (Strix Halo, RDNA3.5) | Active backend |
cuda_sm86 |
NVIDIA Ampere consumer (3090-class) | Planned peer backend |
backend="auto" is the public API/server default. It maps exact gfx1100 and
gfx1151 detections to the matching HIP backend; unknown ROCm targets warn and
select cpu_reference where a CPU implementation exists. Users on nearby targets
such as gfx1101/gfx1102 can force a backend with backend="hip_gfx1100",
--backend hip_gfx1100, or HIPENGINE_BACKEND=hip_gfx1100 after validating
correctness/performance.
Wave32 is the default for hip_gfx1100 device code; wave64 is treated as an
isolated experiment with its own gates (see
docs/PLAN.md).
Memory Usage
The clean 2026-07-12 W7900 run measured hipEngine 8116c453
(rebased-equivalent reachable 8708304f; runtime and benchmark code identical)
against the current Qwen3.6 packed PARO model under the 24 GiB portability gate. Both physical
capacity/layout rows pass, but the required Qwen3.6 long-rollout quality gate
rejects INT8 KV. Accordingly, 256K INT8 is reported as allocation capacity—not
as a supported or usable route.
| Route | Context/decode | Tracked peak | 24 GiB margin | Retained KV | Layout audit | Quality status |
|---|---|---|---|---|---|---|
| PARO BF16 KV | 128K/128 | 22.124 GiB | 1.876 GiB | 2.690 GB | Passed | Reference path |
| PARO INT8 per-token/head KV, FP16 scales | 256K/128 | 23.957 GiB | 0.043 GiB | 2.708 GB | Passed; no BF16 shadow | Rejected by Qwen3.6 128K/128 rollout |
The INT8 layout retains 2,686,976,000 payload bytes plus 20,992,000 FP16 scale
bytes across ten full-attention layers and no BF16 K/V shadow. Its matched
128K/128 BF16 comparison diverges at generated index 2, with mean/max KL
3.7646/10.0796 and 3.88% top-1 agreement. FP32 scales also reject. Memory was
measured once per row; the reported timing fields are diagnostic only.
See the
capacity summary,
FP16-scale quality gate,
and FP32-scale follow-up.
llama.cpp configuration note
The repository has no compact artifact or source revision for the former llama.cpp Q8_0 memory tables, so those numbers are not toplines. The tested configuration was:
--flash-attn on -ctk q8_0 -ctv q8_0 -c 262144 -b 128 -ub 128
A replacement capacity table must record the GGUF fingerprint, llama.cpp commit/build, GPU, full command, and whole-card sampling artifact.
Model Performance
gfx1100 (Radeon RX 7900 XTX / Radeon Pro W7900)
Status: retained. This clean 2026-07-12 refresh measured hipEngine
8116c453 (rebased-equivalent reachable 8708304f; runtime and benchmark code
identical), TheRock HIP 7.15, right-sized resident sessions, production graph decode, two
discarded plus five measured hipEngine runs, and five llama.cpp samples per
phase. The W7900-local GGUF oracle passes external tokens and byte-exact
hidden/Conv/GDN/KV state. All six rows pass clean provenance, stable finite
outputs, exact Q4_K_M identity, corrected W7900 VRAM scope, and sample-variance
gates. PARO remains W4 PARO/BF16 KV; the other columns use Q4_K_M with
BF16/F16 KV, so bold values are descriptive rather than same-quant wins.
Prefill tok/s
| Workload | hipEngine PARO | hipEngine GGUF | llama.cpp HIP | llama.cpp Vulkan |
|---|---|---|---|---|
| 512/128 | 2917.732 | 644.719 | 2412.320 | 2627.990 |
| 1K/128 | 2995.876 | 676.177 | 2389.670 | 2631.750 |
| 4K/128 | 2943.038 | 677.618 | 2255.080 | 2521.770 |
| 32K/128 | 2108.868 | 628.364 | 1667.640 | 1943.920 |
| 64K/128 | 1584.131 | 572.612 | 1291.820 | 1414.470 |
| 128K/128 | 1056.252 | 484.212 | 891.949 | 1079.280 |
Decode tok/s
| Workload | hipEngine PARO | hipEngine GGUF | llama.cpp HIP | llama.cpp Vulkan |
|---|---|---|---|---|
| 512/128 | 115.599 | 89.873 | 80.756 | 107.786 |
| 1K/128 | 103.238 | 94.751 | 80.805 | 107.555 |
| 4K/128 | 105.943 | 96.551 | 79.768 | 103.066 |
| 32K/128 | 92.438 | 83.673 | 74.304 | 91.835 |
| 64K/128 | 78.260 | 71.644 | 69.010 | 83.746 |
| 128K/128 | 60.663 | 56.745 | 60.933 | 70.833 |
Peak memory GiB
| Workload | hipEngine PARO | hipEngine GGUF | llama.cpp HIP | llama.cpp Vulkan |
|---|---|---|---|---|
| 512/128 | 18.144 | 21.478 | 21.606 | 21.260 |
| 1K/128 | 18.367 | 21.710 | 21.618 | 21.220 |
| 4K/128 | 19.161 | 22.995 | 21.674 | 21.278 |
| 32K/128 | 19.864 | 23.559 | 22.216 | 21.855 |
| 64K/128 | 20.403 | 24.203 | 22.895 | 22.512 |
| 128K/128 | 22.124 | 25.493 | 24.089 | 23.824 |
W7900 row sources: accepted summary, hipEngine PARO, hipEngine GGUF, llama.cpp HIP, llama.cpp Vulkan, and W7900 correctness oracle.
gfx1151 (AMD Ryzen AI MAX+ 395 / Radeon 8060S)
Thanks to Framework for sending a dedicated Framework Desktop Strix Halo motherboard for this profiling and tuning work.
Status: retained. GGUF and llama.cpp are the clean 2026-07-11 matched
refresh. PARO 512/1K are the clean 2026-07-12 exact recovery at 9944e481;
4K and 32K-128K are the clean scoped AOTriton queue-isolation refresh at
01e2cec5, all with TheRock HIP 7.15 and TuneD accelerator-performance.
hipEngine uses two discarded warmups plus five measured repetitions per
right-sized resident shape; llama.cpp uses one internal warmup plus five
samples per split phase. The linked artifacts pass their clean provenance,
output/state, variance, model/build/device, and memory-scope gates. Bold marks
the best raw value per row, but PARO is W4 PARO rather than Q4_K_M and memory
scopes differ, so the emphasis is descriptive rather than a controlled
same-quant/backend win.
Prefill tok/s
| Workload | hipEngine PARO | hipEngine GGUF | llama.cpp HIP | llama.cpp Vulkan |
|---|---|---|---|---|
| 512/128 | 1140.101 | 430.767 | 1061.260 | 1067.770 |
| 1K/128 | 1208.343 | 437.467 | 1043.230 | 1069.870 |
| 4K/128 | 1089.031 | 403.946 | 1009.240 | 1016.580 |
| 32K/128 | 906.145 | 369.942 | 743.547 | 814.923 |
| 64K/128 | 716.775 | 334.395 | 573.611 | 660.974 |
| 128K/128 | 474.641 | 270.601 | 390.441 | 476.788 |
Decode tok/s
| Workload | hipEngine PARO | hipEngine GGUF | llama.cpp HIP | llama.cpp Vulkan |
|---|---|---|---|---|
| 512/128 | 66.767 | 49.536 | 50.939 | 62.396 |
| 1K/128 | 61.746 | 52.192 | 50.818 | 62.136 |
| 4K/128 | 62.715 | 52.999 | 50.126 | 60.097 |
| 32K/128 | 50.342 | 43.947 | 44.240 | 51.319 |
| 64K/128 | 42.094 | 37.477 | 39.326 | 44.422 |
| 128K/128 | 30.386 | 27.862 | 32.114 | 34.948 |
Peak memory GiB
| Workload | hipEngine PARO | hipEngine GGUF | llama.cpp HIP | llama.cpp Vulkan |
|---|---|---|---|---|
| 512/128 | 18.039 | 21.478 | 21.375 | 21.551 |
| 1K/128 | 18.051 | 21.710 | 21.387 | 21.501 |
| 4K/128 | 19.026 | 22.995 | 21.444 | 21.507 |
| 32K/128 | 19.729 | 23.559 | 21.987 | 22.191 |
| 64K/128 | 20.403 | 24.203 | 22.666 | 22.627 |
| 128K/128 | 22.124 | 25.493 | 23.862 | 24.254 |
The memory columns have different scopes: hipEngine reports tracked allocator
high-water, while llama.cpp reports absolute whole-device amdgpu GTT used,
sampled every 10 ms. Use them for within-column context growth, not small
cross-column allocator comparisons. Row sources: PARO exact recovery,
PARO 4K-128K AOTriton queue isolation,
accepted July 11 matched summary,
July 11 PARO reference,
hipEngine GGUF,
llama.cpp HIP, and
llama.cpp Vulkan. Exact settings and gates are in the canonical benchmarks/README.md.
Current gfx1151 GGUF decode baselines
These are separate exact repeated-token SOL-G4/G5 controls. The model sweep above excludes graph capture from steady decode throughput; SOL-G5 charges one capture/instantiate and destroy to each 128-token window.
| Path | Platform and protocol | Result | Evidence status |
|---|---|---|---|
| GGUF eager c1 | Radeon 8060S/gfx1151; Qwen3.6-35B-A3B UD-Q4_K_M; BF16 KV; [9707] * 512; TheRock HIP 7.15; TuneD accelerator-performance; clean scalar/candidate/scalar, 1 discarded + 4 measured runs per leg; 128 eager steps; graph off |
48.850 tok/s (20.471 ms/token), +0.309% vs clean scalar control |
Retained for this exact repeated-token protocol; control/candidate ranges do not overlap, every output ID is 9707, and the G1 hidden/state/KV oracle is linked |
| GGUF state-bound graph c1 | Radeon 8060S/gfx1151; same current model/KV/prompt/stack; 1 warmup + 4 measured rotating same-session runs; 128 steps; capture and destroy charged | 48.704 tok/s (20.532 ms/token), -0.293% vs same-run eager; +0.201% vs scalar graph |
Exact 128/128 state/KV/token replay, but current G5 rejects a graph-over-eager speed claim; graph default policy is tracked separately |
Artifacts: SOL-G4 eager audit
and SOL-G5 production graph audit.
See benchmarks/README.md for the platform freshness
index, exact settings, run commands, and evidence status.
Speculative decode (DFlash / MTP)
Every displayed route has its own same-protocol AR control. The exact/default
and llama-compat columns are separate because only llama-compat shares the
B2 natural24 structure used by the llama.cpp comparison.
GGUF MTP comparison, Radeon Pro W7900/gfx1100
| Metric | hipEngine GGUF true AR | hipEngine GGUF exact/default | hipEngine GGUF llama-compat |
llama.cpp HIP base AR |
|---|---|---|---|---|
| Route | State-bound graph, no MTP | B3, fixed 10 cycles | B2, natural24/cyclecap24 | Natural25 request / 24 timed transitions |
| Decode | 98.75 tok/s fixed / 93.30 tok/s natural24 | 68.50 tok/s | 79.70 tok/s | 78.29 tok/s transition-normalized |
| Own true AR | same route | 98.75 tok/s | 93.30 tok/s | same route |
| MTP / own AR | 1.0000x | 0.6936x | 0.8542x | n/a |
| Draft acceptance | n/a | 73.53% | 82.95% | n/a |
| Accepted draft/output | n/a | 50.00% | 60.83% | n/a |
| Complete wall per output/transition | 10.718 ms natural24 | 14.696 ms | 12.578 ms | 12.774 ms |
| State/commit contract | serial autoregressive | serial-prefix preserving | direct partial commit/dp4a; accuracy-traded | native llama.cpp autoregressive |
The old 34.28-34.49 tok/s true-AR denominator was an eager-only benchmark
path, not the fastest production no-MTP route. gfx1100 had no backend graph
capability even though the state-bound implementation was already shared with
gfx1151. A clean W7900 p512/d24 gate now passes all 24 hidden/GDN/KV/token
transitions and moves capture-inclusive wall from 30.536 to 12.514 ms/token
(2.4402x). The full natural24 suite matches every prior eager generated-token
preview/tail and moves 34.28 -> 93.30 tok/s in the same MTP wrapper.
At the matched cross-engine boundary, hipEngine counts 240 complete post-prefill
transitions including graph capture/instantiate/close; llama.cpp build 9648
requests 25 outputs and counts the 240 timed transitions inside predicted_ms.
hipEngine is 93.30 versus 78.29 tok/s (+19.19%). BF16 versus F16 KV remains
disclosed. llama.cpp stays an external diagnostic with
performance_claim=false because its local instrumentation patchset is dirty
but preserved.
Neither MTP route beats the corrected production AR control. Exact/default
remains the semantic control; llama-compat remains explicit-only because
direct partial commit is not serial-prefix-equivalent. The fixed-cycle exact
and natural24 compatibility rows are different protocols and are not ranked
against each other.
W7900 llama-compat full-suite gate against graph AR
| Scope | Prompts | True AR tok/s | llama-compat tok/s |
MTP / AR | Draft acceptance | Accepted/output | Cycle wall/output |
|---|---|---|---|---|---|---|---|
| Full | 10 | 93.30 | 79.70 | 0.8542x | 82.95% | 60.83% | 12.578 ms |
| Train | 6 | 93.73 | 82.01 | 0.8749x | 88.12% | 61.81% | 12.224 ms |
| Heldout | 4 | 92.67 | 76.47 | 0.8252x | 76.00% | 59.38% | 13.110 ms |
code |
4 | 93.63 | 86.99 | 0.9291x | 95.38% | 64.58% | 11.523 ms |
general_en |
2 | 90.99 | 75.87 | 0.8338x | 75.68% | 58.33% | 13.212 ms |
general_ja |
2 | 94.38 | 72.17 | 0.7647x | 69.23% | 56.25% | 13.889 ms |
mixed_ja_en |
2 | 93.98 | 78.71 | 0.8375x | 82.86% | 60.42% | 12.744 ms |
All four categories and heldout lose to graph AR despite unchanged strong draft
acceptance. This corrects the earlier false MTP-win conclusion without changing
the compatibility semantics. Artifact:
2026-07-12-w7900-gfx1100-gguf-graph-ar-refresh.json.
GGUF MTP comparison, Radeon 8060S/gfx1151
| Metric | hipEngine GGUF exact/default | hipEngine GGUF llama-compat |
llama.cpp HIP |
|---|---|---|---|
| Route | B5, fixed 10 cycles | B2, natural24/cyclecap24 | B2, natural25 request / 24 timed transitions |
| Canonical/native MTP decode | 51.81 tok/s (0.9571x own AR) | 69.50 tok/s (1.2776x own AR) | 69.44 tok/s native (1.3752x own AR; not cross-engine comparable) |
| Cross-engine MTP decode-transition rate | n/a: fixed-cycle horizon | 69.38 tok/s | 66.66 tok/s |
| Cross-engine own AR transition rate | n/a: fixed-cycle horizon | 54.40 tok/s | 48.47 tok/s |
| Cross-engine MTP / own AR | n/a | 1.2755x | 1.3752x |
| Draft acceptance | 72.33% | 77.72% | 79.56% |
| Accepted draft/output | 53.49% | 59.58% | 57.60% |
| Full-cycle/predicted wall per counted output or timed transition | 19.360 ms/output | 14.413 ms/output | 15.001 ms/transition |
| State/commit contract | exact/default, serial-prefix preserving | direct partial commit/dp4a; accuracy-traded | native llama.cpp compatibility target |
The current exact/default B5 route no longer beats true AR after the
correctness/state-lifecycle pass: 51.81 vs 54.14 tok/s (0.9571x). Its old
61.98 tok/s row is retained only as history. llama-compat remains a separate,
explicit-only semantic contract and is not serial-prefix-equivalent.
The cross-engine rows use the canonical transition-matched timing contract:
hipEngine uses complete cycle wall; llama.cpp requests 25 outputs and counts
the 24 transitions inside predicted_ms. This removes llama.cpp's native
one-untimed-token numerator advantage. hipEngine uses BF16 KV while llama.cpp
uses F16 KV, which remains a model-execution difference even with matched timer
boundaries. The captured llama.cpp source is dirty but fully preserved in the
repository patchset; the binary hash is authoritative and
performance_claim=false.
gfx1151 llama-compat full-suite gate
| Scope | Prompts | True AR tok/s | llama-compat tok/s |
MTP / AR | Draft acceptance | Accepted/output | Cycle wall/output |
|---|---|---|---|---|---|---|---|
| Full | 10 | 54.40 | 69.50 | 1.2776x | 77.72% | 59.58% | 14.413 ms |
| Train | 6 | 54.44 | 70.96 | 1.3034x | 82.08% | 60.42% | 14.116 ms |
| Heldout | 4 | 54.33 | 67.42 | 1.2408x | 71.79% | 58.33% | 14.858 ms |
code |
4 | 54.42 | 74.81 | 1.3747x | 91.04% | 63.54% | 13.387 ms |
general_en |
2 | 54.50 | 67.62 | 1.2407x | 71.79% | 58.33% | 14.811 ms |
general_ja |
2 | 54.40 | 66.60 | 1.2242x | 69.23% | 56.25% | 15.042 ms |
mixed_ja_en |
2 | 54.25 | 64.90 | 1.1964x | 69.23% | 56.25% | 15.438 ms |
All four categories and the heldout split beat their true same-protocol AR controls. Train/heldout draft acceptance is 82.08% / 71.79%; the gap is kept visible rather than averaged away.
Dense PARO DFlash
| Path | Platform and protocol | Result | Evidence status |
|---|---|---|---|
| DFlash B=4 online-gated | W7900/gfx1100; Qwen3.6-27B PARO target plus Qwen3.6-27B DFlash drafter; 9 prompts; 64 decode tokens | 40.10 vs 32.57 AR tok/s, 1.231x | Retained under the recorded DFlash gate; source tree was dirty and must be refreshed before changing the claim |
Artifacts: W7900 GGUF MTP transfer,
DFlash,
gfx1151 exact MTP,
and gfx1151 llama-compat MTP.
The gfx1151 matched natural24 controls are exact/default B1-B5
and llama.cpp HIP B2.
Historical hipEngine OpenAI MTP server rows are excluded. The current raw-ID
route counts exact completion IDs across every choice and owns batch timing
once. The
corrected 2026-07-11 server matrix finds that compatibility MTP changes true-AR
IDs even at c1, so it must remain explicit-only despite diagnostic c1/c2 speed
gains; SOL-S1 routes automatic requests to exact/default AR while keeping the
compatibility hook explicit-only. See the
route-gate artifact
and canonical benchmarks/README.md.
The clean gfx1151 PARO DFlash S4 profile is exact but not competitive:
9.68 versus 65.27 tok/s AR (0.148x) at B4/32 tokens. Branch-copy is
faster but diverges at generated token 1, and fused target LM-head is 5.16%
slower than unfused. See the
compact profile
and the canonical
benchmark analysis.
Concurrency
The current publishable gfx1151 table is the exact PARO production-routing
catalog below. c1 has a retained timing; c2-c8 use width-1 sessions because
every native candidate fails the independent-c1 oracle. P2 proves that serial
route through ragged c8-to-c1 EOS/cancel transitions and front/middle/tail
sparse slots. Native batching remains closed until a general c>N algorithm
passes the same token/state/KV gates. See
docs/CONCURRENCY.md for the design history.
The linked records keep gfx1100 and gfx1151 separate because the model files,
ROCm stacks, and comparison backends differ. Aggregate is total tok/s across
the batch; per-sequence is tok/s seen by one request. See
docs/VLLM_RDNA3.md for vLLM RDNA3 setup notes.
gfx1100 / W7900 decode tok/s vs concurrency (Qwen3.6 35B-A3B, 512/128)
Status: stale diagnostic. This is a median-of-3 scaling snapshot, not an apples-to-apples engine ranking. hipEngine uses PARO W4/BF16 KV, llama.cpp uses Vulkan Q4_K_M/f16 KV, and vLLM uses GPTQ Int4. hipEngine and llama.cpp report backend decode timing; vLLM reports OpenAI client wall throughput.
No eligible concurrency row; the mixed-quant, mixed-timing sweep remains linked below pending rerun.
Protocol: prompt 512, decode 128, 8 warmup decode tokens, median of 3.
hipEngine c=1 uses the single-sequence graph-replay benchmark and c>1 uses
the native batch benchmark. llama.cpp restarts its server for each concurrency
and repetition with -np c -c 1024*c.
Source artifacts:
hipEngine W7900,
llama.cpp Vulkan W7900,
vLLM local build W7900,
full W7900 refresh summary,
and vLLM RDNA3 notes.
gfx1151 / Radeon 8060S PARO exact shape catalog (2026-07-11, Qwen3.6 35B-A3B, 512/128)
Status: retained c1 performance, c1-c8 routing correctness, and production
lifecycle safety. Clean a18ff7bc uses the same exact 512-token fixture at
every width. c1 graph replay is retained; every c2-c8 native candidate fails
independent-c1 equality at generated index 2 and is explicitly routed through
width-1 sessions. Clean 6f1910c9 then passes ragged c8-to-c1 EOS/cancel
lifecycle coverage without compacting physical slots.
| Client c | Production backend groups | Exact classification | Retained aggregate decode |
|---|---|---|---|
| 1 | 1 |
c1 oracle / accepted | 66.910 tok/s (14.946 ms/token) |
| 2 | 1+1 |
explicitly serial | no separate c>N claim |
| 3 | 1+1+1 |
explicitly serial | no separate c>N claim |
| 4 | 1+1+1+1 |
explicitly serial | no separate c>N claim |
| 5 | five width-1 groups | explicitly serial | no separate c>N claim |
| 6 | six width-1 groups | explicitly serial | no separate c>N claim |
| 7 | seven width-1 groups | explicitly serial | no separate c>N claim |
| 8 | eight width-1 groups | explicitly serial | no separate c>N claim |
Protocol: W4 PARO/BF16 KV, 40 layers, exact prompt-ID SHA-256
b162b2d0...2388, 8 warmup decode steps, 128 measured decode steps, and greedy
sampling. c1 is a clean median of three (66.948/66.754/66.910 tok/s). Native
c2-c8 diagnostic rates are withheld from the topline because all rows fail the
137-token oracle. The P2 gate uses prompt lengths 449 through 512 and matches
all eight generated sequences, 30 linear-state families, and 10 live K/V
families through EOS plus front/middle/tail sparse cancellation. Ragged prefill
uses the correctness-first per_segment_ragged_exact fallback and makes no
throughput claim. See the P1 compact catalog,
P2 lifecycle artifact,
and canonical run record.
gfx1151 / Radeon 8060S historical cross-engine concurrency (2026-06-15)
Status: stale diagnostic. hipEngine uses PARO W4/BF16 KV; llama.cpp uses
Vulkan Q4_K_S/f16 KV. vLLM did not produce a healthy server. The summary lacks
the measured hipEngine commit, and the then-used per-run device properties could
report gfx1100 even though the run forced HIPENGINE_HIP_ARCH=gfx1151.
No eligible concurrency row; the performance_claim=false snapshot remains linked below pending rerun.
Protocol: prompt 512, decode 128, 8 warmup decode tokens, median of 3. Primitive c>1 attention/KV checks passed. The generated-token field used the older batch-shaped reference and is not independent-c1 evidence. Profiler, scaling, and provenance gates also did not pass.
Source artifacts: gfx1151 summary,
hipEngine PARO,
llama.cpp Vulkan, and
vLLM blocked.
A 2026-06-13 RX 7900 XTX rerun reached c1/c2/c4 but c8 blocked with HIP OOM;
see XTX partial.
Replicate the W7900 hipEngine, llama.cpp Vulkan, and vLLM concurrency rows with:
scripts/run_w7900_readme_refresh.sh concurrency
scripts/run_w7900_readme_refresh.sh vllm
The exact settings and gfx1151 runner gap are recorded in
benchmarks/README.md.
GGUF Support
As of v0.2.0, hipEngine includes resident Qwen3.6 GGUF support for Q4_K_M and
Q4_K_S model files (with more formats planned). This is a major runtime path,
not just a loader shim: GGUF has its own quant readers, bulk-prefill path,
decode-repacked T16 layouts, and fast-path controls.
Current caveats:
-
PARO models take ~22s to load on the W7900 test host in the current refresh; GGUF Q4_K_M currently takes about 74s because decode-repack happens on load. On-disk caching could reduce startup time later, but would require additional storage for repacked layouts.
-
GGUF has higher base weight residency than packed PARO before KV cache is the deciding factor. The full-attention KV slope is the same 10-layer Qwen3.6 shape; the 24 GiB long-context gap is mostly the loaded-weight baseline. Packed PARO is ~19.07 GiB on disk, while the local GGUF tensor payloads are:
GGUF tensor family Q4_K_M GiB Q4_K_M mix Q4_K_S GiB Q4_K_S mix Q4_K_S - Q4_K_M Q4_K 11.531 54.7% 16.875 84.8% +5.344 Q5_K 6.531 31.0% 0.000 0.0% -6.531 Q8_0 1.932 9.2% 1.932 9.7% +0.000 Q6_K 1.004 4.8% 1.004 5.0% +0.000 F32/BF16 metadata 0.098 0.5% 0.098 0.5% +0.000 Total tensor payload 21.097 100.0% 19.909 100.0% -1.188 In other words,
Q4_K_Ssaves ~1.19 GiB versusQ4_K_Mby replacing the selected-MoEQ5_Kexpert-down payload withQ4_K; it still starts above packed PARO, and hipEngine's resident T16/pack8 decode layouts add their own allocator shape. On 24 GiB cards, currentQ4_K_MBF16-KV support is a mid-context path unless a lower-memory KV/weight policy is explicitly enabled. The current clean gfx1151 p512/d128 census is 21.478 GiB owned/tracked: 20.461 GiB replacement weights, 0.503 GiB required raw token embedding, 0.097 GiB dense weights/metadata, and 0.417 GiB scratch/session buffers. It confirms the default T16 path replaces source layouts rather than retaining raw+packed copies; this short-context margin is not a 128K capacity claim. -
GGUF is close enough to PARO to share some high-level scheduling ideas, but in practice it needs substantial GGUF-only kernels and dispatch. The goal for future releases is to keep closing the remaining PARO/GGUF speed gap.
Architecture at a glance
┌─────────────────────────────────────────────────────────────────┐
│ USER API │
│ hipengine.LLM.generate() library API │
│ hipengine serve OpenAI-compatible server │
├─────────────────────────────────────────────────────────────────┤
│ LOADING (torch-free) │
│ safetensors mmap + hipMemcpyAsync / HF config / jinja2 chat │
│ templates / HF tokenizers (Rust) │
├─────────────────────────────────────────────────────────────────┤
│ DISPATCH │
│ Scheduler / Block Manager (KVPolicy) / Prefix Cache │
│ Fusion Planner (chain → kernel plan, fused preferred) │
│ Model / Quant / Layer plugins / Engine loop (hipGraph replay) │
├─────────────────────────────────────────────────────────────────┤
│ CORE (torch-free primitives) │
│ hipengine.Tensor / device / memory / stream / graph / blas │
│ build (hipcc subprocess + ctypes.CDLL + .so cache) │
├─────────────────────────────────────────────────────────────────┤
│ KERNELS (backend-keyed custom HIP implementations) │
│ kernels/hip_gfx1100/ attention / linear_attn / moe / quant │
│ wmma / norm / rotary / fused │
│ kernels/hip_gfx1151/ native target-arch peer backend │
│ kernels/cuda_sm86/ (future) │
│ kernels/cpu_reference/ correctness oracle, no GPU required │
└─────────────────────────────────────────────────────────────────┘
Full layer diagram, plugin axes, KV cache ABI, and roadmap are in
docs/PLAN.md.
Installation
# PyPI wheel: runtime, JIT kernel sources, vendored AOTriton, and server
pip install hipengine
# Source checkout: fetch Git LFS payloads before an editable install
git lfs install
git lfs pull
pip install -e .
# with the optional dlpack torch bridge for user-boundary interop
pip install "hipengine[torch]"
# dev / test
pip install -e ".[dev]"
Python 3.10+. A working ROCm install with libamdhip64.so on the loader path
is required for any GPU run; CPU-reference correctness tests run without a GPU.
ROCm / TheRock setup for retained benchmark rows
For retained gfx1100 benchmark rows, use the pinned AMD TheRock environment in
docs/THEROCK.md, not an ad-hoc mixed /opt/rocm runtime.
Current retained rows use TheRock ROCm 7.13.0a20260423 with:
HIP version: 7.13.26162-1140233ffe
On this host (Linux 7.0.10-1-cachyos, W7900 VBIOS 113-D7070100-138, RX 7900
XTX VBIOS 113-EXT89622-001), ROCm 7.14 nightly diagnostics showed GGUF prefill
and MTP wall-time regressions, so 7.13 remains the canonical stack until a newer
ROCm release beats the same gates. See docs/THEROCK.md for the exact pip install/repair commands, clean process wrapper, and the upstream TheRock
RELEASES.md reference.
The installed app exposes a small command group:
hipengine --help
hipengine serve --help
hipengine bench list
Quickstart
Model loading does not start network downloads. Populate the Hugging Face cache before using a repository ID:
hf download shisa-ai/Qwen3.6-35B-A3B-PARO-packed
Then construct LLM with the same repository ID:
from hipengine import LLM, SamplingParams
llm = LLM("shisa-ai/Qwen3.6-35B-A3B-PARO-packed")
outputs = llm.generate(
["Hello, hipEngine."],
SamplingParams(max_tokens=64, temperature=0.0),
)
print(outputs[0])
LLM(model) auto-detects gfx1100 or gfx1151 and selects the model plugin's
quantization. The Qwen3.6 GGUF path also selects T16 decode-repack plus the
retained WMMA-prefill/GEMV-decode session profile. Explicit backend= and
quant= arguments are overrides; supported PARO and GGUF models do not require
hipEngine environment variables. Unsupported registry combinations fail instead
of falling back to a torch path.
OpenAI-compatible server
The OpenAI-compatible FastAPI layer is installed by default:
pip install hipengine
hipengine serve \
--model shisa-ai/Qwen3.6-35B-A3B-PARO-packed \
--served-model-name qwen-paro
--model accepts either a local filesystem path or a Hugging Face model ID
already present in the local HF cache; hipEngine resolves IDs locally and does
not download weights during startup.
Core endpoints are GET /v1/models, POST /v1/completions, and
POST /v1/chat/completions, with token-level SSE streaming, logprobs,
OpenAI-style tools, structured-output validation, and Qwen thinking controls.
hipEngine extensions provide readiness/capability discovery, token and context
diagnostics, and app-local session management. Chat responses separate
<think> reasoning into reasoning_content. The server eagerly warms the model
on startup, caps omitted chat max_tokens with
--chat-default-max-tokens (default 4096), and has an explicit --debug mode
for full request/response payload logging. See the complete
docs/API.md endpoint table for bearer-token auth,
request examples, feature contracts, diagnostics, and current limitations.
Documentation
| File | Purpose |
|---|---|
docs/PLAN.md |
Architecture, plugin axes, phase roadmap, LoC budgets |
docs/BENCHMARK.md |
Benchmark protocols, baselines, correctness gate, artifact format |
docs/TESTING.md |
RED/GREEN workflow, correctness oracles, fixture policy |
docs/KERNELS.md |
Kernel catalog, source-lineage drift workflow, JIT cache gotchas, build profiles |
docs/ENVS.md |
Environment variables, TheRock setup, benchmark/profiling profiles |
docs/ROOFLINE.md |
RDNA3 / W7900 performance model and decision tree |
docs/IMPLEMENTATION.md |
Implementation status and concrete milestones |
docs/API.md |
OpenAI-compatible server usage and endpoint support |
docs/PREFILL.md |
Native prefill implementation spec |
docs/SAMPLING.md |
Normal sampling parameter support plan |
docs/MTP.md |
Multi-token prediction plan |
docs/DFLASH.md |
DFlash draft-model speculative decode plan |
docs/SOL-OPTIMIZATION.md |
gfx1151 PARO/GGUF optimization ledger and completion gates |
docs/MTP-LLAMACPP-PARITY.md |
Current GGUF MTP parity results and open reruns |
docs/PARO-GGUF-MTP-TRANSFER.md |
PARO follow-up queue from GGUF/MTP server and verifier work |
docs/HIP-vs-VULKAN.md |
Current timing-contract v2 backend conclusions and portability gates |
benchmarks/README.md |
Canonical topline scoreboard, platform freshness, protocols, and refresh commands |
AGENTS.md |
Ground rules for every coding / review / benchmarking task |
WORKLOG.md |
Append-only cross-session journal of decisions and measurements |
Development
# narrowest test suite (CPU-only paths run without a GPU)
pytest -q
# kernel source-lineage drift check before any port
python3 scripts/check_lineage.py --kind kernel --diff stat
See AGENTS.md for the full workflow: when to run the
CPU-reference correctness gate, when to add a rocprofv3 --kernel-trace smoke,
and what a retained benchmark row requires.
References & lineage
hipEngine is not a fork of any project; it is a brand new codebase with from-scratch code and kernels. Of course it builds on the work of many others:
- ROCm - of course this all sits on AMD's open-source compute stack, notably on HIP.
- Nano-vLLM - most of the original kernel tuning iteration loops used this as a host-layer. Some of the performance limitations of the architecture motivated the hipEngine rewrite, but we remain grateful and deeply appreciative of nano-vllm as a great research platform.
- ParoQuant - after reviewing the current SOTA on model quantization, we chose ParoQuant as the first target due to both its excellent accuracy and its efficiency (QTIP/YAQA is very cool but proved challenging to implement performant RDNA3 kernels)
- FastDMS - our KVCache ABI is shaped by the lessons learned from building our DMS reference implementation.
Greetz: hipfire, Lucebox, DS4, ExLlamaV3 and ofc the og llama.cpp
See also: Marlin, kernel-anvil, wmma_ops, tilelang, fsr4-rdna3-optimization, ROCm examples
License
hipEngine source code is licensed under AGPL-3.0-or-later. It is built and distributed for anyone who has an AMD card that hasn't been living up to its compute potential.
Model weights, checkpoints, and external datasets remain under their own licenses.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hipengine-0.3.0.tar.gz.
File metadata
- Download URL: hipengine-0.3.0.tar.gz
- Upload date:
- Size: 44.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f25060b807bc9f64d2860cb0d1b0eb960253379417ca6a02df06bdf1f6100890
|
|
| MD5 |
25fc5203e5fe8f3446ab01b664595d0f
|
|
| BLAKE2b-256 |
25138152acede745b5e882f5351a8026bdd8240bbd84888ca898ac2c4da6b858
|
Provenance
The following attestation bundles were made for hipengine-0.3.0.tar.gz:
Publisher:
publish.yml on shisa-ai/hipEngine
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hipengine-0.3.0.tar.gz -
Subject digest:
f25060b807bc9f64d2860cb0d1b0eb960253379417ca6a02df06bdf1f6100890 - Sigstore transparency entry: 2156214138
- Sigstore integration time:
-
Permalink:
shisa-ai/hipEngine@ed52bad75068de637ce6cb81b6505c7b55802ab3 -
Branch / Tag:
refs/tags/v0.3.0 - Owner: https://github.com/shisa-ai
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@ed52bad75068de637ce6cb81b6505c7b55802ab3 -
Trigger Event:
push
-
Statement type:
File details
Details for the file hipengine-0.3.0-py3-none-manylinux_2_39_x86_64.whl.
File metadata
- Download URL: hipengine-0.3.0-py3-none-manylinux_2_39_x86_64.whl
- Upload date:
- Size: 19.7 MB
- Tags: Python 3, manylinux: glibc 2.39+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
55a6e854b8d83ccf41f3cd95c963c6db29f55e0a793327fdf3490da2b6854d3d
|
|
| MD5 |
8752ce022f3cc29270b61c5411dc7cff
|
|
| BLAKE2b-256 |
9b5db4108b939cb81e52879e3145f0c6ed0833f9a13666be097a9b15d4655c36
|
Provenance
The following attestation bundles were made for hipengine-0.3.0-py3-none-manylinux_2_39_x86_64.whl:
Publisher:
publish.yml on shisa-ai/hipEngine
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hipengine-0.3.0-py3-none-manylinux_2_39_x86_64.whl -
Subject digest:
55a6e854b8d83ccf41f3cd95c963c6db29f55e0a793327fdf3490da2b6854d3d - Sigstore transparency entry: 2156214309
- Sigstore integration time:
-
Permalink:
shisa-ai/hipEngine@ed52bad75068de637ce6cb81b6505c7b55802ab3 -
Branch / Tag:
refs/tags/v0.3.0 - Owner: https://github.com/shisa-ai
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@ed52bad75068de637ce6cb81b6505c7b55802ab3 -
Trigger Event:
push
-
Statement type: