Skip to main content

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 torch is not on the hot path. The runtime owns a thin hipengine.Tensor over raw HIP/CUDA device pointers and drives hipblasLt, hipGraph, AOTriton, and JIT builds through ctypes. Torch appears only as an optional dlpack bridge behind the hipengine[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. No if backend == "..." or if 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/). See docs/BENCHMARK.md and benchmarks/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_S saves ~1.19 GiB versus Q4_K_M by replacing the selected-MoE Q5_K expert-down payload with Q4_K; it still starts above packed PARO, and hipEngine's resident T16/pack8 decode layouts add their own allocator shape. On 24 GiB cards, current Q4_K_M BF16-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

hipengine-0.3.0.tar.gz (44.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hipengine-0.3.0-py3-none-manylinux_2_39_x86_64.whl (19.7 MB view details)

Uploaded Python 3manylinux: glibc 2.39+ x86-64

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

Hashes for hipengine-0.3.0.tar.gz
Algorithm Hash digest
SHA256 f25060b807bc9f64d2860cb0d1b0eb960253379417ca6a02df06bdf1f6100890
MD5 25fc5203e5fe8f3446ab01b664595d0f
BLAKE2b-256 25138152acede745b5e882f5351a8026bdd8240bbd84888ca898ac2c4da6b858

See more details on using hashes here.

Provenance

The following attestation bundles were made for hipengine-0.3.0.tar.gz:

Publisher: publish.yml on shisa-ai/hipEngine

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hipengine-0.3.0-py3-none-manylinux_2_39_x86_64.whl.

File metadata

File hashes

Hashes for hipengine-0.3.0-py3-none-manylinux_2_39_x86_64.whl
Algorithm Hash digest
SHA256 55a6e854b8d83ccf41f3cd95c963c6db29f55e0a793327fdf3490da2b6854d3d
MD5 8752ce022f3cc29270b61c5411dc7cff
BLAKE2b-256 9b5db4108b939cb81e52879e3145f0c6ed0833f9a13666be097a9b15d4655c36

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page