For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /max/get-started.md).

Mojo function

topk_gpu

def topk_gpu[dtype: DType, out_idx_type: DType, //, sampling: Bool = True, largest: Bool = True, _force_old_impl: Bool = False, KLayoutType: TensorLayout = Layout[*?, *?], TemperatureLayoutType: TensorLayout = Layout[*?, *?], TopPLayoutType: TensorLayout = Layout[*?, *?], MinPLayoutType: TensorLayout = Layout[*?, *?], SeedLayoutType: TensorLayout = Layout[*?, *?]](ctx: DeviceContext, max_k: Int, input: TileTensor[dtype, Storage=input.Storage, address_space=input.address_space, linear_idx_type=input.linear_idx_type, element_size=input.element_size], out_vals: TileTensor[dtype, Storage=out_vals.Storage, address_space=out_vals.address_space, linear_idx_type=out_vals.linear_idx_type, element_size=out_vals.element_size], out_idxs: TileTensor[out_idx_type, Storage=out_idxs.Storage, address_space=out_idxs.address_space, linear_idx_type=out_idxs.linear_idx_type, element_size=out_idxs.element_size], block_size: Optional[Int] = None, num_blocks_per_input: Optional[Int] = None, k: Optional[TileTensor[DType.int64, KLayoutType, ImmutAnyOrigin]] = None, temperature: Optional[TileTensor[DType.float32, TemperatureLayoutType, ImmutAnyOrigin]] = None, top_p: Optional[TileTensor[DType.float32, TopPLayoutType, ImmutAnyOrigin]] = None, min_p: Optional[TileTensor[DType.float32, MinPLayoutType, ImmutAnyOrigin]] = None, seed: Optional[TileTensor[DType.uint64, SeedLayoutType, ImmutAnyOrigin]] = None, valid: Optional[UnsafePointer[Int8, MutAnyOrigin]] = None)

Generalized implementation of the Top K algorithm with/without sampling. Returns the sampled index from the innermost dimension of the input tensor for each row/subvolume or the top K values and indices across the tensor.

Parameters:

dtype (DType): DType - The data dtype of the input tensor.
out_idx_type (DType): DType - The data dtype of the output indices (default == DType.int).
sampling (Bool): Bool - Whether to return token samples from topK dist (default is True).
largest (Bool): Bool - Whether to find the maximum or minimum value.
_force_old_impl (Bool): Bool - Whether to force use the old implementation.
KLayoutType (TensorLayout): Layout type of the k buffer.
TemperatureLayoutType (TensorLayout): Layout type of the temperature buffer.
TopPLayoutType (TensorLayout): Layout type of the top_p buffer.
MinPLayoutType (TensorLayout): Layout type of the min_p buffer.
SeedLayoutType (TensorLayout): Layout type of the seed buffer.

Args:

ctx (DeviceContext): DeviceContext The context for GPU execution.
max_k (Int): Int Largest number of top elements to keep for each batch element.
input (TileTensor[dtype, Storage=input.Storage, address_space=input.address_space, linear_idx_type=input.linear_idx_type, element_size=input.element_size]): TileTensor[dtype] Input tensor as a device TileTensor.
out_vals (TileTensor[dtype, Storage=out_vals.Storage, address_space=out_vals.address_space, linear_idx_type=out_vals.linear_idx_type, element_size=out_vals.element_size]): TileTensor[dtype] Output buffer on device for the K largest values.
out_idxs (TileTensor[out_idx_type, Storage=out_idxs.Storage, address_space=out_idxs.address_space, linear_idx_type=out_idxs.linear_idx_type, element_size=out_idxs.element_size]): TileTensor[DType.int] Output buffer on device for the indices of the K largest values, or sampled token indices. Last dimension is 1 if sampling is True, otherwise K.
block_size (Optional[Int]): Int The number of threads per block (default is 256 from TRT and empirical testing).
num_blocks_per_input (Optional[Int]): Optional[Int] Number of blocks per input (default computed from input size and block size). This is the equivalent of "BLOCKS_PER_BEAM" in TRT-LLM kernel allowing for much larger batch sizes through packing several elements per thread in the first stage.
k (Optional[TileTensor[DType.int64, KLayoutType, ImmutAnyOrigin]]): Optional TileTensor[DType.int64] Device buffer of top elements to keep for each batch element.
temperature (Optional[TileTensor[DType.float32, TemperatureLayoutType, ImmutAnyOrigin]]): The temperature based scaling.
top_p (Optional[TileTensor[DType.float32, TopPLayoutType, ImmutAnyOrigin]]): Only use the tokens whose cumulative probability exceeds this threshold.
min_p (Optional[TileTensor[DType.float32, MinPLayoutType, ImmutAnyOrigin]]): Per-row min-p threshold. Tokens with probability below min_p * max_prob are excluded from sampling.
seed (Optional[TileTensor[DType.uint64, SeedLayoutType, ImmutAnyOrigin]]): The seed to use for the random number generator.
valid (Optional[UnsafePointer[Int8, MutAnyOrigin]]): Optional per-row validity flags (1 = valid, 0 = invalid). The sampling kernel writes 0 for rows where no finite logit was found (e.g. all-NaN rows); rows default to 1 via memset.