{"record":{"id":"3312387d765565bd","repo":"hiyouga/LlamaFactory","slug":"kt-cpu-activation-is-only-valid-when-use-kt-tr","errorCode":null,"errorMessage":"`kt_cpu_activation` is only valid when `use_kt: true`.","messagePattern":"`kt_cpu_activation` is only valid when `use_kt: true`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":533,"sourceCode":"            \"kt_full_weight_grad\",\n            \"kt_lora_alpha\",\n            \"kt_lora_dropout\",\n            \"kt_lora_expert_intermediate_size\",\n            \"kt_lora_expert_num\",\n            \"kt_lora_rank\",\n            \"kt_non_expert_weight_path\",\n            \"kt_skip_expert_loading\",\n            \"kt_train_mode\",\n            \"kt_use_lora_experts\",\n            \"kt_weight_path\",\n        }\n    )\n\n    def __post_init__(self) -> None:\n        if self.kt_cpu_activation not in {None, \"retain\", \"recompute\"}:\n            raise ValueError(\"`kt_cpu_activation` must be `retain` or `recompute`.\")\n        if not self.use_kt and self.kt_cpu_activation is not None:\n            raise ValueError(\"`kt_cpu_activation` is only valid when `use_kt: true`.\")\n\n    def get_kt_activation_policy(self) -> dict[str, str]:\n        r\"\"\"Resolve LF's GPU checkpoint switch and KT's CPU activation setting.\"\"\"\n        gpu_activation = \"retain\" if self.disable_gradient_checkpointing else \"recompute\"\n        cpu_activation = self.kt_cpu_activation or gpu_activation\n        if cpu_activation == \"recompute\" and gpu_activation == \"retain\":\n            raise ValueError(\n                \"`kt_cpu_activation: recompute` requires GPU gradient checkpointing. \"\n                \"Set `disable_gradient_checkpointing: false` or use `kt_cpu_activation: retain`.\"\n            )\n\n        return {\"cpu\": cpu_activation, \"gpu\": gpu_activation}\n\n    @staticmethod\n    def _get_accelerator_kt_config(training_args: Any) -> Any:\n        accelerator_config = getattr(training_args, \"accelerator_config\", None)\n        if isinstance(accelerator_config, dict):\n            return accelerator_config.get(\"kt_config\")","sourceCodeStart":515,"sourceCodeEnd":551,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L515-L551","documentation":"Raised in the KTransformers arguments __post_init__ (model_args.py:533) when kt_cpu_activation is set but use_kt is false. The CPU activation policy only exists for KTransformers runs (experts on CPU), so configuring it without enabling KT is rejected to prevent a silently-ignored setting.","triggerScenarios":"A config with kt_cpu_activation: retain but no use_kt: true; toggling use_kt off for a comparison run while leaving other kt_* keys in place; partial migration from a KT example config.","commonSituations":"A/B testing KT vs HF execution by flipping only use_kt; YAML anchors that spread kt_* keys across experiments; stale keys left after abandoning KT.","solutions":["Add use_kt: true to the same config","Or remove kt_cpu_activation (and ideally other kt_* keys) when running without KTransformers","Keep all kt_* settings under a single optional YAML include you only merge when use_kt is true"],"exampleFix":"# before\nuse_kt: false\nkt_cpu_activation: retain\n\n# after\nuse_kt: true\nkt_cpu_activation: retain","handlingStrategy":"validation","validationCode":"if not cfg.get('use_kt'):\n    cfg = {k: v for k, v in cfg.items() if not k.startswith('kt_')}  # strip stray KT keys","typeGuard":"def kt_keys_consistent(cfg: dict) -> bool:\n    kt_set = {k for k in cfg if k.startswith('kt_')}\n    return cfg.get('use_kt') or not kt_set","tryCatchPattern":null,"preventionTips":["Keep all kt_* keys in one optional include file merged only for KT runs","When A/B testing, toggle the whole KT block, not just use_kt"],"tags":["ktransformers","config-validation","dependent-fields"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}