Skip to content
forecast-engine

Previsão com fallback

Contexto operacional

Este é o fluxo que protege a plataforma durante inferência. Quando o modelo ativo falha, a engine tenta automaticamente uma versão anterior para reduzir indisponibilidade de previsão.

Caso de uso

run_forecast_with_fallback recebe:

  • RunForecastWithFallbackCommand(run=<ForecastRun>, series=<DemandSeries>)

Dependências:

  • ModelingRepositoryPort
  • ForecastingRepositoryPort
  • StrategyRegistryPort
  • ForecastObservabilityPort (opcional)
  • DomainToColumnarPort | ColumnarToDomainPort

Saída:

  • ForecastRun finalizado em COMPLETED ou FAILED.

Sequência de execução

  1. Valida correspondência command.series.key == run.series_key.
  2. Carrega ModelDefinition.
  3. Coloca run em RUNNING.
  4. Converte histórico para frame.
  5. Resolve instância ativa da série.
  6. Tenta previsão primária.
  7. Se falhar, tenta fallback com versão anterior.
  8. Persiste run com resultado final.
  9. Emite telemetria de inferência quando ForecastObservabilityPort está configurado.

Estados do ForecastRun

  • REQUESTED: run criado.
  • RUNNING: execução em andamento.
  • COMPLETED: previsão válida concluída.
  • FAILED: nenhuma execução válida possível.

Semântica de fallback degradado

Quando fallback funciona:

  • degraded = True
  • fallback_from_version = <versão ativa que falhou>
  • executed_model_version = <versão de fallback que executou>

Regras de consistência:

  • versões de fallback e execução devem ser diferentes;
  • degraded=False não permite fallback_from_version;
  • run concluído exige quantidade de pontos igual ao horizonte.

Telemetria operacional

Quando a porta de observabilidade é injetada, cada execução gera um payload com:

  • requested_model_version
  • executed_model_version
  • fallback_from_version
  • degraded
  • status
  • failure_reason
  • horizon_size
  • prediction_volume
  • duration_ms

Isso torna visível o uso de fallback sem depender de leitura direta da base de forecast runs.

Exemplo de inicialização

from domain.forecasting.model import ForecastRun
from domain.modeling.model import HorizonSpec
from domain.shared.value_objects import TimeGrain, UomCode


run = ForecastRun(
    organization_id=series.key.organization_id,
    model_definition_id=model_definition.id,
    model_version=2,
    series_key=series.key,
    horizon_spec=HorizonSpec(periods=2, grain=TimeGrain.DAILY, step=1),
    expected_uom=UomCode("EA"),
)

Falhas mais comuns

  1. Sem instância ativa para a série.
  2. artifact_uri ausente na instância usada na previsão.
  3. UOM prevista diferente da UOM esperada.
  4. Sequência temporal de pontos fora do step configurado.
  5. Execução degradada recorrente sinalizando problema do modelo ativo em produção.