Model Portability and Avoiding Lock-In
Keep the freedom to switch models: thin adapters, provider-neutral prompts and schemas, portable evals, and a migration checklist for model upgrades.
Every model you use today will be replaced. Providers retire models on published schedules, better and cheaper ones ship every few months, prices change, and occasionally a customer's procurement team or a regional data rule decides which provider you may use. None of that is a problem if switching a feature to a different model is a config change plus an eval run. It's a serious problem if model-specific calls, prompts, and response parsing are scattered through forty files.
This lesson is about keeping that freedom without giving up the provider features that make your product good. You'll map where lock-in actually hides, build a thin adapter at the feature boundary, write prompts and schemas that travel, make your evals the portable core of your AI stack, and work through a migration checklist you can reuse for every model upgrade.
Where lock-in actually hides
"Lock-in" sounds like one thing, but it's several layers of coupling with very different switching costs:
| Layer | Example of coupling | Cost to switch |
|---|---|---|
| API shape | messages.create calls and response parsing in every feature file | Mechanical, but touches everything if not isolated |
| Prompts | A prompt tuned over months against one model's quirks | Re-tuning and re-evaluating each feature |
| Provider features | Prompt caching, citations, server-side tools, effort settings | Re-implementing or accepting a different design |
| Schemas | A JSON Schema that uses keywords only one provider's strict mode accepts | Rewriting schemas, revalidating outputs |
| Stored data | Embeddings, conversation histories with provider-specific blocks | Re-embedding a corpus, migrating stored formats |
| Trained artifacts | A fine-tuned model that exists only on one platform | Retraining from scratch, if you kept the data |
| Operations | Rate limits, keys, data-processing agreements, invoices | Procurement and paperwork, often the slowest part |
The goal isn't zero lock-in. Prompt caching, citations, and structured outputs are worth using even though they're implemented differently by each provider. The goal is to know your switching cost per feature and keep it low where that's cheap. Isolating the API shape costs almost nothing. Avoiding a provider feature that cuts your input costs dramatically, just to stay portable, would be a bad trade.