Диагностика совместимого API

Model not found в OpenAI-совместимом API: каталог, ID и права

Ошибка model not found в OpenAI-совместимом API не означает, что нужно угадывать имя модели или подставлять другой ключ. Это проверяемое состояние: сервер получает актуальный каталог, сопоставляет точный ID с конфигурацией проекта и возвращает понятный статус. RussiaAPI — независимый сторонний gateway; совместимый формат не обещает постоянный набор моделей, одинаковые возможности или правила поставщиков.

Опубликовано 29 августа 2026 · 10 минут чтения · Ключевой запрос: model not found в OpenAI-совместимом API

Сначала отделите имя в интерфейсе от model ID

В интерфейсе удобно показывать короткое название, но API принимает точный идентификатор. Между этими значениями часто возникает ошибка: в переменную окружения попадает display name, старая версия ID или строка с пробелом. Храните в конфигурации именно ID, который вернул текущий каталог, а в UI — отдельную подпись. Не передавайте выбор модели как безусловно доверенный параметр браузера: server-side слой должен сверить его со своим разрешённым набором.

Проверьте также base URL, окружение и ключ, которым выполняется запрос. Dev-ключ и production-ключ могут иметь разные права, а тестовая вкладка — старую конфигурацию. Не публикуйте список «всегда доступных» моделей и не трактуйте название модели как гарантию цены, контекста, streaming или структурированного ответа. Эти свойства подтверждаются текущим каталогом, документами и вашим минимальным тестом.

Получите каталог безопасным server-side запросом

Первое действие — один запрос к /v1/models с собственным ключом RussiaAPI на сервере. Не вставляйте заголовок Authorization в консоль браузера, общий Postman environment или скриншот тикета. Сохраните только время проверки, HTTP-статус, количество записей и безопасный request ID, если он возвращается. Полный заголовок, ключ и пользовательский prompt не нужны для диагностики.

Каталог — снимок, а не договор об вечной доступности. Кешируйте его с ограниченным TTL, не затирайте последний корректный ответ пустым массивом и объединяйте параллельные refresh. Для критичной операции допустима одна принудительная проверка, но она должна иметь rate limit. Подробнее о TTL и нормализации — в руководстве по кешированию /v1/models.

Минимальный проверяемый пример

Пример читает каталог только на сервере и ищет точное совпадение ID. Он запускается в Node.js 18+ при заданном RUSSIAAPI_API_KEY и не раскрывает секрет в выводе. Подставьте нужный ID через переменную окружения после проверки текущего каталога; это не пример для клиентского приложения и не утверждение, что конкретная модель доступна.

const wanted = process.env.RUSSIAAPI_MODEL;
const response = await fetch('https://russiaapi.com/v1/models', {
  headers: { authorization: `Bearer ${process.env.RUSSIAAPI_API_KEY}` },
  signal: AbortSignal.timeout(8_000)
});
if (!response.ok) throw new Error(`catalog_status_${response.status}`);
const json = await response.json();
const ids = Array.isArray(json.data) ? json.data.map((item) => item.id) : [];
if (!ids.includes(wanted)) throw new Error('configured_model_not_in_catalog');
console.log('model configuration is present');

Если ответ не 200, не маскируйте его фиктивным списком. Сначала зафиксируйте класс ошибки: 401/403 обычно указывает на ключ или права, 429 — на ограничение, а 5xx или сеть — на временную проблему. Для JSON и невалидного тела используйте отдельную ветку; повторять один и тот же неверный запрос бессмысленно. Связанный разбор есть в статье об ошибках 400 и 422.

Сделайте fallback явной продуктовой политикой

Автоматически выбирать «любую похожую» модель опасно. У замены могут отличаться формат, стоимость, поведение инструментов, политика данных, задержка и лимиты. Если сценарий действительно допускает fallback, составьте короткий разрешённый список, протестируйте каждый маршрут на обезличенном наборе и покажите пользователю, что выбор изменился. Нельзя использовать fallback для обхода доступа, региональных ограничений или правил поставщика.

После model not found разумная последовательность такова: обновить каталог один раз, сверить ID и права проекта, проверить конфигурацию развёртывания, затем либо применить заранее утверждённую замену, либо вернуть контролируемую ошибку. Не запускайте бесконечный retry и не меняйте ключ. Подход к контролируемому переключению описан в материале о fallback моделей.

Добавьте наблюдаемость без утечки

Для такой ошибки достаточно метрик: возраст каталога, cache hit/miss, число отказов по безопасному имени конфигурации, HTTP-класс и длительность обновления. Логируйте хеш или внутренний alias модели, если это нужно для расследования, но не API key, Bearer-заголовок, prompt, email или полный ответ upstream. Ограничьте доступ к журналам и срок хранения согласно вашей политике.

Тестируйте не только успех. В contract-тесте проверьте пустой каталог, просроченный кеш, отсутствие выбранного ID, 401/403, 429 и сетевой timeout. Затем выкатывайте изменение малой доле трафика. Такой порядок помогает отличить ошибку конфигурации от временного состояния, не создавая лишних запросов и не раскрывая секреты. Практики redaction собраны в руководстве по безопасным логам.

Чек-лист перед запуском

1. Точный model ID получен из текущего каталога и отделён от UI-подписи.
2. Каталог запрашивается только server-side собственным ключом RussiaAPI.
3. Кеш имеет TTL, время получения и безопасное обновление без пустой подмены.
4. Fallback заранее утверждён и протестирован, а не подбирается случайно.
5. Логи содержат статус и request ID, но не секреты и содержимое запросов.

Добавьте в runbook владельца конфигурации и время последней проверки. Тогда дежурный инженер не меняет model ID в спешке: он видит источник каталога, возраст кеша, окружение и результат contract-теста. Перед изменением маршрута проведите обратимый rollout и сохраните возможность вернуть прежнюю явно проверенную конфигурацию.

Так модельная ошибка остаётся наблюдаемой и исправляемой. Окончательное решение всегда принимается по текущему каталогу RussiaAPI, контракту проекта и правилам применимых поставщиков.

FAQ

Читайте также

• Кеширование /v1/models
• Ошибки 401 и 403
• Fallback моделей
• Документы RussiaAPI