[Example] Add Top-n-sigma logit truncation custom logits processor

[Jackie2049]

Summary

Closes #2

Adds an example demonstrating Top-nσ as a custom logits processor in vLLM, based on the paper:

Tang et al., "Top-nσ: Not All Logits Are You Need", ACL 2025. arXiv:2411.07641

What is Top-nσ?

Top-nσ is a logit-space dynamic truncation method that uses the standard deviation of the logit distribution to set a filtering threshold:

threshold = max_logit - n * std_logit
logits[logits < threshold] = -inf

Unlike probability-space filters (top_p, min_p), it operates before softmax and adapts to distribution "peakiness":

• Sharp distribution (model certain): small std → narrow threshold → fewer candidates
• Flat distribution (model uncertain): small std → wide threshold → more candidates

How it compares to other truncation methods

Method	Space	Truncation rule	Adaptive?
top_k	Probability	Keep top-k highest-probability tokens	❌ Fixed count
top_p (nucleus)	Probability	Keep tokens until cumulative probability ≥ p	✅ Adaptive count only
min_p	Probability	Keep tokens with prob ≥ max_prob × min_p	✅ Relative threshold
top_nσ	Logit	threshold = max_logit − n × std	✅ Dual-adaptive
temperature	Logit	logits / T — rescales distribution steepness	❌ No truncation

Key distinction: top_k/top_p/min_p operate after softmax (probability space); top_nσ operates before softmax (logit space).

Why Top-nσ?

• Truncation before softmax — top_nσ filters in logit space first, then softmax only processes the surviving candidates (~2.5% of vocab). In contrast, top_p/min_p must compute a full-vocab softmax first, then truncate in probability space.
• Dual adaptivity — the std-based threshold adjusts both how many and how loosely candidates are kept in one formula: sharp distributions auto-narrow, flat ones auto-widen. top_k fixes the count; top_p adapts the count but not the threshold tightness.
• Temperature-stable — candidate count stays consistent across temperature scaling (logit std scales proportionally), while top_p/min_p candidate counts vary significantly with T.
• Argmax-invariant — the top-1 token always survives (0 std from itself), so greedy decoding can skip this processor entirely.

Changes

• New file: examples/features/logits_processor/top_n_sigma.py
• apply() method uses vectorized Torch operations (not Python per-row loop)

Key properties

• Argmax-invariant: doesn't affect greedy decoding
• Uses vLLM's extra_args mechanism (no SamplingParams changes needed)
• Handles edge cases: NaN/Inf logits, zero std, n≤0 validation

Usage

from vllm import LLM, SamplingParams

llm = LLM(
    model="facebook/opt-125m",
    logits_processors=[TopNSigmaLogitsProcessor],
)

sampling_params = SamplingParams(
    temperature=0.8,
    extra_args={"top_n_sigma": 2.0}
)

Testing

• Example runs with facebook/opt-125m
• Vectorized apply() is bit-for-bit identical to row-by-row loop across FP32/FP16 configs
• Argmax-invariant verified across 32 configurations (all dtype/sharpness/n combinations)
• Edge cases handled: NaN/Inf logits, std=0, n≤0 validation, empty req_info