Promote an adapter to active

What it does

Adapters (LoRA models) are applied on top of a base model during inference. You can promote one adapter to active so all new chats use it. If the adapter fails or is not available, the system falls back to the base model automatically.

Prerequisites

• At least one completed training job (guide 05), or an adapter loaded manually into the registry.
• The adapter appears on the Adapters page.

Steps

1. Open Adapters page

Click Adapters in the left rail. The page lists adapters with:

• Status — green if active, gray if inactive.
• Metrics — eval metrics (F1, accuracy, etc.) from the training run.
• Created — timestamp when the adapter was registered.

2. Find the adapter to promote

Scroll to find the adapter you want to make active. You can filter by:

• Model id — the base model the adapter is trained on (e.g. qwen2.5:3b).
• Status — active or inactive.

3. Click the Promote button

On the adapter row, click the Promote button (or the status badge itself). A confirmation dialog appears:

Promote {adapter_id} to active for {model_id}?

This adapter will serve all new chats. If it fails,
chats fall back to the base model.

Click Confirm. The adapter's status badge turns green and shows active.

4. Verify in Chat

Open the chat panel (⌘K / Ctrl+K). The chat now uses the active adapter for the model. You can observe which adapter is serving by checking the Observability page — each inference row shows adapter_id.

(Direct API) Promote via curl

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BIGWAVE_TOKEN" \
  -d '{"adapter_id": "my-adapter-123"}' \
  "http://localhost:8080/admin/models/{model_id}/adapters" | jq

Returns 200 OK.

Verify

• After promoting, the adapter row shows active status.
• Send a chat message; the inference is logged with your adapter_id.
• Run:

  curl -s -H "Authorization: Bearer $BIGWAVE_TOKEN" \
    "http://localhost:8080/admin/models/{model_id}/active" | jq '.adapter_id'

  Should return your promoted adapter's id.

Common issues

Symptom	Cause	Fix
"Adapter not found"	adapter_id is invalid or deleted	Use a different adapter or train a new one
Promote button is disabled (grayed out)	Adapter is already active or doesn't support your model	Check the model_id; promote a different adapter or train one for this model
Chat still uses old adapter after promotion	Browser cache or SSE connection stale	Refresh the page; the chat panel will pick up the new active adapter
Inference fails with "Adapter load error"	Adapter files are corrupt or missing from disk	Re-train the adapter; this is a data integrity issue on the backend

Related

• Train a LoRA adapter (DPO) — training produces adapters.
• Send a chat message — adapters are used during chat inference.
• Run an eval against a golden set — use evals to validate adapters before promotion.