Ir para o conteúdo principal
Português— Escolher um idioma
Menu

A Regra do Determinismo

Aula 8 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Por que o Determinismo é Obrigatório
  2. Como Isto Se Traduz no Código
  3. Substituições no SDK
  4. O Limite a Recordar
  5. Diagnosticar um Erro de Não Determinismo
  6. Pontos-chave

Por que o Determinismo é Obrigatório

O determinismo é a restrição mais crítica nos fluxos de trabalho do Mistral e decorre diretamente do mecanismo de repetição (replay) que aprendeu anteriormente. Quando um worker retoma um fluxo de trabalho interrompido, ele executa novamente o código do fluxo desde o início e compara, operação por operação, o que o código produz com o que o registo histórico (journal) registou. Enquanto as duas sequências coincidirem, a retomada é invisível. No momento em que divergem, a plataforma não tem como saber onde parou: deteta a inconsistência e falha o fluxo de trabalho com um erro de não determinismo.

Na prática, um fluxo de trabalho determinístico produz exatamente a mesma sequência de operações sempre que é executado com as mesmas entradas. Note a nuance: os resultados das atividades podem variar entre execuções, uma vez que provêm do registo histórico. É a ordem das chamadas que deve permanecer idêntica.

Como Isto Se Traduz no Código

Considere um fluxo de trabalho que envia um relatório a um utilizador com base no estado da sua subscrição.

@workflows.workflow.define(name="deterministic_workflow")
class DeterministicWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, user_id: str) -> dict:
        # Sempre a mesma sequência de chamadas para a mesma entrada
        profile = await get_profile(user_id)
        
        if profile["premium"]:
            report = await generate_full_report(user_id)
        else:
            report = await generate_basic_report(user_id)
        
        await send_email(profile["email"], report)
        return {"status": "completed"}

Este fluxo de trabalho é determinístico, embora contenha uma ramificação. A razão reside na origem da condição: profile["premium"] provém do resultado de uma atividade, logo, vem do registo histórico. Durante a repetição, get_profile devolve exatamente o mesmo valor que na primeira execução e o mesmo caminho é percorrido.

Compare agora com esta versão, que parece inofensiva mas quebra tudo.

import datetime
import random

@workflows.workflow.define(name="non_deterministic_workflow")
class NonDeterministicWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, user_id: str) -> dict:
        # PROIBIDO: datetime.now() muda em cada execução
        if datetime.datetime.now().hour < 12:
            await send_morning_email(user_id)
        else:
            await send_afternoon_email(user_id)
        
        # PROIBIDO: random.random() produz um resultado diferente sempre
        if random.random() > 0.5:
            await send_notification(user_id)
        
        return {"status": "completed"}

Imagine que o worker falha às 11:58 e reinicia às 12:03. Na repetição, datetime.now() devolve uma hora da tarde, enquanto o histórico contém uma chamada a send_morning_email. O fluxo de trabalho falha. random.random() produz o mesmo efeito, apenas mais difícil de diagnosticar.

Substituições no SDK

O SDK não proíbe apenas estas chamadas; fornece equivalentes determinísticos para as três operações mais comuns.

from mistralai.workflows import workflow

# Obter a hora atual (determinístico durante a repetição)
current_time = workflow.now()          # Em vez de datetime.now()

# Gerar um ID único (determinístico durante a repetição)
request_id = workflow.uuid4()          # Em vez de uuid.uuid4()

# Obter um número aleatório (determinístico durante a repetição)
rand_value = workflow.random()         # Em vez de random.random()

O princípio é o mesmo que para as atividades: o valor é calculado e registado no histórico na primeira execução, sendo depois simplesmente repetido. O exemplo anterior torna-se então perfeitamente seguro.

import mistralai.workflows as workflows
from mistralai.workflows import workflow

@workflows.workflow.define(name="fixed_workflow")
class FixedWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, user_id: str) -> dict:
        # CORRETO: workflow.now() é determinístico durante a repetição
        current_hour = workflow.now()
        if current_hour.hour < 12:
            await send_morning_email(user_id)
        else:
            await send_afternoon_email(user_id)
        
        # CORRETO: workflow.random() é determinístico durante a repetição
        if workflow.random() > 0.5:
            await send_notification(user_id)
        
        # CORRETO: workflow.uuid4() é determinístico durante a repetição
        trace_id = workflow.uuid4()
        await log_trace(str(trace_id), user_id)
        
        return {"status": "completed", "trace_id": str(trace_id)}

O Limite a Recordar

As seguintes operações são proibidas no código do fluxo de trabalho: datetime.now(), datetime.utcnow() e time.time(); uuid.uuid4() e uuid.uuid1(); random.random(), random.randint() e random.choice(); qualquer chamada de rede direta (httpx, aiohttp, requests); qualquer leitura ou escrita de ficheiros (open(), aiofiles); qualquer acesso à base de dados; os.environ, porque as variáveis de ambiente podem mudar entre repetições; e finalmente threading e multiprocessing, uma vez que a plataforma gere o paralelismo interno.

Tudo o que for reproduzível permanece permitido: chamar atividades via await, usar workflow.now(), workflow.uuid4() e workflow.random(), escrever lógica condicional ou loops cujas condições dependam de resultados de atividades, manipular dados em memória (cálculos, strings) e fazer logging — o logging é considerado um efeito colateral aceitável.

Diagnosticar um Erro de Não Determinismo

Quando o erro ocorre, quatro verificações são geralmente suficientes para o localizar.

  1. Presença de chamadas não determinísticas — Procure por datetime.now, uuid.uuid4, random.random no código do fluxo de trabalho
  2. I/O direto — Qualquer chamada de rede ou de ficheiro deve residir numa atividade
  3. Variáveis de ambiente — Se usar os.environ para ramificação, mova a leitura para uma atividade
  4. Bibliotecas de terceiros — Algumas bibliotecas fazem chamadas de rede ou usam aleatoriedade internamente

Este último ponto é o mais insidioso: uma biblioteca de serialização que ordena por um ID gerado aleatoriamente, ou um cliente HTTP instanciado no carregamento do módulo, pode fazer falhar uma repetição sem que uma única linha suspeita apareça no seu fluxo de trabalho.

A defesa mais eficaz consiste em manter o fluxo de trabalho o mais leve possível e empurrar toda a lógica complexa para as atividades. Um fluxo de trabalho que simplesmente encadeia três chamadas não tem mecanicamente qualquer oportunidade de ser não determinístico.

# MELHOR PRÁTICA: fluxo de trabalho simples, lógica nas atividades
@workflows.workflow.define(name="simple_pipeline")
class SimplePipeline:
    @workflows.workflow.entrypoint
    async def run(self, params: dict) -> dict:
        step1 = await prepare_data(params)
        step2 = await process_data(step1)
        step3 = await finalize(step2)
        return step3

Pontos-chave

  • O código do fluxo de trabalho deve ser determinístico: mesmas entradas = mesma sequência de operações
  • Use workflow.now(), workflow.uuid4(), workflow.random() em vez dos equivalentes padrão do Python
  • Todas as operações de I/O (rede, ficheiro, BD) devem residir numa atividade, nunca no fluxo de trabalho
  • Ramificações condicionais são permitidas se dependerem de resultados de atividades
  • Uma violação do determinismo faz com que o fluxo de trabalho falhe durante a repetição
  • Em caso de dúvida, mova a lógica para uma atividade