[Docs] Explain pointer-alignment JIT specialization in Triton skill (#57669)
Signed-off-by: Woosuk Kwon <woosuk@inferact.ai>
Woosuk Kwon committed
Sep 19, 2026 at 00:53 UTC
c3b48446349569512749db7f6e2164aa8a33437d
1 file changed
+11
-5
.agents/skills/triton-kernel-writing/SKILL.md
+11
-5
@@ -22,10 +22,14 @@ description: Write or review Triton kernels for vLLM, with practical guidance fo
22
a small, legible heuristic when workloads need different choices. Use
23
`triton.autotune` only when tuning is critical to performance, such as for a
24
matrix multiplication. Otherwise prioritize simple code and fast startup.
25
-- Be careful to avoid unintended runtime JIT compilation. For example, put
26
- unimportant runtime integer scalars in `do_not_specialize`, especially those
27
- that may alternate between values such as 0 and 1, which can produce
28
- different specialization keys.
25
+- Avoid unintended runtime JIT compilation. Put unimportant runtime integer
26
+ scalars in `do_not_specialize`, especially values that alternate between 0
27
+ and 1. Pointer alignment also affects specialization: an offset tensor view
28
+ can trigger a new variant after warmup used an aligned allocation. For
29
+ scalar-only pointers whose alignment provides no useful optimization, use
30
+ `@triton.jit(do_not_specialize_on_alignment=["end_ptr"])`. Retain alignment
31
+ specialization when vectorized accesses benefit from it. See the
32
+ [Triton JIT options](https://triton-lang.org/main/python-api/generated/triton.jit.html).
33
- The Triton compiler does not guarantee safe ordering when a kernel writes to
34
a pointer and subsequently reads from the same pointer. This pattern must
35
have a `tl.debug_barrier()` between the write and read. The barrier
@@ -49,7 +53,9 @@ description: Write or review Triton kernels for vLLM, with practical guidance fo
53
## Validation
54
55
- Check correctness at boundary shapes and at sizes that exercise masks and
52
- large offsets.
56
+ large offsets. Include offset tensor views, not only fresh allocations.
57
+ Warm aligned buffers, then exercise offset views with vLLM's
58
+ `--jit-monitor-mode error --jit-monitor-verbose` to catch missing variants.
59
- Choose accumulation and intermediate dtypes explicitly. Test numerically
60
difficult inputs, not only random, well-scaled tensors.
61
- Use `$kernel-microbenchmark` for benchmark construction, measurement, and