Премини към основното съдържание
Български— Изберете език
Меню

Входни данни и таймаути

Урок 9 от 14 Обновен 29 юли 2026 г. Напреднало
На тази страница
  1. Какво постъпва в работния поток
  2. Структуриране и валидиране с Pydantic
  3. Продължителност на изпълнението
  4. Две нива на таймаут, които не бива да бъркате
  5. Ключови изводи

Какво постъпва в работния поток

Всеки работен поток получава входни параметри, които дефинират неговия контекст на изпълнение. Тъй като тези параметри пътуват по мрежата и се съхраняват в дневника за изпълнение, те трябва да спазват едно строго правило: трябва да бъдат сериализируеми във формат JSON. Примитивните типове на Python преминават без проблеми, както и списъци, речници и стойности 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

Обаче datetime, bytes, set, tuple и потребителски класове, които не са на Pydantic, не се поддържат директно. Ако Вашият работен поток трябва да получи дата на фактура, конвертирайте я в низ ISO 8601, преди да я предадете, и реконструирайте обекта вътре в дейността. Този принцип важи за всички подобни типове: конвертирането е Ваша отговорност, а не на платформата.

Структуриране и валидиране с Pydantic

Предаването на речник в свободен формат работи, но губите всички гаранции относно неговото съдържание. За структурирани и валидирани параметри разчитайте на моделите на Pydantic, които документират интерфейса на работния поток толкова, колкото и го защитават.

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

От страната на извикващия няма нищо специално за правене: полетата на BaseModel просто се превръщат в ключове от най-високо ниво във входния речник.

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 автоматично валидира получените данни. Ако дадено поле е невалидно, работният поток се проваля незабавно с ясно съобщение за грешка, вместо да започне изпълнение и да се срине три дейности по-късно. Тази валидация се затяга според нуждите: ограничения за формат на имейл адрес, числови граници за приоритет и най-вече extra = "forbid", което отхвърля неизвестни полета.

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

Този последен пункт заслужава внимание. Без extra="forbid", правописна грешка в името на поле остава незабелязана: очакваното поле приема стойността си по подразбиране и работният поток се изпълнява с параметри, които не са тези, които сте планирали. Провалът е тих, следователно скъп.

Когато един единствен работен поток трябва да приема множество форми на входни данни, обединените типове (union types) Ви позволяват да опишете тези варианти, без да умножавате работните потоци.

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"

Продължителност на изпълнението

Всеки работен поток има максимална продължителност на изпълнение, зададена чрез параметъра execution_timeout. По подразбиране тя е един час: след този краен срок работният поток се отменя автоматично, независимо от напредъка му. За процес, предназначен да трае тридесет секунди, тази стойност е удобна; за пайплайн, работещ през нощта, тя е капан.

Коригирайте този таймаут според естеството на обработката, както надолу, така и нагоре. Работен поток за бърза обработка се възползва от тесен лимит, защото превишаването тогава сигнализира за реален проблем, а не за временно забавяне.

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)

В другия край на скалата,允许еният таван е 7 дни. Тази продължителност има смисъл само за процеси, чакащи външно събитие, обикновено човешко валидиране: доклад, събран автоматично, но подписан от мениджър, който няма да се върне от отпуск чак следващата седмица.

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)

За калибриране използвайте този порядък според семейството употреби.

Случай на употребаПрепоръчителен таймаут
Обработка в реално време1-5 минути
Данни пайплайн15-60 минути
Генериране на сложен доклад1-4 часа
Работен поток с човешко валидиране1-7 дни

Две нива на таймаут, които не бива да бъркате

execution_timeout ограничава целия работен поток; start_to_close_timeout ограничава една единствена дейност. Двете съществуват едновременно и се допълват: първото Ви предпазва от работен поток, който никога не завършва, второто – от дейност, заседнала на тиха услуга. Забележете в примера по-долу, че таймаутът на HTTP клиента (240 секунди) е умишлено по-нисък от start_to_close_timeout (5 минути), така че грешката да излезе на повърхността чисто, преди платформата да прекъсне връзката.

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}

Един последен рефлекс за Вашите входни данни: поддържайте ги леки. Лимитът е 2 MB и нищо не Ви принуждава да се доближавате до него. Предавайте URL адреса на документ, а не неговото съдържание, идентификатор на поръчка, а не цялата поръчка, и оставете дейностите да извличат данните. Дефинирайте стойности по подразбиране за всичко opcionално, документирайте всяко поле с Field(description="...") и възложете валидирането на Pydantic, вместо на разпръснати из целия работен поток инструкции if.

Ключови изводи

  • Входните данни на работния поток трябва да бъдат сериализируеми във формат JSON (str, int, float, bool, list, dict)
  • Използвайте Pydantic BaseModel за структурирани входни данни с автоматично валидиране
  • Таймаутът по подразбиране е 1 час, конфигурируем до максимум 7 дни
  • Различавайте таймаута на работния поток (execution_timeout) от таймаута на дейността (start_to_close_timeout)
  • Поддържайте входните данни леки: идентификатори и URL адреси вместо големи сурови данни