← Resources
TUTORIAL · 2026-03-26
Vom Vercel AI SDK zu einem BYOK-, selbst hostbaren Stack migrieren
Das Vercel AI SDK ist in Ordnung, bis Sie portable Schlüssel, benutzerdefiniertes Routing oder ein Deploy-Ziel benötigen, das nicht Vercel ist. Dieser Leitfaden mappt jedes Primitiv auf einen selbst hostbaren BYOK-Stack und liefert Ihnen einen einwöchigen Dual-Write-Cutover.
Warum Teams aus dem Vercel AI Gateway herauswachsen
Das AI SDK liefert schnell: `streamText`, `generateText` und `generateObject` decken die meisten Produktionsbedürfnisse mit einer einzigen TypeScript-Oberfläche ab. Die Reibung zeigt sich später, meist an drei Stellen.
Erstens ist die Runtime in Richtung Vercel meinungsstark. Edge-Runtime-Eigenheiten, auf Next.js abgestimmte Streaming-Primitive und das AI Gateway als empfohlener Router gehen alle davon aus, dass Ihr Produktivziel Vercel ist.
Zweitens sitzt das AI Gateway im Request-Pfad, sogar bei BYOK. Laut Vercels öffentlicher AI-Gateway-Preisliste von Mai 2026 läuft BYOK mit 0 % Token-Aufschlag, aber Ihr Team muss AI-Gateway-Credits stets ausreichend ausstatten, weil fehlgeschlagene BYOK-Requests gegen Vercels System-Credentials wiederholt werden. Diese Kopplung zählt, sobald Compliance oder VPC-Routing ins Spiel kommen.
Drittens lebt die Pro-Tenant-Richtlinie in Ihrem App-Code. Es gibt kein natives Konzept von Tenant, Modell-Whitelist oder Budget-Cap im SDK. Teams, die Multi-Tenant-SaaS betreiben, bauen am Ende ein zweites Mini-Gateway auf das erste.
Vercel-Primitive auf einen BYOK-Stack mappen
Die gute Nachricht: Die öffentliche Oberfläche des AI SDK ist klein. Die meisten Calls reduzieren sich auf drei Funktionen und ein Provider-Objekt. Mappen Sie sie so:
- `streamText` und `generateText` mappen direkt auf `chat.completions.create` des OpenAI SDK mit `stream: true` oder `false`. Jeder OpenAI-kompatible Endpunkt funktioniert als `baseURL`, was bedeutet llama.cpp, vLLM, LiteLLM oder ein gehosteter Anbieter hinter einem tenant-bewussten Proxy.
- `generateObject` mappt auf `response_format: { type: 'json_schema' }` bei OpenAI-kompatiblen Servern oder auf einen Structured-Output-Adapter für Anbieter, die ein anderes Schema verwenden (Anthropic-Tools, Gemini-JSON-Modus).
- Provider-Objekte (`openai('gpt-4o')`, `anthropic('claude-...')`) werden zu einem einzigen Client, der auf Ihr Gateway zeigt, mit der Modell-ID als String übergeben. Das Routing passiert serverseitig, statt im Import-Statement festgebacken zu sein.
Behalten Sie Ihre bestehenden React-Hooks. `useChat` und `useCompletion` brauchen nur eine Route, die einen Server-Sent-Events-Stream in derselben Form zurückgibt.
Streaming, Tool-Calls und strukturierte Outputs ohne Lock-in
Alle drei Features überleben die Migration, wenn Sie ein OpenAI-kompatibles Gateway wählen. Hier derselbe Call vorher und nachher.
Vorher, mit dem Vercel AI SDK:
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
const result = await streamText({
model: openai('gpt-4o'),
messages,
tools: { search: searchTool },
});
return result.toDataStreamResponse();
```
Nachher, mit dem OpenAI SDK, das auf Ihr eigenes Gateway zeigt:
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: process.env.GATEWAY_URL, apiKey: tenantKey });
const stream = await client.chat.completions.create({
model: 'gpt-4o',
messages,
tools: [searchToolSchema],
stream: true,
});
```
Tool-Calls kommen in `delta.tool_calls` an. Strukturierte Outputs verwenden `response_format`. Beide sind standard OpenAI-Spec-Felder, die LiteLLM, vLLM und die meisten Managed Provider ehren.
Schlüssel, Quotas und Pro-Tenant-Routing
Hier zahlt sich ein dünnes SDK aus. Sobald Requests durch einen OpenAI-kompatiblen Endpunkt fließen, den Sie kontrollieren, wandert jedes Querschnittsthema aus dem App-Code heraus.
Ein selbst gehostetes Gateway wie LiteLLM lässt Sie virtuelle Schlüssel pro Tenant prägen, RPM- und TPM-Obergrenzen setzen, Budgets anhängen und nach Modell-Alias routen. Ein Request für `model: 'fast'` kann für einen Tenant auf Groq Llama auflösen und für einen anderen auf einen lokalen llama.cpp-Server, ohne Code-Änderung in der Next.js-App.
osFoundry nimmt dieselbe reine BYOK-Durchleitungshaltung ein und ergänzt Pro-Tenant-Routing-Regeln, Streaming, Tool-Calls und strukturierte Outputs in einem Runtime, das Sie selbst hosten können. Mit-Erwähnung: LiteLLM ist hier die offensichtliche Open-Source-Baseline und für viele Teams die richtige Wahl; nehmen Sie, was Ihrem Ops-Modell entspricht.
Die tragende Entscheidung ist, dass das Gateway, nicht die App, Schlüssel und Quotas besitzt. Alles andere, einschließlich Modellwechsel, wird zu einer Config-Änderung.
Self-Hosten oder hybrid betreiben: Kosten und Betrieb
Drei Deploy-Formen decken die meisten Teams ab.
1. Vollständig selbst gehostet. Gateway in Ihrer VPC, BYOK an Anbieter, optionale lokale Modelle auf einem GPU-Server. Null Aufschlag, vollständiger Audit-Trail, Sie tragen die Bereitschaft. Am besten, wenn Compliance oder Datenresidenz die Entscheidung treibt.
2. Hybrid. Selbst gehostetes Gateway für Routing und Richtlinien, Managed Provider für Inferenz, lokale Modelle nur für günstige oder private Workloads. Das ist der häufige stabile Zustand.
3. Managed Gateway, Ihre Schlüssel. Verwenden Sie einen gehosteten OpenAI-kompatiblen Proxy, der BYOK-Durchleitung unterstützt. Sie geben etwas Kontrolle über den Request-Pfad ab; Sie sparen sich, einen weiteren Dienst zu betreiben.
Die Betriebskosten für Option 1 sind real: ein kleiner Container, ein Postgres für Schlüssel und Ausgaben, Log-Versand und eine Update-Kadenz. Für die meisten Teams unter ein paar hundert Millionen Tokens pro Monat sind die Einsparungen gegenüber einem aufschlagsbasierten Gateway kleiner als die Zeit, die mit der Debatte darüber verbracht wird. Wählen Sie nach Kontrolle, nicht nach Cent-Beträgen.
Cutover-Skript: eine Woche Dual-Write
Schalten Sie den Import nicht in einem PR um. Schreiben Sie sieben Tage lang dual, vergleichen Sie, schalten Sie dann um.
Tag 0: Fügen Sie den neuen Gateway-Client hinter einem Feature-Flag hinzu. Fahren Sie für jeden Request den alten `streamText`-Pfad und feuern Sie parallel den neuen `chat.completions`-Call mit denselben Messages ab. Verwerfen Sie die zweite Antwort, aber zeichnen Sie Latenz, Token-Anzahl, Finish Reason und alle Tool-Call-Formabweichungen auf.
Tage 1-3: Schatten-Sie 100 % des Traffics. Vergleichen Sie strukturierte Outputs und Tool-Call-Argument-JSON. Die meisten Regressionen sind schemabezogen: Anthropic gibt leicht andere Stop Reasons zurück, Gemini wickelt JSON anders ein. Fixen Sie im Gateway, nicht in der App.
Tage 4-6: Schalten Sie 10 %, dann 50 %, dann 100 % der Nur-Lese-Routen (Chat, Zusammenfassen) um. Behalten Sie Schreib- oder agentische Routen auf dem alten Pfad, bis der Diff 24 Stunden sauber ist.
Tag 7: Entfernen Sie die `ai`- und `@ai-sdk/*`-Pakete, löschen Sie die AI-Gateway-Env-Variablen und archivieren Sie das Flag.
Nach der Migration: Caching, Observability, Evals
Den Request-Pfad zu besitzen, schaltet drei Dinge frei, die innerhalb des SDK umständlich waren.
Caching: Ein Gateway kann auf `(model, messages, tools, response_format)` hashen und identische Requests aus Redis bedienen. Für RAG- und Agent-Loops mit wiederholten System-Prompts setzt sich Prompt-Prefix-Caching auf Anbieterebene (Anthropic, OpenAI) darüber. Verdrahten Sie beides; Cache-Treffer zeigen sich sofort in der Latenz-p50.
Observability: Geben Sie pro Request ein strukturiertes Log mit Tenant-ID, Modell, Prompt-Tokens, Completion-Tokens, Tool-Call-Anzahl, Finish Reason und Upstream-Latenz aus. Versenden Sie an das, was Sie ohnehin nutzen. Sie brauchen keine anbieterspezifische Tracing-Integration mehr, um zu sehen, was das Modell getan hat.
Evals: Mit allem Traffic, der durch einen Endpunkt fließt, wird Sampling für ein Eval-Set zu einer SQL-Abfrage. Wiederholen Sie gegen neue Modelle, indem Sie das `model`-Feld ändern. Das ist der langfristige Grund, das Gateway zu besitzen: Die Modellwahl wird zu einem wöchentlichen Experiment, nicht zu einer vierteljährlichen Migration.
Frequently asked questions
- Bedeutet das Wegwerfen des Vercel AI SDK, dass ich useChat und die React-Streaming-Hooks verliere?
- Nein. Die Hooks sind vom Server-Runtime entkoppelt, solange Ihre API-Route einen Server-Sent-Events-Stream in der Form zurückgibt, die der Hook erwartet. Sie können `useChat` und `useCompletion` aus dem `ai`-Paket behalten und sie auf eine Route richten, die eine OpenAI-kompatible Streaming-Antwort proxiert. Viele Teams halten die React-Seite den ersten Monat der Migration unberührt und tauschen nur den Server-Handler. Wenn Sie schließlich die `ai`-Abhängigkeit vollständig fallen lassen wollen, ist ein dünner SSE-Parser etwa 30 Zeilen TypeScript.
- Ist LiteLLM eine echte Alternative oder ein Notbehelf?
- Es ist eine echte Alternative und wird in der Produktion breit eingesetzt. LiteLLM ist ein Open-Source-OpenAI-kompatibler Proxy, der über 140 Anbieter abdeckt, virtuelle Schlüssel, Pro-Schlüssel-Budgets, RPM- und TPM-Limits und Load Balancing unterstützt. Es läuft als einzelner Docker-Container mit Postgres. Der Trade-off gegenüber einem volleren Orchestrierungs-Runtime liegt meist bei Agent-Loops, Structured-Output-Normalisierung über Anbieter hinweg und Tenant-bezogener Richtlinie jenseits von Schlüsseln und Budgets. Für einen reinen Routing- und BYOK-Anwendungsfall ist LiteLLM oft die richtige Antwort für sich allein.
- Wie halte ich strukturierte Outputs nach der Migration über Anbieter hinweg funktionsfähig?
- Normalisieren Sie im Gateway, nicht in der App. OpenAI und OpenAI-kompatible Server akzeptieren `response_format: { type: 'json_schema', json_schema: {...} }`. Anthropic verwendet ein Tool-Call-Muster, um Schemas zu erzwingen. Gemini hat ein `responseMimeType` plus `responseSchema`. Eine kleine Adapter-Schicht im Gateway übersetzt eine kanonische Request-Form in den jeweiligen Anbieter, an den Sie dispatchen, und validiert das zurückgegebene JSON, bevor sie antwortet. Das hält Ihren Anwendungscode bei einer einzigen Funktion und lässt Sie Modelle tauschen, ohne Schema-Handling-Logik anzufassen.
- Was ist mit der Latenz? Ein selbst gehostetes Gateway klingt nach einem weiteren Hop.
- In der Praxis ist die zusätzliche Latenz einstellig in Millisekunden, wenn das Gateway in derselben Region wie Ihre App ist, was von der Modell-Inferenzzeit (Hunderte ms bis Sekunden) in den Schatten gestellt wird. Der größere Latenz-Gewinn ist auf der Cache-Seite: Ein Gateway kann wiederholte Prompts in unter 5 ms aus Redis bedienen, was unmöglich ist, wenn jeder Request direkt zu einem Anbieter geht. Messen Sie p50 und p95 vorher und nachher; Teams sehen meist neutrale oder verbesserte Zahlen, sobald Caching an ist.
Sources