{"record":{"id":"d994c654dc5bf15c","repo":"vllm-project/vllm","slug":"dspark-draft-topk-must-be-between-1-and-the-draft","errorCode":null,"errorMessage":"dspark_draft_topk must be between 1 and the draft vocabulary size ({draft_vocab_size})","messagePattern":"dspark_draft_topk must be between 1 and the draft vocabulary size \\((.+?)\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/speculative.py","lineNumber":1106,"sourceCode":"\n                if self.dspark_draft_topk is not None and self.method != \"dspark\":\n                    raise ValueError(\"dspark_draft_topk is only supported by DSpark\")\n\n                dspark_draft_topk = None\n                if self.method == \"dspark\":\n                    hf_config = self.draft_model_config.hf_config\n                    dspark_draft_topk = self.dspark_draft_topk\n                    if dspark_draft_topk is None:\n                        dspark_draft_topk = getattr(\n                            hf_config, \"dspark_draft_topk\", None\n                        )\n                    if dspark_draft_topk is not None:\n                        draft_vocab_size = (\n                            getattr(hf_config, \"draft_vocab_size\", None)\n                            or hf_config.vocab_size\n                        )\n                        if not 1 <= dspark_draft_topk <= draft_vocab_size:\n                            raise ValueError(\n                                \"dspark_draft_topk must be between 1 and the \"\n                                f\"draft vocabulary size ({draft_vocab_size})\"\n                            )\n                        if (\n                            \"Qwen3DSparkModel\"\n                            not in self.draft_model_config.architectures\n                        ):\n                            raise ValueError(\n                                \"dspark_draft_topk is only supported by \"\n                                \"Qwen3DSparkModel\"\n                            )\n                        hf_config.dspark_draft_topk = dspark_draft_topk\n\n                self.draft_tensor_parallel_size = (\n                    SpeculativeConfig._verify_and_get_draft_tp(\n                        self.target_parallel_config,\n                        self.draft_tensor_parallel_size,\n                        self.draft_model_config.hf_config,","sourceCodeStart":1088,"sourceCodeEnd":1124,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/speculative.py#L1088-L1124","documentation":"Raised inside the dspark branch when the resolved dspark_draft_topk (from the CLI/config or the draft hf_config) falls outside [1, draft_vocab_size], where draft_vocab_size is hf_config.draft_vocab_size if present, else hf_config.vocab_size. The top-k logits slice must reference real vocabulary rows, so out-of-range k is rejected before the draft worker is built.","triggerScenarios":"Setting dspark_draft_topk to 0, a negative number, or a value larger than the draft model's vocab (e.g. 200000 against a 152k vocab draft); or a draft checkpoint whose embedded dspark_draft_topk exceeds its own vocab_size after tokenizer remapping.","commonSituations":"Tuning top-k for acceptance-rate vs. cost without checking the draft head size; mixing a large-vocab top-k value copied from a different model family.","solutions":["Set dspark_draft_topk to a value in [1, draft_vocab_size]; check the draft config's vocab_size/draft_vocab_size first","If the bad value comes from the checkpoint's hf_config, override it explicitly in speculative_config","Lower the value to a conventional small k (e.g. 1-10) which is the intended usage]"],"exampleFix":"# before\nspeculative_config={\"method\": \"dspark\", \"model\": \"...\", \"dspark_draft_topk\": 200000}  # draft vocab 152k\n# after\nspeculative_config={\"method\": \"dspark\", \"model\": \"...\", \"dspark_draft_topk\": 8}","handlingStrategy":"validation","validationCode":"draft_vocab = getattr(hf_config, \"draft_vocab_size\", None) or hf_config.vocab_size\nif not 1 <= topk <= draft_vocab:\n    raise ValueError(f\"dspark_draft_topk={topk} outside [1, {draft_vocab}]\")","typeGuard":"def is_valid_dspark_topk(topk: int, draft_vocab_size: int) -> bool:\n    return 1 <= topk <= draft_vocab_size","tryCatchPattern":null,"preventionTips":["Read draft_vocab_size/draft_vocab_size from the draft config.json before choosing top-k","Clamp user-supplied top-k to the vocabulary range in your serving-layer config validator"],"tags":["speculative-decoding","dspark","topk","range-validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}