Model aliases
Expose stable application-level names while changing the underlying model.
AI Tools · Function
customProvider
Creates a custom AI SDK provider that maps application-specific IDs to models from another provider. It can also fall back to another provider for missing models or capabilities.
- Since
- 4.2
How it works
customProvider builds a Provider from named model mappings. Application code retrieves models by those custom IDs, while an optional fallbackProvider can resolve models or capabilities that the custom provider does not contain.
Syntax
customProvider({ languageModels?, fallbackProvider? }): ProviderParameters
| Name | Type | Description |
|---|---|---|
languageModels? | Record<string, LanguageModel> | A record whose keys are custom model IDs and whose values are language model instances. |
fallbackProvider? | Provider | An optional provider used when a requested model or capability is not found in the custom provider. |
Returns
A Provider instance with methods for retrieving models by custom IDs, including languageModel and embeddingModel.
Key points
- Map convenient custom IDs to models from another provider.
- Use aliases to centralize model configuration and expose stable names to application code.
- Optionally delegate unresolved models or capabilities to another provider.
- A custom provider can organize several model capability types, not only language models.
- The function returns a Provider that exposes model lookup methods.
Common mistakes
- A fallback provider is only used when the requested model or capability is absent from the custom provider.
Example: Create model aliases
import { openai } from '@ai-sdk/openai';
import { customProvider } from 'ai';
const provider = customProvider({
languageModels: {
fast: openai('gpt-4o-mini'),
quality: openai('gpt-4o'),
},
});
const model = provider.languageModel('fast');Creates aliases for two OpenAI models, then retrieves the configured model through the custom provider.
When to use it
Restrict model access
Keep approved models in a controlled mapping.
Centralize model setup
Add shared configuration around provider models.
Fallback resolution
Resolve models not present in the custom mapping.
Related
ProviderLanguageModelembeddingModellanguageModel