Cara membina aplikasi AI yang tidak terikat kepada satu penyedia

Penguncian vendor dalam aplikasi AI biasanya tidak berlaku serta-merta. Ia meresap sedikit demi sedikit — satu import openai terus di sini, satu nama model dikeraskan (hardcoded) di sana, satu medan respons yang anda huraikan tanpa menyemak sama ada pembekal lain memulangkan perkara yang sama. Enam bulan kemudian, menukar pembekal bermaksud menulis semula separuh backend anda.

Empat cara penguncian berlaku

Kebanyakan pembangun berfikir penguncian bermaksud “Saya menggunakan OpenAI SDK.” Itu jenis yang paling kurang berisiko. Perangkap sebenar lebih halus:

Matlamatnya bukan untuk menghapuskan semuanya — sesetengahnya ialah pertukaran yang boleh diterima. Matlamatnya ialah mengetahui yang mana satu anda sanggupi ambil.

Guna endpoint serasi OpenAI sebagai lapisan abstraksi anda

Cara paling bersih untuk mengelakkan penguncian SDK ialah menggunakan satu endpoint serasi OpenAI yang merutekan ke berbilang pembekal. Anda kekalkan OpenAI SDK, tetapi backend boleh daripada mana-mana pembekal.

CometAPI melakukannya — satu endpoint, satu kunci, 500+ model merentasi OpenAI, Anthropic, Google, DeepSeek, xAI dan lain-lain:

import osfrom openai import OpenAIfrom dotenv import load_dotenv​load_dotenv()​api_key = os.environ.get("AI_API_KEY")if not api_key:    raise ValueError("AI_API_KEY environment variable is not set")​client = OpenAI(    base_url=os.environ.get("AI_BASE_URL", "https://api.cometapi.com/v1"),    api_key=api_key,)

Menukar daripada GPT ke Claude ke Gemini hanyalah perubahan satu baris:

# Beforeresponse = client.chat.completions.create(model="gpt-5.4", messages=[...])​# After — same code, different modelresponse = client.chat.completions.create(model="claude-sonnet-4-6", messages=[...])

Nota: Nama model seperti gpt-5.4 dan claude-sonnet-4-6 ialah pengecam platform CometAPI — ia berfungsi melalui https://api.cometapi.com/v1 sahaja, bukan terus melalui API OpenAI atau Anthropic. Lihat senarai model penuh untuk katalog dan harga lengkap.

Jauhkan nama model daripada logik perniagaan anda

Nama model yang bertaburan dalam kod anda ialah bentuk penguncian yang paling biasa. Penyelesaiannya ialah konfigurasi pusat yang membaca daripada pemboleh ubah persekitaran:

# config.py — one place to change model assignmentsimport os​MODEL_CONFIG = {    "summarize": os.environ.get("MODEL_SUMMARIZE", "claude-opus-4-7"),    "code":      os.environ.get("MODEL_CODE",      "gpt-5.4"),    "classify":  os.environ.get("MODEL_CLASSIFY",  "claude-haiku-4-5"),    "chat":      os.environ.get("MODEL_CHAT",       "gpt-5.4-mini"),}​# Validate at startup — fail fast rather than getting mysterious API errorsfor task, model in MODEL_CONFIG.items():    if not model:        raise ValueError(f"Model config for '{task}' is not set")

Logik perniagaan anda tidak pernah merujuk nama model secara langsung:

from config import MODEL_CONFIG​def summarize(text: str) -> str:    response = client.chat.completions.create(        model=MODEL_CONFIG["summarize"],        messages=[{"role": "user", "content": f"Summarize: {text}"}],        max_tokens=300  # move to config in production    )    return response.choices[0].message.content

Untuk menukar model pemeringkasan di seluruh aplikasi anda, ubah satu pemboleh ubah persekitaran. Tiada grep, tiada cari-dan-ganti.

Bungkus respons supaya kod anda tidak bergantung pada medan khusus pembekal

Pembekal berbeza memulangkan bentuk respons yang sedikit berbeza. Jika anda menghurai respons API mentah di seluruh pangkalan kod anda, anda terkunci kepada format pembekal tersebut.

Bungkuskannya ke dalam dataclass yang dinormalkan:

from dataclasses import dataclassfrom typing import Optionalfrom openai import OpenAI, APIStatusError, APIConnectionError, APITimeoutErrorfrom openai.types.chat import ChatCompletionimport logging​@dataclassclass AIResponse:    content: str    model: str    input_tokens: int    output_tokens: int​def call_model(task: str, messages: list, **kwargs) -> AIResponse:    """    Single entry point for all LLM calls.    Returns a normalized AIResponse regardless of which model handled it.    Raises on 4xx (client errors). Logs and re-raises on 5xx/network errors.    """    model = MODEL_CONFIG.get(task, "gpt-5.4-mini")    if not model:        raise ValueError(f"No model configured for task '{task}'")​    try:        response: ChatCompletion = client.chat.completions.create(            model=model,            messages=messages,            **kwargs        )    except APIStatusError as e:        logging.error(f"API error for task={task} model={model}: {e.status_code} {e.message}")        raise    except (APIConnectionError, APITimeoutError) as e:        logging.error(f"Network error for task={task} model={model}: {e}")        raise​    # content is None when the model triggers a tool call instead of returning text    content = response.choices[0].message.content or ""​    # usage is None in streaming mode — default to 0 if not available    usage = response.usage    input_tokens = usage.prompt_tokens if usage else 0    output_tokens = usage.completion_tokens if usage else 0​    logging.info(        f"task={task} model={model} "        f"input_tokens={input_tokens} output_tokens={output_tokens}"    )​    return AIResponse(        content=content,        model=response.model,        input_tokens=input_tokens,        output_tokens=output_tokens,    )

Kini logik perniagaan anda berfungsi dengan objek AIResponse, bukan respons API mentah. Jika pembekal mengubah format respons mereka, anda membetulkannya di satu tempat.

Tambah sokongan penstriman pada pembungkus

Untuk antara muka sembang, anda akan mahukan penstriman. Pembungkus menanganinya sebagai laluan berasingan:

from typing import Iterator​def stream_model(task: str, messages: list, **kwargs) -> Iterator[str]:    """    Stream tokens from the routed model.    Note: streaming doesn't return usage data.    Fallback is not supported in streaming mode — you've already    started yielding tokens before you know if the full request succeeds.    """    model = MODEL_CONFIG.get(task, "gpt-5.4-mini")    if not model:        raise ValueError(f"No model configured for task '{task}'")​    stream = client.chat.completions.create(        model=model,        messages=messages,        stream=True,        **kwargs    )​    for chunk in stream:        delta = chunk.choices[0].delta.content        if delta:            yield delta​# Usagefor token in stream_model("chat", [{"role": "user", "content": "Hello"}]):    print(token, end="", flush=True)

Ketahui parameter mana yang mewujudkan penguncian

Sesetengah parameter hanya wujud pada pembekal tertentu. Menggunakannya tidak mengapa — cuma sedari bahawa anda membuat pilihan yang disengajakan:

Jika anda menggunakan logprobs untuk pemarkahan keyakinan, anda terkunci kepada GPT untuk ciri tersebut. Itu pertukaran yang munasabah — cuma dokumentasikan supaya pembangun seterusnya tahu sebabnya.

Jadikan endpoint pembekal boleh dikonfigur

Mengkeras kod base_url="https://api.cometapi.com/v1" masih merupakan satu bentuk penguncian. Jadikannya pemboleh ubah persekitaran:

# .env — using CometAPIAI_BASE_URL=https://api.cometapi.com/v1AI_API_KEY=your_cometapi_key​# To switch to OpenAI directly, change two lines:# AI_BASE_URL=https://api.openai.com/v1# AI_API_KEY=your_openai_key

Inisialisasi klien daripada Langkah 1 sudah membaca daripada pemboleh ubah ini. Bertukar antara CometAPI dan sambungan pembekal terus kini hanya perubahan konfigurasi, bukan perubahan kod.

Versi Node.js

import OpenAI from 'openai';​const apiKey = process.env.AI_API_KEY;if (!apiKey) throw new Error('AI_API_KEY is not set');​const client = new OpenAI({  baseURL: process.env.AI_BASE_URL ?? 'https://api.cometapi.com/v1',  apiKey,});​// Model IDs are CometAPI platform identifiers — see cometapi.com/modelsconst MODEL_CONFIG = {  summarize: process.env.MODEL_SUMMARIZE ?? 'claude-opus-4-7',  code:      process.env.MODEL_CODE      ?? 'gpt-5.4',  classify:  process.env.MODEL_CLASSIFY  ?? 'claude-haiku-4-5',  chat:      process.env.MODEL_CHAT      ?? 'gpt-5.4-mini',};​// Validate at startupfor (const [task, model] of Object.entries(MODEL_CONFIG)) {  if (!model) throw new Error(`Model config for '${task}' is not set`);}​/** * Single entry point for all LLM calls. * Returns normalized response. Raises on 4xx, logs and re-raises on 5xx/network. */async function callModel(task, messages, options = {}) {  const model = MODEL_CONFIG[task] ?? 'gpt-5.4-mini';​  let response;  try {    response = await client.chat.completions.create({      model,      messages,      ...options,    });  } catch (err) {    // Don't swallow errors — log and re-raise    console.error(`API error task=${task} model=${model}:`, err.message);    throw err;  }​  // content is null when model triggers a tool call  const content = response.choices[0].message.content ?? '';​  // usage may be absent in some configurations  const inputTokens  = response.usage?.prompt_tokens     ?? 0;  const outputTokens = response.usage?.completion_tokens ?? 0;​  console.log(`task=${task} model=${model} input=${inputTokens} output=${outputTokens}`);​  return { content, model: response.model, inputTokens, outputTokens };}​/** * Stream tokens from the routed model. * Usage data is not available in streaming mode. */async function* streamModel(task, messages, options = {}) {  const model = MODEL_CONFIG[task] ?? 'gpt-5.4-mini';​  const stream = await client.chat.completions.create({    model,    messages,    stream: true,    ...options,  });​  for await (const chunk of stream) {    const delta = chunk.choices[0]?.delta?.content;    if (delta) yield delta;  }}​// Usage — blockingconst result = await callModel('classify', [  { role: 'user', content: 'Positive or negative? "Loved it!"' }]);console.log(result.content);​// Usage — streamingfor await (const token of streamModel('chat', [  { role: 'user', content: 'Hello' }])) {  process.stdout.write(token);}

Penguncian yang boleh diterima

Tidak semua penguncian wajar dilawan. Sesetengah pertukaran masuk akal:

• Menggunakan OpenAI SDK — Ia standard de facto. Kebanyakan pembekal menyokongnya. Penguncian berisiko rendah.
• Ciri khusus pembekal yang anda benar-benar perlukan — Jika anda perlukan logprobs, gunakannya. Asingkan kod itu supaya mudah dicari dan diganti kemudian.
• Model ditala halus (fine-tuned) — Model ditala halus secara asasnya terikat pada satu pembekal. Itu dijangka.

Penguncian yang patut dielakkan ialah jenis tidak sengaja — nama model dalam logik perniagaan, penghuraian respons mentah merata fail, kunci API dikeraskan dalam sumber.

Langkah seterusnya

Kini anda mempunyai lapisan abstraksi yang mengekalkan butiran pembekal di luar logik perniagaan anda. Artikel terakhir dalam siri ini membincangkan apa yang berlaku apabila sesuatu tidak kena: cara menyahpepijat penjanaan yang gagal, mentafsir kod ralat, dan membina pengendalian ralat yang benar-benar memberitahu anda apa yang rosak.

Seterusnya: Cara Menyahpepijat Penjanaan API AI yang Gagal

Soalan Lazim

Q: Apakah perbezaan antara penguncian SDK dan penguncian model?

Penguncian SDK bermaksud kod anda mengimport pustaka tertentu dan perlu diubah jika anda menukar SDK. Penguncian model bermaksud nama model bertaburan dalam logik perniagaan anda. Penguncian SDK kurang berbahaya kerana kebanyakan pembekal kini menyokong format OpenAI SDK. Penguncian model lebih licik kerana sukar dikesan dan diperbaiki.

Q: Jika saya menggunakan CometAPI, adakah saya hanya menukar penguncian OpenAI kepada penguncian CometAPI?

Sebahagiannya. Anda menukar penguncian pembekal terus kepada lapisan proksi. Kelebihannya: satu kunci, satu endpoint, pertukaran model yang mudah. Risikonya: jika CometAPI terhenti, semua pembekal anda turut terjejas. Mitigasinya sudah ada dalam kod di atas — AI_BASE_URL ialah pemboleh ubah persekitaran. Jika anda perlu memintas CometAPI dan menghubungi pembekal secara langsung, itu perubahan konfigurasi, bukan perubahan kod.

Q: Bolehkah saya menggunakan extended thinking Claude atau OpenAI's reasoning_effort melalui corak ini?

Ya, hantarkan sebagai **kwargs kepada call_model. Sedari bahawa jika anda merutekan tugas itu ke model lain, parameter tersebut akan diabaikan atau menyebabkan ralat. Dokumentasikan tugas mana yang menggunakan ciri khusus pembekal supaya pembangun seterusnya tahu sebabnya.

Q: Bagaimana saya mengendalikan had temperature Claude pada 1.0 apabila merutek antara Claude dan GPT**?****

Kekalkan temperature pada atau di bawah 1.0 untuk kekal dalam julat selamat bagi kedua-duanya. Jika anda memerlukan temperature lebih tinggi untuk tugas kreatif pada GPT secara khusus, rute tugas tersebut secara jelas ke GPT dalam MODEL_CONFIG dan jangan biarkan ia melalui penghala umum.

Q: Patutkah saya mengabstrakkan API penjanaan imej dan video dengan cara yang sama?

Prinsip yang sama terpakai — konfigurasi pusat, pembungkus respons dinormalkan, tiada medan khusus pembekal dalam logik perniagaan. API imej dan video mempunyai lebih banyak perbezaan struktur (asinkron vs segerak, set parameter berbeza) jadi lapisan abstraksi memerlukan lebih banyak kerja. Mulakan dengan teks, kemudian kembangkan corak apabila struktur telah terbukti.

Q: Bagaimana dengan perbezaan context window antara model?

Ini risiko sebenar apabila merutekan. GPT-5.5 mempunyai context window 1M token, model Claude menyokong sehingga 200K, dan Gemini 3.5 Flash menyokong sehingga 1M. Jika anda merutekan tugas dokumen panjang ke model dengan context window yang lebih pendek, input akan dipotong secara senyap. Tambahkan semakan panjang konteks sebelum merutekan jika tugas anda melibatkan input panjang — atau sentiasa rute tugas berkonteks panjang ke model khusus dalam MODEL_CONFIG dan jangan biarkan ia jatuh ke lalai.