Heuristic:Mlc ai Web llm Penalty Parameter Defaults
| Knowledge Sources | |
|---|---|
| Domains | LLMs, Debugging, Sampling |
| Last Updated | 2026-02-14 22:00 GMT |
Overview
Auto-correction behavior for frequency and presence penalty parameters, plus valid ranges for all sampling configuration values.
Description
WebLLM's generation config validation automatically pairs `frequency_penalty` and `presence_penalty`: if only one is set, the other defaults to `0.0` with a warning. This prevents accidental penalty application. Additionally, all sampling parameters have strict valid ranges that are checked at request time, preventing silent misconfiguration.
Usage
Use this heuristic when configuring sampling parameters for chat completions. Applies to all `ChatCompletionRequest` calls that override default generation settings.
The Insight (Rule of Thumb)
- Action: Always set both `frequency_penalty` and `presence_penalty` together, or neither.
- Valid Ranges:
- `frequency_penalty`: [-2.0, 2.0]
- `presence_penalty`: [-2.0, 2.0]
- `repetition_penalty`: > 0
- `top_p`: (0, 1]
- `temperature`: >= 0
- `logit_bias` values: [-100, 100], keys must be integer token IDs
- `max_tokens`: > 0
- Trade-off: Setting only one penalty triggers auto-correction with a console warning, which may cause confusion in production.
Reasoning
The frequency and presence penalties work together in the sampling pipeline: frequency penalty reduces the likelihood of tokens proportional to how often they appear, while presence penalty reduces likelihood of any previously-seen token. Using one without the other is usually unintentional and can produce unexpected generation behavior. The auto-correction to 0.0 ensures the penalty system is either fully configured or fully off.
Penalty auto-correction from `src/config.ts:179-195`:
// If only one of frequency or presence penalty is set, make the other one 0.0
if (
_hasValue(config.frequency_penalty) &&
!_hasValue(config.presence_penalty)
) {
config.presence_penalty = 0.0;
log.warn("Only frequency_penalty is set; we default presence_penaty to 0.");
}
if (
_hasValue(config.presence_penalty) &&
!_hasValue(config.frequency_penalty)
) {
config.frequency_penalty = 0.0;
log.warn(
"Only presence_penalty is set; we default frequency_penalty to 0.",
);
}
Range validation from `src/config.ts:155-177`:
if (
config.frequency_penalty &&
(config.frequency_penalty < -2.0 || config.frequency_penalty > 2.0)
) {
throw new RangeError("frequency_penalty", -2.0, 2.0);
}
if (_hasValue(config.repetition_penalty) && config.repetition_penalty! <= 0) {
throw new MinValueError("repetition_penalty", 0);
}
if ((_hasValue(config.top_p) && config.top_p! <= 0) || config.top_p! > 1) {
throw new RangeError("top_p", 0, 1);
}
if (_hasValue(config.temperature) && config.temperature! < 0) {
throw new NonNegativeError("temperature");
}