Единый API для нейросетей: policy выбора модели по задаче

Опишите решение как правила, а не как предпочтение бренда

Начните с карточки задачи: какой формат входа разрешён, нужен ли структурированный JSON, допускается ли внешний инструмент, какие данные нельзя передавать и кто отвечает за итог. Затем сформулируйте несколько наблюдаемых критериев: допустимое время ожидания, максимальная стоимость вашей операции, минимальная полнота ответа и условия ручной проверки. Для каждой комбинации создайте маршрут с понятным именем, например support_safe или draft_review. Название не должно скрывать реальную логику. В policy полезно хранить только локальные правила приложения и идентификаторы, сверенные с актуальным каталогом перед запуском. Не считайте модель универсальной заменой проверки: для юридических, финансовых, медицинских и иных чувствительных сценариев нужен отдельный процесс и владелец решения.

Сделайте allowlist и проверяйте контекст запроса на сервере

Выбор маршрута выполняется server-side после аутентификации пользователя и проверки tenant, роли, окружения и класса данных. Клиент может передать намерение, но не должен подставлять произвольный model ID, base URL или служебный флаг. Allowlist связывает разрешённый маршрут с небольшой группой актуально проверенных идентификаторов; неизвестное значение возвращает контролируемую ошибку, а не тихо уходит в запасной сервис. Отдельно фиксируйте, какие инструменты, размеры вложений и форматы ответа разрешены для маршрута. Это защищает от случайной смены конфигурации, упрощает code review и не превращает ответ модели в разрешение на действие. Ключ RussiaAPI хранится только в защищённой переменной окружения на сервере; логи получают request ID, решение policy и класс ошибки, но не prompt и не Authorization.

Соберите маленький набор тестов до автоматического выбора

Полезный eval-набор состоит из синтетических, обезличенных примеров с заранее описанным ожидаемым результатом: корректный JSON, запрос на уточнение, отказ при недопустимом входе и передача человеку. Не подменяйте качество одним общим score. Отмечайте отдельные свойства: валидность структуры, наличие разрешённого источника, соблюдение лимита, отсутствие нежелательного действия и понятность текста для пользователя. Запускайте одинаковый набор для каждого кандидата, версии шаблона и адаптера; фиксируйте дату, версию теста и локальную конфигурацию. Один удачный прогон не доказывает стабильность. Если результат не соответствует условиям, policy должна вернуть нейтральный статус review_required, а не менять маршрут автоматически. Так команда отделяет измерение от рекламного утверждения и сохраняет воспроизводимый повод для решения.

Планируйте rollout и rollback как часть policy

Сначала включите новую ветку для внутреннего тестового tenant или небольшой доли разрешённого трафика. До начала определите стоп-условия: рост ошибок схемы, увеличение timeout, отсутствие обязательного поля, жалоба пользователя или превышение вашего локального бюджета. Храните предыдущую конфигурацию как версию и переключайте её вручную по подтверждённой процедуре; не копируйте секреты между окружениями. Наблюдайте только минимальные данные: количество запросов, длительность, класс результата, версию policy и собственный request ID. Полный текст запроса и скрытые рассуждения не нужны для операционного решения. Временная деградация не оправдывает бесконечные повторы: retry допустим лишь для понятной идемпотентной операции с ограничением числа попыток. Пользователь должен увидеть честный статус и вариант продолжить позже или обратиться к оператору.

Разделите fallback и перенос данных

Fallback — не обещание, что любая задача автоматически будет исполнена другой моделью. Перед переключением policy должна проверить, можно ли передать этот класс данных на альтернативный разрешённый маршрут, не нарушает ли это внутренние правила и сохранится ли требуемый формат. Для чувствительного контекста безопаснее завершить операцию статусом manual_review, чем отправить данные по новому пути «для удобства». Даже при технической совместимости различаются ошибки, ограничения и наблюдаемая структура ответа, поэтому адаптер нормализует только проверенные поля. Добавьте тесты для отсутствующего маршрута, запретного tenant, изменения каталога и невалидного ответа. Если нет подтверждённого варианта, интерфейс не должен сообщать, что работа выполнена. Такая граница помогает не превратить единый API в непрозрачную цепочку непроверенных обещаний.

Регулярно пересматривайте решение и оставляйте след

Policy устаревает при изменении продукта, схемы входа, состава команды или внешнего контракта. Назначьте владельца, срок пересмотра и короткий журнал изменений: что поменялось, на каком тестовом наборе проверено, какие стоп-условия действуют и как вернуться к прошлой версии. Не храните в журнале ключи, полные prompts или персональные данные; достаточно версии, локального request ID, агрегированных показателей и ссылки на pull request. Перед новым deploy сверяйте разрешённые идентификаторы с актуальным каталогом и запускайте canary на синтетическом наборе. Если задача требует сравнения качества, публикуйте методику и ограничения, а не объявляйте постоянного победителя. Так решение остаётся проверяемым для команды и понятным для поддержки, даже когда доступность или параметры внешних моделей меняются.

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. В нём нет реального ключа: это логика приложения, а не текущая спецификация внешнего API. До интеграции подтвердите маршрут, схему и ограничения в документации.

const policy = {
  support_safe: { allowedModels: new Set(['approved-model-id']), requireHumanReview: false },
  sensitive_case: { allowedModels: new Set(), requireHumanReview: true }
};

export function selectRoute({ intent, modelId, tenantAllowed, hasSensitiveData }) {
  const route = policy[intent] ?? policy.sensitive_case;
  if (!tenantAllowed || hasSensitiveData || route.requireHumanReview) return { status: 'review_required' };
  if (!route.allowedModels.has(modelId)) return { status: 'blocked', reason: 'model_not_allowlisted' };
  return { status: 'approved', modelId };
}
// Run server-side; keep API keys and full prompts out of the client and logs.

Проверьте синтаксис через node --check, добавьте аутентификацию, лимиты и отрицательные тесты. Не помещайте тело запроса, ответ целиком или заголовки авторизации в журнал.

Граница ответственности и данных

Это инженерное руководство для вашего приложения, а не описание гарантированной функции внешнего поставщика. Не помещайте в браузер, тикет, статью или журнал API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt или персональные данные. Для регулируемых данных, договорных условий и прав на контент проверяйте применимые требования с ответственным специалистом.

Материалы для сверки

Внешние источники объясняют общие инженерные принципы. Они не подтверждают функции, тарифы, доступность или SLA RussiaAPI и сторонних моделей.

• OWASP: риски LLM-приложений
• OWASP: контроль доступа
• Martin Fowler: feature toggles