Publishing Models: Adapter vs Merged to the Hub

Data & fine-tuningmedium30 min
Ask Cairnly about this lesson
On this page

What you will learn

  • Distinguish a LoRA adapter from a merged full model
  • Decide which to publish for which consumer
  • Upload an artifact to the Hugging Face Hub programmatically
  • Version artifacts and write a model card so others can use them

Why this matters

Training a model is worthless if no one can load it. Publishing to a hub (or registry) is the handoff from "it ran on my GPU" to "the team can serve it." Knowing the adapter-vs-merged distinction — and which to ship — is a practical fine-tuning skill and a tidy portfolio artifact (a public model others can actually run).

Adapter vs merged

LoRA training produces a small adapter — just the low-rank deltas, often a few MB — not a new full model. You have two things to publish:

  • The adapter — tiny, but the consumer must load it on top of the exact base model. Great for sharing cheaply and stacking multiple adapters.
  • The merged model — adapter folded into the base weights, producing a standalone full model (GBs). Heavier, but loads like any normal model with no base-model coordination.

Which to ship

  • Publish the adapter when consumers already have the base model and you want lightweight, composable artifacts (and you can iterate cheaply).
  • Publish the merged model when you want a drop-in artifact a serving stack can load directly, or when the base model isn't conveniently available to consumers.

Often you publish both: the adapter for tinkerers, the merged model for serving.

Upload programmatically

Pushing is a folder upload to a hub repo with an auth token. Wrap it so adapter and merged pushes are one call each, with a clear commit message:

python
from huggingface_hub import HfApi
 
def _upload_folder(folder, repo_id, token, message):
    HfApi(token=token).upload_folder(folder_path=str(folder), repo_id=repo_id,
                                     repo_type="model", commit_message=message)
 
def push_adapter(adapter_dir, repo_id, token):
    _upload_folder(adapter_dir, repo_id, token, "Upload LoRA adapter")
 
def push_merged(merged_dir, repo_id, token):
    _upload_folder(merged_dir, repo_id, token, "Upload merged FP16 model")

Version it and write a card

Tag releases (commit/branch/version) so a consumer can pin a known-good artifact — the same "serve by version, roll back by re-pointing" discipline as a model registry. Include a model card: base model, training data summary, eval numbers, and intended use.

Book

From AI Engineering (Chip Huyen)

When you finetune with an adapter method like LoRA, chapter 7 makes clear you end up with two things: the large base model you started from and a small set of trained adapter weights. How you package them is a real decision, not a detail.

If you merge the adapter into the base weights, you get one ordinary model. It is simple to load and adds no extra work at inference time, but every variant is a full-size copy. If you keep the adapter separate, each variant is only megabytes, many variants can share one base model in memory, and you can swap them quickly. The cost is a little more setup when serving.

For publishing, that suggests clear habits. Record exactly which base model and version the adapter expects, because an adapter is useless or harmful on the wrong base. Describe the training data and the evaluation results so others know what the model is for and where it fails. Version your releases so a user can pin the one they tested, and check the base model's license before you share anything built on it.

Further reading: Chip Huyen, AI Engineering (O'Reilly, 2025), chapter 7

python
import os
 
def publish(adapter_dir, merged_dir, repo_id: str):
    token = os.environ["HF_TOKEN"]                 # never hardcode
    # tinkerers want the small, composable adapter...
    push_adapter(adapter_dir, f"{repo_id}-adapter", token)
    # ...serving wants a standalone merged model
    push_merged(merged_dir, f"{repo_id}-merged", token)
    return {"adapter": f"{repo_id}-adapter", "merged": f"{repo_id}-merged"}
 
# consumer side — pin a version, don't float on 'latest'
# adapter:  PeftModel.from_pretrained(base_model, f"{repo_id}-adapter", revision="v1.0")
# merged:   AutoModelForCausalLM.from_pretrained(f"{repo_id}-merged", revision="v1.0")

Try it yourself

  1. After a LoRA run, locate the adapter directory and check its size vs the base model
  2. Merge the adapter into the base and compare the merged model's size
  3. Push the adapter to a Hub repo with push_adapter
  4. Load it back on top of the base model and run inference
  5. Write a minimal model card (base, data, eval, intended use) and pin a revision

Common mistakes

  • Publishing an adapter without naming the base model — it's unusable alone
  • Hardcoding the HF token — read it from the environment
  • Floating on latest — consumers should pin a revision for reproducibility
  • No model card — others can't tell what it was trained on or for
  • Shipping only the merged model when consumers wanted the cheap adapter (or vice versa)

Checklist

  • Explained adapter vs merged and when to ship each
  • Uploaded an artifact to the Hub programmatically
  • Loaded it back and ran inference
  • Pinned a version/revision
  • Wrote a model card with base, data, eval, and intended use

Quick quiz

Q: You publish only a 12 MB LoRA adapter but omit which base model it targets. What happens for a consumer?

How to explain it in an interview

"LoRA produces a small adapter — just the low-rank deltas — not a full model, so I have two things I can publish. The adapter is tiny and composable but must be loaded on top of the exact base model; the merged model folds the adapter into the base into a standalone artifact that serving can load directly. I publish the adapter for people who already have the base and want to iterate cheaply, the merged model for a drop-in serving artifact — often both. Uploading is a folder push to the hub with a token read from the environment, never hardcoded, and I pin versions and write a model card with the base model, data summary, eval numbers, and intended use so the artifact is actually reproducible and usable."