{"record":{"id":"2f6a82d22ec6c90a","repo":"hiyouga/LlamaFactory","slug":"ktransformers-accepts-a-single-adapter-name-or-pa","errorCode":null,"errorMessage":"KTransformers accepts a single `adapter_name_or_path`.","messagePattern":"KTransformers accepts a single `adapter_name_or_path`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":647,"sourceCode":"                \"kt_weight_path\": self.kt_weight_path,\n                \"kt_non_expert_weight_path\": self.kt_non_expert_weight_path,\n                \"kt_expert_checkpoint_path\": self.kt_expert_checkpoint_path,\n                \"kt_model_max_length\": max(model_max_length or 0, configured_capacity or 0) or None,\n                \"kt_use_lora_experts\": self.kt_use_lora_experts,\n                \"kt_lora_expert_num\": self.kt_lora_expert_num,\n                \"kt_lora_expert_intermediate_size\": self.kt_lora_expert_intermediate_size,\n                \"kt_activation_policy\": self.get_kt_activation_policy(),\n                \"kt_train_mode\": \"lora\",\n                \"kt_full_weight_grad\": False,\n            }\n        )\n        return {key: value for key, value in kt_config.items() if value is not None}\n\n    def _resolve_kt_adapter_artifact_dir(self, operation: str) -> str | None:\n        if not self.adapter_name_or_path:\n            return None\n        if len(self.adapter_name_or_path) != 1:\n            raise ValueError(\"KTransformers accepts a single `adapter_name_or_path`.\")\n\n        adapter_root = os.path.realpath(os.path.expanduser(self.adapter_name_or_path[0]))\n        adapter_dir = adapter_root\n        if self.adapter_folder:\n            adapter_dir = os.path.realpath(os.path.join(adapter_root, self.adapter_folder))\n            if os.path.commonpath((adapter_root, adapter_dir)) != adapter_root:\n                raise ValueError(\"`adapter_folder` must stay inside the KT adapter directory.\")\n        if not os.path.isdir(adapter_dir):\n            raise ValueError(f\"KTransformers {operation} requires a local adapter directory.\")\n        return adapter_dir\n\n    def apply_kt_config(self, finetuning_args: Any, training_args: Any, model_max_length: int | None) -> None:\n        r\"\"\"Apply LLaMA-Factory KT args to transformers/accelerate KT integration points.\"\"\"\n        if not self.use_kt:\n            return\n\n        self.configure_kt_checkpointing(training_args)\n        kt_config = self.get_kt_config_dict(","sourceCodeStart":629,"sourceCodeEnd":665,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L629-L665","documentation":"Raised by _resolve_kt_adapter_artifact_dir when adapter_name_or_path contains more than one entry. KT loads exactly one LoRA adapter directory into its AMX expert layout; LLaMA-Factory's general ability to merge multiple adapters path-by-path has no KT equivalent.","triggerScenarios":"Setting adapter_name_or_path as a multi-item list (e.g. [saves/lora1, saves/lora2]) while use_kt: true, then starting training or inference, which calls the resolver with operation 'training' or 'inference'.","commonSituations":"Configs that stacked several LoRA adapters for vanilla HF inference are reused for KT evaluation or continued training.","solutions":["Keep only one adapter path in `adapter_name_or_path` for KT runs.","If several adapters must be combined, merge them first (`llamafactory-cli export` with multiple adapters produces a single merged model) and point at the result."],"exampleFix":"# before (yaml)\nuse_kt: true\nadapter_name_or_path:\n  - saves/lora_v1\n  - saves/lora_v2\n\n# after (yaml)\nuse_kt: true\nadapter_name_or_path: saves/lora_v2","handlingStrategy":"validation","validationCode":"adapters = cfg.get('adapter_name_or_path')\nif cfg.get('use_kt') and isinstance(adapters, list) and len(adapters) > 1:\n    raise SystemExit('KT accepts a single adapter; merge extras first')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Normalize adapter lists to a single path when switching a config to KT."],"tags":["ktransformers","lora","adapter","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}