Pengujian migrasi base URL API AI harus dilakukan sebelum perubahan environment variable, bukan setelah traffic produksi mulai gagal. Mengubah satu baseURL atau base_url dapat memindahkan autentikasi, pemilihan model, streaming, tool calling, catatan penggunaan, perilaku kuota, dan kontrol rollback ke jalur baru sekaligus.
Flatkey dirancang untuk tim yang menginginkan satu key, satu lapisan routing yang kompatibel dengan OpenAI, dan peninjauan billing serta penggunaan yang lebih jelas di seluruh provider model. Homepage publik Flatkey yang dicek pada 7 Juli 2026 menampilkan rute contoh https://router.flatkey.ai/v1/chat/completions, sementara halaman models dan pricing saat ini menampilkan konteks model, endpoint, provider, dan billing untuk ditinjau. Perlakukan halaman-halaman tersebut sebagai bukti pada hari migrasi, lalu jalankan smoke test akun Anda sendiri sebelum memindahkan traffic.
Gunakan panduan ini sebagai urutan praktis pengujian migrasi base URL API AI. Tujuannya bukan membuktikan setiap jalur aplikasi. Tujuannya adalah membuktikan jalur paling kecil yang aman melalui base URL baru, lalu menambahkan fitur satu lapisan demi satu lapisan.
7 Tes Migrasi URL Basis API AI
Jalankan pengujian dalam urutan ini. Masing-masing harus menghasilkan bukti yang bisa Anda lampirkan ke tiket deployment.
| Test | What It Proves | Evidence To Save |
|---|---|---|
| 1. Auth and base URL composition | Key, host, root /v1, dan path endpoint tersambung dengan benar. |
Snapshot env yang disensor, status code, body respons, waktu request. |
| 2. Model catalog and endpoint family | Alias model yang dipilih termasuk dalam endpoint yang Anda panggil. | Screenshot atau ekspor katalog, alias model, family endpoint. |
| 3. Plain chat completion | Request minimal non-streaming berhasil tanpa kompleksitas SDK atau aplikasi. | Perintah curl, response ID, teks output, objek usage jika dikembalikan. |
| 4. SDK parity | SDK aplikasi membangun rute yang sama seperti yang dibuktikan oleh curl. | Base URL yang ter-resolve, versi SDK, respons, log config startup tanpa secret. |
| 5. Streaming or SSE | Event inkremental mencapai klien tanpa buffering atau ketidaksesuaian parser. | Contoh stream mentah, content type, waktu token pertama, event final. |
| 6. Tool or function calling | Rute yang dipilih mendukung skema tool dan perilaku tool-choice Anda. | Request skema kecil, output tool call, body kegagalan jika tidak didukung. |
| 7. Usage, quota, and rollback | Jalur baru terlihat oleh operasi, dan kegagalan bisa dibalik dengan cepat. | Readback dashboard, hasil kuota, config sebelumnya, pemilik rollback. |
Jangan melewatkan pengujian awal hanya karena wrapper framework sudah berhasil di staging. Sebagian besar pengujian migrasi base URL API AI gagal karena SDK diam-diam membaca key yang berbeda, menerima root base URL yang salah, atau mengirim model yang valid ke family endpoint yang salah.
Tes 1: Komposisi Auth dan URL Dasar
Mulailah di luar aplikasi. Anda perlu membuktikan bahwa key dan base URL dapat mencapai bentuk endpoint paling sederhana.
Kesalahan base URL yang umum adalah mengoper endpoint lengkap ke SDK. Untuk SDK yang kompatibel dengan OpenAI, base URL biasanya adalah root API, seperti https://router.flatkey.ai/v1, dan SDK menambahkan /chat/completions, /responses, atau endpoint lain. Mengoper https://router.flatkey.ai/v1/chat/completions sebagai base URL dapat membuat path duplikat.
Gunakan pemeriksaan environment yang disensor terlebih dahulu:
test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"
Kemudian lakukan satu request langsung:
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"
curl -sS "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{"role": "user", "content": "Reply with exactly: base url ok"}
]
}'
Jika ini mengembalikan 401, perbaiki key dan header auth sebelum mengubah model. Jika mengembalikan 404, periksa host, root /v1, dan apakah path endpoint diduplikasi. Jika mengembalikan 403, periksa akun, project, model, region, atau kebijakan IP. Dokumentasi kode error OpenAI menganggap 401 sebagai autentikasi, 429 sebagai rate atau kuota, dan 500 atau 503 sebagai kondisi server atau overload; gateway dapat menambahkan detail lain, jadi simpan body respons.
Tes 2: Katalog Model dan Keluarga Titik Akhir
Base URL yang kompatibel dengan OpenAI tidak membuat setiap nama model menjadi portabel. Endpoint List models pada API OpenAI, serta endpoint Chat Completions dan Responses, menggunakan bentuk request yang berbeda. Sebuah gateway atau route yang kompatibel dengan provider dapat mengekspos model untuk satu family endpoint tetapi tidak untuk yang lain.
Sebelum Anda mengubah config produksi, buat map model kecil:
| Field | Contoh |
|---|---|
| App alias | support_chat |
| Gateway alias | support-chat-primary |
| Provider model or Flatkey model alias | Nilai konsol saat ini |
| Endpoint family | chat, responses, images, embeddings, atau video |
| Owner | Platform, produk AI, otomasi, atau tim support |
| Rollback value | Model sebelumnya dan base URL sebelumnya |
Kondisi lulus bukanlah "nama model terlihat benar." Kondisi lulus adalah bahwa konsol Flatkey saat ini, direktori model, atau katalog provider menampilkan alias yang persis untuk family endpoint yang persis yang akan Anda panggil. Hubungkan pekerjaan ini dengan tata kelola model yang lebih luas menggunakan panduan nama model yang kompatibel dengan OpenAI.
Tes 3: Penyelesaian Obrolan Biasa
Pengujian migrasi base URL API AI ketiga adalah request generasi nyata yang paling kecil. Biarkan tanpa streaming. Jangan sertakan tools, skema JSON, file, gambar, retry, atau middleware aplikasi.
Simpan:
| Field | Mengapa Ini Penting |
|---|---|
| Status HTTP | Mengonfirmasi rute menerima request. |
| ID respons atau ID request | Memungkinkan support melacak request. |
| Model yang dikembalikan | Menunjukkan model atau alias mana yang menangani request. |
| Teks output | Mengonfirmasi respons berhasil dibuat. |
| Objek usage | Memulai billing dan rekonsiliasi token. |
Jika request biasa gagal, jangan debug streaming dulu. Gunakan panduan troubleshooting API yang kompatibel dengan OpenAI untuk mengisolasi masalah key, route, family endpoint, dan alias model terlebih dahulu.
Tes 4: Paritas SDK
Setelah curl berhasil, buktikan bahwa SDK membangun rute yang sama. Dokumentasi resmi OpenAI saat ini mengarahkan developer ke SDK resmi untuk JavaScript dan Python. Cookbook OpenAI juga menunjukkan penggunaan endpoint kustom saat sebuah client dibuat dengan token dan base URL kustom. Untuk migrasi, buat ini eksplisit dalam kode alih-alih mengandalkan nilai OPENAI_API_KEY atau OPENAI_BASE_URL yang tersisa.
Template Python:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[{"role": "user", "content": "Balas dengan tepat: sdk ok"}],
)
print(response.choices[0].message.content)
print(response.usage)
Template Node:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL!,
messages: [{ role: "user", content: "Balas dengan tepat: sdk ok" }],
});
console.log(response.choices[0]?.message?.content);
console.log(response.usage);
Log base URL yang ter-resolve saat proses dimulai, tetapi jangan log key. Jika curl berhasil dan SDK gagal, periksa precedence variabel environment, versi SDK, penggabungan path, header organization/project, dan perilaku proxy sebelum mengubah model.
Tes 5: Streaming Atau SSE
Streaming adalah bagian ketika banyak migrasi terlihat sehat di layer HTTP tetapi gagal di aplikasi. Referensi Chat Completions OpenAI mengembalikan objek JSON atau chunk chat completion yang di-stream ketika streaming diaktifkan. Responses API juga dapat mengembalikan text/event-stream, dengan nama event yang berbeda dari chunk Chat Completions.
Jalankan ini setelah request tanpa streaming berhasil:
curl -N "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"stream": true,
"messages": [
{"role": "user", "content": "Hitung dari satu sampai lima dengan perlahan."}
]
}'
Kondisi lulus:
| Check | Kondisi Lulus |
|---|---|
| Content type | Stream yang kompatibel dengan SSE, bukan respons JSON yang dibuffer kecuali memang diharapkan. |
| Event pertama | Klien menerima event inkremental sebelum respons penuh selesai. |
| Parser | Chunk Chat Completions tidak diparse sebagai event Responses, atau sebaliknya. |
| Event final | Klien melihat completion dan tidak meninggalkan koneksi terbuka. |
| Penanganan usage | Aplikasi Anda tahu apakah usage muncul di event final, respons penuh, atau pembacaan ulang dashboard. |
Untuk parsing stream yang lebih mendalam, bandingkan dengan test streaming SSE yang kompatibel dengan OpenAI yang sudah ada.
Tes 6: Pemanggilan Alat Atau Fungsi
Tool calling menambahkan risiko skema dan kapabilitas. Panduan function-calling OpenAI menjelaskan alur multi-langkah: kirim tools, terima tool call, jalankan kode aplikasi, kembalikan output tool, lalu terima respons model final. Migrasi base URL dapat gagal di salah satu batas tersebut bahkan ketika teks biasa berfungsi.
Jangan mulai dengan seluruh surface tool produksi Anda. Gunakan satu fungsi kecil:
{
"model": "your-current-flatkey-model-alias",
"messages": [
{"role": "user", "content": "Gunakan tool untuk pesanan A123."}
],
"tools": [
{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Mengembalikan status pesanan uji.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}
Jika ini gagal sementara chat biasa berfungsi, Anda tidak lagi sedang men-debug base URL. Anda sedang men-debug kapabilitas model, keluarga endpoint, keketatan skema, tool_choice, atau dukungan gateway untuk rute yang dipilih. Panduan kompatibilitas tool-calling yang diterbitkan mencakup daftar periksa provider yang lebih besar.
Pengujian 7: Usage, Kuota, Dan Rollback
Pengujian migrasi AI API base URL yang terakhir bersifat operasional. Respons yang dihasilkan tidak cukup jika bagian keuangan tidak dapat merekonsiliasinya, kuota tidak berperilaku seperti yang diharapkan, atau rollback memerlukan perubahan kode darurat.
Setelah satu smoke test berhasil, verifikasi:
| Area | Yang Perlu Diperiksa |
|---|---|
| Pembacaan usage | Permintaan muncul di usage, log, billing, atau tampilan dashboard Flatkey. |
| Field token | Field usage untuk prompt, completion, total, cached, atau spesifik rute tertangkap di tempat yang diharapkan aplikasi Anda. |
| Perilaku kuota | Key staging atau batas rendah yang dikontrol menghasilkan respons kuota/rate yang dapat dikenali. |
| Kebijakan retry | 429, 500, 502, 503, dan 504 mengikuti aturan backoff dan fallback Anda. |
| Rollback | Base URL lama, key lama, model lama, dan pemilik siap sebelum cutover. |
Gunakan file rollback yang cukup sederhana untuk dijalankan di bawah tekanan:
# active
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias
# rollback
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall
Jangan mengandalkan ingatan untuk rollback. Simpan konfigurasi sebelumnya, feature flag, perintah deploy, dan perintah verifikasi dalam tiket deployment yang sama dengan pengujian migrasi AI API base URL.
Paket Bukti Yang Perlu Disimpan
Untuk setiap lingkungan, simpan satu paket yang menjawab pertanyaan-pertanyaan ini:
| Pertanyaan | Bukti |
|---|---|
| Apa yang berubah? | Base URL lama, base URL baru, model lama, model baru, versi SDK. |
| Siapa yang memiliki tanggung jawab? | Pemilik engineering, pemilik operasi, persetujuan finance/procurement jika diperlukan. |
| Apa yang lulus? | Tujuh pengujian, stempel waktu, ID respons, rekaman usage, dan tangkapan layar rute. |
| Apa yang gagal? | Status code, body respons, hasil retry, dan keputusan. |
| Apa rollback-nya? | Konfigurasi sebelumnya, pemilik, perkiraan waktu untuk mengembalikan, dan smoke test setelah rollback. |
Inilah keuntungan praktis menjalankan pengujian migrasi AI API base URL sebelum cutover. Artefak ini berguna untuk tinjauan deployment, respons insiden, rekonsiliasi usage, dan bukti procurement.
Di Mana Flatkey Berperan
Flatkey dapat mengurangi penyebaran kompleksitas migrasi dengan memusatkan akses model, routing, billing, analitik usage, dan tinjauan operasional di balik satu key. Itu tidak menghapus kebutuhan untuk melakukan pengujian. Itu memberi tim satu titik kontrol tempat engineering, finance, dan operations dapat memeriksa bukti rute yang sama.
Sebelum bermigrasi, tinjau halaman model Flatkey dan harga yang live, pastikan base URL console saat ini, dan mulai dengan satu pengujian rute kecil. Jika Anda masih merencanakan cutover yang lebih luas, pasangkan panduan ini dengan panduan migrasi API yang kompatibel dengan OpenAI. Saat Anda siap menjalankan pengujian sendiri, dapatkan key dan buat permintaan pertama cukup kecil untuk diperiksa secara manual.
Pertanyaan yang sering diajukan
Apa itu pengujian migrasi AI API base URL?
Pengujian migrasi AI API base URL adalah pemeriksaan sebelum cutover yang membuktikan root API baru berfungsi untuk autentikasi, routing model, chat biasa, penggunaan SDK, streaming, tools, pembacaan usage, perilaku kuota, dan rollback.
Haruskah saya menguji curl atau SDK terlebih dahulu?
Uji curl terlebih dahulu. Curl membuktikan key, URL, path endpoint, dan alias model tanpa perilaku framework. Setelah itu, uji SDK dengan nilai yang sama.
Apakah base URL harus menyertakan /chat/completions?
Biasanya tidak. Berikan SDK root API seperti /v1, lalu biarkan SDK menambahkan endpoint. Gunakan endpoint lengkap hanya untuk permintaan curl langsung.
Mengapa streaming gagal saat chat biasa berfungsi?
Streaming dapat gagal karena rute melakukan buffering pada respons, parser klien mengharapkan bentuk event yang salah, middleware mengonsumsi stream, atau keluarga endpoint yang dipilih tidak mendukung bentuk stream yang Anda gunakan.
Bagaimana jika saya belum dapat menjalankan request Flatkey secara langsung?
Simpan cuplikan kode sebagai template, validasi dokumen publik dan konfigurasi console, dan jangan pindahkan traffic produksi sampai key yang nyata membuktikan tujuh pengujian migrasi AI API base URL di lingkungan Anda sendiri.
Kesimpulan
Mengubah base URL API AI adalah migrasi produksi, bukan sekadar mengedit string. Jalankan pengujian migrasi base URL API AI secara berurutan: autentikasi, katalog model, chat biasa, paritas SDK, streaming, tools, dan usage serta rollback. Saat ketujuhnya lulus, perubahan base URL menjadi cutover yang terkendali, bukan sesi debugging terlambat.
