feat (docs): add comprehensive provider registry example (#5419)

Author: lgrammel

content/docs/03-ai-sdk-core/45-middleware.mdx content/docs/03-ai-sdk-core/40-middleware.mdx

@@ -1,9 +1,9 @@
 ---
-title: Provider Management
-description: Learn how to work with multiple providers
+title: Provider & Model Management
+description: Learn how to work with multiple providers and models
 ---
 
-# Provider Management
+# Provider & Model Management
 
 When you work with multiple providers and models, it is often desirable to manage them in a central place
 and access the models through simple string ids.
@@ -171,3 +171,87 @@ const { image } = await generateImage({
   prompt: 'A beautiful sunset over a calm ocean',
 });
 ```
+
+## Combining Custom Providers, Provider Registry, and Middleware
+
+The central idea of provider management is to set up a file that contains all the providers and models you want to use.
+You may want to pre-configure model settings, provide model name aliases, limit the available models, and more.
+
+Here is an example that implements the following concepts:
+
+- pass through a full provider with a namespace prefix (here: `xai > *`)
+- setup an OpenAI-compatible provider with custom api key and base URL (here: `custom > *`)
+- setup model name aliases (here: `anthropic > fast`, `anthropic > writing`, `anthropic > reasoning`)
+- pre-configure model settings (here: `anthropic > reasoning`)
+- validate the provider-specific options (here: `AnthropicProviderOptions`)
+- use a fallback provider (here: `anthropic > *`)
+- limit a provider to certain models without a fallback (here: `groq > gemma2-9b-it`, `groq > qwen-qwq-32b`)
+- define a custom separator for the provider registry (here: `>`)
+
+```ts
+import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { xai } from '@ai-sdk/xai';
+import { groq } from '@ai-sdk/groq';
+import {
+  createProviderRegistry,
+  customProvider,
+  defaultSettingsMiddleware,
+  wrapLanguageModel,
+} from 'ai';
+
+export const registry = createProviderRegistry(
+  {
+    // pass through a full provider with a namespace prefix
+    xai,
+
+    // access an OpenAI-compatible provider with custom setup
+    custom: createOpenAICompatible({
+      name: 'provider-name',
+      apiKey: process.env.CUSTOM_API_KEY,
+      baseURL: 'https://api.custom.com/v1',
+    }),
+
+    // setup model name aliases
+    anthropic: customProvider({
+      languageModels: {
+        fast: anthropic('claude-3-haiku-20240307'),
+
+        // simple model
+        writing: anthropic('claude-3-7-sonnet-20250219'),
+
+        // extended reasoning model configuration:
+        reasoning: wrapLanguageModel({
+          model: anthropic('claude-3-7-sonnet-20250219'),
+          middleware: defaultSettingsMiddleware({
+            settings: {
+              maxTokens: 100000, // example default setting
+              providerMetadata: {
+                anthropic: {
+                  thinking: {
+                    type: 'enabled',
+                    budgetTokens: 32000,
+                  },
+                } satisfies AnthropicProviderOptions,
+              },
+            },
+          }),
+        }),
+      },
+      fallbackProvider: anthropic,
+    }),
+
+    // limit a provider to certain models without a fallback
+    groq: customProvider({
+      languageModels: {
+        'gemma2-9b-it': groq('gemma2-9b-it'),
+        'qwen-qwq-32b': groq('qwen-qwq-32b'),
+      },
+    }),
+  },
+  { separator: ' > ' },
+);
+
+// usage:
+const model = registry.languageModel('anthropic > reasoning');
+```