Entradas e tempos limite
Nesta página
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 uso | Tempo limite recomendado |
|---|---|
| Processamento em tempo real | 1-5 minutos |
| Pipeline de dados | 15-60 minutos |
| Geração de relatórios complexos | 1-4 horas |
| Workflow com validação humana | 1-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