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

Entradas e tempos limite

Aula 9 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. O que entra num workflow
  2. Estruturar e validar com Pydantic
  3. Tempo de vida da execução
  4. Dois níveis de tempo limite para não confundir
  5. Pontos-chave

O que entra num workflow

Cada workflow recebe parâmetros de entrada que definem o seu contexto de execução. Como estes parâmetros viajam pela rede e são armazenados no registo de execução, devem obedecer a uma regra estrita: têm de ser serializáveis em JSON. Os tipos primitivos do Python passam sem problemas, tal como listas, dicionários e valores nulos.

# Tipos primitivos
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True

# Coleções
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}

# Nulos
commentaire: str | None = None

No entanto, datetime, bytes, set, tuple e classes personalizadas não-Pydantic não são suportados diretamente. Se o seu workflow precisar de receber uma data de fatura, converta-a para uma cadeia ISO 8601 antes de a passar e reconstrua o objeto dentro da atividade. Este princípio aplica-se a todos esses tipos: a conversão é da sua responsabilidade, não da plataforma.

Estruturar e validar com Pydantic

Passar um dicionário de forma livre funciona, mas perde todas as garantias sobre o seu conteúdo. Para parâmetros estruturados e validados, recorra a modelos Pydantic, que documentam a interface do workflow tanto quanto a protegem.

from pydantic import BaseModel, Field

class ParametresAnalyse(BaseModel):
    url_document: str
    langue: str = "fr"
    max_tokens: int = Field(default=1000, ge=100, le=10000)
    inclure_metadata: bool = False

@workflows.workflow.define(name="analyse_documentaire")
class AnalyseDocumentaire:
    @workflows.workflow.entrypoint
    async def run(self, params: ParametresAnalyse) -> dict:
        extraction = await extraire_texte(params.url_document, params.langue)
        analyse = await analyser_contenu(extraction["texte"], params.max_tokens)
        
        if params.inclure_metadata:
            metadata = await extraire_metadata(params.url_document)
            return {**analyse, "metadata": metadata}
        
        return analyse

Do lado do chamador, não há nada de especial a fazer: os campos do BaseModel tornam-se simplesmente chaves de nível superior no dicionário de entrada.

execution = await client.workflows.execute_workflow_async(
    workflow_identifier="analyse_documentaire",
    input={
        "url_document": "https://example.com/rapport.pdf",
        "langue": "fr",
        "max_tokens": 2000,
        "inclure_metadata": True
    }
)

O Pydantic valida automaticamente os dados recebidos. Se um campo for inválido, o workflow falha imediatamente com uma mensagem de erro explícita, em vez de iniciar a execução e falhar três atividades depois. Esta validação aperta-se conforme necessário: restrições de formato num endereço de e-mail, limites numéricos numa prioridade e, acima de tudo, extra = "forbid", que rejeita campos desconhecidos.

class ParametresStricts(BaseModel):
    email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
    priorite: int = Field(ge=1, le=5)

    class Config:
        extra = "forbid"  # Rejeita campos desconhecidos

Este último ponto merece atenção. Sem extra="forbid", um erro ortográfico num nome de campo passa despercebido: o campo esperado assume o seu valor padrão e o workflow executa com parâmetros que não são os que pretendia. A falha é silenciosa, logo, dispendiosa.

Quando um único workflow deve aceitar múltiplas formas de entrada, os tipos de união permitem descrever estas variantes sem multiplicar workflows.

from typing import Union

class TraitementTexte(BaseModel):
    texte: str
    type_traitement: str = "resume"

class TraitementURL(BaseModel):
    url: str
    type_traitement: str = "resume"

class ParametresFlexibles(BaseModel):
    source: Union[TraitementTexte, TraitementURL]

    class Config:
        extra = "forbid"

Tempo de vida da execução

Cada workflow tem uma duração máxima de execução, definida pelo parâmetro execution_timeout. Por predefinição, é de uma hora: passado este prazo, o workflow é cancelado automaticamente, independentemente do seu progresso. Para um processo destinado a durar trinta segundos, este valor é confortável; para um pipeline noturno, é uma armadilha.

Ajuste este tempo limite à natureza do processamento, tanto para baixo como para cima. Um workflow de processamento rápido beneficia de um limite apertado, porque um excedente sinaliza então um problema real e não uma desaceleração temporária.

from datetime import timedelta

@workflows.workflow.define(
    name="traitement_rapide",
    execution_timeout=timedelta(minutes=10)
)
class TraitementRapide:
    @workflows.workflow.entrypoint
    async def run(self, donnees: dict) -> dict:
        return await traiter(donnees)

Na outra extremidade, o teto permitido é de 7 dias. Esta duração só faz sentido para processos à espera de um evento externo, tipicamente uma validação humana: um relatório recolhido automaticamente, mas assinado por um gestor que só regressa de férias na semana seguinte.

from datetime import timedelta

@workflows.workflow.define(
    name="workflow_longue_duree",
    execution_timeout=timedelta(days=7)
)
class WorkflowLongueDuree:
    @workflows.workflow.entrypoint
    async def run(self, params: dict) -> dict:
        # Este workflow pode durar até 7 dias
        # Útil para processos com períodos de espera humana
        donnees = await collecter_donnees_multi_sources(params)
        validation = await attendre_validation_humaine(donnees)
        return await finaliser_rapport(validation)

Para calibrar, utilize esta ordem de grandeza por família de utilização.

Caso de usoTempo limite recomendado
Processamento em tempo real1-5 minutos
Pipeline de dados15-60 minutos
Geração de relatórios complexos1-4 horas
Workflow com validação humana1-7 dias

Dois níveis de tempo limite para não confundir

execution_timeout limita todo o workflow; start_to_close_timeout limita uma única atividade. Os dois coexistem e complementam-se: o primeiro protege-o de um workflow que nunca termina, o segundo de uma atividade bloqueada num serviço silencioso. Note no exemplo abaixo que o tempo limite do cliente HTTP (240 segundos) é intencionalmente inferior ao start_to_close_timeout (5 minutos), para que o erro surja limpa e claramente antes de a plataforma cortar a ligação.

from datetime import timedelta

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
    # Esta atividade tem 5 minutos para concluir
    async with httpx.AsyncClient(timeout=240) as client:
        response = await client.post(params["url"], json=params["data"])
    return response.json()

@workflows.workflow.define(
    name="pipeline_multi_etapes",
    execution_timeout=timedelta(hours=2)
)
class PipelineMultiEtapes:
    @workflows.workflow.entrypoint
    async def run(self, sources: list) -> dict:
        # Todo o workflow tem 2 horas
        # Mas cada atividade individual tem o seu próprio tempo limite
        resultats = []
        for source in sources:
            resultat = await appel_api_externe(source)
            resultats.append(resultat)
        return {"résultats": resultats}

Um último reflexo para as suas entradas: mantenha-as leves. O limite é de 2 MB e nada o obriga a aproximar-se dele. Passe o URL de um documento em vez do seu conteúdo, um ID de encomenda em vez da encomenda completa e deixe as atividades irem buscar os dados. Defina valores padrão para tudo o que for opcional, documente cada campo com Field(description="...") e confie a validação ao Pydantic em vez de instruções if espalhadas pelo workflow.

Pontos-chave

  • As entradas do workflow devem ser serializáveis em JSON (str, int, float, bool, list, dict)
  • Utilize Pydantic BaseModel para entradas estruturadas com validação automática
  • O tempo limite padrão é de 1 hora, configurável até um máximo de 7 dias
  • Distinga o tempo limite do workflow (execution_timeout) do tempo limite da atividade (start_to_close_timeout)
  • Mantenha as entradas leves: IDs e URLs em vez de grandes volumes de dados brutos