hiyouga/LlamaFactory · error · ValueError

KTransformers accepts a single `adapter_name_or_path`.

Error message

KTransformers accepts a single `adapter_name_or_path`.

What it means

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.

Source

Thrown at src/llamafactory/hparams/model_args.py:647

                "kt_weight_path": self.kt_weight_path,
                "kt_non_expert_weight_path": self.kt_non_expert_weight_path,
                "kt_expert_checkpoint_path": self.kt_expert_checkpoint_path,
                "kt_model_max_length": max(model_max_length or 0, configured_capacity or 0) or None,
                "kt_use_lora_experts": self.kt_use_lora_experts,
                "kt_lora_expert_num": self.kt_lora_expert_num,
                "kt_lora_expert_intermediate_size": self.kt_lora_expert_intermediate_size,
                "kt_activation_policy": self.get_kt_activation_policy(),
                "kt_train_mode": "lora",
                "kt_full_weight_grad": False,
            }
        )
        return {key: value for key, value in kt_config.items() if value is not None}

    def _resolve_kt_adapter_artifact_dir(self, operation: str) -> str | None:
        if not self.adapter_name_or_path:
            return None
        if len(self.adapter_name_or_path) != 1:
            raise ValueError("KTransformers accepts a single `adapter_name_or_path`.")

        adapter_root = os.path.realpath(os.path.expanduser(self.adapter_name_or_path[0]))
        adapter_dir = adapter_root
        if self.adapter_folder:
            adapter_dir = os.path.realpath(os.path.join(adapter_root, self.adapter_folder))
            if os.path.commonpath((adapter_root, adapter_dir)) != adapter_root:
                raise ValueError("`adapter_folder` must stay inside the KT adapter directory.")
        if not os.path.isdir(adapter_dir):
            raise ValueError(f"KTransformers {operation} requires a local adapter directory.")
        return adapter_dir

    def apply_kt_config(self, finetuning_args: Any, training_args: Any, model_max_length: int | None) -> None:
        r"""Apply LLaMA-Factory KT args to transformers/accelerate KT integration points."""
        if not self.use_kt:
            return

        self.configure_kt_checkpointing(training_args)
        kt_config = self.get_kt_config_dict(

View on GitHub (pinned to f28afaf635)

Solutions

1. Keep only one adapter path in `adapter_name_or_path` for KT runs.
2. 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.

Example fix

# before (yaml)
use_kt: true
adapter_name_or_path:
  - saves/lora_v1
  - saves/lora_v2

# after (yaml)
use_kt: true
adapter_name_or_path: saves/lora_v2

adapters = cfg.get('adapter_name_or_path')
if cfg.get('use_kt') and isinstance(adapters, list) and len(adapters) > 1:
    raise SystemExit('KT accepts a single adapter; merge extras first')

When it happens

Trigger: 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'.

Common situations: Configs that stacked several LoRA adapters for vanilla HF inference are reused for KT evaluation or continued training.

Related errors

• KTransformers thin integration currently supports LoRA finet
• KTransformers {operation} requires a local adapter directory
• Adapter is only valid for the LoRA method.
• KTransformers uses LLaMA-Factory's `disable_gradient_checkpo
• KTransformers supplies its checkpoint context; remove `gradi

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/2f6a82d22ec6c90a. Report an issue: GitHub.