Vercel AI SDK custom provider base URL: Catatan Penyiapan Flatkey

Penyiapan Vercel AI SDK custom provider base URL lebih dari sekadar mengganti string. Bagian yang berguna adalah mengarahkan provider AI SDK ke Flatkey, tetapi pekerjaan aman untuk produksi adalah memverifikasi alias model, keluarga endpoint, perilaku streaming, pemanggilan tool, bukti penggunaan, kontrol kuota, dan rollback sebelum trafik pengguna berpindah.

Panduan ini ditujukan untuk developer, tim produk AI, engineer platform, pembuat automasi, operator keuangan, dan reviewer pengadaan yang menggunakan AI SDK di route Next.js, server action, worker, antrean, atau loop agen. Panduan ini diperbarui pada 29 Juni 2026 berdasarkan dokumentasi AI SDK terkini, pengecekan tipe terhadap paket AI SDK saat ini, dan halaman publik Flatkey yang live. Cuplikan kode di sini adalah template. Tidak ada API key Flatkey live yang tersedia dalam tugas ini, jadi jalankan smoke test dengan key Anda sendiri, base URL konsol Flatkey saat ini, dan alias model yang diaktifkan untuk akun Anda.

Jawaban Singkat: Vercel AI SDK Custom Provider Base URL

Untuk penyiapan Vercel AI SDK custom provider base URL dengan Flatkey, mulailah dengan paket provider OpenAI-compatible resmi. Buat provider dengan createOpenAICompatible, set baseURL ke base URL Flatkey terbaru dari konsol Anda, set apiKey ke key Flatkey Anda, dan gunakan alias model Flatkey di generateText atau streamText.

npm install ai @ai-sdk/openai-compatible zod

export FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Salin nilai terkini dari Flatkey
export FLATKEY_MODEL="your-flatkey-model-alias"

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short Flatkey AI SDK routing check.',
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);

Itulah bentuk minimum yang bekerja untuk migrasi Vercel AI SDK custom provider base URL. Jangan berhenti di sana. Respons teks yang berhasil hanya membuktikan bahwa satu bentuk request mencapai satu alias model. Itu tidak membuktikan streaming usage, tools, structured output, visibilitas biaya, perilaku kuota, atau rollback.

Apa yang Didukung Dokumentasi AI SDK Terkini

Dokumentasi AI SDK saat ini memiliki dua jalur yang relevan. Paket OpenAI Compatible provider dibuat untuk provider yang mengimplementasikan OpenAI API. Paket ini mengekspos createOpenAICompatible dengan opsi termasuk name, apiKey, baseURL, headers, queryParams, fetch kustom, includeUsage, supportsStructuredOutputs, transformasi body request, dan ekstraksi metadata.

Paket OpenAI provider juga mendukung createOpenAI({ baseURL }) untuk setup yang dikustomisasi, termasuk server proxy. OpenAI Compatible provider adalah default yang lebih bersih untuk Vercel AI SDK custom provider base URL karena nama provider, ekstraksi metadata kustom, opsi khusus provider, dan nama factory model dirancang untuk route OpenAI-compatible non-OpenAI.

Bukti Flatkey Terkini Yang Harus Digunakan Dengan Hati-Hati

Beranda Flatkey.s yang diperiksa pada 29 Juni 2026 memiliki judul One API gateway for production AI teams dan deskripsi meta yang menyatakan bahwa Flatkey menyatukan akses model, routing, billing, analitik penggunaan, dan kontrol operasional. API pricing live mengembalikan 633 baris model, 23 vendor, dan keluarga endpoint untuk /v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:generateContent, /v1/images/generations, dan /v1/video/generations.

Gunakan fakta-fakta itu sebagai bukti publik bertanggal untuk positioning dan bentuk katalog, bukan sebagai bukti bahwa setiap akun bisa memanggil setiap route, setiap alias model tersedia, atau setiap fitur diaktifkan. Sebelum trafik produksi, pemeriksaan Vercel AI SDK custom provider base URL Anda harus menggunakan key, base URL, alias model, keluarga endpoint, dan path fitur yang persis sama dengan yang akan dikirim aplikasi Anda.

Base URL Dan Penyiapan Environment

Simpan base URL, key, dan alias model di environment variables. Itu membuat rollout Vercel AI SDK custom provider base URL dapat ditinjau dalam konfigurasi deployment, alih-alih tersembunyi di dalam route handler, file prompt, dan worker.

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

Kemudian pisahkan routing workload dari setup transport. Base URL memberi tahu SDK ke mana permintaan dikirim. Alias model menentukan route Flatkey dan model upstream mana yang Anda minta.

const MODEL_ROUTES = {
  supportTriage: 'FLATKEY_SUPPORT_MODEL',
  workflowPlanning: 'FLATKEY_PLANNING_MODEL',
  codeReview: 'FLATKEY_CODE_MODEL',
  fallback: 'FLATKEY_FALLBACK_MODEL',
} as const;

function modelFor(routeName: keyof typeof MODEL_ROUTES) {
  return flatkey.chatModel(requiredEnv(MODEL_ROUTES[routeName]));
}

Pola ini mencegah tim menyebarkan nama provider, alias model, dan base URL ke seluruh codebase. Ini juga memberi tim finance dan operations kumpulan nama workload yang stabil untuk dicocokkan dengan baris usage.

Smoke Test Teks Non-Streaming Terlebih Dahulu

Mulailah dengan generateText. Ini memberi Anda objek hasil yang sederhana dengan text, finish reason, usage, warnings, steps, dan metadata respons. Gunakan ini untuk membuktikan autentikasi, bentuk base URL, alias model, dan visibilitas usage sebelum menguji streaming atau tools.

import { generateText } from 'ai';

const result = await generateText({
  model: modelFor('supportTriage'),
  prompt: 'Balas dengan satu cek kesiapan migrasi yang singkat.',
});

console.log({
  text: result.text,
  finishReason: result.finishReason,
  usage: result.usage,
  warnings: result.warnings,
});

Setujui pemeriksaan Vercel AI SDK custom provider base URL pertama ini hanya jika text yang dihasilkan, alias model, finish reason, dan field usage sudah cukup baik untuk kebutuhan logging dan reviewer aplikasi Anda. Jika panggilan mengembalikan text tetapi usage tidak dapat ditemukan di catatan Flatkey, migrasi belum siap untuk produksi.

Uji Streaming Secara Terpisah

Streaming memiliki permukaan kegagalan yang berbeda. Ini menyentuh streaming respons, serverless timeout, pembatalan UI, penanganan error, dan pencatatan usage. Dokumen AI SDK menampilkan streamText, result.textStream, callback onError, dan promise hasil seperti result.usage. OpenAI Compatible provider juga memiliki includeUsage untuk metadata respons streaming ketika provider mendukungnya.

import { streamText } from 'ai';

const stream = streamText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Stream tiga cek penyiapan yang singkat.',
  onError({ error }) {
    console.error(error);
  },
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);
}

const usage = await stream.usage;
console.log({ usage });

Biarkan streaming tetap diaktifkan hanya setelah alias model Flatkey yang dipilih terbukti stabil pada bentuk request nyata Anda. Jika text yang di-stream bekerja tetapi usage tidak lengkap, putuskan apakah tim Anda dapat mengumpulkan usage dari catatan Flatkey alih-alih dari respons stream sebelum traffic pengguna berpindah.

Verifikasi Tool Calls Dengan Alias Yang Sama

API tool AI SDK menggunakan objek tools, helper tool, inputSchema, dan fungsi execute opsional. Satu pass chat biasa tidak menyetujui pemanggilan tool. Uji skema kecil terlebih dahulu, lalu perluas ke set tool yang benar-benar digunakan agen Anda.

import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_TOOL_MODEL')),
  tools: {
    routeReadiness: tool({
      description: 'Mengembalikan status kesiapan untuk suatu route Flatkey.',
      inputSchema: z.object({
        routeName: z.string().describe('Nama route internal yang akan diperiksa'),
      }),
      execute: async ({ routeName }) => ({
        routeName,
        checked: true,
      }),
    }),
  },
  stopWhen: isStepCount(2),
  prompt: 'Gunakan tool untuk route supportTriage.',
});

console.log(result.toolCalls);
console.log(result.toolResults);
console.log(result.usage);

Untuk traffic agent, catat apakah model memanggil tool yang diharapkan, apakah input tervalidasi, apakah hasil tool kembali dengan bersih, dan apakah baris usage Flatkey dapat ditautkan kembali ke route yang sama. Jika skema ketat, alur persetujuan, atau parallel tool calls penting, uji fitur tersebut dengan alias model yang persis sama.

Kapan Menggunakan createOpenAI Sebagai Ganti

Jika aplikasi Anda sudah menggunakan @ai-sdk/openai di semua tempat, opsi baseURL dari provider OpenAI bisa menjadi jalur migrasi dengan perubahan yang lebih kecil. Ini tetap merupakan setup Vercel AI SDK custom provider base URL, tetapi Anda harus lebih eksplisit tentang pemilihan API model.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const flatkeyViaOpenAIProvider = createOpenAI({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
});

const result = await generateText({
  model: flatkeyViaOpenAIProvider.chat(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Balas dengan satu cek singkat base URL provider OpenAI.',
});

Dokumentasi provider OpenAI saat ini menyatakan bahwa Responses adalah API default untuk provider OpenAI sejak AI SDK 5 kecuali Anda menentukan route seperti .chat(...). Itulah mengapa contoh di atas menggunakan .chat(...) secara eksplisit. Jika Anda bermaksud menguji keluarga endpoint /v1/responses milik Flatkey, perlakukan itu sebagai pengecekan route terpisah dengan alias model dan jalur rollback yang terpisah.

Daftar Periksa Penyiapan

Mode Kegagalan Umum

Posisinya dalam Panduan Flatkey Lainnya

Jika Anda memerlukan jalur migrasi yang lebih luas, mulai dengan panduan migrasi API yang kompatibel dengan OpenAI. Untuk pola penyiapan tool yang berdekatan, tinjau panduan penyiapan API Cherry Studio dan panduan cc-switch Claude Code Flatkey. Gunakan harga Flatkey untuk memeriksa katalog model saat ini, lalu dapatkan key ketika Anda siap menjalankan smoke test di akun Anda sendiri.

FAQ

Bagaimana cara mengatur base URL provider kustom Vercel AI SDK untuk Flatkey?

Buat provider yang kompatibel dengan OpenAI menggunakan createOpenAICompatible, setel baseURL ke base URL Flatkey saat ini, setel apiKey ke key Flatkey Anda, dan berikan alias model Flatkey ke generateText atau streamText.

Haruskah saya menggunakan @ai-sdk/openai-compatible atau @ai-sdk/openai?

Gunakan @ai-sdk/openai-compatible untuk penyiapan Flatkey baru karena dirancang untuk provider yang kompatibel dengan OpenAI. Gunakan @ai-sdk/openai dengan createOpenAI({ baseURL }) ketika aplikasi Anda sudah menstandarkan provider OpenAI dan Anda menginginkan diff kode yang lebih kecil.

Apakah base URL perlu menyertakan /v1?

Gunakan nilai yang ditampilkan di konsol Flatkey Anda saat ini. Dalam sebagian besar pola SDK yang kompatibel dengan OpenAI, base URL menyertakan prefiks versi sehingga panggilan SDK dapat menambahkan path seperti /chat/completions dengan benar.

Bisakah satu base URL Flatkey merutekan banyak model?

Posisi publik Flatkey adalah satu gateway untuk akses model, routing, billing, analitik usage, dan kontrol operasional. Di aplikasi Anda, tetap petakan setiap workload ke alias model Flatkey yang eksplisit dan uji alias yang sebenarnya sebelum traffic berpindah.

Apakah potongan kode AI SDK ini telah diuji?

Potongan kode telah dicek tipenya pada 29 Juni 2026 terhadap ai@7.0.4, @ai-sdk/openai-compatible@3.0.1, @ai-sdk/openai@4.0.2, TypeScript, dan Zod. Kode tersebut tidak dijalankan terhadap Flatkey karena tidak ada API key Flatkey aktif yang tersedia di runtime ini.

Inti Kesimpulan

Vercel AI SDK custom provider base URL migration seharusnya hanya menjadi perubahan provider kecil dengan daftar verifikasi yang serius di sekitarnya. Gunakan createOpenAICompatible untuk provider Flatkey, simpan base URL dan alias model dalam konfigurasi, uji teks non-streaming terlebih dahulu, uji streaming dan panggilan tool secara terpisah, pastikan bukti penggunaan di Flatkey, dan siapkan rollback hingga traffic produksi stabil. Saat pemeriksaan sudah siap, dapatkan kunci dan jalankan smoke test dengan alias model Anda sendiri.