Бір жеткізушіге тәуелді емес ЖИ қосымшаларын қалай жасауға болады

AI қолданбаларындағы вендорға тәуелділік көбіне бірден пайда болмайды. Ол білінбей енеді — мұнда тікелей import openai, анда бизнес-логикада қатты кодталған модель атауы, басқа провайдерлер дәл сол нәрсені қайтара ма, жоқ па тексермей талдайтын жауап өрісі. Алты айдан кейін провайдерді ауыстыру бэкендтің жартысын қайта жазуды білдіреді.

Lock-in қалай пайда болады: төрт жол

Көптеген әзірлеушілер lock-in дегенді "Мен OpenAI SDK қолданамын" деп түсінеді. Бұл — ең азы қауіпті түрі. Нағыз тұзақтар анағұрлым жасырын:

Мақсат — мұның бәрін толықтай жою емес — кейбірі қабылданатын ымыра. Мақсат — қайсысын саналы түрде қабылдап жатқаныңызды білу.

Абстракция қабаты ретінде OpenAI-мен үйлесімді endpoint қолданыңыз

SDK lock-in-нен сақтанудың ең таза жолы — бірнеше провайдерге бағыттайтын бірыңғай OpenAI-үйлесімді endpoint пайдалану. OpenAI SDK қалады, бірақ бэкенд кез келген провайдер бола алады.

CometAPI осылай істейді — бір endpoint, бір кілт, OpenAI, Anthropic, Google, DeepSeek, xAI және басқалардан 500+ модель:

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,)

GPT-тан Claude-қа, сосын Gemini-ге ауысу — бір жолдық өзгеріс:

# 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=[...])

Ескерту: gpt-5.4 және claude-sonnet-4-6 сияқты модель атаулары CometAPI платформасының идентификаторлары — олар тек https://api.cometapi.com/v1 арқылы жұмыс істейді, OpenAI немесе Anthropic API-лары арқылы тікелей емес. Толық каталог пен бағалар үшін модельдердің толық тізімін қараңыз.

Модель атауларын бизнес-логикадан тыс ұстаңыз

Кодқа шашылған модель атаулары — lock-in-нің ең жиі кездесетін түрі. Түзету — орталықтанған конфиг, ол орта айнымалыларынан оқиды:

# config.py — бір жерде модель тағайындауларын өзгертуimport 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"),}​# Іске қосылғанда тексеріңіз — түсініксіз API қателерінің орнына алдын ала сәтсіздікке тоқтаңызfor task, model in MODEL_CONFIG.items():    if not model:        raise ValueError(f"Model config for '{task}' is not set")

Сіздің бизнес-логикаңыз ешқашан модель атауын тікелей пайдаланбайды:

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

Қолданбаңыз бойынша суммаризация моделін ауыстыру үшін бір орта айнымалысын өзгерту жеткілікті. Ешқандай grep, ешқандай find-and-replace қажет емес.

Жауапты ораңыз — кодыңыз провайдерге тән өрістерге тәуелді болмасын

Әр провайдер аздап әртүрлі жауап пішімін қайтарады. Егер сіз шикі API жауаптарын кодтың әр жерінде талдайтын болсаңыз, сол провайдердің форматына байланып қаласыз.

Оны біріздендірілген dataclass-қа ораңыз:

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,    )

Енді сіздің бизнес-логикаңыз шикі API жауаптарымен емес, AIResponse объектілерімен жұмыс істейді. Егер провайдер өзінің жауап пішімін өзгертсе, оны бір жерде түзетесіз.

Ораушыға стриминг қолдауын қосыңыз

Чат интерфейстері үшін стриминг қажет болады. Ораушы оны жеке жол ретінде өңдейді:

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)

Қай параметрлер lock-in тудыратынын біліңіз

Кейбір параметрлер тек белгілі провайдерлерде ғана бар. Оларды қолдану — қалыпты, тек сіз саналы таңдау жасап жатқаныңызды біліп жүріңіз:

Егер сіз logprobs-ты сенімділік бағасы үшін қолдансаңыз, сол мүмкіндік бойынша GPT-қа байланып қаласыз. Бұл орынды ымыра — тек кейінгі әзірлеуші не үшін екенін түсінсін деп құжаттаңыз.

Провайдер endpoint-ін конфигурацияланатын етіңіз

base_url="https://api.cometapi.com/v1"-ді хардкодтау да lock-in-нің бір түрі. Оны орта айнымалысына шығарыңыз:

# .env — CometAPI пайдалануAI_BASE_URL=https://api.cometapi.com/v1AI_API_KEY=your_cometapi_key​# OpenAI-ға тікелей ауысу үшін екі жолды өзгертіңіз:# AI_BASE_URL=https://api.openai.com/v1# AI_API_KEY=your_openai_key

1-қадамдағы клиент инициализациясы бұл айнымалылардан оқиды. CometAPI мен тікелей провайдер арасында ауысу енді код емес, конфиг өзгерісі.

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);}

Қандай lock-in қабылданады

Барлық lock-in-мен күресу қажет емес. Кей ымыралар орынды:

• OpenAI SDK қолдану — Бұл де-факто стандарт. Көп провайдер оны қолдайды. Тәуекелі төмен lock-in.
• Шын мәнінде қажет провайдерге тән мүмкіндіктер — Егер logprobs керек болса, қолданыңыз. Бұл кодты оңай табылып, кейін ауыстырылатын етіп оқшаулаңыз.
• Fine-tuned модельдер — Fine-tuned модель табиғаты бойынша бір провайдерге байланған. Бұл күтілетін жайт.

Құнды болатыны — кездейсоқ lock-in-нен қашу: бизнес-логикаға шашылған модель атаулары, файлдарға таралған шикі жауапты талдау, кодқа хардкодталған API кілттері.

Келесі не

Енді сізде провайдер бөлшектерін бизнес-логикадан тыс ұстайтын абстракция қабаты бар. Осы серияның соңғы мақаласы ақаулар болғанда не болатынын қамтиды: сәтсіз генерацияларды debug ету, қате кодтарын түсіндіру және шынымен не бұзылғанын көрсететін қате өңдеуді құру.

Келесі: AI API генерациялары сәтсіз болғанда Debug қалай жасауға болады

Жиі қойылатын сұрақтар

Q: SDK lock-in мен модель lock-in арасында қандай айырмашылық бар?

SDK lock-in — кодыңыз белгілі бір кітапхананы импорттайды және SDK-ны ауыстырсаңыз, кодты өзгертуіңіз керек дегенді білдіреді. Модель lock-in — модель атаулары бизнес-логика бойына шашылған. SDK lock-in азырақ қауіпті, себебі көптеген провайдер қазір OpenAI SDK пішімін қолдайды. Модель lock-in әлдеқайда зәкірлі, өйткені оны табу мен түзету қиынырақ.

Q: CometAPI қолдансам, мен тек OpenAI lock-in-ін CometAPI lock-in-іне айырбастап жатқан жоқпын ба?

Жартылай. Сіз тікелей провайдерге тәуелділікті прокси қабатына айырбастайсыз. Артықшылығы: бір кілт, бір endpoint, модельдерді оңай ауыстыру. Тәуекел: CometAPI істен шықса, барлық провайдерлеріңіз бірге тоқтайды. Тәуекелді азайту жоғарыдағы кодта бар — AI_BASE_URL орта айнымалысы. Қажет болса, CometAPI-ды айналып өтіп провайдерге тікелей қоңырау шалу — конфиг өзгерісі, код өзгерісі емес.

Q: Claude-тың кеңейтілген ойлауы немесе OpenAI-дың reasoning_effort мүмкіндігін осы үлгімен қолдана аламын ба?

Иә, оларды **kwargs ретінде call_model-ға жіберіңіз. Тек сол тапсырманы басқа модельге бағыттасаңыз, бұл параметрлер еленбеуі немесе қате тудыруы мүмкін екенін біліңіз. Қай тапсырмалар провайдерге тән мүмкіндіктерді қолданатынын құжаттаңыз, келесі әзірлеуші не үшін екенін білсін.

Q: Claude-тың temperature шегі 1.0 болғанда, Claude пен GPT**?** арасында бағыттауды қалай басқарсам болады?

temperature-ді 1.0 немесе одан төмен ұстаңыз — бұл екеуі үшін де қауіпсіз ауқым. Егер GPT-де креативті тапсырмаларға жоғары температура қажет болса, ол тапсырмаларды MODEL_CONFIG ішінде GPT-ке нақты бағыттаңыз, ортақ рутерге қалдырмаңыз.

Q: Сурет пен видео генерациясы API-ларын да осылай абстракциялау керек пе?

Сол принциптер қолданылады — орталық конфиг, біріздендірілген жауап ораушысы, бизнес-логикада провайдерге тән өрістердің болмауы. Сурет пен видео API-ларында құрылымдық айырмашылықтар көбірек (асинхронды/синхронды, параметр жиындары әртүрлі), сондықтан абстракциялау көбірек еңбекті талап етеді. Алдымен мәтіннен бастаңыз, құрылым дәлелденген соң үлгіні кеңейтіңіз.

Q: Модельдер арасындағы context window айырмашылықтары ше?

Маршрутизациялау кезінде бұл — нақты тәуекел. GPT-5.5 1M токендік context window ұсынады, Claude модельдері 200K-ке дейін, ал Gemini 3.5 Flash 1M-ге дейін қолдайды. Ұзын құжат тапсырмасын контексті қысқа модельге бағыттасаңыз, енгізу үнсіз қысқартылуы мүмкін. Тапсырмаларыңыз ұзын енгізулерді қамтыса, бағыттамас бұрын контекст ұзындығын тексеруді қосыңыз — немесе ұзын контексті қажет тапсырмаларды әрдайым MODEL_CONFIG ішінде нақты бір модельге бағыттаңыз, әдепкіге түсірмей.