Preskočiť na obsah

Úvod

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 2cc7b2b

Queuety je doplnok WordPress, ktorý poskytuje rýchly front úloh, odolný nástroj na riadenie pracovných postupov a runtime prostredie odolného stavového automatu. Pracovníci si nárokujú úlohy priamo z MySQL a spracúvajú ich v dlho bežiacom procese WP-CLI. Runtime prostredie PHP, ktoré načítava WordPress a WP-CLI, potrebuje buď mysqli, alebo pdo_mysql.

Prečo Queuety?

WordPress nemá skutočný systém úloh na pozadí. wp_cron sa spúšťa iba pri návštevách stránok. Predvolený spúšťač Action Scheduler využíva WP-Cron a požiadavky HTTP na lokálnu adresu; každú požiadavku spracúva v dávkach najviac 30 sekúnd. Volanie API od LLM, ktoré trvá 60 sekúnd, ukončí 30-sekundový časový limit PHP. Nemožno spúšťať viackrokové procesy, ktoré prežijú zlyhania a pokračujú od miesta, kde sa prerušili.

Queuety to rieši pomocou troch základných prvkov:

  1. Úlohy na prácu na pozadí bez čakania na výsledok
  2. Workflowy na trvácne viackrokové procesy s uloženým stavom
  3. Stavové automaty na dlhodobý životný cyklus riadený udalosťami

Rýchly príklad

Odošlite úlohu pomocou modernej API:

PHP
use Queuety\Contracts\Job;
use Queuety\Dispatchable;

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );

Alebo použite klasický prístup s názvom obslužnej rutiny:

PHP
use Queuety\Queuety;

Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

Spustite trvácny workflow:

PHP
Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );

Modelujte dlhotrvajúcu reláciu pomocou stavového automatu:

PHP
use Queuety\Enums\StateMachineStatus;

Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Spustite pracovníka:

Shell
wp queuety work

Ak vytvárate systém v štýle agenta, začnite témou Orchestrácia agentov. Ukazuje, ako spolu súvisia toky plánovania a vykonávania, kontrolné kroky s ľudským dohľadom a čakanie medzi workflowmi.

Ak je systém riadený udalosťami a má dlhú životnosť, okrem workflowov začnite témou Stavové automaty.

Ak hľadáte príklady integrácie od začiatku do konca, pozrite si Príklady, ktoré teraz obsahujú vzory založené na Neuron na prepínanie poskytovateľov, streamovanie, opakovanie kontroly s podporou pamäte a závislé workflowy.

Ak chcete spúšťať workflowy na základe doménových udalostí WordPress, ako je save_post, pozrite si Spúšťače akcií.

Ak chcete používať prostredie s databázou mimo WordPress, pozrite si Samostatné použitie.

Kľúčové odlišnosti

  • Rýchle vykonávanie. Pracovníci pristupujú priamo k frontu MySQL a vyhýbajú sa vzoru cron pri každej požiadavke, ktorý spomaľuje prácu na pozadí v WordPress.
  • Trvácne workflowy. Viackrokové procesy s uloženým stavom, ktoré odolávajú časovým limitom PHP, zlyhaniam a opakovaniam. Hranica každého kroku tvorí atómovú transakciu MySQL.
  • Explicitné stavové automaty. Modelujte chatovacie relácie, schvaľovania a ďalšie dlhotrvajúce životné cykly pomocou pomenovaných stavov, strážených prechodov, úloh zaradených do frontu pri vstupe do stavu a trvácnych časových osí udalostí.
  • Moderné API na odosielanie úloh API. Samostatné triedy úloh s traitom Dispatchable, typovanými vlastnosťami konštruktora ako údajmi úlohy a deklaráciami $tries/$timeout/$backoff v triede. Trieda readonly nemôže týmto vlastnostiam nastaviť predvolené hodnoty, preto ich deklarujte v bežnej triede s vlastnosťami konštruktora propagovanými ako readonly.
  • Postupnosť middleware. Middleware v štýle cibule na obmedzovanie frekvencie, tlmenie výnimiek, jedinečné úlohy a vlastnú logiku. Deklaruje sa pre každú úlohu pomocou metódy middleware().
  • Streamované kroky. Rozhranie StreamingStep poskytuje časti, ktoré sa okamžite ukladajú do databázy. Pri opakovanom pokuse sa poskytnú predtým uložené časti, takže streamovanie môže pokračovať od miesta prerušenia. Ideálne riešenie pre odpovede LLM a veľké súbory na stiahnutie.
  • Prispôsobiteľná vrstva cache. CacheFactory automaticky zistí APCu alebo použije záložnú vyrovnávaciu pamäť v pamäti. Vlastné úložiská implementujú Contracts\Cache. Používa sa interne pri vyhľadávaní obmedzovačov frekvencie a stavu frontov.
  • Dávkovanie a reťazenie. Odosielajte skupiny úloh s callbackmi then/catch/finally a sledovaním priebehu alebo reťazte úlohy postupne tak, že každá závisí od dokončenia predchádzajúcej.
  • Trvácne oneskorenia a čakanie. delay() pridáva oneskorenia bezpečné pri reštarte procesu. wait_for_signal(), wait_for_signals(), wait_for_approval(), wait_for_input() a wait_for_workflow() umožňujú workflowom čakať na externé udalosti alebo iné workflowy bez toho, aby proces PHP musel zostať spustený.
  • Dynamický cyklus for-each. for_each() rozširuje vetvy práce zistené za behu na základe stavu workflowu a podporuje režimy dokončenia: všetky úspešné, prvý úspešný a kvórum.
  • Asynchrónne odovzdávanie medzi workflowmi. start_workflows() mení položky zistené za behu na nezávislé workflowy najvyššej úrovne, na ktoré možno čakať neskôr.
  • Spúšťače akcií WordPress. on_action() mapuje hooky akcií jadra alebo pluginov na spustenia trvácnych workflowov s podmienkami a idempotenciou.
  • Trvácne artefakty. Ukladajte pomenované výstupy workflowov mimo hlavného úložiska stavu a zahrňte ich do prehľadu stavu, kontroly CLI, exportu a prehrávania.
  • Ochranné prvky workflowov. version(), deterministický hash definície, idempotentné kľúče odoslania a rozpočty workflowov uľahčujú kontrolu behov v štýle agentov a pomáhajú predísť ich duplikovaniu či nekontrolovanému predlžovaniu.
  • Správa zdrojov. Skupiny súbežnosti, nákladové jednotky, rozpočty workflowov a prijímanie úloh pracovníkmi pomáhajú udržať náročnú prácu v štýle agentov v stanovených medziach.
  • Kompenzácia krokov. compensate_with() a compensate_on_failure() poskytujú hooky na vrátenie dokončených krokov späť pri zrušení alebo zlyhaní workflowov.
  • Signály aktivity. Dlho bežiace kroky odosielajú signály aktivity, aby systém obnovy zastaraných úloh neprevzal aktívnu prácu.
  • Sledovanie workflowov. Každý prechod kroku sa zaznamenáva spolu so vstupom, výstupom, stavom pred a po zmene, kontextom, artefaktmi, časťami, chybami a ladením s prechodom v čase pomocou workflow_state_at().
  • Paralelné kroky. Spúšťajte kroky súbežne a pred pokračovaním čakajte na dokončenie všetkých.
  • Podmienené vetvenie. Pomocou _next_step preskočte na pomenované kroky podľa predchádzajúceho stavu.
  • Spúšťanie workflowov. Spúšťajte podriadené workflowy, ktoré vracajú výsledky nadradenému workflowu.
  • Fronty s prioritou. Štyri úrovne (Low, Normal, High, Urgent) prostredníctvom typovo bezpečných enumov PHP.
  • Pracovníci pre viacero frontov. Spracúvajte viacero frontov s prísnym poradím priorít v jednom pracovníkovi.
  • Obmedzovanie frekvencie. Limity vykonávania pre jednotlivé obslužné rutiny s posuvným časovým oknom.
  • Opakované úlohy. Plánovanie na základe intervalu a cron s konfigurovateľnými pravidlami prekrývania (Povoliť, Preskočiť, Uložiť do frontu).
  • Zrušenie workflowov. Zrušte spustené workflowy a aktivujte zaregistrované obslužné rutiny na vyčistenie.
  • Prečisťovanie stavu. Automaticky odstraňujte staré výstupy krokov, aby sa dal spravovať rozsiahly stav workflowov.
  • Súbežnosť pracovníkov. --workers=N vytvára viacero procesov a po zlyhaní ich automaticky reštartuje.
  • Úplný prehľad. Zaznamenávanie do databázy, metriky pre jednotlivé obslužné rutiny a webhooky udalostí.
  • Pomôcky na testovanie. QueueFake zaznamenáva odoslané úlohy a dávky, aby sa dali overovať tvrdenia v jednotkových testoch.
  • Atribúty PHP. #[QueuetyHandler('name')] na registráciu obslužných rutín bez konfigurácie.

Ako to funguje

Pracovníci bežia v dlhodobo spustenom procese WP-CLI a preberajú úlohy priamo z MySQL. Riadky frontu, stav pracovného postupu, záznamy, dávky, signály aj časti streamu sú uložené v MySQL, takže reštart pracovníkov nespôsobí stratu stavu orchestrácie.

Pracovné postupy rozdeľujú dlhotrvajúcu prácu na kroky. Každý krok uloží svoj výstup do zdieľaného objektu stavu v databáze. Ak PHP počas kroku zlyhá, pracovník tento krok zopakuje a zachová celý predchádzajúci stav. Hranicu kroku tvorí jediná transakcia MySQL: aktualizácia stavu, dokončenie úlohy aj zaradenie ďalšieho kroku do frontu prebehnú atómovo.

Kód
Workflow: generate_report (3 steps)

Step 0: fetch_data     -> state: {user_data: {...}}
Step 1: call_llm       -> PHP dies -> retry -> state: {user_data: {...}, llm_response: "..."}
Step 2: format_output  -> state: {user_data: {...}, llm_response: "...", report_url: "/reports/42.pdf"}

Workflow: completed

Požiadavky

  • PHP 8.2 alebo novšia
  • WordPress 6.4 alebo novšia
  • MySQL 8.0+ alebo MariaDB 10.6+, pretože pracovníci preberajú úlohy pomocou SELECT ... FOR UPDATE SKIP LOCKED
  • mysqli alebo pdo_mysql v prostredí PHP, ktoré načítava WordPress a WP-CLI
  • WP-CLI na spúšťanie vyhradených pracovníkov s wp queuety work
  • Rozšírenia pcntl a posix PHP pre skupiny pracovníkov (--workers, --min-workers, --max-workers)

Inštaláciu nájdete v časti Začíname.