{"record":{"id":"a4b6634ac27dd358","repo":"hiyouga/LlamaFactory","slug":"ktransformers-thin-integration-currently-supports","errorCode":null,"errorMessage":"KTransformers thin integration currently supports LoRA finetuning only.","messagePattern":"KTransformers thin integration currently supports LoRA finetuning only\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":612,"sourceCode":"            raise ValueError(\"Disable FSDP activation checkpointing when using KTransformers.\")\n        if os.environ.get(\"FSDP_ACTIVATION_CHECKPOINTING\", \"false\").lower() in {\"1\", \"true\", \"yes\"}:\n            raise ValueError(\"Disable FSDP activation checkpointing when using KTransformers.\")\n\n        self.get_kt_activation_policy()\n        if not self.disable_gradient_checkpointing:\n            self.use_reentrant_gc = False\n        training_args.gradient_checkpointing = False\n        training_args.gradient_checkpointing_kwargs = None\n\n    def get_kt_config_dict(\n        self,\n        finetuning_args: Any,\n        model_max_length: int | None,\n        advanced_config: dict[str, Any] | None = None,\n    ) -> dict[str, Any]:\n        r\"\"\"Map LLaMA-Factory-owned training values to the public KT configuration.\"\"\"\n        if getattr(finetuning_args, \"finetuning_type\", None) != \"lora\":\n            raise ValueError(\"KTransformers thin integration currently supports LoRA finetuning only.\")\n\n        kt_config = dict(advanced_config or {})\n        configured_capacity = kt_config.pop(\"kt_model_max_length\", None)\n        if configured_capacity is not None:\n            try:\n                configured_capacity = int(configured_capacity)\n            except (TypeError, ValueError) as exc:\n                raise ValueError(\"`kt_model_max_length` must be a positive integer.\") from exc\n            if configured_capacity <= 0:\n                raise ValueError(\"`kt_model_max_length` must be a positive integer.\")\n\n        kt_config.update(\n            {\n                \"kt_lora_rank\": getattr(finetuning_args, \"lora_rank\", None),\n                \"kt_lora_alpha\": getattr(finetuning_args, \"lora_alpha\", None),\n                \"kt_lora_dropout\": getattr(finetuning_args, \"lora_dropout\", None),\n                \"kt_weight_path\": self.kt_weight_path,\n                \"kt_non_expert_weight_path\": self.kt_non_expert_weight_path,","sourceCodeStart":594,"sourceCodeEnd":630,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L594-L630","documentation":"Raised by get_kt_config_dict when finetuning_args.finetuning_type is anything other than 'lora'. The KT thin integration hard-codes kt_train_mode='lora' and kt_full_weight_grad=False, so full/pissa/freeze/Galore and other LLaMA-Factory finetuning types have no KT mapping.","triggerScenarios":"Calling apply_kt_config or configure_kt_loading with use_kt: true and finetuning_type: full (or freeze/pissa) in the YAML; the check runs before any KT config keys are built.","commonSituations":"Users assume the AMX MoE backend accelerates full finetuning of large models and set finetuning_type: full with use_kt: true.","solutions":["Set `finetuning_type: lora` in the training YAML to use KTransformers.","If full finetuning is required, remove `use_kt: true` and run the standard HF Trainer path."],"exampleFix":"# before (yaml)\nuse_kt: true\nfinetuning_type: full\n\n# after (yaml)\nuse_kt: true\nfinetuning_type: lora\nlora_rank: 16","handlingStrategy":"validation","validationCode":"if cfg.get('use_kt') and cfg.get('finetuning_type') != 'lora':\n    raise SystemExit('KTransformers supports finetuning_type: lora only')","typeGuard":"def is_kt_compatible(cfg: dict) -> bool:\n    return not cfg.get('use_kt') or cfg.get('finetuning_type') == 'lora'","tryCatchPattern":null,"preventionTips":["Check the supported finetuning_type list for a backend before enabling it."],"tags":["ktransformers","lora","config","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}