Unify LoRA target selection with HF model layouts

docs/advanced/lora.md

@@ -102,12 +102,12 @@ in PR #1792 are not released on `main` yet. FSDP does not currently implement
 LoRA training.
 </Warning>
 
-`all-linear` expands to Q/K/V/O and gate/up/down projections, and conditionally
-adds MLA Q/KV projections based on the HF config. It does not literally wrap
-every linear layer. GDN and other model-specific projections require an explicit
-target list. Current GLM recipes validate models that contain DSA while leaving
-the DSA indexer unadapted; current hybrid-model recipes also leave MTP blocks and
-vision towers unadapted. Use the model launcher as the source of truth.
+Omitting `--target-modules` or passing `all-linear` uses the model defaults from
+`miles/utils/lora/hf_lora_targets.py`: attention + MLP, with model-specific exclusions
+and output-head defaults. Multi-LoRA without explicit targets selects all three
+training groups. Use `--target-modules attn,mlp,unembed` to select groups explicitly.
+Ordinary LoRA also accepts specific HF targets mixed with group names, such as
+`--target-modules attn,lm_head`; Tinker accepts only group names.
 
 ### Core arguments
 
@@ -117,19 +117,97 @@ vision towers unadapted. Use the model launcher as the source of truth.
 | `--lora-alpha` | `16` | Adapter scaling factor. |
 | `--lora-dropout` | `0.0` | Dropout on the adapter path. |
 | `--lora-type` | `lora` | `lora` uses fused Megatron projections; `canonical_lora` uses split Q/K/V and gate/up projections. The canonical path is implemented and covered by fast name-mapping tests, but has no maintained recipe or E2E validation. |
-| `--target-modules` | none | Required with a positive rank. Accepts `all-linear`, HF leaf names, Megatron names, or model-specific wildcard paths. |
-| `--exclude-modules` | none | Comma-separated exact entries removed from the resolved targets. |
+| `--target-modules` | none | Uses HF model defaults when omitted. Accepts `all-linear`, `attn/mlp/unembed` groups, HF leaf names or scoped HF paths; Bridge also accepts Megatron selectors. |
+| `--exclude-modules` | none | Comma-separated HF leaf names or scoped HF paths removed after selection; Bridge also accepts Megatron selectors. |
 | `--lora-adapter-path` | none | Warm-start/resume path. Also provide the matching positive rank, alpha, and target modules. Bridge training resume currently requires miles' per-rank adapter shards and the same parallel topology; an HF PEFT-only adapter cannot yet be loaded directly into the Bridge model. Inkling native has its own HF adapter loader. |
 | `--lora-base-cpu-backup` | off | Colocated mode only: keep a CPU mirror of the frozen SGLang base and avoid re-sending base weights. This trades host RAM for faster and more reliable pause/resume. |
 | `--lora-train-only` | off | Train the adapter while keeping ordinary rollout engines on the frozen base policy. |
 | `--experts-shared-outer-loras` | off | Use shared outer factors for grouped MoE experts. This layout is not checkpoint-compatible with per-expert LoRA. |
 | `--check-lora-weight-equal` | off | On the colocated path, verify each synchronized adapter tensor with SHA-256. |
 | `--update-weights-interval` | `1` | Publish new weights every N rollout/train iterations. This is not LoRA-specific, but it controls when the live adapter is synchronized. |
 
-This argument table describes the general Bridge surface. Current native Inkling
-uses a fixed model-specific adapter schema: `--target-modules` does not select
-individual training modules, `--exclude-modules` is not applied, and
-`canonical_lora` is not implemented. Use the Inkling launcher defaults.
+### HF target source of truth
+
+`miles/utils/lora/hf_lora_targets.py` owns **HF target groups and defaults** for all
+backends. It derives attention, MLP, and output-head paths from the model config,
+including nested text models, optional MLA projections, expert layouts, and
+hybrid attention. Vision towers, routers, norms, and GDN convolutions are excluded.
+
+| Model layout | Attention | MLP | Ordinary LoRA default |
+|---|---|---|---|
+| Llama, Qwen2/2.5, Qwen3 | Q/K/V/O | Dense gate/up/down | Attention + MLP |
+| Qwen3 MoE | Q/K/V/O | Routed experts; dense layers when configured | Attention + MLP |
+| Qwen3-Next | Q/K/V/O + GDN qkvz/ba/out | Routed + shared experts; configured dense layers | Attention + MLP |
+| Qwen3.5/3.6, text and multimodal | Q/K/V/O + GDN qkv/z/b/a/out | Dense or packed routed + shared experts | Attention + MLP |
+| GPT-OSS | Q/K/V/O | Packed gate_up/down experts | Attention + MLP |
+| DeepSeek V2/V3, Kimi K2/K2.5 | MLA | Dense + routed + shared experts as configured | Attention + MLP |
+| DeepSeek V3.2, GLM-5/5.1/5.2 | MLA + DSA indexer | Dense + routed + shared experts as configured | Attention + MLP, excluding indexer |
+| GLM-4 MoE | Q/K/V/O | Dense + routed + shared experts as configured | Attention + MLP |
+| Inkling | Q/K/V/R/O | Dense + packed routed + shared expert projections | Attention + MLP + output head |
+
+`--target-modules` accepts comma-separated `attn`, `mlp`, and `unembed` groups,
+explicit HF targets, or a mix of both. Group names expand through the model's HF
+definition, so `mlp` includes dense, shared, and routed expert projections, including
+packed `gate_up_proj` weights. Only exact group names expand; full paths remain
+literal target patterns. Duplicates are removed, then `--exclude-modules` applies.
+Explicit module selections must not overlap exclusions; defaults and group
+selections may still be narrowed with exclusions.
+
+A matching pair of `gate_proj` and `up_proj` selectors also selects
+`gate_up_proj` when the HF model has packed projections, with a warning.
+Scoped pairs retain their path prefix; selecting only gate or only up does not
+expand to the packed projection. Split selectors remain where the model has
+split modules and are replaced where it has only packed modules.
+
+Without explicit targets, ordinary LoRA uses its model defaults and multi-LoRA
+selects all three groups. `all-linear` selects the ordinary model defaults and
+must be used alone. Explicit lists replace the defaults.
+
+Packed expert entries identify HF parameters rather than `nn.Linear` modules.
+Inkling entries follow the native HF model namespace. Its native Megatron LoRA
+implementation requires the complete fixed layout. SGLang discovers its adapter
+modules with `all`, and online weight-sync config uses `all-linear`; adapter
+checkpoints derive explicit names from exported tensors. Adapter factors, tensor
+packing, and checkpoint names are unchanged. The pinned Transformers version does
+not yet include native Inkling, so its HF structure is not covered by the native
+meta-model tests. A layout entry is not a backend support claim.
+
+Ordinary LoRA and Tinker share these HF target groups. HF targets retain their
+meaning throughout training and serving. `miles/utils/hf_utils/weight_mapping.py`
+uses Transformers conversion rules and a meta model's parameter names to relate
+checkpoint keys to the current HF model namespace, without loading base weights.
+This resolves renamed and packed parameter names. Custom models absent from
+native Transformers keep their existing checkpoint namespace.
+
+Bridge resolves mappings against parameters that actually exist across PP/EP
+ranks before checking fused selections. Explicit Megatron selectors retain a
+compatibility conversion at startup. Adapter factories receive only Megatron
+targets; they do not overwrite the HF selection. Arbitrary layer/expert subsets
+within a registry template are not implemented and are rejected.
+Standard LoRA requires all projections of a fused weight together;
+`canonical_lora` supports individual Q/K/V and dense gate/up selections.
+Grouped-expert FC1 and GDN input projections remain fused and require all of
+their HF projections even in canonical mode.
+
+Tinker uses `--target-modules attn,mlp,unembed` by default; for example,
+`--target-modules attn,mlp` disables output-head training. Client SDK flags must
+match the selected server groups. Tinker rejects explicit module names,
+`all-linear`, and `--exclude-modules` because the SDK describes only whole groups.
+
+For Bridge, SGLang receives the selected HF paths and normalizes them into buffer types
+(for example, Q/K/V become `qkv_proj`); it does not own the selection policy.
+Adapter checkpoints derive their concrete `target_modules` from exported tensor
+keys rather than a separate Megatron-to-HF name table. Online adapter registration
+uses the resolved HF selection for Bridge and `all-linear` for native Inkling,
+without an extra tensor export.
+This requires [SGLang's HF-path normalization support](https://github.com/sgl-project/sglang/pull/40242),
+including GDN split names. FSDP LoRA injection remains
+unsupported.
+
+Native Inkling
+uses a fixed model-specific adapter schema: defaults select that complete schema,
+and partial/custom layouts or `canonical_lora` are rejected before injection.
+Use the Inkling launcher defaults.
 
 ### Rollout topology
 
@@ -160,7 +238,7 @@ LORA_ARGS=(
   --lora-rank 32
   --lora-alpha 32
   --lora-dropout 0.0
-  --target-modules "gate_proj,up_proj,down_proj"
+  --target-modules "gate_up_proj,down_proj"
   --sglang-lora-backend triton
   --megatron-to-hf-mode bridge
 )

docs/models/kimi/kimi-k3.md

@@ -96,6 +96,8 @@ torchrun --nnodes=8 --nproc-per-node=4 ... \
 
 ## 4. Launch
 
+The launcher uses `all-linear`, which selects Kimi K3's HF defaults: MLA query/KV down projections, attention output projections, dense/shared MLPs, and routed experts. `attn,mlp` selects the same set. Explicit HF targets can omit `language_model.model.layers.*.block_sparse_moe.experts.*.w2` to leave routed-expert down projections frozen; other layouts remain unsupported by the native backend.
+
 `--train-mode lora` (default) or `full`. Validated on **16 nodes × 4 GPUs**: one container per
 node, a ray cluster across them, `export MILES_SCRIPT_EXTERNAL_RAY=1`, then:
 

examples/lora/run-gpt-oss-20B-megatron-moe-lora.sh

@@ -29,7 +29,7 @@ LORA_ARGS=(
    --lora-rank 32                    # LoRA rank (typical values: 8, 16, 32, 64)
    --lora-alpha 32                   # LoRA alpha (usually 2x rank)
    --lora-dropout 0.0                # LoRA dropout (0.0 for RL training)
-   --target-modules "gate_proj,up_proj,down_proj"
+   --target-modules "gate_up_proj,down_proj"
    --sglang-lora-backend triton      # !!! must for moe-lora !!!, else display "Current LoRA backend does not support LoRA on MoE layers; skipping MoE layer"
 )
 

examples/multi_lora/README.md

@@ -15,11 +15,10 @@ One 8-GPU node, disaggregated (multi-LoRA forbids `--colocate`):
   (`linear_qkv`, `linear_proj`), the per-expert MoE projections (`linear_fc1`, `linear_fc2`),
   and the output layer (`output_layer`) so the cookbook's default `train_unembed=True` is servable.
 
-The gateway currently resolves Tinker training groups for `qwen3` and `qwen3_moe`.
-`--tinker-train-attn`, `--tinker-train-mlp`, and `--tinker-train-unembed` default to enabled;
-use `--no-tinker-train-attn`, `--no-tinker-train-mlp`, or `--no-tinker-train-unembed` to disable a group.
-Every client's corresponding SDK flags must match the server layout. Tinker startup rejects
-`--target-modules` and `--exclude-modules`; native Miles training still accepts them.
+The example enables attention, MLP, and output-head training. Client SDK flags
+must match the server's selected groups. See [LoRA target selection](../../docs/advanced/lora.md#hf-target-source-of-truth)
+for `--target-modules attn,mlp,unembed`; use `attn,mlp` to disable output-head
+training. Tinker accepts only these group names and rejects `--exclude-modules`.
 
 ## Run
 

examples/multi_lora/serve_qwen3_30b_a3b_tinker.py

@@ -29,9 +29,7 @@ class ScriptArgs(U.ExecuteTrainConfig):
     lora_rank: int = 32
     lora_alpha: int = 64
     n_adapters: int = 4
-    tinker_train_attn: bool = True
-    tinker_train_mlp: bool = True
-    tinker_train_unembed: bool = True
+    target_modules: str = "attn,mlp,unembed"
 
     tinker_port: int = 10613
     rollout_num_gpus_per_engine: int = 2
@@ -69,14 +67,11 @@ def serve(args: ScriptArgs):
         f"--lora-rank {args.lora_rank} --lora-alpha {args.lora_alpha} --lora-dropout 0.0 "
         "--no-gradient-accumulation-fusion "
         f"--multi-lora-n-adapters {args.n_adapters} "
+        f'--target-modules "{args.target_modules}"'
     )
 
     tinker_args = f"--tinker-server-port {args.tinker_port} " f"--tinker-checkpoint-root {args.save_dir}/{args.run_id}"
 
-    for group in ("attn", "mlp", "unembed"):
-        enabled = getattr(args, f"tinker_train_{group}")
-        tinker_args += f" --{'' if enabled else 'no-'}tinker-train-{group}"
-
     # initial config only; AdamParams come per optim_step request
     optimizer_args = "--optimizer adam --lr 1e-4 "
 

examples/swe-agent-harbor-docker/run_glm52_lora_tb2_daytona.py

@@ -49,7 +49,7 @@
 # tilelang the indexer adapter gets no gradient at all — and EXCLUDING the MLP/MoE
 # leaves (gate_proj/up_proj/down_proj): this is the MoE-LoRA-off ablation, so all
 # experts (routed + shared) and the dense MLP stay frozen.
-_DEFAULT_TARGET_MODULES = "q_proj,k_proj,v_proj,o_proj,q_a_proj,kv_a_proj_with_mqa,q_b_proj,kv_b_proj"
+_DEFAULT_TARGET_MODULES = "o_proj,q_a_proj,kv_a_proj_with_mqa,q_b_proj,kv_b_proj"
 
 
 @dataclass

miles/backends/megatron_utils/actor.py

@@ -13,7 +13,7 @@
 from torch_memory_saver import torch_memory_saver
 
 from miles.backends.megatron_utils.ft.types import TrainStepOutput
-from miles.backends.megatron_utils.lora.utils import build_lora_sync_config, is_lora_enabled, lora_rollout_enabled
+from miles.backends.megatron_utils.lora.utils import is_lora_enabled, lora_rollout_enabled
 from miles.backends.megatron_utils.rematerialize_utils import build_main_cast_context
 from miles.backends.megatron_utils.update_weight.hf_weight_iterator import get_hf_weight_iterator
 from miles.backends.training_utils.weight_update.updater import WeightUpdater
@@ -28,6 +28,7 @@
 from miles.utils.distributed_utils import get_gloo_group
 from miles.utils.ft_utils.indep_dp import IndepDPInfo
 from miles.utils.hf_utils.config import load_hf_config
+from miles.utils.lora.utils import build_lora_config
 from miles.utils.memory_utils import clear_memory, print_memory
 from miles.utils.processing_utils import load_tokenizer
 from miles.utils.ray_utils import Box
@@ -287,7 +288,7 @@ def _init_training_state(self) -> None:
             iterator_factory=get_hf_weight_iterator,
             parallel_state=get_parallel_state(),
             is_lora=is_lora,
-            lora_sync_config=build_lora_sync_config(args) if is_lora else None,
+            lora_sync_config=build_lora_config(args, target_modules=args.lora_adapter_targets) if is_lora else None,
         )
 
     def _clear_quantized_weight_workspaces(self) -> None:

miles/backends/megatron_utils/lora/actor.py

@@ -4,12 +4,11 @@
 from miles.backends.megatron_utils.lora import checkpoint as lora_checkpoint
 from miles.backends.megatron_utils.lora import model as lora_model
 from miles.backends.megatron_utils.lora.optimizer import SlotOptimizer
-from miles.backends.megatron_utils.lora.utils import build_lora_sync_config
 from miles.backends.megatron_utils.update_weight.hf_weight_iterator import get_hf_weight_iterator
 from miles.backends.training_utils.data import get_rollout_data
 from miles.backends.training_utils.weight_update.hf_weight_iterator import WeightUpdatePlacement
 from miles.backends.training_utils.weight_update.snapshot_publisher import WeightPublisher
-from miles.utils.lora.utils import AdapterSpec
+from miles.utils.lora.utils import AdapterSpec, build_lora_config
 from miles.utils.ray_utils import Box
 from miles.utils.tracking_utils.structured_log import with_logs
 
@@ -25,7 +24,9 @@ def _init_training_state(self) -> None:
             model_name=type(self.hf_config).__name__.lower() if args.model_name is None else args.model_name,
             quantization_config=getattr(self.hf_config, "quantization_config", None),
         )
-        self.weight_publisher = WeightPublisher(iterator, build_lora_sync_config(args))
+        self.weight_publisher = WeightPublisher(
+            iterator, build_lora_config(args, target_modules=args.lora_adapter_targets)
+        )
 
     @with_logs
     def forward_backward(self, batch_id: int, rollout_data_ref: Box) -> dict: