Как создавать ИИ-приложения без привязки к одному поставщику

Поставщик-лок-ин в AI-приложениях обычно не возникает сразу. Он подкрадывается — тут прямой import openai, там — жестко прописанное имя модели, еще где-то — поле ответа, которое вы парсите, не проверив, возвращают ли другие провайдеры то же самое. Через шесть месяцев переход на другого провайдера оборачивается переписыванием половины бэкенда.

Четыре способа, как возникает привязка

Большинство разработчиков думают, что привязка — это «я использую SDK OpenAI». Это наименее опасный вид. Настоящие ловушки тоньше:

Цель — не устранить все виды привязки: часть из них — приемлемые компромиссы. Цель — осознавать, на какие из них вы соглашаетесь.

Используйте совместимую с OpenAI конечную точку как слой абстракции

Самый чистый способ избежать SDK-привязки — использовать единую конечную точку, совместимую с OpenAI, которая маршрутизирует запросы к нескольким провайдерам. Вы сохраняете SDK OpenAI, но бэкенд может быть любым.

CometAPI делает именно это — одна конечная точка, один ключ, 500+ моделей от OpenAI, Anthropic, Google, DeepSeek, xAI и других:

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, а не напрямую через API OpenAI или Anthropic. См. полный список моделей для каталога и цен.

Держите имена моделей вне бизнес-логики

Разбросанные по коду имена моделей — самый распространенный вид привязки. Решение — центральная конфигурация, читаемая из переменных окружения:

# 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")

Ваша бизнес-логика никогда напрямую не ссылается на имя модели:

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

Теперь ваша бизнес-логика работает с объектами AIResponse, а не с «сырыми» ответами API. Если провайдер изменит формат ответа, вы исправите это в одном месте.

Добавьте поддержку стриминга в обертку

Для чат-интерфейсов вам понадобится стриминг. Обертка обрабатывает его отдельным путем:

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)

Понимайте, какие параметры создают привязку

Некоторые параметры существуют только у конкретных провайдеров. Использовать их можно — просто осознавайте, что это осознанный выбор:

Если вы используете logprobs для оценки уверенности, вы привязаны к GPT для этой функции. Это разумный компромисс — просто задокументируйте это, чтобы следующий разработчик понимал, почему так.

Сделайте конечную точку провайдера настраиваемой

Жестко прописанный base_url="https://api.cometapi.com/v1" — это тоже форма привязки. Сделайте это переменной окружения:

# .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

Инициализация клиента из шага 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);}

Какая привязка приемлема

Не с каждой привязкой стоит бороться. Некоторые компромиссы имеют смысл:

• Использование OpenAI SDK — де-факто стандарт. Большинство провайдеров его поддерживают. Низкий риск привязки.
• Специфические для провайдера функции, которые действительно нужны — если вам нужны logprobs, используйте их. Изолируйте этот код, чтобы его было легко найти и заменить позже.
• Модели с дообучением — дообученная модель по определению привязана к одному провайдеру. Это ожидаемо.

Привязка, которой стоит избегать, — это случайная: имена моделей в бизнес-логике, парсинг «сырых» ответов, разбросанный по файлам, и ключи API, жестко прописанные в коде.

Что дальше

Теперь у вас есть слой абстракции, который держит детали провайдера вне вашей бизнес-логики. Последняя статья в серии рассказывает, что делать, когда что-то идет не так: как отлаживать неудачные генерации, интерпретировать коды ошибок и строить обработку ошибок, которая действительно сообщает, что сломалось.

Далее: How to Debug Failed AI API Generations

FAQ

В: В чем разница между SDK-привязкой и привязкой к модели?

SDK-привязка означает, что ваш код импортирует конкретную библиотеку и его придется менять при смене SDK. Привязка к модели означает, что имена моделей разбросаны по бизнес-логике. SDK-привязка менее опасна, потому что большинство провайдеров теперь поддерживают формат SDK OpenAI. Привязка к модели коварнее, потому что ее сложнее найти и исправить.

В: Если я использую CometAPI, разве это не обмен привязки к OpenAI на привязку к CometAPI?

Частично. Вы меняете привязку к конкретному провайдеру на прокси-слой. Плюсы: один ключ, одна конечная точка, простая смена моделей. Риск: если у CometAPI случится простой, все ваши провайдеры лягут одновременно. Смягчение риска уже есть в коде выше — AI_BASE_URL — это переменная окружения. Если нужно обойти CometAPI и обратиться к провайдеру напрямую, это изменение конфигурации, а не кода.

В: Могу ли я использовать расширенное мышление Claude или OpenAI reasoning_effort в рамках этого паттерна?

Да, передавайте их через **kwargs в call_model. Просто имейте в виду, что если вы маршрутизируете эту задачу на другую модель, эти параметры будут проигнорированы или вызовут ошибку. Задокументируйте, какие задачи используют специфические для провайдера функции, чтобы следующий разработчик понимал, почему.

В: Как обойти ограничение Claude на temperature до 1.0 при маршрутизации между Claude и GPT**?****

Держите temperature на уровне 1.0 или ниже, чтобы оставаться в безопасном диапазоне для обеих. Если вам нужна более высокая температура для творческих задач именно на GPT, маршрутизируйте эти задачи явно на GPT в MODEL_CONFIG, а не давайте им проваливаться в общий роутер.

В: Следует ли абстрагировать API генерации изображений и видео таким же образом?

Принципы те же — центральная конфигурация, нормализованный обертчик ответа, никакой зависимости бизнес-логики от полей провайдеров. У API изображений и видео больше структурных различий (асинхронность vs синхронность, разные наборы параметров), поэтому слой абстракции потребует больше усилий. Начните с текста, затем расширяйте паттерн, когда структура будет отлажена.

В: Что насчет различий в context window между моделями?

Это реальный риск при маршрутизации. У GPT-5.5 — контекст 1M токенов, у моделей Claude — до 200K, а Gemini 3.5 Flash поддерживает до 1M. Если вы направите длинный документ на модель с более коротким контекстом, вход будет молча обрезан. Добавьте проверку длины контекста перед маршрутизацией, если ваши задачи — с длинными входами, или всегда направляйте задачи с большим контекстом на конкретную модель в MODEL_CONFIG, а не давайте им попадать в модель по умолчанию.