Распространённые ошибки LiteLLM: тайм-ауты, предупреждения о бюджете и сбои провайдеров

Распространённые ошибки LiteLLM: тайм-ауты, предупреждения о бюджете и сбои провайдеров

Большинство распространённых ошибок LiteLLM сначала выглядят как проблема провайдера: запрос завершается по тайм-ауту, предупреждение о бюджете не приходит или исправная модель внезапно возвращает 404 либо 503. Самый быстрый способ исправить проблему — определить сбойный уровень управления до изменения повторных попыток или замены моделей.

Используйте это руководство, чтобы разделить клиентские дедлайны, политики шлюза LiteLLM, конфигурацию модели, доступную мощность провайдера и контроль расходов. В него включён небольшой рабочий процесс для инцидентов, который можно повторять при тайм-аутах, контроле бюджета и сбоях провайдеров.

Краткий ответ: Сохраните один неудачный запрос, классифицируйте ошибку, воспроизведите её минимальным вызовом и меняйте по одному элементу управления за раз. Начните с нормализованного типа исключения LiteLLM, метаданных запроса и ID вызова, а не только со статуса HTTP.

LiteLLM сопоставляет многие сбои провайдеров с типами исключений, совместимыми с OpenAI, и предоставляет в исключении HTTP-статус, сообщение и исходного провайдера. Это упрощает устранение распространённых ошибок LiteLLM, если сохранять исходный контекст ошибки, а не заменять его универсальным 500. Актуальное сопоставление смотрите в справочнике сопоставления исключений LiteLLM.

Матрица распространённых ошибок LiteLLM

Эта таблица — главный практический элемент этого руководства по распространённым ошибкам LiteLLM: она превращает неопределённый сбой шлюза в следующее конкретное наблюдение.

Пятиминутный процесс первичной диагностики распространённых ошибок LiteLLM

Перед редактированием config.yaml сохраните один типичный сбой. При необходимости удалите секреты и содержимое промпта, но сохраните операционные поля.

1. Зафиксируйте идентификаторы запроса. Запишите временную метку, среду, маршрут, запрошенную model, HTTP-статус, тип исключения LiteLLM, сообщение об ошибке, имя провайдера и номер попытки клиента.
2. Зафиксируйте идентификаторы шлюза. Сохраните x-litellm-call-id, если он присутствует. LiteLLM документирует этот заголовок как лучший способ отслеживать запрос в системах логирования. Также запишите x-litellm-model-id, x-litellm-model-api-base и заголовки версий, если они доступны в ответе. В документации по логированию LiteLLM перечислены актуальные заголовки.
3. Классифицируйте сбой. Это недопустимый запрос, проблема аутентификации/разрешений, ограничение бюджета/частоты, тайм-аут или сбой вышестоящего сервиса? Не помещайте все ошибки 4xx в одну категорию повторных попыток.
4. Выполните одно минимальное воспроизведение вне production. Используйте тот же виртуальный ключ и публичное model_name, которое использует приложение. Перед тестированием базового запроса исключите специфичную для приложения конкурентность и вызовы инструментов.
5. Изменяйте только один уровень. Исправление имени модели, изменение тайм-аута и изменение резервного варианта в одном развёртывании делают конечный результат невозможным для объяснения.

Ниже приведён универсальный минимальный тест для OpenAI-совместимого прокси LiteLLM:

curl -i --request POST "$LITELLM_PROXY_URL/v1/chat/completions" \
  --header "Authorization: Bearer $LITELLM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "support-chat",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "max_tokens": 16
  }'

Суть не в том, что support-chat — это универсальное имя модели. Суть в том, что тест должен использовать публичное имя, настроенное в вашем шлюзе, а затем сохранять заголовки и тело ответа для сравнения с неудавшимся запросом приложения.

Ошибки тайм-аута: найдите дедлайн, который фактически сработал

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

• Вызывающая сторона может отменить запрос первой.
• Развёртывание или маршрутизатор LiteLLM могут применить более короткий дедлайн.
• request_timeout прокси может остановить длительный вызов к апстриму.
• Провайдер, балансировщик нагрузки или сетевой маршрут могут закрыть запрос.
• Потоковый ответ может успешно начаться, а затем зависнуть между фрагментами.

Сопоставление исключений LiteLLM документирует сбои тайм-аута как openai.APITimeoutError. Для нативных и транзитных маршрутов текущая документация по тайм-аутам описывает порядок приоритета между настройками запроса, развёртывания, маршрутизатора и прокси. Прежде чем изменять конфигурацию, проверьте версию документации, соответствующую вашему развёртыванию.

Начните с бюджета дедлайна, а не с большего числа

Выберите общую задержку, приемлемую для пользовательского сценария, а затем распределите её в обратном порядке. Например, интерактивный сценарий может резервировать время на постановку в очередь, одну повторную попытку и отрисовку ответа, вместо того чтобы позволить вызову апстрима занять весь видимый пользователю дедлайн.

# Illustrative starting point — tune it to your workload and LiteLLM version.
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

Этот пример намеренно консервативен: он задаёт для прокси ограниченный режим сбоя, а не позволяет соединениям зависать. В рекомендациях для production LiteLLM рекомендуется задавать тайм-аут запроса и использовать структурированное логирование в production.

При возникновении тайм-аута последовательно ответьте на следующие вопросы:

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

Для проблем с очередями или ёмкостью, вызванных 429 и проявляющихся как высокая задержка, используйте этот раздел вместе с руководством Flatkey по RPM, TPM и повторным попыткам. Тайм-аут может быть симптомом перегруженного контроля допуска, а не настройки длительности запроса.

Предупреждения о бюджете: отделяйте уведомления от принудительного ограничения

Поведение бюджетов вызывает непропорционально большую долю распространённых ошибок LiteLLM, поскольку команды часто объединяют три разных механизма словом «предупреждение». Они не взаимозаменяемы.

Первая проверка бюджета: есть ли база данных?

Текущая документация LiteLLM по бюджетам однозначна: бюджеты прокси применяются на основе данных о расходах, считываемых из базы данных. В развёртывании без БД настроенный глобальный max_budget не действует как надёжный лимит расходов; поведение бюджетов виртуальных ключей, команд и пользователей также зависит от базы данных.

Это приводит к распространённому сценарию сбоя: команда задаёт max_budget, видит предупреждение при запуске или значение конфигурации и предполагает, что production-трафик остановится на пороге. Без необходимой настройки отслеживания расходов это не будет надёжным механизмом контроля.

# Illustrative policy only. Validate with a non-production key before rollout.
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  fail_closed_budget_enforcement: true

litellm_settings:
  max_budget: 100
  budget_duration: 30d

Рассматривайте fail_closed_budget_enforcement как решение в области надёжности, а не как исправление, которое можно просто скопировать и вставить. В текущей документации LiteLLM объясняется, что более строгая проверка бюджета может отклонять запросы, когда расходы невозможно подтвердить; перед широким включением протестируйте поведение базы данных и Redis при сбоях в вашем развертывании.

Тестируйте путь бюджета, а не только панель мониторинга

Используйте одноразовый ключ или команду в непродуктивной среде и проверьте следующую последовательность:

1. Убедитесь, что прокси может читать и записывать хранилище расходов.
2. Создайте намеренно небольшой жёсткий бюджет в правильной области: ключ, команда, пользователь, проект или конечный пользователь.
3. Отправьте минимальный запрос через прокси.
4. Отправьте второй запрос, который обязательно должен превысить порог.
5. Независимо проверьте возвращённое исключение, запись о расходах, окно сброса и канал оповещений.
6. Убедитесь, что приложение обрабатывает блокировку бюджета, не повторяя запрос так, как если бы это была временная перегрузка провайдера.

LiteLLM также документирует бюджетные окна и механизмы контроля бюджета для отдельных моделей. Точно определите расписание сброса: ежедневное ограничение и месячный лимит решают разные риски.

Оповещения о бюджете Azure и AWS — это резервная мера, а не замена

Вторичные ключевые слова оповещения о бюджете Azure и оповещения о бюджете AWS важны, поскольку оповещения о выставлении счетов от облачных провайдеров охватывают другую границу. Они могут предупреждать о расходах на уровне учётной записи провайдера или подписки, включая трафик, который обходит LiteLLM. Они не заменяют решение на уровне шлюза о том, следует ли сейчас пропустить этот запрос, ключ, арендатора или модель.

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

• Политика бюджета LiteLLM защищает маршрут и арендатора, которых шлюз способен идентифицировать.
• Оповещения о бюджете Azure или AWS отслеживают расходы на уровне вышестоящей облачной учётной записи.
• Журнал использования шлюза сверяет оба уровня и выявляет трафик, обошедший предусмотренный путь.

Для расходов OpenAI проверка коэффициента учёта расходов LiteLLM может сравнивать отслеживаемые расходы с OpenAI Organization Costs API. В настоящее время у неё есть предварительные требования, зависящие от провайдера, поэтому перед тем, как считать её универсальной функцией сверки для нескольких провайдеров, ознакомьтесь с документацией для соответствующей версии.

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

Сбои провайдеров: отдельно проверяйте публичное имя модели и вышестоящее развертывание

Сбои провайдеров — наиболее заметные распространённые ошибки LiteLLM, но часто они вызваны ошибками конфигурации шлюза. Клиент обычно вызывает предоставляемое вами публичное model_name. Затем LiteLLM сопоставляет это имя с моделью провайдера, развертыванием, конечной точкой, учётными данными и параметрами, специфичными для провайдера.

model_list:
  - model_name: support-chat       # The name the client requests
    litellm_params:
      model: azure/<deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

model_name и litellm_params.model намеренно обозначают разные понятия. Когда клиент получает ошибку недопустимой модели, сначала сравните точное запрошенное имя с model_name. Документация по управлению моделями LiteLLM различает публичное имя модели и модель провайдера, а также предоставляет рабочий процесс проверки подключения для настроенных моделей.

Таблица принятия решений при сбоях провайдеров

Тип исключения должен определять следующее действие. В справочнике исключений LiteLLM состояния 401, 402, 403, 404, 408, 429, 500 и 503 сопоставляются с нормализованными классами; также доступны поля, специфичные для провайдера, для более глубокого анализа.

Повторные попытки, резервные маршруты и периоды охлаждения: восстановление без сокрытия инцидента

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

В документации LiteLLM описано полезное разделение:

• Повторные попытки пытаются восстановить выполнение в рамках текущей группы моделей.
• Резервные маршруты переключают на другую группу моделей после настроенных повторных попыток.
• Периоды охлаждения изолируют сбойное развёртывание, пока доступны работоспособные альтернативы.

Ниже приведена небольшая иллюстративная конфигурация на основе руководства LiteLLM по отказоустойчивости провайдеров:

model_list:
  - model_name: primary-chat
    litellm_params:
      model: openai/<primary-model>
      api_key: os.environ/PRIMARY_PROVIDER_KEY

  - model_name: backup-chat
    litellm_params:
      model: azure/<backup-deployment>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

litellm_settings:
  num_retries: 1
  request_timeout: 30
  fallbacks: [{"primary-chat": ["backup-chat"]}]
  allowed_fails: 3
  cooldown_time: 30

Проверяйте это только с намеренно вызванной ошибкой нерабочего провайдера. В документации LiteLLM предупреждается, что устаревшие флаги mock fallback не тестируют запросы прокси; подходящим способом проверки прокси является реальный контролируемый сбой.

Не включайте условия 404, аутентификации, разрешений, схемы и политики контента в общий цикл повторных попыток, если только вы явно не разработали отдельную реакцию. Документация LiteLLM по маршрутизации поддерживает политики повторных попыток для конкретных ошибок, включая ноль повторных попыток для NotFoundError; это не позволяет недопустимому имени модели превратиться в затяжной инцидент.

Перед включением резервного маршрута между провайдерами проверьте контракт продукта:

• Поведение контекстного окна и семантику вызовов инструментов
• Поддержку структурированного вывода и формата ответа
• Требования к резидентности и хранению данных, а также политики клиентов
• Поведение безопасности и ожидания в отношении политики контента
• Границы задержек и затрат
• Идемпотентность побочных эффектов в нижестоящих системах

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

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

Чек-лист готовности к инцидентам для проблем LiteLLM

Выполните этот чек-лист, прежде чем закрывать инцидент или объявлять одну из распространённых ошибок LiteLLM устранённой.

Когда стоит упростить поверхность маршрутизации

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

Flatkey полезен, когда приложению нужна совместимая с OpenAI поверхность интеграции для поддерживаемых маршрутов моделей, при этом маршрутизация, анализ использования и биллинг должны быть более тесно связаны. Он не устраняет необходимость классифицировать тайм-ауты, бюджетные блокировки или ошибки провайдеров; он сокращает количество специфичных для провайдеров клиентских интеграций, которые должно поддерживать ваше приложение. Начните с одного API-ключа для нескольких ИИ-моделей или краткого руководства по Flatkey API, если хотите оценить эту операционную модель.

Полное пошаговое руководство по настройке и пример конфигурации см. в нашем руководстве по прокси LiteLLM.

Часто задаваемые вопросы

Безопасно ли повторять запросы при всех распространённых ошибках LiteLLM?

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

Почему max_budget не останавливает расходы в моём прокси LiteLLM?

Сначала убедитесь, что в прокси включено отслеживание расходов с использованием базы данных, необходимое для применения бюджетных ограничений. Затем подтвердите, что трафик проходит через LiteLLM, а не напрямую обращается к провайдеру, и что настроенный ключ, команда, пользователь или проект — это именно та область, которая фактически выполняет запрос. В документации по бюджетам LiteLLM объясняются требование к базе данных и поведение областей применения.

Достаточно ли бюджетных предупреждений Azure или AWS, чтобы предотвратить превышение бюджета приложением?

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

Что следует сохранять при неудачном вызове LiteLLM?

Сохраняйте очищенное тело ошибки, нормализованный класс исключения, HTTP-статус, имя провайдера, запрошенную модель, временную метку, окружение, номер попытки клиента и x-litellm-call-id, если он доступен. Не записывайте в журналы API-ключи и конфиденциальное содержимое промптов или ответов.

Может ли резервный маршрут скрыть неверную конфигурацию?

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

Главный вывод

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

Источники

• Сопоставление исключений LiteLLM
• Бюджеты и ограничения скорости LiteLLM
• Переключение при сбоях провайдеров и резервные маршруты LiteLLM
• Маршрутизация, повторные попытки, периоды охлаждения и параллелизм LiteLLM
• Рекомендации LiteLLM для производственной среды
• Логирование LiteLLM
• Проверки коэффициента учёта расходов LiteLLM