Dane wejściowe i limity czasu
Na tej stronie
Co trafia do workflow
Każde workflow otrzymuje parametry wejściowe definiujące jego kontekst wykonania. Ponieważ parametry te są przesyłane przez sieć i zapisywane w dzienniku wykonania, muszą one spełniać jedną ścisłą regułę: muszą być serializowalne do formatu JSON. Typy prymitywne Pythona przechodzą bez problemu, podobnie jak listy, słowniki i wartości null.
# Primitive types
nom: str = "Marie"
age: int = 32
score: float = 0.95
actif: bool = True
# Collections
tags: list = ["urgent", "client-vip"]
metadata: dict = {"source": "api", "version": 2}
# Nullable
commentaire: str | None = None
Jednakże typy datetime, bytes, set, tuple oraz niestandardowe klasy inne niż Pydantic nie są bezpośrednio obsługiwane. Jeśli Twoje workflow musi otrzymać datę faktury, przekonwertuj ją najpierw na ciąg znaków w formacie ISO 8601 przed przekazaniem, a następnie zrekonstruuj obiekt wewnątrz aktywności. Zasada ta dotyczy wszystkich takich typów: konwersja leży po Twojej stronie, a nie platformy.
Strukturyzowanie i walidacja z Pydantic
Przekazywanie luźnego słownika działa, ale tracisz wszelkie gwarancje co do jego zawartości. W przypadku strukturyzowanych, zwalidowanych parametrów polegaj na modelach Pydantic, które dokumentują interfejs workflow tak samo skutecznie, jak go chronią.
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
Po stronie wywołującego nie musisz robić niczego specjalnego: pola modelu BaseModel po prostu stają się kluczami najwyższego poziomu w słowniku wejściowym.
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
}
)
Pydantic automatycznie waliduje otrzymane dane. Jeśli pole jest nieprawidłowe, workflow natychmiast kończy się niepowodzeniem z czytelnym komunikatem błędu, zamiast rozpoczynać wykonanie i awariować trzy aktywności później. Walidację można zaostrzać w miarę potrzeb: ograniczenia formatu dla adresu e-mail, granice liczbowe dla priorytetu, a przede wszystkim extra = "forbid", które odrzuca nieznane pola.
class ParametresStricts(BaseModel):
email: str = Field(pattern=r"^[\w.+-]+@[\w-]+\.[\w.]+$")
priorite: int = Field(ge=1, le=5)
class Config:
extra = "forbid" # Rejects unknown fields
Ostatni punkt zasługuje na szczególną uwagę. Bez extra="forbid" literówka w nazwie pola pozostaje niezauważona: oczekiwane pole przyjmuje wartość domyślną, a workflow uruchamia się z parametrami innymi niż zamierzałeś. Awaria jest cicha, a więc kosztowna.
Gdy pojedyncze workflow musi akceptować wiele form danych wejściowych, typy unii pozwalają opisać te warianty bez mnożenia liczby workflow.
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"
Czas życia wykonania
Każde workflow ma maksymalny czas wykonania ustawiany za pomocą parametru execution_timeout. Domyślnie wynosi on jedną godzinę: po upływie tego terminu workflow jest automatycznie anulowane, niezależnie od postępu. Dla procesu trwającego trzydzieści sekund wartość ta jest komfortowa; dla potoku działającego przez całą noc stanowi pułapkę.
Dostosuj ten limit czasu do charakteru przetwarzania, zarówno w dół, jak i w górę. Workflow przetwarzające szybko zyskuje na ścisłym limicie, ponieważ jego przekroczenie sygnalizuje wtedy rzeczywisty problem, a nie chwilowe spowolnienie.
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)
Z drugiej strony, dopuszczalny maksymalny czas to 7 dni. Taki okres ma sens tylko w procesach oczekujących na zdarzenie zewnętrzne, typowo walidację przez człowieka: raport zbierany automatycznie, ale podpisywany przez menedżera, który wróci z urlopu dopiero w przyszłym tygodniu.
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:
# This workflow can last up to 7 days
# Useful for processes with human waiting periods
donnees = await collecter_donnees_multi_sources(params)
validation = await attendre_validation_humaine(donnees)
return await finaliser_rapport(validation)
Aby dobrać odpowiednią wartość, kieruj się następującymi rzędami wielkości w zależności od rodzaju zastosowania.
| Przypadek użycia | Zalecany limit czasu |
|---|---|
| Przetwarzanie w czasie rzeczywistym | 1–5 minut |
| Potok danych | 15–60 minut |
| Generowanie złożonych raportów | 1–4 godziny |
| Workflow z walidacją przez człowieka | 1–7 dni |
Dwa poziomy limitu czasu, których nie wolno mylić
execution_timeout ogranicza całe workflow; start_to_close_timeout ogranicza pojedynczą aktywność. Obie wartości współistnieją i uzupełniają się: pierwsza chroni przed workflow, które nigdy się nie kończy, druga przed aktywnością zawieszoną na cichej usłudze. Zauważ w poniższym przykładzie, że limit czasu klienta HTTP (240 sekund) jest celowo niższy niż start_to_close_timeout (5 minut), dzięki czemu błąd pojawia się czysto, zanim platforma przerwie połączenie.
from datetime import timedelta
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5)
)
async def appel_api_externe(params: dict) -> dict:
# This activity has 5 minutes to complete
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:
# The entire workflow has 2 hours
# But each individual activity has its own timeout
resultats = []
for source in sources:
resultat = await appel_api_externe(source)
resultats.append(resultat)
return {"résultats": resultats}
Jeszcze jedna zasada dotycząca danych wejściowych: utrzymuj je w lekkiej formie. Limit wynosi 2 MB i nic nie zmusza Cię, aby się do niego zbliżać. Przekaż URL dokumentu zamiast jego treści, identyfikator zamówienia zamiast pełnego zamówienia i pozwól aktywnościom pobrać dane. Zdefiniuj wartości domyślne dla wszystkiego, co opcjonalne, udokumentuj każde pole za pomocą Field(description="...") i powierz walidację Pydantic zamiast rozrzucać instrukcje if po całym workflow.
Kluczowe wnioski
- Dane wejściowe workflow muszą być serializowalne do JSON (str, int, float, bool, list, dict)
- Używaj Pydantic BaseModel do strukturyzowanych danych wejściowych z automatyczną walidacją
- Domyślny limit czasu to 1 godzina, konfigurowalny do maksimum 7 dni
- Rozróżniaj limit czasu workflow (
execution_timeout) od limitu czasu aktywności (start_to_close_timeout) - Utrzymuj dane wejściowe w lekkiej formie: identyfikatory i URL-e zamiast dużych, surowych danych