ShadowPEFT in PEFT: The Adapter Export Decision Map

Same get_peft_model API, different deployment contract

Training still starts with get_peft_model. That familiarity is helpful, but it can also hide the deployment question that matters most: what exactly are you going to ship?

With ShadowPEFT, the answer is not a merged base model. Attached inference keeps the base model in the loop. Detached language-model inference uses a different computation. Both can be legitimate choices, but they need different packaging, different tests, and different acceptance evidence.

What the September 15 integration changes

The authors' September 15, 2026 integration announcement reports that ShadowPEFT has been merged into PEFT's main branch. The April paper gives useful background, but it is not a new September paper. At announcement time, trying the integration means installing PEFT from source; the main documentation separates that path from the stable package. The announcement date is not independent evidence of the exact merge date.

Pin the PEFT and Transformers revisions you tested. Pin the base model and shadow model revisions too. An unpinned main-branch install is not a reproducible release plan.

The announcement explains the method and reports experiments. The API reference documents the operations. This article connects those pieces to a deployment decision: which artifact exists, which dependencies must be present, and what evidence proves the artifact is fit to ship. It is a planning guide, not an Optijara reproduction of the authors' results.

Why a shadow trajectory cannot merge into base weights

The ShadowPEFT documentation describes a small backbone that produces an initial shadow state. Across contiguous decoder blocks, the discrepancy h-s passes through a low-rank correction into the base input. Gated updates then advance the shadow state using block outputs. Only one adapter trajectory can be active at a time.

That is input-dependent behavior. It is not a fixed delta that can be folded into the base weights. As a result, merge, merge_adapter, and merge_and_unload raise errors. Familiar PEFT save and load methods do not remove that restriction.

Keep three inventories separate: the saved adapter, the attached base-plus-shadow inference setup, and the full detached language-model checkpoint. They are not three filenames for the same thing. They are different products.

The Adapter Export Decision Map: choose the artifact before training

Four deployment routes and their acceptance evidence

Optijara's Adapter Export Decision Map is an original planning aid for this article, not a vendor standard. Start with the route you need in production, then choose training, export, and validation steps that can actually produce it.

The detached route deserves close inspection. A small adapter file is not the same as a checkpoint with an embedding table, projection, backbone, output head, tokenizer, and configuration. Record which components the chosen setup shares, trains, and saves. That inventory is also useful when reviewing artifact details rather than filenames, although this article does not claim GGUF conversion support for ShadowPEFT.

For Diffusers, the documentation separates the registered Flux2 architecture backend from a token-wise residual MLP fallback for compatible architectures. Neither path supports standalone unloading. That limitation applies to Diffusers models broadly, not only to architectures without a registered backend.

Training, attached inference, and detached export are different branches

The branches below show ShadowPEFT decisions and the checks attached to them. The Diffusers branch is explicitly unsupported. They do not describe an implemented edge-cloud router.

This compact summary is descriptive JSON. It is not a PEFT configuration and it does not perform compatibility checks.

{
  "framework": "Adapter Export Decision Map",
  "shadow_merge_supported": false,
  "attached_requires_base": true,
  "detached_lm_requires_separate_evaluation": true,
  "independent_export_copy": true,
  "diffusers_standalone_supported": false
}

Export a detached language model without losing the artifact contract

Train the standalone path deliberately

The documented detached Transformers computation is head(projection(backbone(x))). It is not the final cross-layer shadow state sL, because sL depends on interactions with the base decoder. Strong attached results therefore do not prove detached task quality.

Treat predictor quality as a separate acceptance question. An export can be technically valid and still be the wrong predictor for the task. A successful save does not settle that question.

The auxiliary task loss supervises the initial shadow state s0, the path available without those base interactions. The configuration documents auxiliary_loss_weight=0.05 as the default, with the loss added when labels are provided. Check that the training job supplies labels and handles the task head as intended. Setting a value in configuration is not the same as verifying the loss path.

For causal language modeling, the base output head is reused. Include modules_to_save=['lm_head'] when that head must be trained and saved through PEFT. Do not make head training a reflex. Record the head vocabulary size and its relationship to the tokenizer and embedding table.

Use unload_shadow(copy=True) for independent export

The following snippet follows the documented export interface. It is illustrative and unexecuted here. peft_model means an already trained, compatible Transformers PEFT model, not an arbitrary Diffusers pipeline.

# Illustrative only: not executed for this article.
detached_model = peft_model.base_model.unload_shadow(copy=True)
detached_model.save_pretrained("standalone-shadow")

By default, copy=False shares modules with the PEFT model. If the shadow uses frozen base input embeddings through a reference outside its registered submodule tree, saving that detached object can omit the embedding table. The documentation recommends copy=True when saving or pushing an independent model because it attaches a private embedding copy. The tradeoff is extra memory during export.

That flag solves one serialization dependency. It does not prove that the tokenizer was saved, that the loader is compatible, or that detached quality meets the task requirement. Use the loading interface for the pinned implementation. Do not infer the reload class from a convenient name.

Cold-reload checklist, explicitly not executed here

Use this prospective checklist before calling an export deployable. Optijara has not trained, exported, reloaded, or evaluated the model for this article. Documentation and source inspection are not a substitute for local serialization-test evidence.

Keep the attached artifact while testing the export. A clean load should not automatically replace the attached deployment candidate. It only clears the serialization check. Reject incomplete artifacts before interpreting quality differences, especially when tokenizer settings or missing weights may explain the behavior.

Measure attached and detached inference as separate products

Four baselines on the same held-out workload

Plan a comparison of base-only, LoRA, Shadow attached, and Shadow detached. Use the same held-out tasks, prompts, scoring rules, and generation settings where they make sense. Record tokenizer differences, model sizes, and training budgets. A smaller detached architecture is not identical to the base, and the evaluation should not pretend otherwise.

Set acceptance thresholds before looking at results. A hypothetical document-labeling task might care most about label correctness and stable structured output. An interactive assistant also needs latency checks. These are proposed evaluation choices, not reported ShadowPEFT outcomes.

Adapter size is not serving memory

Attached generation uses paired base and shadow KV caches. The API reference describes ShadowCache as intentionally not compileable; legacy tuple conversion is unsupported. Do not promise torch.compile support or inference-engine compatibility just because generate() looks familiar. The model implementation separately defines the standalone export path and its Diffusers restriction.

Measure cache growth under the workload you intend to serve. Separate adapter bytes, export bytes, loading peaks, and steady-state serving memory. Follow the same discipline used to test the exact artifact on the target runtime and device. A smaller download does not establish a smaller attached runtime.

Read the authors' benchmark without a cost shortcut

The authors' integration benchmark reports the following MetaMathQA training and GSM8K evaluation results for Llama 3.2 3B on an NVIDIA A100 80GB. Their table labels the storage column "Checkpoint"; these are reported experiment artifacts, not verified standalone exports.

In that experiment, ShadowPEFT has a higher score and smaller checkpoint, with higher peak memory and longer training. Inspect the linked Shadow configuration and LoRA configuration. The announcement calls the settings defaults, but the Shadow file specifies auxiliary_loss_weight=0.01 and shadow_alpha=0.5, rather than the API defaults of 0.05 and 0.1. Use the linked files to understand the experiment; do not assume an equal hyperparameter search. One reported result without uncertainty does not establish broad superiority. It also says nothing by itself about detached serving memory, latency, or detached inference accuracy.

What to avoid in ShadowPEFT deployment

Treating every PEFT adapter as mergeable

The following are anticipated implementation mistakes, not incidents from Optijara client work. A deployment script that calls merge_and_unload for every adapter type needs a method-specific branch. Replacing that call with shadow unloading also changes the predictor being shipped, so the old acceptance report cannot simply move over.

Potential failure modes include treating checkpoint size as peak memory, assigning attached benchmark scores to a detached model, and validating serialization in a process where the original base remains available. Shared modules can make an in-memory experiment look complete while leaving an independent export untested.

Confusing auxiliary image training with a detachable denoiser

An auxiliary denoising training path does not create a supported standalone Diffusers product. Flux2 backend support concerns how the shadow computation is built. It does not remove the NotImplementedError on standalone unloading.

The authors also report an image-generation comparison using a small, single-cat DreamBooth dataset. That model-specific experiment does not prove all-subject generalization, universal image quality, or standalone denoiser quality. Keep those claims out of a deployment proposal.

For teams moving between image tools, familiar controls do not prove execution parity. The same logic applies here. Shared API names are useful ergonomics, not evidence that two methods export equivalent models.

Caveats before adopting the main-branch integration

Compatibility, implementation cost, and evaluation limits

Main-branch behavior depends on the revision. Record the architecture, loader, dependency versions, and runtime restrictions covered by your tests. The documentation's support description is where the work starts. It is not certification for every serving engine.

Budget for export verification, evaluation, storage, and maintenance in addition to training. Hardware, provider pricing, context length, concurrency, and model choice all affect the measured outcome. A smaller adapter cannot carry a savings claim on its own. Keep uncertainty visible in comparisons, and rerun relevant checks after dependency changes.

Privacy and license checks remain artifact-specific

Review the base model, shadow checkpoint, dataset, tokenizer, and task-head terms before distribution. The projected Qwen shadow checkpoint is a concrete configuration to inspect, not blanket permission for every derived deployment. Detachment does not grant redistribution rights or remove training-data privacy concerns.

Choose a supported route, retain its dependency inventory, and evaluate the artifact that will actually reach the target environment. Leave unsupported Diffusers standalone export out of the release plan until the implementation explicitly supports it.