Migrasi SDK Multi-Model: Pertahankan Klien OpenAI untuk Claude, Gemini, dan DeepSeek

Migrasi SDK multi-model tidak boleh dimulai dengan mengganti setiap library klien di aplikasi Anda. Jika kode produksi Anda sudah menggunakan OpenAI Python atau Node SDK untuk chat completions, langkah awal yang lebih aman adalah menjaga permukaan klien itu tetap stabil, memindahkan pilihan provider ke dalam konfigurasi, dan membuktikan perilaku Claude, Gemini, dan DeepSeek melalui rute yang kompatibel sebelum Anda memperluas traffic.

Flatkey dibuat untuk tim yang menginginkan satu key, lapisan routing yang kompatibel dengan OpenAI, akses model lintas provider, serta tinjauan penggunaan dan penagihan di satu tempat. Ini membuatnya berguna untuk migrasi SDK multi-model, tetapi tidak menghilangkan kebutuhan untuk menguji family endpoint, alias model, streaming, panggilan tool, dan catatan penggunaan. Perlakukan setiap contoh kode di sini sebagai template sampai Anda memvalidasinya dengan Flatkey key Anda sendiri dan katalog model saat ini.

Tujuan praktisnya sederhana: pertahankan objek request yang sudah dikenal aplikasi Anda, isolasi beberapa nilai yang harus berubah, dan bangun paket pembuktian sebelum cutover.

Matrix Keputusan Migrasi SDK Multi-Model

Gunakan matrix ini sebelum Anda mengubah kode. Ini memisahkan apa yang dapat tetap stabil dari apa yang harus dibuat dapat dikonfigurasi.

Inilah disiplin inti migrasi SDK multi-model: jangan mencampur penggantian library, migrasi prompt, evaluasi provider, validasi penagihan, dan rollout produksi ke dalam satu deploy.

Apa Kata Dokumen Resmi Tentang Kompatibilitas

SDK OpenAI sudah mendukung pola yang Anda butuhkan. README OpenAI Python saat ini mendokumentasikan klien OpenAI dan opsi base_url, dan README Node mendokumentasikan klien OpenAI standar dan chat completions. Referensi API OpenAI mengatakan Chat Completions membuat respons model untuk sebuah percakapan, mendukung streaming, dan mengembalikan objek chat completion atau potongan stream.

Jika Anda memisahkan rollout berdasarkan runtime, pasangkan checklist ini dengan panduan base URL kustom OpenAI Python SDK dan panduan base URL OpenAI Node SDK. Jika keputusan pertama adalah routing provider alih-alih setup klien, gunakan panduan routing API Claude vs GPT sebelum Anda memilih workload pengujian.

Kompatibilitas provider berbeda:

Pelajaran pentingnya adalah bahwa "OpenAI-compatible" biasanya berarti klien dapat mengirim permintaan yang berbentuk OpenAI. Itu tidak berarti setiap parameter, skema tool, kontrol penalaran, input media, atau field usage berperilaku identik di semua penyedia.

Langkah 1: Bekukan Batas Klien

Mulailah migrasi SDK multi-model dengan menempatkan klien OpenAI di belakang satu factory lokal. Factory tersebut harus menjadi satu-satunya tempat yang mengetahui key, base URL, timeout, dan alias model.

import os
from openai import OpenAI


def make_llm_client() -> OpenAI:
    return OpenAI(
        api_key=os.environ["FLATKEY_API_KEY"],
        base_url=os.getenv("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
        timeout=float(os.getenv("LLM_TIMEOUT_SECONDS", "60")),
        max_retries=int(os.getenv("LLM_MAX_RETRIES", "2")),
    )


client = make_llm_client()

completion = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[
        {"role": "system", "content": "Anda menjawab dengan catatan implementasi singkat."},
        {"role": "user", "content": "Balas tepat dengan: migration probe ok"},
    ],
)

print(completion.choices[0].message.content)

Untuk Node:

import OpenAI from "openai";

export function makeLlmClient() {
  return new OpenAI({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
    timeout: Number(process.env.LLM_TIMEOUT_MS ?? 60000),
    maxRetries: Number(process.env.LLM_MAX_RETRIES ?? 2),
  });
}

const client = makeLlmClient();

const completion = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL,
  messages: [
    { role: "system", content: "Anda menjawab dengan catatan implementasi singkat." },
    { role: "user", content: "Balas tepat dengan: migration probe ok" },
  ],
});

console.log(completion.choices[0].message.content);

Aplikasi harus memanggil make_llm_client() atau makeLlmClient(), bukan membuat klien di berbagai controller, worker, dan skrip. Batas tunggal itulah yang membuat migrasi SDK multi-model tetap dapat dibalik.

Langkah 2: Bangun Peta Model dan Endpoint

Jangan arahkan setiap workload ke satu nama model baru. Mulailah dengan peta yang menyebutkan workload, keluarga endpoint, penyedia saat ini, penyedia target, dan nilai rollback.

Halaman model Flatkey berguna di sini karena menampilkan jenis endpoint. Jika sebuah model tercantum di bawah keluarga endpoint native, jangan anggap model itu tersedia melalui jalur chat OpenAI sampai katalog akun dan smoke test Anda membuktikannya.

Langkah 3: Jalankan Smoke Test Empat Penyedia

Smoke test migrasi SDK multi-model yang minimal dan berguna memiliki empat baris penyedia dan prompt yang sama. Jaga prompt tetap biasa saja agar gaya respons tidak menutupi kegagalan transport.

Simpan body request mentah, header yang sudah disamarkan, body respons, status HTTP, alias model, request ID jika dikembalikan, dan entri usage di dashboard. Jika ada penyedia yang memerlukan parameter berbeda, pindahkan parameter itu ke profile penyedia alih-alih menyebarkan cabang if provider == ke seluruh aplikasi Anda.

Langkah 4: Uji Streaming dan Panggilan Tool Secara Terpisah

Completion biasa hanya membuktikan jalur dengan risiko terendah. Streaming dan panggilan tool adalah kontrak yang terpisah.

Untuk streaming, simpan:

Untuk tools, uji skema kecil terlebih dahulu:

{
  "type": "function",
  "function": {
    "name": "lookup_order_status",
    "description": "Mengembalikan status pesanan uji.",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" }
      },
      "required": ["order_id"]
    }
  }
}

Jangan gunakan skema tool produksi terbesar Anda sebagai bukti pertama. Dokumentasi kompatibilitas Anthropic, misalnya, menyoroti batasan terkait kompatibilitas OpenAI dan merekomendasikan API Claude native untuk set fitur penuh Claude. Itulah jenis detail yang seharusnya ditangkap oleh checklist migrasi SDK multi-model sebelum peluncuran.

Langkah 5: Jaga Profil Penyedia Tetap Kecil

Profil penyedia seharusnya menjelaskan perbedaan, bukan memiliki logika bisnis.

{
  "support_chat": {
    "base_url_env": "FLATKEY_BASE_URL",
    "model_env": "FLATKEY_SUPPORT_CHAT_MODEL",
    "endpoint_family": "openai_chat_completions",
    "stream": true,
    "tools": "basic",
    "fallback_alias": "support_chat_previous"
  },
  "analysis_fast": {
    "base_url_env": "FLATKEY_BASE_URL",
    "model_env": "FLATKEY_ANALYSIS_FAST_MODEL",
    "endpoint_family": "openai_chat_completions",
    "stream": false,
    "tools": "none",
    "fallback_alias": "analysis_fast_previous"
  }
}

Jauhkan fitur native penyedia dari jalur klien OpenAI bersama, kecuali Anda memiliki pengujian untuk setiap penyedia target. Jika kutipan Claude, perilaku media khusus Gemini, kontrol thinking DeepSeek, atau endpoint batch native penyedia diperlukan, buat adapter native bernama dan tetap gunakan jalur yang kompatibel dengan OpenAI untuk beban kerja yang benar-benar cocok dengannya.

Langkah 6: Buktikan Penagihan dan Rollback

Migrasi yang mengembalikan teks tetapi kehilangan bukti penagihan belum selesai. Sebelum meningkatkan trafik, simpan:

Di sinilah penagihan terpadu dan tinjauan usage Flatkey menjadi penting. Tujuannya bukan hanya akses ke lebih banyak model. Tujuan migrasi SDK multi-model adalah akses yang dapat diperiksa oleh produk, operasi, dan keuangan setelah trafik berpindah.

Alur Cutover untuk Migrasi SDK Multi-Model

Gunakan urutan ini untuk irisan produksi pertama:

1. Pilih satu beban kerja berisiko rendah dengan klien OpenAI SDK yang sudah ada.
2. Tambahkan factory klien dan variabel lingkungan tanpa mengubah penyedia saat ini.
3. Buktikan model saat ini melalui factory baru.
4. Buktikan satu target Claude, Gemini, atau DeepSeek dengan completion biasa.
5. Buktikan streaming dan tools hanya jika beban kerja itu menggunakannya.
6. Verifikasi usage, penagihan, penanganan error, dan rollback.
7. Arahkan sebagian kecil trafik ke alias model baru.
8. Tinjau kegagalan berdasarkan penyedia dan family endpoint sebelum menambahkan beban kerja berikutnya.

Jika beban kerja pertama membutuhkan fitur native penyedia, pilih beban kerja berbeda untuk migrasi SDK multi-model pertama. Irisan pertama harus membuktikan pola migrasi, bukan setiap kemampuan model.

FAQ

Bisakah saya menggunakan satu klien OpenAI SDK untuk Claude, Gemini, dan DeepSeek?

Anda sering kali bisa mempertahankan klien OpenAI SDK untuk rute yang kompatibel dengan OpenAI, tetapi Anda tetap memerlukan pengujian khusus penyedia. Google dan DeepSeek mendokumentasikan akses yang kompatibel dengan OpenAI. Anthropic mendokumentasikan lapisan kompatibilitas OpenAI SDK, tetapi menyatakan bahwa itu terutama untuk pengujian dan perbandingan, bukan pilihan produksi jangka panjang untuk sebagian besar kasus penggunaan.

Haruskah saya memigrasikan trafik Responses API dengan cara yang sama?

Hanya jika gateway target dan model target secara eksplisit mendukung family endpoint yang Anda gunakan. Chat Completions dan Responses bukan kontrak yang sama. Mulailah dengan family endpoint yang sudah digunakan aplikasi Anda, lalu buat rencana pengujian terpisah untuk Responses.

Apa kesalahan paling umum dalam migrasi SDK multi-model?

Kesalahan paling umum adalah memperlakukan perubahan base URL sebagai seluruh migrasi. Migrasi SDK multi-model yang sesungguhnya juga memverifikasi nama model, family endpoint, streaming, tools, usage, kuota, penanganan error, dan rollback.

Kapan saya harus mempertahankan SDK native penyedia?

Pertahankan SDK native penyedia ketika beban kerja Anda bergantung pada fitur khusus penyedia yang tidak dicakup oleh lapisan kompatibilitas. Fitur native Claude, jalur media khusus Gemini, atau kontrol penalaran khusus DeepSeek mungkin memerlukan adapter terpisah.

Daftar Periksa Akhir

Sebelum Anda menyatakan migrasi selesai, pastikan Anda telah:

Migrasi SDK multi-model paling baik dilakukan saat prosesnya tidak rumit: satu beban kerja kecil, satu batas klien, satu peta model, dan bukti untuk setiap penyedia yang Anda tambahkan. Saat Anda siap menjalankan pengujian tersebut melalui rute terpadu, dapatkan kunci Flatkey dan mulai dengan jalur chat yang kompatibel dengan OpenAI berisiko rendah.