Kit unterstützt vier KI-Provider über ein einheitliches Interface. Provider werden über das Vercel AI Gateway mittels
provider/model-Strings geroutet — ein Wechsel des Providers erfordert nur das Ändern einer Umgebungsvariable. Diese Seite behandelt die Provider-Einrichtung, Modellkonfiguration, den Standard-Modellkatalog, Gateway-Failover und Fähigkeiten.Schnelleinrichtung
Mit einem einzigen API-Schlüssel in
apps/boilerplate/.env.local funktionieren sowohl LLM-Chat als auch RAG-Chat sofort. Keine Konfiguration von AI_PROVIDER oder AI_MODEL nötig — Kit verwendet sinnvolle Standardwerte.Verfügbare Provider
API-Schlüssel:
OPENAI_API_KEY Standardmodell: gpt-5-nano Base-URL-Override: OPENAI_BASE_URL| Modell | Kontext | Eingabe (pro 1M) | Ausgabe (pro 1M) | Optimal für |
|---|---|---|---|---|
gpt-5.2 | 400K | $1,75 | $14,00 | Neuestes Flaggschiff-Reasoning |
gpt-5 | 400K | $1,25 | $10,00 | Coding und agentische Aufgaben |
gpt-5-mini | 400K | $0,25 | $2,00 | Klar definierte Aufgaben |
gpt-5-nano | 400K | $0,05 | $0,40 | Standard — schnell, günstigster |
gpt-4.1 | 1M | $2,00 | $8,00 | Komplexe Aufgaben, Coding |
gpt-4.1-mini | 1M | $0,40 | $1,60 | Effizienter Coding |
o3 | 200K | $2,00 | $8,00 | Tiefgreifendes Reasoning |
o4-mini | 200K | $1,10 | $4,40 | Reasoning mit kleinem Budget |
OpenAI ist für RAG-Embeddings (
text-embedding-3-small) erforderlich, auch wenn ein anderer Provider für den Chat verwendet wird.Modell-Auswahl
Du wählst ein Modell über einen
provider/model-String (z. B. anthropic/claude-haiku-4-5-20251001). Das Gateway routet es zum passenden Provider; ein Provider-Wechsel erfordert keine Code-Änderung. Wird kein Modell angegeben, greift das providerspezifische Standardmodell aus DEFAULT_MODELS. Den Standard-Provider legst du über AI_PROVIDER fest (Standard: anthropic):bash
# Anthropic als Standard-Provider für nicht qualifizierte Anfragen
AI_PROVIDER=anthropic
Gateway-Routing
Kit leitet jede Chat-Anfrage über das Vercel AI Gateway. Statt providerspezifische SDK-Clients zu erstellen, übergibt der Service einen einfachen
provider/model-Routing-String an streamText / generateText. Die Modell-Registry (model-registry.ts) ist die einzige Quelle der Wahrheit für Preise, Reasoning-Flags und den Routing-String-Builder:typescript
// src/lib/ai/model-registry.ts — Gateway-Routing-String
export function toGatewayModelString(
provider: AIProvider,
modelId: string
): string {
return `${provider}/${modelId}`
}
// src/lib/ai/ai-service.ts — eine Anfrage über das Gateway routen
const provider = resolveProviderForModel(modelId, this._provider)
const gatewayModel = toGatewayModelString(provider, modelId)
const result = streamText({
model: gatewayModel, // z. B. 'anthropic/claude-haiku-4-5-20251001'
messages,
...buildGatewaySettings({ modelId, isReasoning /* ... */ }),
})
Wesentliche Verhaltensweisen:
- Ein API-Schlüssel für alle Provider — das SDK liest
AI_GATEWAY_API_KEYautomatisch; keine providerspezifische Client-Erstellung - Provider aus dem Modell abgeleitet —
resolveProviderForModelschlägt das Modell in der Registry nach und fällt bei unbekannten Modellen auf den per Env konfigurierten Provider zurück - String-Routing — das Gateway akzeptiert
provider/modeldirekt, daher ist kein Provider-Import nötig
Gateway-Fallback
Wenn das primäre Modell nicht verfügbar ist, kann das Gateway auf alternative Modelle ausweichen. Das wird über die optionale Umgebungsvariable
AI_GATEWAY_FALLBACK_MODELS konfiguriert (eine kommagetrennte provider/model-Liste). Wenn gesetzt, hängt Kit die Liste an providerOptions.gateway.models an:bash
# Optional: kommagetrennte provider/model-Fallbacks
AI_GATEWAY_FALLBACK_MODELS=openai/gpt-5,google/gemini-2.5-flash
typescript
// src/lib/ai/gateway.ts — Fallback-Modelle anhängen (nur wenn konfiguriert)
const fallbackModels = getFallbackModels()
return {
maxOutputTokens: maxTokens ?? (isReasoning ? 16384 : defaultMaxTokens),
...(fallbackModels.length > 0 && {
providerOptions: { gateway: { models: fallbackModels } },
}),
}
Der Provider-Failover wird serverseitig vom Gateway übernommen, nicht durch einen clientseitigen Bewertungsalgorithmus. Wenn keine Fallback-Modelle konfiguriert sind, gibt es keinen automatischen Provider-Wechsel — das primäre Modell wird direkt verwendet.
Provider-Fähigkeiten
Nicht alle Provider unterstützen alle Funktionen. Die Fähigkeitsmatrix dient als Referenz für die Modellwahl und die Konfiguration von Gateway-Fallbacks:
| Fähigkeit | OpenAI | Anthropic | xAI | |
|---|---|---|---|---|
| Streaming | Ja | Ja | Ja | Ja |
| Functions/Tools | Ja | Ja | Ja | Ja |
| Vision | Ja | Ja | Ja | Nein |
| Embeddings | Ja | Nein | Ja | Nein |
| System Messages | Ja | Ja | Ja | Ja |
| Max. Kontext | 1M | 200K (1M Beta) | 1M | 2M |
Die RAG-Suche verwendet OpenAIs Embedding-Modell (konfigurierbar über
AI_EMBEDDING_MODEL, Standard: text-embedding-3-small), unabhängig vom aktiven Chat-Provider. Stelle sicher, dass OPENAI_API_KEY gesetzt ist (oder AI_API_KEY als Fallback), wenn du das RAG-System verwendest — auch mit Anthropic oder Google als primärem Provider.Reasoning-Modell-Behandlung
GPT-5-Familie und o-Series-Modelle sind Reasoning-Modelle mit besonderen Parameter-Einschränkungen. Das
isReasoningModel-Flag auf ModelInfo steuert das Laufzeitverhalten:| Modell | Reasoning | Temperature | Standard maxTokens |
|---|---|---|---|
| GPT-5, GPT-5.2, GPT-5 Mini, GPT-5 Nano | Ja | Nicht unterstützt | 16.384 |
| o3, o4-mini | Ja | Nicht unterstützt | 16.384 |
| GPT-4.1 | Nein | 0,7 (Standard) | 1.000 |
Wesentliche Einschränkungen:
- Temperature wird nicht unterstützt — das Übergeben an Reasoning-Modelle löst eine SDK-Warnung aus und kann das Verhalten verschlechtern. Kit lässt
temperaturebei Reasoning-Modellen vollständig weg. - maxOutputTokens deckt SOWOHL internes Reasoning ALS AUCH sichtbare Ausgabe ab — Reasoning-Modelle verwenden den Großteil des Token-Budgets für interne Gedankenketten. Der Standard von 1.000 ist viel zu niedrig; Kit verwendet 16.384 für Reasoning-Modelle.
- Symptom eines zu niedrigen maxOutputTokens:
finishReason: 'length'mit 0 Ausgabe-Tokens → leere Antwort für den Benutzer.
Diese Logik ist in
buildGatewaySettings (gateway.ts) zentralisiert — der einzigen Stelle, an der die v6-Settings-Namen (maxTokens → maxOutputTokens) und die Reasoning-Sicherheit leben:typescript
// Reasoning-bewusstes Parameter-Handling (gateway.ts → buildGatewaySettings)
const isReasoning = isReasoningModel(modelId)
return {
...(isReasoning ? {} : { temperature: temperature ?? defaultTemperature }),
maxOutputTokens: maxTokens ?? (isReasoning ? 16384 : defaultMaxTokens),
}
Streaming-Antwort-Diagnose
streamText() aus dem Vercel AI SDK gibt lazy Promises zurück, die sich nach dem Stream-Ende auflösen. Kit liest diese für Diagnosezwecke:| Eigenschaft | Typ | Zweck |
|---|---|---|
result.finishReason | Promise<string> | Grund für das Stream-Ende ('stop', 'length', 'content_filter') |
result.usage | Promise<object> | Token-Anzahlen (promptTokens, completionTokens) |
result.warnings | Warning[] | Nicht unterstützte Parameter, Modell-Deprecations |
finishReason-Werte:
| Wert | Bedeutung | Maßnahme |
|---|---|---|
'stop' | Normaler Abschluss | Keine |
'length' | Token-Budget erschöpft | maxTokens erhöhen |
'content_filter' | Provider hat Antwort blockiert | Content-Policy prüfen |
Kit protokolliert eine Warnung, wenn der Stream mit 0 Inhalts-Chunks oder einem Nicht-
'stop'-Finish-Reason endet. Diese Diagnosedaten sind für das Debuggen leerer KI-Antworten unverzichtbar.Benutzerdefinierte Base-URLs
Jeder Provider unterstützt eine benutzerdefinierte Base-URL für Proxys, selbst gehostete Modelle oder alternative Endpunkte:
| Variable | Standard | Zweck |
|---|---|---|
OPENAI_BASE_URL | https://api.openai.com/v1 | OpenAI-API-Proxy oder kompatibler Endpunkt |
ANTHROPIC_BASE_URL | https://api.anthropic.com | Anthropic-API-Proxy |
GOOGLE_AI_BASE_URL | https://generativelanguage.googleapis.com/v1 | Google-AI-Proxy |
XAI_BASE_URL | https://api.x.ai/v1 | xAI-API-Proxy |
OPENAI_ORG_ID | — | OpenAI-Organisations-ID für die Abrechnung |
Fehlerbehandlung und Wiederholungsversuche
Wiederholungsversuche werden vom Vercel AI SDK übernommen. Sowohl
streamText als auch generateText akzeptieren eine maxRetries-Einstellung (Standard: 2) und wenden automatisch exponentiellen Backoff mit Jitter an. Fehlgeschlagene Anfragen bei transienten Fehlern (Netzwerk-Timeouts, 5xx-Antworten) werden wiederholt; Client-Fehler (400, 401, 403) schlagen sofort fehl.typescript
// Wiederholungsversuche werden pro Aufruf über das AI SDK konfiguriert
streamText({
model: gatewayModel,
messages,
maxRetries: 2, // Standard; auf 0 setzen, um zu deaktivieren
})
Kits strukturierte Fehlerklassen (
src/lib/ai/errors.ts) kapseln Provider-Fehler mit Wiederholbarkeits-Metadaten:| Fehlerklasse | Wann | Wiederholbar |
|---|---|---|
AIProviderError | Basisklasse für alle Provider-Fehler | Unterschiedlich |
NetworkError | Verbindungsfehler, DNS-Fehler | Ja |
TimeoutError | Anfrage überschreitet Timeout | Ja |
ValidationError | Ungültige Konfiguration oder Anfrage | Nein |
InvalidProviderError | Unbekannter Provider-String | Nein |