{"record":{"id":"1da24917cc84dd93","repo":"sgl-project/sglang","slug":"quanto-checkpoint-is-missing-quantization-map-base","errorCode":null,"errorMessage":"Quanto checkpoint is missing quantization_map_base64","messagePattern":"Quanto checkpoint is missing quantization_map_base64","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/quantization/configs/quanto_int8_config.py","lineNumber":95,"sourceCode":"            return unquantized_method()\n        self.selected.add(prefix)\n        return QuantoInt8LinearMethod()\n\n\ndef inspect_quanto_int8_checkpoint(\n    file_path: str,\n    param_name_mapper: Callable[[str], str] | None = None,\n) -> QuantoInt8Config | None:\n    \"\"\"Validate a self-describing Quanto qint8 safetensors checkpoint.\"\"\"\n\n    with safe_open(file_path, framework=\"pt\", device=\"cpu\") as checkpoint:\n        metadata = checkpoint.metadata() or {}\n        if metadata.get(\"quantization_format\") != \"quanto\":\n            return None\n\n        encoded_map = metadata.get(\"quantization_map_base64\")\n        if encoded_map is None:\n            raise ValueError(\"Quanto checkpoint is missing quantization_map_base64\")\n        try:\n            quantization_map = json.loads(\n                base64.b64decode(encoded_map, validate=True).decode(\"utf-8\")\n            )\n        except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as error:\n            raise ValueError(\"Invalid Quanto quantization_map_base64\") from error\n        if not isinstance(quantization_map, dict) or not quantization_map:\n            raise ValueError(\"Quanto quantization map must be a non-empty object\")\n        if not all(\n            isinstance(prefix, str) and isinstance(spec, dict)\n            for prefix, spec in quantization_map.items()\n        ):\n            raise ValueError(\"Quanto quantization map entries must be named objects\")\n\n        checkpoint_keys = set(checkpoint.keys())\n        data_suffix = \".weight._data\"\n        data_prefixes = {\n            name.removesuffix(data_suffix)","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/quantization/configs/quanto_int8_config.py#L77-L113","documentation":"inspect_quanto_int8_checkpoint found a safetensors file whose metadata has quantization_format == 'quanto' but no quantization_map_base64 key. The per-layer quantization map (which layers are int8-quantized) is mandatory for quanto checkpoints in this runtime.","triggerScenarios":"Opening a quanto-flavored safetensors file whose header lacks 'quantization_map_base64' — e.g. exported by an older quanto version or hand-stripped metadata.","commonSituations":"Version mismatch between the quanto exporter and this runtime; merging/converting checkpoints with tools that drop unknown metadata fields.","solutions":["Re-export the checkpoint with a quanto version that writes quantization_map_base64 metadata","Re-attach the base64-encoded JSON map to the safetensors header","If the model is actually unquantized, remove the quantization_format='quanto' metadata key"],"exampleFix":"# before\nmetadata = {\"quantization_format\": \"quanto\"}  # missing map -> ValueError\n\n# after\nimport base64, json\nmetadata = {\n  \"quantization_format\": \"quanto\",\n  \"quantization_map_base64\": base64.b64encode(json.dumps({\"encoder.layers.0\": {\"weights\": \"int8\"}}).encode()).decode(),\n}","handlingStrategy":"type-guard","validationCode":"meta = checkpoint.metadata() or {}\nif meta.get(\"quantization_format\") == \"quanto\" and \"quantization_map_base64\" not in meta:\n    raise RuntimeError(\"quanto checkpoint lacks quantization map; re-export it\")","typeGuard":"def is_complete_quanto_metadata(meta: dict | None) -> bool:\n    meta = meta or {}\n    return meta.get(\"quantization_format\") != \"quanto\" or \"quantization_map_base64\" in meta","tryCatchPattern":null,"preventionTips":["Re-export with the runtime's supported quanto version","Round-trip verify metadata keys after any checkpoint conversion"],"tags":["quantization","quanto","safetensors","checkpoint-metadata"],"backgroundTag":"missing-checkpoint-metadata","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}