Przejdź do głównej treści
Polski— Wybierz język
Menu

Dane wejściowe i limity czasu

Lekcja 9 z 14 Zaktualizowano 29 lipca 2026 Zaawansowany
Na tej stronie
  1. Co trafia do workflow
  2. Strukturyzowanie i walidacja z Pydantic
  3. Czas życia wykonania
  4. Dwa poziomy limitu czasu, których nie wolno mylić
  5. Kluczowe wnioski

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życiaZalecany limit czasu
Przetwarzanie w czasie rzeczywistym1–5 minut
Potok danych15–60 minut
Generowanie złożonych raportów1–4 godziny
Workflow z walidacją przez człowieka1–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