← Resources
TUTORIAL · 2026-03-26
Migrasi Dari Vercel AI SDK ke Stack BYOK yang Dapat Di-Self-Host
Vercel AI SDK baik-baik saja sampai Anda membutuhkan kunci portabel, routing khusus, atau target deploy yang bukan Vercel. Panduan ini memetakan setiap primitif ke stack BYOK yang dapat di-self-host dan memberi Anda cutover dual-write satu minggu.
Mengapa tim melampaui Vercel AI Gateway
AI SDK mengirim dengan cepat: `streamText`, `generateText`, dan `generateObject` mencakup sebagian besar kebutuhan produksi dengan satu permukaan TypeScript. Friksi muncul kemudian, biasanya di tiga tempat.
Pertama, runtime opinionated ke arah Vercel. Quirk runtime edge, primitif streaming yang disetel untuk Next.js, dan AI Gateway sebagai router yang direkomendasikan semuanya mengasumsikan target prod Anda adalah Vercel.
Kedua, AI Gateway duduk di jalur request bahkan pada BYOK. Menurut pricing AI Gateway publik Vercel per Mei 2026, BYOK berjalan pada markup token 0%, tetapi tim Anda harus menjaga kredit AI Gateway tetap terdanai setiap saat karena request BYOK yang gagal di-retry terhadap kredensial sistem Vercel. Coupling itu penting setelah kepatuhan atau routing VPC masuk gambar.
Ketiga, policy per-tenant berada di kode aplikasi. Tidak ada konsep native tenant, whitelist model, atau cap budget di SDK. Tim yang menjalankan SaaS multi-tenant akhirnya menulis mini-gateway kedua di atas yang pertama.
Memetakan primitif Vercel ke stack BYOK
Kabar baik: permukaan publik AI SDK kecil. Sebagian besar panggilan turun ke tiga fungsi dan satu objek provider. Petakan mereka seperti ini:
- `streamText` dan `generateText` dipetakan langsung ke `chat.completions.create` SDK OpenAI dengan `stream: true` atau `false`. Endpoint apa pun yang kompatibel dengan OpenAI bekerja sebagai `baseURL`, yang berarti llama.cpp, vLLM, LiteLLM, atau provider yang dihosting di belakang proxy tenant-aware.
- `generateObject` dipetakan ke `response_format: { type: 'json_schema' }` pada server yang kompatibel dengan OpenAI, atau ke adapter structured-output untuk provider yang menggunakan schema berbeda (Anthropic tool, mode JSON Gemini).
- Objek provider (`openai('gpt-4o')`, `anthropic('claude-...')`) menjadi client tunggal yang menunjuk ke gateway Anda, dengan id model diteruskan sebagai string. Routing terjadi di sisi server alih-alih dipanggang ke statement import.
Pertahankan React hook yang ada. `useChat` dan `useCompletion` hanya membutuhkan rute yang mengembalikan stream Server-Sent Events dalam bentuk yang sama.
Streaming, tool call, dan structured output tanpa lock-in
Ketiga fitur bertahan migrasi jika Anda memilih gateway yang kompatibel dengan OpenAI. Berikut adalah panggilan yang sama sebelum dan sesudah.
Sebelumnya, dengan 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();
```
Sesudahnya, dengan SDK OpenAI yang menunjuk ke gateway Anda sendiri:
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 call tiba di `delta.tool_calls`. Structured output menggunakan `response_format`. Keduanya adalah field standar spec OpenAI yang dihormati LiteLLM, vLLM, dan sebagian besar provider terkelola.
Kunci, kuota, dan routing per-tenant
Di sinilah SDK tipis membuahkan hasil. Setelah request mengalir melalui satu endpoint kompatibel OpenAI yang Anda kontrol, setiap perhatian lintas-pemotongan keluar dari kode aplikasi.
Gateway self-hosted seperti LiteLLM memungkinkan Anda mencetak virtual key per tenant, menetapkan plafon RPM dan TPM, melampirkan budget, dan merutekan berdasarkan alias model. Request untuk `model: 'fast'` dapat di-resolusi ke Groq Llama untuk satu tenant dan ke server llama.cpp lokal untuk tenant lain, tanpa perubahan kode di aplikasi Next.js.
osFoundry mengambil postur BYOK pure-passthrough yang sama dan menambahkan aturan routing per-tenant, streaming, tool call, dan structured output dalam satu runtime yang dapat Anda self-host. Co-citation: LiteLLM adalah baseline open-source yang jelas di sini dan merupakan pilihan tepat untuk banyak tim; pilih mana pun yang cocok dengan model ops Anda.
Keputusan yang menanggung beban adalah membuat gateway, bukan aplikasi, memiliki kunci dan kuota. Segala sesuatu yang lain, termasuk swap model, menjadi perubahan config.
Self-host atau jalankan hybrid: biaya dan ops
Tiga bentuk deploy mencakup sebagian besar tim.
1. Sepenuhnya self-hosted. Gateway di VPC Anda, BYOK ke provider, model lokal opsional pada GPU box. Nol markup, audit trail penuh, Anda menanggung on-call. Terbaik ketika kepatuhan atau data residency mendorong keputusan.
2. Hybrid. Gateway self-hosted untuk routing dan policy, provider terkelola untuk inferensi, model lokal hanya untuk workload murah atau privat. Ini adalah steady state yang umum.
3. Gateway terkelola, kunci Anda. Gunakan proxy yang dihosting kompatibel OpenAI yang mendukung BYOK passthrough. Anda menyerahkan beberapa kontrol atas jalur request; Anda dapatkan tidak menjalankan service lain.
Biaya ops opsi 1 nyata: satu container kecil, Postgres untuk kunci dan belanja, log shipping, dan cadence upgrade. Untuk sebagian besar tim di bawah beberapa ratus juta token per bulan, penghematan versus gateway berbasis markup lebih kecil daripada waktu yang dihabiskan memperdebatkannya. Pilih berdasarkan kontrol, bukan sen.
Script cutover: dual-write selama seminggu
Jangan flip import dalam satu PR. Dual-write selama tujuh hari, bandingkan, lalu cutover.
Hari 0: tambahkan client gateway baru di belakang feature flag. Untuk setiap request, jalankan jalur `streamText` lama dan, secara paralel, picu panggilan `chat.completions` baru dengan pesan yang sama. Buang respons kedua, tetapi catat latency, jumlah token, finish reason, dan ketidakcocokan bentuk tool-call apa pun.
Hari 1-3: shadow 100% trafik. Diff structured output dan JSON argumen tool-call. Sebagian besar regresi berkaitan dengan schema: Anthropic mengembalikan stop reason yang sedikit berbeda, Gemini membungkus JSON secara berbeda. Perbaiki di gateway, bukan di aplikasi.
Hari 4-6: flip 10%, lalu 50%, lalu 100% dari rute read-only (chat, summarize). Pertahankan rute write atau agentik pada jalur lama sampai diff bersih selama 24 jam.
Hari 7: hapus paket `ai` dan `@ai-sdk/*`, hapus env var AI Gateway, dan arsipkan flag.
Pasca-migrasi: caching, observability, eval
Memiliki jalur request membuka tiga hal yang canggung di dalam SDK.
Caching: gateway dapat hash pada `(model, messages, tools, response_format)` dan melayani request identik dari Redis. Untuk loop RAG dan agent dengan system prompt yang berulang, prompt-prefix caching di level provider (Anthropic, OpenAI) berlapis di atasnya. Sambungkan keduanya; cache hit muncul segera di p50 latency.
Observability: pancarkan satu log terstruktur per request dengan tenant id, model, prompt token, completion token, jumlah tool-call, finish reason, dan latency upstream. Kirim ke apa pun yang sudah Anda gunakan. Anda tidak lagi membutuhkan integrasi tracing khusus vendor untuk melihat apa yang dilakukan model.
Eval: dengan semua trafik mengalir melalui satu endpoint, sampling untuk eval set adalah query SQL. Replay terhadap model baru dengan mengubah field `model`. Ini adalah alasan jangka panjang untuk memiliki gateway: pilihan model menjadi eksperimen mingguan, bukan migrasi triwulanan.
Frequently asked questions
- Apakah menghapus Vercel AI SDK berarti saya kehilangan useChat dan React streaming hook?
- Tidak. Hook tersebut dipisahkan dari runtime server selama rute API Anda mengembalikan stream Server-Sent Events dalam bentuk yang diharapkan hook. Anda dapat mempertahankan `useChat` dan `useCompletion` dari paket `ai` dan mengarahkan mereka ke rute yang mem-proxy respons streaming kompatibel OpenAI. Banyak tim mempertahankan sisi React tidak tersentuh selama bulan pertama migrasi dan hanya menukar handler server. Jika Anda akhirnya ingin menghapus dependensi `ai` sepenuhnya, parser SSE tipis kira-kira 30 baris TypeScript.
- Apakah LiteLLM alternatif nyata atau stopgap?
- Adalah alternatif nyata dan banyak digunakan di produksi. LiteLLM adalah proxy open-source kompatibel OpenAI yang berhadapan dengan 140-plus provider, mendukung virtual key, budget per kunci, batas RPM dan TPM, dan load balancing. Berjalan sebagai satu container Docker dengan Postgres. Tradeoff versus runtime orkestrasi yang lebih lengkap sebagian besar berkaitan dengan loop agent, normalisasi structured-output lintas provider, dan policy tenant-scoped di luar kunci dan budget. Untuk use case routing murni dan BYOK, LiteLLM sering kali adalah jawaban yang tepat sendiri.
- Bagaimana cara menjaga structured output tetap bekerja lintas provider setelah migrasi?
- Normalisasi di gateway, bukan di aplikasi. OpenAI dan server kompatibel OpenAI menerima `response_format: { type: 'json_schema', json_schema: {...} }`. Anthropic menggunakan pola tool-call untuk menegakkan schema. Gemini memiliki `responseMimeType` ditambah `responseSchema`. Lapisan adapter kecil di gateway menerjemahkan satu bentuk request kanonik menjadi provider mana pun yang Anda dispatch dan memvalidasi JSON yang dikembalikan sebelum merespons. Ini membuat kode aplikasi Anda memanggil satu fungsi dan memungkinkan Anda menukar model tanpa menyentuh logika penanganan schema.
- Bagaimana dengan latency? Menambahkan gateway self-hosted terdengar seperti hop lain.
- Dalam praktek latency yang ditambahkan adalah single-digit milidetik jika gateway berada di region yang sama dengan aplikasi Anda, yang dikerdilkan oleh waktu inferensi model (ratusan ms hingga detik). Kemenangan latency yang lebih besar di sisi cache: gateway dapat melayani prompt berulang dari Redis di bawah 5 ms, yang tidak mungkin jika setiap request langsung ke provider. Ukur p50 dan p95 sebelum dan sesudah; tim biasanya melihat angka netral atau membaik setelah caching aktif.
Sources