Erros Comuns do LiteLLM: Timeouts, Alertas de Orçamento e Falhas de Provedor

Erros Comuns do LiteLLM: Timeouts, Alertas de Orçamento e Falhas de Provedor

A maioria dos Erros Comuns do LiteLLM parece, a princípio, um problema do provedor: uma solicitação expira, um alerta de orçamento nunca chega ou um modelo saudável de repente retorna um 404 ou 503. A correção mais rápida é identificar a camada de controle que falhou antes de alterar as tentativas ou trocar modelos.

Use este guia para separar prazos do cliente, política do gateway LiteLLM, configuração do modelo, capacidade do provedor e aplicação de limites de gastos. Ele inclui um pequeno fluxo de trabalho de incidentes que você pode repetir para timeouts, controles de orçamento e falhas de provedores.

Resposta rápida: Preserve uma solicitação que falhou, classifique o erro, reproduza-o com uma chamada mínima e altere um controle por vez. Comece pelo tipo de exceção normalizado do LiteLLM, pelos metadados da solicitação e pelo ID da chamada — não apenas pelo status HTTP.

O LiteLLM mapeia muitas falhas de provedores para tipos de exceção compatíveis com OpenAI e expõe o status HTTP, a mensagem e o provedor de origem na exceção. Isso torna os Erros Comuns do LiteLLM mais fáceis de solucionar quando você mantém intacto o contexto do erro original, em vez de substituí-lo por um 500 genérico. Consulte a referência de mapeamento de exceções do LiteLLM para o mapeamento atual.

A matriz de Erros Comuns do LiteLLM

Esta tabela é o principal recurso deste guia de Erros Comuns do LiteLLM: ela transforma uma falha vaga do gateway na próxima observação específica.

Um fluxo de triagem de Erros Comuns do LiteLLM em cinco minutos

Antes de editar o config.yaml, salve uma falha representativa. Oculte segredos e conteúdo de prompts quando necessário, mas mantenha os campos operacionais.

1. Capture a identidade da solicitação. Registre o carimbo de data/hora, ambiente, rota, model solicitado, status HTTP, tipo de exceção do LiteLLM, mensagem de erro, nome do provedor e número da tentativa do cliente.
2. Capture a identidade do gateway. Salve x-litellm-call-id quando estiver presente. O LiteLLM documenta esse cabeçalho como a melhor referência para acompanhar uma solicitação pelos sistemas de logs. Registre também x-litellm-model-id, x-litellm-model-api-base e os cabeçalhos de versão, caso sua resposta os exponha. A documentação de logs do LiteLLM lista os cabeçalhos atuais.
3. Classifique a falha. É uma solicitação inválida, um problema de autenticação/permissão, um limite de orçamento/taxa, um timeout ou uma falha de serviço upstream? Não coloque todos os erros 4xx em um único grupo de tentativas.
4. Faça uma reprodução mínima, fora de produção. Use a mesma chave virtual e o model_name público que a aplicação usa. Remova a concorrência específica da aplicação e as chamadas de ferramentas antes de testar uma solicitação básica.
5. Altere apenas uma camada. Uma correção de nome de modelo, uma alteração de timeout e uma alteração de fallback na mesma implantação tornam impossível explicar o resultado final.

Aqui está uma sondagem mínima genérica para um proxy LiteLLM compatível com OpenAI:

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
  }'

O ponto não é que support-chat seja um nome de modelo universal. O ponto é que o teste deve usar o nome público configurado no seu gateway e, em seguida, preservar os cabeçalhos e o corpo da resposta para comparação com a solicitação da aplicação que falhou.

Erros de timeout: encontre o prazo que realmente foi acionado

Os timeouts estão entre os Erros Comuns do LiteLLM mais enganosos, pois uma solicitação pode expirar em mais de uma camada:

• O chamador pode cancelar primeiro.
• A implantação ou o roteador do LiteLLM pode aplicar um prazo menor.
• O request_timeout do proxy pode interromper uma chamada upstream de longa duração.
• O provedor, o balanceador de carga ou o caminho de rede pode encerrar a solicitação.
• Uma resposta em streaming pode começar com sucesso e depois parar entre os chunks.

O mapeamento de exceções do LiteLLM documenta falhas de timeout como openai.APITimeoutError. Para rotas nativas e pass-through, a documentação de timeout atual descreve uma ordem de precedência entre as configurações de solicitação, implantação, roteador e proxy. Verifique a versão da documentação que corresponde à sua implantação antes de aplicar uma alteração de configuração.

Comece com um orçamento de prazo, não com um número maior

Escolha a latência total que o seu fluxo de usuário pode tolerar e, em seguida, faça a alocação de trás para frente. Por exemplo, uma experiência interativa pode reservar tempo para enfileiramento, uma nova tentativa e a renderização da resposta, em vez de deixar a chamada upstream consumir todo o prazo visível ao usuário.

# Ponto de partida ilustrativo — ajuste-o à sua carga de trabalho e à versão do LiteLLM.
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

O exemplo é intencionalmente conservador: ele dá ao proxy um modo de falha limitado, em vez de permitir que as conexões fiquem travadas. As orientações de produção do LiteLLM recomendam definir um timeout de solicitação e usar logs estruturados de produção.

Quando ocorrer um timeout, responda a estas perguntas na ordem:

Não deixe uma nova tentativa automática de timeout continuar indefinidamente. Uma nova tentativa só é razoável quando o trabalho pode ser repetido com segurança e uma tentativa alternativa ainda pode terminar dentro do prazo do chamador. Se uma solicitação aciona ferramentas, grava dados ou inicia um stream visível ao usuário, defina primeiro a idempotência e a semântica de reinicialização.

Para problemas de enfileiramento ou capacidade motivados por 429 que se apresentam como latência longa, combine esta seção com o guia de RPM, TPM e novas tentativas da Flatkey. Um timeout pode ser o sintoma de um controle de admissão sobrecarregado, não de uma configuração de duração da solicitação.

Alertas de orçamento: separe a notificação da aplicação

O comportamento do orçamento causa uma parcela desproporcional dos Erros Comuns do LiteLLM porque as equipes frequentemente reúnem três controles diferentes sob a palavra “alerta”. Eles não são intercambiáveis.

A primeira verificação de orçamento: há um banco de dados?

A documentação de orçamento atual do LiteLLM é explícita: os orçamentos do proxy são aplicados com base nos gastos lidos do banco de dados. Em uma implantação sem banco de dados, um max_budget global configurado não atua como um limite de gastos confiável; o comportamento de orçamento de chave virtual, equipe e usuário também depende do banco de dados.

Isso leva a um padrão de falha comum: uma equipe define max_budget, vê um aviso de inicialização ou um valor de configuração e presume que o tráfego de produção será interrompido no limite. Isso não será um controle confiável sem a configuração necessária de rastreamento de gastos.

# 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

Trate fail_closed_budget_enforcement como uma decisão de confiabilidade, não como uma solução de copiar e colar. A documentação atual do LiteLLM explica que verificações de orçamento mais rigorosas podem rejeitar solicitações quando o gasto não pode ser verificado; teste o comportamento de falha do banco de dados e do Redis na sua implantação antes de ativá-lo amplamente.

Teste o caminho do orçamento, não apenas o painel

Use uma chave ou equipe descartável em um ambiente que não seja de produção e verifique esta sequência:

1. Confirme que o proxy consegue ler e gravar no armazenamento de gastos.
2. Crie um orçamento rígido deliberadamente pequeno no escopo correto: chave, equipe, usuário, projeto ou usuário final.
3. Envie uma solicitação mínima pelo proxy.
4. Envie uma segunda solicitação que necessariamente ultrapasse o limite.
5. Verifique de forma independente a exceção retornada, o registro de gastos, a janela de redefinição e o canal de alerta.
6. Confirme que a aplicação lida com um bloqueio de orçamento sem tentar novamente como se fosse uma sobrecarga transitória do provedor.

O LiteLLM também documenta janelas de orçamento e controles de orçamento por modelo. Seja preciso quanto ao cronograma de redefinição: uma proteção diária e um teto mensal resolvem riscos diferentes.

Os alertas de orçamento do Azure e da AWS são salvaguardas, não substitutos

As palavras-chave secundárias alertas de orçamento do Azure e alertas de orçamento da AWS são importantes porque os alertas de cobrança dos provedores de nuvem abrangem um limite diferente. Eles podem avisar sobre gastos da conta ou assinatura do provedor, incluindo tráfego que ignora o LiteLLM. Eles não substituem uma decisão no nível do gateway sobre se esta solicitação, chave, locatário ou modelo deve ser aceito agora.

Use ambas as camadas quando apropriado:

• A política de orçamento do LiteLLM protege a rota e o locatário que o gateway consegue identificar.
• Os alertas de orçamento do Azure ou da AWS monitoram os gastos da conta de nuvem upstream.
• Um livro-razão de uso do gateway reconcilia os dois e expõe o tráfego que ignorou o caminho pretendido.

Para gastos da OpenAI, a verificação da taxa de captura de gastos do LiteLLM pode comparar os gastos rastreados com a API de custos da organização OpenAI. Atualmente, ela tem pré-requisitos específicos do provedor, portanto, leia a documentação versionada antes de tratá-la como um recurso universal de reconciliação com vários provedores.

Se a necessidade operacional for mais ampla do que uma única implantação do LiteLLM, consulte o guia de avaliação de painel unificado de cobrança de IA para conhecer as perguntas a fazer sobre chaves, orçamentos, alocações, alertas e reconciliação.

Falhas de provedor: verifique separadamente o nome público do modelo e a implantação upstream

As falhas de provedor são os Erros Comuns do LiteLLM mais visíveis, mas muitas vezes são erros de configuração do gateway. Normalmente, um cliente chama o model_name público que você expõe. O LiteLLM então resolve esse nome para um modelo de provedor, implantação, endpoint, credencial e parâmetros específicos do provedor.

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

O model_name e o litellm_params.model são conceitos deliberadamente distintos. Quando um cliente recebe um erro de modelo inválido, compare primeiro o nome exato solicitado com model_name. A documentação de gerenciamento de modelos do LiteLLM diferencia o nome público do modelo do modelo do provedor e disponibiliza um fluxo de teste de conexão para modelos configurados.

Tabela de decisão para falhas de provedor

O tipo de exceção deve orientar a próxima ação. A referência de exceções do LiteLLM mapeia as condições 401, 402, 403, 404, 408, 429, 500 e 503 para classes normalizadas; também expõe campos específicos do provedor para uma investigação mais aprofundada.

Tentativas, fallbacks e períodos de resfriamento: recupere-se sem ocultar o incidente

As tentativas e os fallbacks podem reduzir falhas visíveis, mas também podem transformar um erro de configuração em latência, custo ou trabalho duplicado. Um bom tratamento de Erros Comuns do LiteLLM utiliza uma política diferente para configuração inválida e para uma breve interrupção do provedor.

O LiteLLM documenta uma divisão útil:

• Tentativas procuram recuperar dentro do grupo de modelos atual.
• Fallbacks passam para outro grupo de modelos após as tentativas configuradas.
• Períodos de resfriamento isolam uma implantação com falha enquanto alternativas saudáveis permanecem disponíveis.

Aqui está uma pequena configuração ilustrativa baseada no guia de failover de provedores do 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

Valide isso apenas com um erro intencional de provedor fora de produção. A documentação do LiteLLM alerta que flags antigas de fallback simulado não testam solicitações de proxy; uma falha real e controlada é o caminho apropriado para validar o proxy.

Mantenha condições de 404, autenticação, permissões, esquema e política de conteúdo fora de um loop geral de tentativas, a menos que você tenha projetado explicitamente uma resposta separada. A documentação de roteamento do LiteLLM oferece suporte a políticas de tentativas específicas para erros, incluindo zero tentativas para NotFoundError; isso impede que um nome de modelo inválido se transforme em um incidente lento.

Antes de habilitar um fallback entre provedores, valide o contrato do produto:

• Comportamento da janela de contexto e semântica de chamadas de ferramentas
• Suporte a saída estruturada e formato de resposta
• Requisitos de residência e retenção de dados e de políticas do cliente
• Comportamento de segurança e expectativas de política de conteúdo
• Limites de latência e custo
• Idempotência dos efeitos colaterais posteriores

Os fallbacks devem ser observáveis após a solicitação, não silenciosos. O LiteLLM documenta campos como fallbacks tentados e grupo de modelos original nos metadados do log de gastos. Monitore a taxa de fallback, a taxa de sucesso final, a latência adicionada por tentativa/fallback e o custo da rota que efetivamente atendeu à solicitação.

Para um projeto de roteamento mais amplo, consulte o guia de roteamento com fallback da Flatkey. A mesma regra se aplica: roteie somente quando a alternativa ainda atender ao contrato do fluxo de trabalho.

Uma lista de verificação preparada para incidentes de problemas do LiteLLM

Execute esta lista de verificação antes de encerrar um incidente ou declarar corrigido um dos Erros Comuns do LiteLLM.

Quando simplificar a superfície de roteamento

Algumas equipes querem o LiteLLM porque ele centraliza a configuração de modelos, o uso e a política de confiabilidade. Outras querem menos infraestrutura de gateway para operar. A resposta certa depende de quem é responsável pela política de roteamento, credenciais de provedores, aplicação de orçamento e ciclo de resposta a incidentes.

O Flatkey é útil quando uma aplicação precisa de uma superfície de integração compatível com OpenAI em rotas de modelos suportadas, mantendo o roteamento, a revisão de uso e a faturação mais próximos. Não elimina a necessidade de classificar timeouts, bloqueios de orçamento ou erros de fornecedor; reduz o número de integrações de cliente específicas de fornecedor que a sua aplicação tem de manter. Comece com uma chave de API para vários modelos de IA ou o guia de início rápido da API Flatkey quando quiser avaliar esse modelo operacional.

Para um guia completo de configuração e um exemplo de configuração, consulte o nosso guia do proxy LiteLLM.

Perguntas frequentes

É seguro repetir todos os erros comuns do LiteLLM?

Não. Falhas de autenticação, permissões, modelo inválido, parâmetro não suportado, orçamento e a maioria das falhas de faturação exigem uma correção na configuração ou na conta. Repita apenas condições claramente transitórias, com um limite pequeno de tentativas e de tempo, e apenas quando for seguro repetir a operação.

Porque é que max_budget não impede os gastos no meu proxy LiteLLM?

Primeiro, verifique se o proxy tem o acompanhamento de gastos baseado em base de dados necessário para a aplicação do orçamento. Em seguida, confirme que o tráfego chega ao LiteLLM em vez de chamar diretamente um fornecedor e que a chave, equipa, utilizador ou projeto configurado é o âmbito que está realmente a fazer o pedido. A documentação de orçamento do LiteLLM explica o requisito da base de dados e o comportamento do âmbito.

Os alertas de orçamento do Azure ou da AWS são suficientes para evitar que uma aplicação exceda o orçamento?

São salvaguardas úteis ao nível da conta do fornecedor, mas não decidem se um pedido específico ao gateway deve ser aceite. Mantenha os alertas de faturação do fornecedor e adicione um orçamento de gateway testado e um limite de produto ao nível da aplicação, onde o contexto do pedido é conhecido.

O que devo guardar de uma chamada LiteLLM que falhou?

Guarde o corpo do erro sanitizado, a classe de exceção normalizada, o estado HTTP, o nome do fornecedor, o modelo solicitado, o carimbo de data e hora, o ambiente, o número da tentativa do cliente e x-litellm-call-id, quando disponível. Evite registar chaves de API e conteúdo sensível de prompts/respostas.

Um fallback pode ocultar uma má configuração?

Sim. Um fallback pode fazer com que um pedido de cliente seja bem-sucedido enquanto a rota principal continua a falhar. Por isso, a taxa de fallback, os erros específicos da rota, o grupo de modelos final, a latência e o custo precisam de alertas ou painéis. Trate uma taxa de fallback crescente como um sinal operacional, e não como uma correção concluída.

Conclusão final

A solução duradoura para os erros comuns do LiteLLM não é uma contagem universal de tentativas ou um timeout maior. É um ciclo operacional repetível: capturar a falha real, identificar a camada de política, validar a menor alteração segura e comprovar o caminho de recuperação com um teste controlado. Isto mantém os timeouts limitados, os alertas de orçamento significativos e as falhas de fornecedor suficientemente visíveis para serem corrigidas.

Fontes

• Mapeamento de exceções do LiteLLM
• Orçamentos e limites de taxa do LiteLLM
• Failover de fornecedor e fallbacks do LiteLLM
• Roteamento, tentativas, períodos de arrefecimento e concorrência do LiteLLM
• Boas práticas de produção do LiteLLM
• Registo de logs do LiteLLM
• Verificações da taxa de captura de gastos do LiteLLM