{"record":{"id":"ce68adc61c72dc84","repo":"hiyouga/LlamaFactory","slug":"please-use-scripts-pissa-init-py-to-initialize-pis","errorCode":null,"errorMessage":"Please use scripts/pissa_init.py to initialize PiSSA for a quantized model.","messagePattern":"Please use scripts/pissa_init\\.py to initialize PiSSA for a quantized model\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/parser.py","lineNumber":240,"sourceCode":"        torch.npu.set_compile_mode(jit_compile=is_env_enabled(\"NPU_JIT_COMPILE\"))\n        # avoid use fork method on NPU devices, see https://github.com/hiyouga/LLaMA-Factory/issues/7447\n        os.environ[\"VLLM_WORKER_MULTIPROC_METHOD\"] = \"spawn\"\n\n\ndef _verify_model_args(\n    model_args: \"ModelArguments\",\n    data_args: \"DataArguments\",\n    finetuning_args: \"FinetuningArguments\",\n) -> None:\n    if model_args.adapter_name_or_path is not None and finetuning_args.finetuning_type != \"lora\":\n        raise ValueError(\"Adapter is only valid for the LoRA method.\")\n\n    if model_args.quantization_bit is not None:\n        if finetuning_args.finetuning_type not in [\"lora\", \"oft\"]:\n            raise ValueError(\"Quantization is only compatible with the LoRA or OFT method.\")\n\n        if finetuning_args.pissa_init:\n            raise ValueError(\"Please use scripts/pissa_init.py to initialize PiSSA for a quantized model.\")\n\n        if model_args.resize_vocab:\n            raise ValueError(\"Cannot resize embedding layers of a quantized model.\")\n\n        if model_args.adapter_name_or_path is not None and finetuning_args.create_new_adapter:\n            raise ValueError(\"Cannot create new adapter upon a quantized model.\")\n\n        if model_args.adapter_name_or_path is not None and len(model_args.adapter_name_or_path) != 1:\n            raise ValueError(\"Quantized model only accepts a single adapter. Merge them first.\")\n\n\ndef _check_extra_dependencies(\n    model_args: \"ModelArguments\",\n    finetuning_args: \"FinetuningArguments\",\n    training_args: Optional[\"TrainingArguments\"] = None,\n) -> None:\n    if model_args.use_kt:\n        check_version(\"kt-kernel\", mandatory=True)","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/parser.py#L222-L258","documentation":"Raised by _verify_model_args when quantization_bit is set together with pissa_init. PiSSA initialization rewrites the base weights by decomposing them (producing residual weights to export), which cannot be done in-recipe on an already-quantized model; the dedicated scripts/pissa_init.py handles the quantized case.","triggerScenarios":"A YAML with quantization_bit: 4 plus pissa_init: true; get_train_args -> _verify_model_args rejects the pair immediately.","commonSituations":"Users enable PiSSA for faster LoRA convergence and quantize at the same time, not realizing PiSSA residual export must precede quantization.","solutions":["Run `scripts/pissa_init.py` on the model first to generate the PiSSA-initialized base + adapter, then quantize/point the training config at those outputs.","Or disable `pissa_init` and use plain LoRA on the quantized model."],"exampleFix":"# before (yaml)\nquantization_bit: 4\npissa_init: true\n\n# after (bash)\npython scripts/pissa_init.py --model_name_or_path meta-llama/Llama-3-8B \\\n  --lora_rank 16 --output_dir saves/pissa_base\n# then reference saves/pissa_base in the training YAML with quantization_bit set","handlingStrategy":"validation","validationCode":"if cfg.get('quantization_bit') is not None and cfg.get('pissa_init'):\n    raise SystemExit('use scripts/pissa_init.py for quantized models')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat pissa_init as a pre-processing step, not an in-training flag, when weights are quantized."],"tags":["pissa","quantization","config","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}