Solução de Problemas do AI Ops

Esta página cobre as questões mais comuns do AI Ops e como resolvê-las.

O heat map está vazio

Sintoma: /dashboard/analytics/heat-maps carrega, mas nenhum polígono de hex é desenhado.

Verifique na ordem:

1. ai_ops_enabled está true no subaccount? Se for false, nenhum cron roda para ele. Defina como true e aguarde um ciclo.

2. O backfill foi executado? Subaccount novo não tem previsões até o backfill inicial. Rode:

   curl -X POST "https://fleets.levyelectric.com/api/internal/forecast/backfill" \
     -H "Authorization: Bearer $AI_OPS_INTERNAL_TOKEN" \
     -d '{"subaccountId":"<uuid>"}'
   

3. O subaccount tem pelo menos 14 dias de histórico de corridas? Sem isso, o modelo não consegue ajustar uma previsão por subaccount. Verifique a contagem de corridas.

4. O cron de inferência rodou recentemente? Olhe demand_forecasts.created_at para o subaccount. Se a linha mais recente tem mais de 2 horas, o cron está travado.

O banner "Forecast may be stale" está aparecendo

Sintoma: Banner amarelo na página de heat maps com "Forecast may be stale — last refresh was X minutes ago."

O banner aparece quando a previsão mais recente tem mais de 90 minutos. Causas:

• O cron de inferência (/api/cron/ai-ops-run-inference) está falhando. Veja os logs de cron no Vercel.
• A Modal está fora e o forecaster local em fallback estoura tempo num subaccount grande.
• O construtor de features (/api/cron/ai-ops-build-features) não está produzindo linhas, então a inferência não tem o que consumir.

Diagnostique pela tabela model_runs. Se há entradas em model_runs mas não em demand_forecasts, a inferência está rodando mas as gravações falham — verifique a conexão com o banco.

Nenhuma recomendação de rebalanceamento aparece

Sintoma: /dashboard/operations/rebalance está vazio.

Verifique na ordem:

1. ai_ops_tier está em pro ou enterprise? O nível Starter não gera recomendações.
2. O cron do recomendador já rodou? Ele roda no minuto 25 de cada hora. Aguarde um ciclo após definir ai_ops_tier.
3. Existem hexes candidatos? O recomendador precisa de um hex subabastecido (previsão > fornecimento) e um hex superabastecido (fornecimento > previsão) no mesmo subaccount. Se sua frota está bem distribuída, nenhuma recomendação é gerada — comportamento correto.
4. O ganho projetado é positivo? Cada candidato é descartado se (dest_gain - src_loss) * avg_fare - distance * tech_cost_per_mile_usd ficar negativo. Um tech_cost_per_mile_usd alto pode suprimir todas as recomendações.

Se suspeitar que a matemática está conservadora demais, reduza temporariamente tech_cost_per_mile_usd para 0.25 e aguarde a próxima execução do cron.

Todos os veículos foram para maintenance sem motivo aparente

Sintoma: Vários veículos em um subaccount foram para maintenance e você não fez isso.

É a regra de auto-manutenção em ação — a Fase 3 marca cada veículo de parada pickup como maintenance quando um técnico aceita uma rota. É intencional, mas limitada:

• Só ocorre quando ai_ops_tier='enterprise'.
• Só ocorre depois que o técnico toca em Accept numa rota planned.
• Reverte automaticamente quando a rota é concluída ou abandonada.

Para desativar, rebaixe o subaccount para ai_ops_tier='pro'. Rotas deixam de ser geradas e a regra não se aplica.

Para resgatar veículos presos agora, encontre a rota em rebalance_routes (status in_progress) e abandone-a. Os veículos em auto-manutenção voltam a available.

A aba Route do técnico está vazia

Sintoma: O técnico abre a aba Route, mas nenhuma rota é exibida.

Verifique na ordem:

1. O subaccount está em ai_ops_tier='enterprise'? Caso contrário, nenhuma rota é gerada.
2. O técnico está logado no subaccount correto? A aba é scoped por subaccount.
3. O cron do solver de rotas rodou hoje? Ele roda a cada 30 min, entre 06:00 e 22:00 (horário local). Fora desse intervalo, nenhuma rota nova é construída.
4. Existem paradas a rotear? O solver precisa de pelo menos um veículo com bateria baixa ou uma recomendação aceita para produzir uma rota. Se a frota está saudável e nenhuma recomendação foi aceita, nenhuma rota é construída.
5. O técnico está atribuído ao turno de hoje? Rotas são por técnico — só aparecem rotas atribuídas a esse technician_id.

Conclusões offline nunca sincronizam

Sintoma: Um técnico concluiu paradas sem sinal, voltou a ficar online, e as paradas continuam "pending sync."

A operator-app esvazia a fila offline a cada evento de foco e a cada 60 segundos. Se a sincronização falha por vários minutos:

• Pull-to-refresh na aba Route força a sync.
• Force-close e reabra o app.
• Confira se a sessão de auth do técnico não expirou. Se necessário, faça login novamente.

Se a API retorna 4xx em chamadas complete-stop, veja o Sentry para o ID da rota — em geral, a causa é a rota ter sido abandonada nesse meio-tempo.

Recomendações parecem visivelmente erradas

Sintoma: O recomendador sugere mover veículos para um hex que você sabe estar inutilizável (rua fechada, problema de licença etc.).

O modelo não conhece fechamentos de rua nem restrições regulatórias. Dois caminhos:

1. Dispensar a recomendação. O modelo aprende com padrões de dismiss — dismissals repetidos do mesmo hex de destino reduzem a confiança futura ali.
2. Usar zonas de estacionamento. Se um hex está fora de qualquer zona de estacionamento válida, o fornecimento não se acumula ali e o recomendador deixa de sugerir movimentos para esse destino. Mantenha sua geometria de zonas refletindo a realidade operacional.

Pico de custo na Modal

Sintoma: Alerta de cobrança da Modal disparou.

O retreinamento noturno em todos os subaccounts deve custar ~US$ 15-30/mês na nossa escala. Picos costumam significar:

• Um subaccount com volume de features anormalmente grande domina o tempo de treino.
• A Modal escalou mais contêineres automaticamente do que o esperado.

Inspecione a tabela model_runs em busca de linhas com duration_ms excepcionalmente longas. Faça cap ou shard do subaccount afetado no script de treino.

Onde buscar ajuda

• Sentry — a maioria dos erros do AI Ops é taggeada com ai-ops. Filtre por essa tag.
• Logs de cron no Vercel — confira o status de execução dos cinco crons do AI Ops.
• Tabela model_runs — linha de auditoria por chamada de inferência, com MAPE, RMSE e duração.
• Suporte — escreva para support@levyelectric.com.