{"record":{"id":"d5fb1b7d01b61c27","repo":"huggingface/transformers","slug":"top-h-must-be-in-the-range-0-1","errorCode":null,"errorMessage":"`top_h` must be in the range (0, 1].","messagePattern":"`top_h` must be in the range \\(0, 1\\]\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/logits_process.py","lineNumber":639,"sourceCode":"    >>> from transformers import AutoTokenizer, AutoModelForCausalLM\n\n    >>> model = AutoModelForCausalLM.from_pretrained(\"meta-llama/Llama-3.1-8B\")\n    >>> tokenizer = AutoTokenizer.from_pretrained(\"meta-llama/Llama-3.1-8B\")\n\n    >>> inputs = tokenizer(\"A sequence: 1, 2\", return_tensors=\"pt\")\n\n    >>> outputs = model.generate(**inputs, do_sample=True, top_h=0.4)\n    >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])\n    A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9\n    ```\n    \"\"\"\n\n    def __init__(self, top_h: float, filter_value: float = -float(\"Inf\")):\n        super().__init__()\n\n        # input checks\n        if not (0 < top_h <= 1):\n            raise ValueError(\"`top_h` must be in the range (0, 1].\")\n\n        # Maximum number of top tokens to consider before applying the entropy-based filter.\n        # Acts as a cap for efficiency and numerical stability — increasing this allows more\n        # tokens to be evaluated but may slow down generation. Default is 100.\n        self.top_n = 100\n\n        self.top_h = top_h\n        self.filter_value = filter_value\n\n    def __call__(self, input_ids: torch.LongTensor, scores: torch.FloatTensor) -> torch.FloatTensor:\n        \"\"\"\n        Filters logits using Top-H sampling.\n\n        Args:\n            input_ids (`torch.LongTensor` of shape `(batch_size, sequence_length)`):\n                Input token IDs.\n            scores (`torch.FloatTensor` of shape `(batch_size, vocab_size)`):\n                Raw logits from the model.","sourceCodeStart":621,"sourceCodeEnd":657,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/logits_process.py#L621-L657","documentation":"Thrown by TopHLogitsProcessor.__init__ when top_h is not in the open-closed interval (0, 1]. Top-H sampling filters tokens by an entropy-based threshold scaled by top_h, so it must be a fraction greater than 0 and at most 1 (1.0 disables the filter, 0 would keep nothing).","triggerScenarios":"TopHLogitsProcessor(0.0); top_h=1.1; top_h=-0.2; model.generate(do_sample=True, top_h=0) via generation config.","commonSituations":"Newer parameter with fewer examples in the wild — values copied from top_p configs where 0 was tolerated; percentage-style input (40 instead of 0.4); sweeps crossing the boundary.","solutions":["Use a fraction in (0, 1]: top_h=0.4 (the docstring example)","Convert percentages: top_h = pct / 100.0 and clamp to at most 1.0","Validate external config values with 0 < top_h <= 1 before generate()"],"exampleFix":"# before\nproc = TopHLogitsProcessor(0)  # ValueError\n\n# after\nproc = TopHLogitsProcessor(0.4)\nout = model.generate(**inputs, do_sample=True, top_h=0.4)","handlingStrategy":"validation","validationCode":"def valid_top_h(h):\n    return isinstance(h, (int, float)) and 0 < float(h) <= 1","typeGuard":"def is_valid_top_h(h) -> bool:\n    return isinstance(h, (int, float)) and 0.0 < h <= 1.0","tryCatchPattern":"try:\n    proc = TopHLogitsProcessor(float(h))\nexcept ValueError as e:\n    raise ValueError(f'top_h={h!r} must be in (0, 1]') from e","preventionTips":["top_h is a fraction; 1.0 disables the filter, 0 is invalid","Convert percentages to fractions before passing","Validate config values early since this parameter is newer and often hand-written"],"tags":["generation","top-h","entropy-sampling","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}