NormaHub

И это только начало.

Через некоторое время появляются отдельные кабинеты, разные форматы API, различные лимиты, непохожие ошибки и загадочные списания. Вроде бы каждый сервис по отдельности работает нормально, но вместе получается небольшой зоопарк.

Я попробовал посмотреть на эту проблему со стороны разработчика и пришёл к выводу: единый API-ключ удобен, но сам по себе не решает главные проблемы работы с нейросетями.

Что вообще даёт единый ключ

Если несколько моделей доступны через один API-шлюз, приложение может обращаться к ним примерно в одном стиле:

```python
from openai import OpenAI
client = OpenAI(
api_key="API_KEY",
base_url="https://example.com/v1",
)
response = client.chat.completions.create(
model="MODEL_ID",
messages=[
{
"role": "user",
"content": "Сделай краткое резюме текста",
}
],
)
print(response.choices[0].message.content)```

Чтобы выбрать другую модель, достаточно поменять `model`.

На практике это полезно по нескольким причинам:

- не нужно хранить ключи разных сервисов в одном проекте;

- проще менять модель;

- можно использовать привычный SDK;

- проще централизованно отслеживать расходы;

- меньше отдельных кабинетов и настроек;

- легче подключать AI к существующим скриптам.

Я использовал для таких экспериментов NormaHub. Проект предоставляет единый API-доступ к нескольким AI-моделям через совместимый с OpenAI интерфейс. Для базовых запросов это действительно удобнее, чем держать отдельную интеграцию под каждого провайдера.

Но дальше начинаются нюансы.

Проблема № 1. Одинаковый API не означает одинаковые модели

Самая частая ошибка — считать, что если у моделей одинаковый формат запроса, то и ведут они себя одинаково.

Нет!!!

У моделей могут различаться:

- качество ответа;

- скорость;

- размер контекста;

- максимальная длина результата;

- поддержка изображений;

- поддержка tools;

- structured output;

- streaming;

- правила тарификации;

- допустимые параметры.

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

```json
{
"model": "MODEL_ID",
"messages": [
{
"role": "user",
"content": "Привет"
}
]
}
```

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

Одна модель примет `response_format`, другая вернёт ошибку. Одна умеет работать с изображением, другая принимает только текст. Одна поддерживает streaming, у другой он недоступен для выбранного маршрута.

Поэтому в приложении недостаточно хранить только адрес API и ключ. Желательно иметь ещё и описание возможностей модели:

```python
MODEL_CAPABILITIES = {
"model-a": {
"streaming": True,
"tools": True,
"vision": False,
},
"model-b": {
"streaming": False,
"tools": False,
"vision": True,
},
}
```

Это немного скучнее, чем просто заменить строку `model`, зато приложение не будет пытаться отправить модели функцию, которую она не умеет выполнять.

Проблема № 2. Ошибка не всегда означает одно и то же

У AI API есть привычные HTTP-статусы:

- 400 — плохой запрос;

- 401 — проблема с ключом;

- 403 — нет доступа;

- 429 — превышен лимит;

- 500 или 503 — временная ошибка сервера.

Но одного статуса недостаточно. Нужно смотреть код ошибки и сообщение.

Например, 429 может означать:

- слишком много запросов;

- превышение бюджета;

- временное ограничение;

- слишком много попыток с неверным ключом.

Повторять все ошибки автоматически нельзя.

Если запрос вернул 400, повтор с тем же телом не поможет. Если вернулся 401, нужно проверять ключ. Если закончился баланс, бессмысленно отправлять тот же запрос ещё десять раз.

У себя я использую простое правило:

```text
400, 401, 402, 403, 413 — сначала исправить причину
429 — повторять только при временном rate limit
5xx — ограниченное число повторов с задержкой
```

Важно также ограничивать общее время операции. Иначе один зависший запрос может занять больше времени, чем сама полезная работа приложения.

Проблема № 3. Автоматический retry может создать дубликат

С обычным GET-запросом всё относительно понятно: если соединение оборвалось, его часто можно повторить.

С генерацией текста сложнее.

Представим:

1. приложение отправило запрос;

2. модель начала возвращать ответ;

3. клиент получил половину текста;

4. соединение оборвалось;

5. приложение решило повторить запрос.

В результате можно получить два ответа и два списания. Для пользователя это может выглядеть как один запрос, а для системы - как две операции.

Особенно осторожно нужно обращаться со streaming. Если ответ уже начал поступать, нельзя бездумно считать обрыв признаком того, что сервер ничего не сделал.

Перед повтором полезно сохранять:

- идентификатор запроса;

- HTTP-статус;

- код ошибки;

- время начала;

- количество уже полученных данных;

- модель;

- число попыток.

У разных API эти возможности реализованы по-разному. Единый API упрощает подключение, но не отменяет необходимость продумать идемпотентность и обработку обрывов.

Проблема № 4. Контекст постепенно съедает бюджет

В чате пользователь видит короткий вопрос. Модель при этом может получить:

- системные инструкции;

- всю историю диалога;

- результаты предыдущих tool calls;

- документы;

- описание доступных функций;

- текущий запрос.

В итоге пользователь написал пару строк, а модель обработала десятки тысяч токенов.

Если история передаётся целиком при каждом запросе, стоимость и время ответа постепенно растут.

Упрощённая формула обычно выглядит так:

Стоимость =
входные токены × цена входа
+
выходные токены × цена выхода

Но реальная стоимость пользовательской операции может включать несколько запросов:

Стоимость операции =
первый запрос
+ вызовы инструментов
+ повтор после ошибки
+ финальный ответ

Поэтому смотреть только на цену одной генерации недостаточно. Полезно отдельно учитывать:

- входные токены;

- выходные токены;

- количество запросов;

- retry;

- размер контекста;

- стоимость вспомогательных операций.

В NormaHub мне удобен именно централизованный учёт: можно смотреть использование и стоимость в одном месте. Но это решает только проблему наблюдения. Само приложение всё равно должно ограничивать контекст и не отправлять модели каждый раз весь архив переписки.

Проблема № 5. Ключ может утечь даже при едином API

Один ключ вместо пяти — это удобнее. Но если он утечёт, проблема станет даже заметнее: одним ключом можно будет получить доступ сразу к нескольким моделям.

Ключ не должен находиться:

- в JavaScript-коде браузера;

- в мобильном приложении;

- в публичном GitHub-репозитории;

- в Docker-образе;

- в логах;

- в скриншотах;

- в сообщениях с примером кода.

Минимальный вариант для Python:

```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AI_API_KEY"],
base_url=os.environ["AI_BASE_URL"],
)
```

Для команды лучше использовать:

- отдельный ключ для разработки;

- отдельный ключ для staging;

- отдельный ключ для production;

- лимиты расходов;

- ротацию ключей;

- ограниченный доступ к журналам;

- мониторинг необычной активности.

Единый баланс и единый кабинет помогают видеть расходы, но не заменяют базовую гигиену секретов.

Проблема № 6. Gateway тоже становится зависимостью

Единый API уменьшает зависимость от отдельных SDK, но добавляет зависимость от самого gateway.

Это нормальный архитектурный компромисс.

Перед подключением стоит выяснить:

- какие модели доступны;

- как часто обновляется каталог;

- какие endpoint поддерживаются;

- что происходит при недоступности модели;

- где хранятся запросы;

- сколько времени сохраняется история;

- есть ли лимиты;

- есть ли SLA;

- как работает поддержка;

- можно ли экспортировать данные и перейти на другой сервис.

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

Лучше сделать небольшой собственный слой:

```python
class AIProvider:
def generate(self, prompt: str) -> str:
raise NotImplementedError
```

А уже внутри реализации хранить конкретный SDK и формат запроса.

Тогда смена endpoint будет неприятной задачей, но не полной переделкой продукта.

Когда единый API действительно полезен

На мой взгляд, единый API особенно удобен в таких сценариях:

- нужно попробовать несколько моделей;

- приложение уже использует OpenAI SDK;

- есть несколько небольших AI-функций;

- команда не хочет поддерживать пять разных кабинетов;

- требуется единый контроль расходов;

- модель может меняться в зависимости от задачи;

- нужно быстро подключить AI к внутреннему инструменту или боту.

Для простого личного эксперимента отдельный ключ конкретного провайдера тоже может быть вполне достаточным.

Для крупного production-продукта нужно дополнительно проверить юридические условия, хранение данных, SLA, ограничения и безопасность. Тут нельзя выбирать только по принципу «у этого API один красивый пример на Python».

Мой практический чек лист

Перед подключением новой модели я бы проверил:

1. - базовый текстовый запрос;

2. - список доступных моделей;

3. - максимальный размер контекста;

4. - лимит результата;

5. - streaming;

6. - tools;

7. - structured output;

8. - vision, если нужны изображения;

9. - ошибки 400, 401, 403, 429 и 503;

10. - поведение после обрыва соединения;

11. - usage;

12. - стоимость;

13. - request ID;

14. - лимит расходов;

15. - правила хранения данных.

Это занимает больше времени, чем просто скопировать API-ключ. Зато потом меньше шансов обнаружить в production, что выбранная модель не умеет ровно ту функцию, на которой построен пользовательский сценарий.

Итог

Один API-ключ действительно может убрать часть рутины:

- меньше кабинетов;

- меньше отдельных интеграций;

- проще смена модели;

- понятнее контроль расходов;

- удобнее эксперименты.

Но он не решает автоматически:

- несовместимость возможностей;

- ошибки и retry;

- рост контекста;

- утечки секретов;

- дублирование запросов;

- зависимость от gateway;

- вопросы хранения данных;

- качество ответов модели.

Мой вывод такой:

Единый API — это хороший инфраструктурный слой, но не готовая архитектура приложения.

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

Иначе получится не «один ключ вместо десяти», а «одна точка отказа вместо десяти маленьких».