diffusers-workflow 0.11.0__py3-none-any.whl → 0.11.1__py3-none-any.whl

{diffusers_workflow-0.11.0.dist-info → diffusers_workflow-0.11.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffusers-workflow
-Version: 0.11.0
+Version: 0.11.1
 Summary: Declarative workflow engine and web UI for Hugging Face Diffusers
 Author: dkackman
 License: Apache-2.0

{diffusers_workflow-0.11.0.dist-info → diffusers_workflow-0.11.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-diffusers_workflow-0.11.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+diffusers_workflow-0.11.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
 dw/__init__.py,sha256=YKwvXdngbW8iY6xFcfVwDCeiD_oFyCdWb-rRVUogp0Y,19969
 dw/adapter_compatibility.py,sha256=MzNfxK-yOBrn6Mp90m_i_QY-N4zz4C0ZCvKIByUpXAw,10674
 dw/argument_media.py,sha256=fIsvlDRCuTz_DPH4MXFxBZiKTQfgR1vY0-wTU5P9p-I,15145
@@ -30,13 +30,13 @@ dw/log_setup.py,sha256=ATwSO0CCDtgEA-VoPsS8HVeuDwL2jBg--4QXSZwecQs,1478
 dw/lora_catalog.py,sha256=B6RRgdyY0NSCyAwMVoDS3_wxyqF9i3Q3JjEx-hCMVAI,4893
 dw/lora_catalog_schema.json,sha256=i-oh9JR8DbKoNxZ2ufnyPaTaNT8hpeY_I6I3Zrhrl_w,2120
 dw/lora_hub.py,sha256=Px2cV9yAQsKve6WZuvuQCOfgLWjJ1bJx0uDbxeK2kmQ,8500
-dw/media.py,sha256=rRxEDLvj1u_KU9XyLrXihVbbumXSJLvMGzAnWNksf5I,42281
+dw/media.py,sha256=bfMHKcqE-STfyS6szwOR0jwpGZjgfwOONqEQF5X9Ul4,43047
 dw/media_frames.py,sha256=2WLLU4Z1NgN4rTxSVDHDs5VZVQqbHXMtOz-ekvonoAA,12789
 dw/media_types.py,sha256=GFnWr8Eq6jU1Y-wccXDKFO5MX-oePAjj8RsE23wvsp8,9770
 dw/outbound.py,sha256=Noaerzmzz-n23JGe9ciMuvo8QQZO-SBOK_gyFXB22Do,20508
 dw/output_extraction.py,sha256=m_uppccZeGPF2lb8UQLCrLHH1PQxmSniB8fuT5TMm_E,10341
 dw/path_redaction.py,sha256=GnZ154Q4X_bvmQEjTVvgcMmlnz1g8N6VkDLj91lLREM,4324
-dw/pipeline_ownership.py,sha256=rmdsYvbp7JqoHcZYl2HLNDgzSOUUozGjqWBLJTrnIKk,13078
+dw/pipeline_ownership.py,sha256=wFzGE6H6tq-2Bzg0EcHkVaNgUU8f_V3HbMMfs1X5woM,13964
 dw/plan.py,sha256=PMu9bRE2tmY69ux6TOwa61f6WHsnC55blS95wZr9r8g,44509
 dw/previous_results.py,sha256=0ReOCNwkHVFhP9VIErvsREVVu3a9RItC33vxhqp4tYw,17361
 dw/probe_paths.py,sha256=iJgy4G256zELyzi4Aol4_qifejjZsUtdeEEDWryAB0o,2683
@@ -60,7 +60,7 @@ dw/shot_span_preflight.py,sha256=AZP1VY_J9KdjoGdgr3k-H149ojIQr00e6um3XXO3Ga8,431
 dw/shots.py,sha256=mLDI_FXHvrG8gIMcY_gJGDLMSUAB8xAomogjA66gcno,21616
 dw/slice_preflight.py,sha256=IJ1NWZPfFBgz_YKU8CvHilasAa6nEIUGu3XW8Vf4gHY,7492
 dw/step.py,sha256=ReYYvfQUKDVtSJ2bcShHDJEmga0YunRIYQV0k1ySSKc,10259
-dw/step_cache.py,sha256=aT51amck-da2_mOwYRCQXHkJAJJHLh0XPdivn2P8PWc,29096
+dw/step_cache.py,sha256=VDJSH5W6ItzKzFzy0e5rEu7_Rt08WpzXJoyAgaZVbhU,33264
 dw/step_value_checks.py,sha256=60yn46QKVCq4uYwFwkT7z1LB-1C4PpnttlB3m-Yjiag,14212
 dw/subfolders.py,sha256=ZRRxMhHk1Yha9yt_5C_kJfe1YBWJYRba5n2w6Nx30xw,3738
 dw/task_domains.py,sha256=cxfTaECzTOCrFNZQdzgVme6yYk5Hr-P-nHnO8n_zTBo,35379
@@ -78,46 +78,46 @@ dw/video_size_errors.py,sha256=X6F0LukghxPbOonc7iKVfMNPig2Oiq4sghhhZsR1a4Y,4465
 dw/vram_estimate.py,sha256=eTOE9B_9G6sVjZj7mBp0HyxPi09C_uEjQm-qV-hfVOU,22790
 dw/vram_inheritance.py,sha256=JryUJ9k8DduQLKfX2MUkQDea7GsuRYdOty5_qHve2Fc,8369
 dw/window_count_errors.py,sha256=GIifaclu65kV0eiQFP1cscUuHJab80S3KFdP4Beho9k,4876
-dw/worker.py,sha256=I0KyzP5aHzubZFwkUd42iEtdMbruoFlc--JVNe-GzJc,35252
+dw/worker.py,sha256=uh2DIBYxFIOT6vL8j3bxgdsmBUp-jqlZ-NOPmU8cMXA,37032
 dw/worker_manager.py,sha256=MgGZKf_49R8VbyVc5iQrGvCB2PM-rw-J44TyggaTp1Y,12046
 dw/worker_protocol.py,sha256=lz1__T2l6RB72_F7D9atLhEmKOtP7ae0Hydc0TrYTFE,6585
-dw/workflow.py,sha256=DGnzzh3mMiop3stp8-y4CqymIYHnUq0mJM6fwnReMGY,40176
-dw/workflow_run.py,sha256=FiiOu03NXq0w50w-DO1Pw5YIIqP_NP3BWT0vHYaTw0c,41042
+dw/workflow.py,sha256=OyGzzZwtMeF4TLsHuqMTJXsSF1sKNqqNN4sizUjroQc,40640
+dw/workflow_run.py,sha256=PzLhl-4ScKydyAwKtSeKnyYgtSOwpevwW2HrGjBw4cI,42778
 dw/workflow_schema.json,sha256=45oJbjnf3VDor5ZJi00-JJHDKSIduGO9OgD9gFNTjkc,71690
 dw/workspace.py,sha256=8OdAqHjIZGX8MLpuNqzEZcowFXNnHC9kKZot4KNUyyE,25831
 dw/writers.py,sha256=S2-c1zitCHrH7UY8r_O5AmpNFc1eB2IErbAOeSNeWI0,15427
 dw/community_pipelines/pipeline_flux_rf_inversion.py,sha256=XjLO58h5wQn16qP8wEIZKg2Y46mxzQ8qkUu29iQnrrA,50587
 dw/community_pipelines/pipeline_ltx2_refine.py,sha256=kvDBeiaDvt_BX2AjbN6nnYN0EZsEvMzvSC6WzorA_48,6619
-dw/docs/ACCELERATION.md,sha256=UxPUcxPWniJ0zN2Xn3HaPnV9DNhOGZGEswPNS0901-0,18509
+dw/docs/ACCELERATION.md,sha256=qXqaOROm1RTjYATf1l3kEAnTdcy8aFM6bFCBmRmbI9c,19832
 dw/docs/AGENT_LOOP.md,sha256=rMb_c_r2ucsB7djwtQdp9_VVRagvhevWo-Iep7emmS8,4729
 dw/docs/ARCHITECTURE.md,sha256=WxoTTCSf1oTHdKGij27vL8Irghn5gKvCQ87981lDCUs,62415
 dw/docs/DEPENDENCIES.md,sha256=FKkPm98UeXYBcf26MUpaXkOeoeu3ADyMsC3oP3B4bn4,4455
 dw/docs/IP_ADAPTER.md,sha256=AAHaUIfbnOojHfT0noIeypbhdYPluR7sbZeVn5FpbjU,3730
-dw/docs/LORAS.md,sha256=lwug-7yQp7O1AHJfzv5jzvH8Vta4KMAt5G8m6khyMH8,6895
+dw/docs/LORAS.md,sha256=iIdMH50hnZtspzG6fXkCkm5-wVmEncb2SvX8SfZyLik,7093
 dw/docs/MCP.md,sha256=_mja-bGds4S4bXHuasTxON1kttOE2RCp86wlRw7Iaok,57495
 dw/docs/PROMPT_WEIGHTING.md,sha256=Pvr25d3yvS8SlnYwX9qc61VvTa8yFMxK_1zMLvrEigI,3031
 dw/docs/QUANTIZATION.md,sha256=NZCL-09bDM-JhzV1WqK2JGkL1la8VoH9fie1X39arsE,7678
-dw/docs/RECIPES_24GB.md,sha256=Wy0clDoGhALMbYzO4nWxt-A63rqy7OppU5I-h77EPDo,16134
-dw/docs/RELEASING.md,sha256=KUA9N0LotzP-EnrUltF9OAlUin4q9lG3rvp1yTr7GtU,51857
+dw/docs/RECIPES_24GB.md,sha256=Xu0JNK-PkTnoK0of_0CbjFn-oteVWg2OHNkJ8wLFifE,18867
+dw/docs/RELEASING.md,sha256=7F5be8jR8u_cIa0TvDgJLSFwHVLpxG-9VbaM7Xuu9Tc,54218
 dw/docs/REMOTE.md,sha256=quum2Y54g2bp2rgXg9WkSPY3zhVGHEpMkEAiL6oAQDU,6650
 dw/docs/SECURITY.md,sha256=Y8eIMvJrYPmK6KsMQ9TY6UGE_IjwTU-8EuE13Ikc2uU,20002
 dw/docs/SECURITY_QUICKREF.md,sha256=-xZNIV6j1oWcoy5B-oHKqh3ko2zJgB2fuNMiDV4f1zY,3537
-dw/docs/SERVER.md,sha256=LDZXkxvg-DiRMgCxtvtpa8obeQVprNHpVn5X0VmAN78,57277
-dw/docs/TASKS.md,sha256=afCTS8bdw4r4KsBxjaGeHT1R9H0-Iunn1-gR8eJrJDc,176225
+dw/docs/SERVER.md,sha256=UQodcMi5mHkuVQa9qGk2hfPP8bXUsDZD-jCb3OTDD48,57452
+dw/docs/TASKS.md,sha256=gfSzqEJrSspxaewwol5GP0oTknKRqn0vegHpcehF43s,176358
 dw/docs/TESTING.md,sha256=D4zmQp0iVmREM9J1tq4RxTmmIxvxsp5dRtuRGovP96s,3973
-dw/docs/WORKER_GUIDE.md,sha256=FqzXVuH91XtonpBeXj_7WhMVz5JiB4Rqu2lnGBHchE4,2065
-dw/docs/WORKFLOW_GUIDE.md,sha256=YFlW0IIadffzL3pABM-w3ZAJawb9IMLL8hADiHLsx1Q,148366
+dw/docs/WORKER_GUIDE.md,sha256=DHcOrk10Qbb_HBzPzXKsF5lULR4gZJQEWWaa9udx7Mc,2492
+dw/docs/WORKFLOW_GUIDE.md,sha256=wbEvT96wUmOqTDdO0d_nsqzt5o9UjwyBa1D0uUpGodo,149357
 dw/docs/WORKSPACES.md,sha256=PBAuB4zSdPDkkNf8n2D2fc79qClBILpOnzx-CB63FWo,16672
-dw/pipeline_processors/adapters.py,sha256=HIDYa20vWTuD4XK8q4rntr9zZAHgbxkIPPQqeUVa0oQ,6638
+dw/pipeline_processors/adapters.py,sha256=2i9XIbxeDfHWsB5RD4oUbExdg9WJnLTy4VFO8s8lcPE,9705
 dw/pipeline_processors/chain.py,sha256=2KscX3jQttJL6NmEfiQquPGmBjYIGPOaueHbDv0OUHw,41721
-dw/pipeline_processors/components.py,sha256=S7SjUIg7MOxM0fG67zZe5xJm7WBNfZzdkaTlsMdoaqo,36292
+dw/pipeline_processors/components.py,sha256=6NNHoanDpQdiKbNVQ34Aw-B9coOlF8aDPTzXsGsaQho,37001
 dw/pipeline_processors/config_objects.py,sha256=nQYKx00544UzJFlEZ-th45b-8sav1hz3tKJaaBDNJns,10911
 dw/pipeline_processors/h3_guide_steps.py,sha256=wsaV7jFqcoZAEfjjyKYAMust3XgotqMkftlA-Ov5WrE,21580
 dw/pipeline_processors/h3_guides.py,sha256=DAhNOzOUD9i33Iopd-9nG3H5jaJPbDnEtqkP8-_GJDk,12445
 dw/pipeline_processors/h3_hold.py,sha256=dwpUuT8NuAVo77_4YVBAvn3G5oBW32e6M6i-cds66oU,9912
 dw/pipeline_processors/h3_hold_steps.py,sha256=mjoWAYHrVhQbpcXCzDVHhOXtCH50wXSUJjTmRhAGfzw,16437
 dw/pipeline_processors/h3_rules.py,sha256=Kpm4xeO7oiM2hdECjvnPg_NZTgCO-vBxs2jHtNW08iA,9244
-dw/pipeline_processors/pipeline.py,sha256=d8zXrmjrp99B44uglhOvjgloagvpMeMlJBtFtmWnF04,44789
+dw/pipeline_processors/pipeline.py,sha256=93ABX25UQ3EfZg4eSk8DonfMv2z94Ww4rmyzLIkefKA,46141
 dw/pipeline_processors/placement.py,sha256=D-7ZMNs2P8t81CTtwc_APVrlk_8bz7Ek0M-Hb8wFhV4,16342
 dw/pipeline_processors/progress.py,sha256=uSKPsMug1AZqDoaFXsF5sRcJNiNLzbBuX3C3H3xVzms,9196
 dw/pipeline_processors/remote.py,sha256=eZl6fPEKUrd1ieFgX94QNKAR4ziPH9JXTV_Hse4VsqY,2450
@@ -293,7 +293,7 @@ dw/tasks/model_handlers.py,sha256=JbAVIZVQUr3r4y3p8HyQHKw0dUksRPpCPKsw13qwkX4,11
 dw/tasks/pair_audio.py,sha256=5q56WfKh5srvjLx_sjXBpl-Pk_0qvdMKULT-CJXKkY8,17842
 dw/tasks/qr_code.py,sha256=xyckWTixcMYasJPI5N7-co4jmyHwfScGWD2D1RbFzuM,548
 dw/tasks/registry.py,sha256=nk8mcqkpg-OBdiN4K7Go9lpJVR2mQREmxv4wTzB7k1c,9107
-dw/tasks/restore_faces.py,sha256=0gRhEofAlWw-e3X6mpMPzzEQsHQ5krtocOKPvsuBBMY,6440
+dw/tasks/restore_faces.py,sha256=Q9TzuwWdT5H7kZxcgTCitCCLc8clI2T6Qd6azfaoKx0,6926
 dw/tasks/rife_model.py,sha256=eO77oSH4OGY5pXBp6UDaXIDbGPlOHPIiXMrf1RMzYjo,6387
 dw/tasks/script_check.py,sha256=S8YdJ1bPKdiYh-m5YmIXQ_r_aJGGel8TZquMHDYWXm0,28478
 dw/tasks/segment.py,sha256=2g-jndKDlIcVMH4OApWNlWzt-8DzQvhK82_TNMSXoTI,4267
@@ -333,8 +333,8 @@ dw_mcp/tools_catalog.py,sha256=kpa75deedQEFI90RHKjjqrNY9pFA4E5KtbtOogGwFtY,21962
 dw_mcp/tools_jobs.py,sha256=Hk7MNtd-GA-he6VIepOJHkLnHD594IEMNuriqj88MEk,12015
 dw_mcp/tools_media.py,sha256=YovyYnkRzhAjIQ54Sl12c-lOy9Jq5vrQWVRxd015ehU,16909
 dw_mcp/workspaces.py,sha256=OF6oVMQx_pkTuRMLvbOYkpVWwcA6GQwaEf5k0oxqBnI,8449
-diffusers_workflow-0.11.0.dist-info/METADATA,sha256=P7Mj4vsFRqR08lcGSSgaf0tdwSAW0ZW64ROEkzQDNnM,14939
-diffusers_workflow-0.11.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-diffusers_workflow-0.11.0.dist-info/entry_points.txt,sha256=Dem_AOzV-Kcpr9AASlSvJ-S5sn3f6TQu6ABb6BbApho,148
-diffusers_workflow-0.11.0.dist-info/top_level.txt,sha256=o-uFAN_oUOrhXfMKO39HsMs2r19L9LykxoVKj2S9q7U,10
-diffusers_workflow-0.11.0.dist-info/RECORD,,
+diffusers_workflow-0.11.1.dist-info/METADATA,sha256=_ghxhXxXWRSceZi1J8ZmUtvdVSWhep5QWSvAP4Mqwbw,14939
+diffusers_workflow-0.11.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+diffusers_workflow-0.11.1.dist-info/entry_points.txt,sha256=Dem_AOzV-Kcpr9AASlSvJ-S5sn3f6TQu6ABb6BbApho,148
+diffusers_workflow-0.11.1.dist-info/top_level.txt,sha256=o-uFAN_oUOrhXfMKO39HsMs2r19L9LykxoVKj2S9q7U,10
+diffusers_workflow-0.11.1.dist-info/RECORD,,

dw/docs/ACCELERATION.md

@@ -136,6 +136,18 @@ Select the attention implementation diffusers uses for the duration of each pipe
 
 Common values: `"flash"`, `"flash_hub"`, `"sage"`, `"sage_hub"`, `"native"`, `"flex"`. The full set is diffusers' `AttentionBackendName` enum - availability depends on what's installed (`flash-attn`, `sageattention`, etc.) and the platform. `_hub`-suffixed backends are fetched from the Hugging Face Hub kernel registry on first use, which needs the `kernels` package installed (`pip install kernels`) - it is not a dw dependency, and no bundled workflow sets a backend, so each runs on a plain install. diffusers also refuses a Hub kernel whose publisher it does not list as trusted - `sage_hub` among them, since SageAttention 2 comes from `SageAttention/sage-attention` - until `DIFFUSERS_TRUST_REMOTE_KERNELS=true`, which allows remote code from any such publisher. On an RTX 3090 `sage_hub` measured about 30% faster per MiniMax-H3 step (13.8 s against 19.2 s at 960x544x124, 54.7 s against 81.2 s at 345 frames); the local `sage` backend needs `sageattention>=2.1.1`, which PyPI does not carry.
 
+The MiniMax-H3 baselines expose this as a variable: `attention_backend` on
+[video-with-audio.json](../workflows/templates/minimax/video-with-audio.json),
+[video-with-audio-768p.json](../workflows/templates/minimax/video-with-audio-768p.json),
+[image-to-video.json](../workflows/templates/minimax/image-to-video.json) and
+[reference-to-video.json](../workflows/templates/minimax/reference-to-video.json), pinned
+on the transformer and `null` by default. Pass `attention_backend=sage_hub` to a box with
+the `kernels` package and `DIFFUSERS_TRUST_REMOTE_KERNELS=true` in its `.env`; on MPS
+leave it null. The other H3 templates take the same key under `components.transformer`
+(`transformer_ref` for a ref2va workflow). LTX-2.5 cannot use it: its transformer
+passes an attention mask, and sage attention refuses one ("`attn_mask` is not supported
+for sage attention", measured 2026-10-10), so the LTX templates expose no backend.
+
 A component can also pin its backend persistently instead, via `set_attention_backend`:
 
 ```json
@@ -232,7 +244,11 @@ Three older per-component knobs, set in the pipeline `configuration` beside
 
 ## Memory Offloading
 
-`offload` (`"model"` or `"sequential"`) and `group_offload` trade speed for VRAM by streaming weights between system memory and the accelerator instead of keeping everything resident. `"model"` moves whole submodules and costs the least speed; `"sequential"` moves individual layers and is the slowest but uses the least memory; block/leaf-level `group_offload` sits between the two and is what a modular pipeline's self-loaded components use, since they aren't reachable in time for `offload`. Full configuration syntax is in [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#memory-offloading). Omit both for the fastest run, when VRAM allows it.
+`offload` (`"model"` or `"sequential"`) and `group_offload` trade speed for VRAM by streaming weights between system memory and the accelerator instead of keeping everything resident. `"model"` moves whole submodules and costs the least speed; `"sequential"` moves individual layers and is the slowest but uses the least memory; block/leaf-level `group_offload` sits between the two and is what a modular pipeline's self-loaded components use, since they aren't reachable in time for `offload`. Full configuration syntax is in [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#memory-offloading). Omit both for the fastest run, when VRAM allows it. Measured on an RTX 3090 (RECIPES_24GB.md): sequential
+offload costs about 6x per step on FLUX dev and 3.4x on Z-Image against model offload;
+a block-level, streamed `group_offload` of the transformer from pinned host memory
+matches the resident per-step cost while holding one block on the card, at ~22 GB of
+pinned host RAM per FLUX pipeline - the placement the unquantized FLUX templates use.
 
 `"residency": "on_demand"` on a component is the cheap case of the same trade: the model rests in system memory and is moved to the device whole around each of its own calls. That is a bad deal for anything called once per step, and a good one for a VAE called twice a run - it frees the VAE's VRAM for the denoise loop at the cost of two transfers, where group offloading the same VAE would restream it once per decode tile. See [On-demand components](WORKFLOW_GUIDE.md#on-demand-components).
 

dw/docs/LORAS.md

@@ -48,6 +48,10 @@ LoRA (Low-Rank Adaptation) models apply lightweight style or subject modificatio
 
 Any other property (e.g. `revision`) is forwarded as-is to the underlying `load_lora_weights()` call.
 
+`scale` and `alpha` are set in place on the loaded adapter, so a server run that changes
+only them reuses the warm pipeline instead of reloading it; changing `model_name` or
+`weight_name` reloads.
+
 ## Multiple LoRAs
 
 Stack multiple LoRAs. They are blended via weighted adapter composition:

dw/docs/RECIPES_24GB.md

@@ -12,23 +12,79 @@ The general recipe, in order of impact:
 
 ## Flux dev (12B)
 
-The bf16 transformer is ~24GB - it does not fit alongside the T5 encoder, and it does
-not fit alongside the VAE either: a resident bf16 transformer runs the denoise and then
-fails at decode. `offload: "model"` is what makes bf16 work on 24GB, and on an RTX 3090
-it is also the fastest configuration measured (1024x1024, 28 steps, pipeline loaded):
-
-| Approach | Config | Measured on RTX 3090 |
-| -------- | ------ | -------------------- |
-| **bf16 + model offload** | [flux-dev.json](../workflows/models/flux-dev.json) | 55s per image (72s cold) |
-| **bf16 + model offload + compile** | [flux-dev-compile.json](../workflows/models/flux-dev-compile.json) - `compile: {repeated_blocks: true}` on the transformer | 52s per image (64s cold) |
-| **int8 TorchAO** | transformer `quant_type: "torchao.quantization.Int8WeightOnlyConfig"` + `compile`, with or without `cache: first_block` | over 60s per *denoising step* - do not use on Ampere |
-| **float8 TorchAO** (RTX 40-series+) | `Float8DynamicActivationFloat8WeightConfig` + `compile` | needs compute capability 8.9+ (Ada); unmeasured |
-| **GGUF Q8** | [flux-gguf.json](../workflows/models/flux-gguf.json) - `from_single_file` Q8_0 transformer + `offload: "model"` | unmeasured; smallest VRAM, best quality retention |
-
-Measured 2026-09-07. A number in this table came from a run on the named card; a row
-without one is a configuration that loads, not a speed claim.
-
-**Examples:** [flux-dev-compile.json](../workflows/models/flux-dev-compile.json), [flux-gguf.json](../workflows/models/flux-gguf.json), [step-caching.json](../workflows/templates/step-caching.json)
+The bf16 transformer is ~22 GB, so on 24 GB it cannot sit beside its own activations
+with any margin, and it cannot sit beside the T5 encoder or the VAE at all. Three
+placements, measured on an RTX 3090 (2026-10-10, cold load included):
+
+| Placement | 1024x1024, 25 steps, 1 image, dev + LoRA | 768x768, 25 steps, 4 images, Krea | 1232x1632, 50 steps, Fill |
+| --------- | ----------------------------------------- | --------------------------------- | ------------------------- |
+| `offload: "sequential"` | 273 s (10.8 s/step) | not measured - same per-step cost | not measured |
+| `offload: "model"` | 61 s (1.7 s/step) at **23.3 GB reserved, 491 MB free** | **OOM** at 23.45 GiB | not attempted |
+| **transformer `group_offload`, block-level, streamed, pinned host copies** | 78 s (1.5 s/step), 17.7 GB peak reserved, 6 GB free | 131 s (3.2 s/step) | 152 s denoise (3.0 s/step), 1 s decode |
+
+Model offload is the fastest placement that loads, and the one #580 (9c708a12) retired:
+at 1024x1024 it runs with a few hundred MB to spare and fails on anything larger -
+a batch, a second encoder resident for prompt weighting, a cache's state. Sequential
+offload is safe everywhere and 6x slower per step. The streamed group offload is both:
+the transformer's blocks are copied in one at a time from pinned host memory under a
+CUDA stream, so each step costs the same as the resident model's, and the card holds
+one block plus the activations. It is what every unquantized FLUX template now uses:
+
+```json
+"configuration": {
+    "component_type": "FluxPipeline",
+    "components": {
+        "transformer": {
+            "group_offload": {
+                "offload_type": "block_level",
+                "num_blocks_per_group": 1,
+                "use_stream": true,
+                "record_stream": true
+            }
+        },
+        "text_encoder": { "device": "cuda" },
+        "text_encoder_2": { "device": "cuda" },
+        "vae": { "device": "cuda" }
+    }
+}
+```
+
+Two things the shape depends on. The non-offloaded components are placed explicitly:
+with no pipeline-level `offload`, nothing else moves them, and a T5 or VAE left on the
+CPU costs a minute per prompt encode and per decode (measured: 70 s before the first
+step, 185 s decoding). And the host copies are pinned - diffusers' default,
+`low_cpu_mem_usage: false` - which holds ~22 GB of unswappable host memory per loaded
+FLUX pipeline and takes ~35 s once per load; with `low_cpu_mem_usage: true` the copies
+come from pageable memory at 8 s/step, barely ahead of sequential. A host with less
+than 32 GB free should take `offload: "sequential"` instead.
+
+Compile and caching stack on top as before: `compile: {repeated_blocks: true}` measured
+52 s vs 55 s per image on the old model-offload placement; `cache: first_block` is
+[step-caching.json](../workflows/templates/step-caching.json). TorchAO int8 is over 60 s
+per *denoising step* on Ampere - do not use it there; float8 needs compute capability
+8.9+ (Ada) and is unmeasured; GGUF Q8 ([flux-gguf.json](../workflows/models/flux-gguf.json))
+loads with the least VRAM and is unmeasured for speed.
+
+**Examples:** [lora.json](../workflows/templates/lora.json), [flux-dev-compile.json](../workflows/models/flux-dev-compile.json), [flux-gguf.json](../workflows/models/flux-gguf.json), [step-caching.json](../workflows/templates/step-caching.json)
+
+## Z-Image Turbo (6B)
+
+Fits a 24 GB card in bf16 with model offload, and that is the configuration to use.
+Measured on an RTX 3090 (960x544, 9 steps, 4 images per prompt, cold load included,
+2026-10-10):
+
+| Offload | Load | Denoise | Decode | Total | Peak VRAM reserved |
+| ------- | ---- | ------- | ------ | ----- | ------------------ |
+| `sequential` | 18 s | 84 s | 2 s | 107 s | 1.1 GB |
+| **`model`** | 4 s | 25 s | 9 s | 41 s | 13.0 GB |
+| none (resident) | 11 s | 17 s | 2 s | 33 s | 23.7 GB, 95 MB free at decode |
+
+Sequential offload streams the transformer's layers every step and costs 3.4x on the
+denoise for a model that does not need the room. Resident is faster still but decodes
+four images with nothing to spare, so [z-image.json](../workflows/models/z-image.json)
+and the Z-Image portrait steps of the MiniMax templates use `"offload": "model"`. The
+decode's 9 s under model offload is the VAE swapping in; `vae.enable_slicing` would
+trade it for per-image decodes.
 
 ## Qwen-Image (20B)
 

dw/docs/RELEASING.md

@@ -7,6 +7,47 @@ notes from commits at tag time (see below). This section is a scratch pad
 for items a branch's author wants the next release note to name; clear it
 when a release ships.
 
+### 0.11.1
+
+<!-- Drafted from v0.11.0..develop. Paste into the GitHub release body once the tag has published: gh release edit v0.11.1 --notes-file ... -->
+
+A speed release. The unquantized FLUX templates run about 3.5x faster on
+a 24 GB card, Z-Image Turbo about 2.6x, a LoRA scale or scheduler shift
+change no longer reloads the model, and switching workflows keeps the
+models the next one shares. Every number below was measured on an RTX 3090;
+the placement tables are in docs/RECIPES_24GB.md.
+
+**Workflow speed**
+
+- The 14 unquantized FLUX templates and `models/flux-krea` stream the
+  transformer block by block from pinned host memory (`group_offload`)
+  instead of `offload: "sequential"`: a 25-step 1024x1024 image takes 78 s
+  instead of 273 s (1.5 s/step against 10.8), with 6 GB of VRAM to spare -
+  enough for the 4-image batches `offload: "model"` runs out of memory on.
+  It holds ~22 GB of pinned host RAM per loaded FLUX pipeline.
+- Z-Image Turbo (`models/z-image` and the MiniMax portrait steps) takes
+  `offload: "model"`: four 960x544 images in 41 s instead of 107 s.
+- The four MiniMax-H3 family baselines expose `attention_backend` (null by
+  default; `sage_hub` measured about 30% faster per step on a 3090; it needs
+  the `kernels` package and `DIFFUSERS_TRUST_REMOTE_KERNELS=true`, see
+  docs/ACCELERATION.md). LTX-2.5 cannot use sage attention (its attention
+  mask is refused).
+- A LoRA `scale`/`alpha` change or a scheduler `shift` change re-applies on
+  the warm pipeline instead of reloading it. Removing an alpha or shift still
+  reloads, and a `pipeline_reference` runs at the referenced step's own values.
+- Switching workflows in the worker keeps the warm pipelines the next
+  workflow loads anyway, instead of releasing everything first.
+- `restore_faces` builds its face helper once per run instead of once per
+  frame, and picture frames decode with libav threading, so video inputs
+  process faster.
+- Catalog defaults corrected: compose-workflows video steps run 5 steps
+  (was 20) and the prompt-weighting schnell workflow runs 4 steps at guidance
+  0 (was 20).
+- The six 9-step minimax ref2va templates drop a dead `first_block` cache,
+  and minimax/shots-batch drops its `release_pipeline`: a no-op inside the
+  run, but it unloaded H3 at job end, so H3 now stays resident after a
+  shots-batch job, which is the win.
+
 ### 0.11.0
 
 <!-- Drafted from v0.10.0..develop. Paste into the GitHub release body once the tag has published: gh release edit v0.11.0 --notes-file ... -->

dw/docs/SERVER.md

@@ -222,7 +222,9 @@ Among the free cards a job fits, dispatch prefers the one it has an affinity
 for: a rerun goes to the card that ran the original, and any job to the card
 whose worker last ran the same workflow (the same file, or an inline
 definition's `id`) - that worker's pipelines and step cache are warm, and a
-worker frees both when the workflow changes. A busy preferred card is not
+worker's step cache and any model the next workflow does not load are freed
+when the workflow changes, while a model both workflows load (same weights
+identity) stays warm. `clear_memory` still empties the card by hand. A busy preferred card is not
 waited for. A validation's cache probe and its `plan.estimate` ask about the
 card the job would be dispatched to now, and the estimate names it in
 `priced_for`. Memory is per card: `GET /api/memory` and `POST

dw/docs/TASKS.md

@@ -2632,7 +2632,7 @@ Restore and enhance faces in images using spandrel-compatible face restoration m
 | `eye_dist_threshold` | No | Skip faces with eye distance below this (default: 5) |
 | `upsample_img` | No | Pre-upscaled background image (e.g., from a prior upscale step) |
 
-Models are loaded via spandrel, so any `.pth`/`.safetensors` face restoration weights work. CodeFormer requires `pip install spandrel-extra-arches` (non-commercial license).
+Models are loaded via spandrel, so any `.pth`/`.safetensors` face restoration weights work. CodeFormer requires `pip install spandrel-extra-arches` (non-commercial license). The detector and parser are loaded once per settings/device and reused across frames; `release_models` drops them with the restorer.
 
 **Example:** [restore-faces.json](../workflows/templates/restore-faces.json) — Generate a portrait, then restore faces with GFPGAN v1.4.
 

dw/docs/WORKER_GUIDE.md

@@ -28,6 +28,13 @@ The worker cleans up automatically between runs (garbage collection + GPU
 cache clearing). If memory grows unexpectedly, `GET /api/memory` reports the
 current reading and `POST /api/memory/clear` resets it.
 
+Switching to a different workflow releases only the models the next workflow
+does not load: the worker prepares the incoming definition, and a pipeline
+both workflows load (same weights identity) stays warm. The step cache and
+the task model cache are still emptied, and if the incoming definition cannot
+be prepared everything is released. `clear_memory` (`POST /api/memory/clear`)
+remains the way to empty the card by hand.
+
 ## Troubleshooting
 
 **Worker crashes**: `JobManager` detects it and starts a fresh worker on the

dw/docs/WORKFLOW_GUIDE.md

@@ -112,6 +112,10 @@ inverted latents:
 ```
 
 `reference_name` must name a step earlier in the same workflow that has a `pipeline`.
+Two steps whose pipelines differ only in a LoRA's `scale` or `alpha` or a scheduler's
+`shift` share one warm model, and a reference always runs at the referenced step's own
+values; `release_pipeline` on either step frees the shared model, as it does for two
+identical steps.
 See [workflows/templates/community-pipeline.json](../workflows/templates/community-pipeline.json) for a full example.
 
 ### Task Steps
@@ -1173,7 +1177,7 @@ Control how models use memory:
 ```
 
 - `"model"` — Moves entire models between CPU and GPU. Good balance of speed and memory.
-- `"sequential"` — Moves individual layers. Slowest but uses least GPU memory. On MPS it is downgraded to `"model"` with a warning: with unified memory there is no separate pool to keep small, so the per-layer copies cost speed and save nothing.
+- `"sequential"` — Moves individual layers. Slowest but uses least GPU memory (measured at 6x the per-step cost of model offload on FLUX dev and 3.4x on Z-Image; a streamed block-level `group_offload` of the transformer is the usual better answer - see [RECIPES_24GB.md](RECIPES_24GB.md#flux-dev-12b)). On MPS it is downgraded to `"model"` with a warning: with unified memory there is no separate pool to keep small, so the per-layer copies cost speed and save nothing.
   `exclude_from_cpu_offload` names components the sweep should leave alone.
 - Omit for no offloading (fastest, requires enough VRAM).
 
@@ -1325,6 +1329,13 @@ The step-level `release_pipeline` flag unloads the step's pipeline after its res
 saved. A later `pipeline_reference` to a released step is an error, and the process-wide
 step cache will not retain it.
 
+What keeps a pipeline warm: the server's worker keeps a pipeline loaded across runs for as
+long as what it *loads* is unchanged. A LoRA's `scale` and `alpha` and a scheduler's (or
+`audio_scheduler`'s) `shift` are applied in place on the warm pipeline, so iterating on
+them costs no reload; removing (nulling) an alpha or a shift reloads, so the checkpoint
+default comes back. Changing a LoRA's `model_name` or `weight_name`, the quantization,
+the placement or the scheduler type reloads it.
+
 #### Releasing task models mid-workflow
 
 Task models - the checkpoints behind `text_generation`, `segment`, `depth_estimator` and

dw/media.py

@@ -33,6 +33,15 @@ from .dsp import SILENCE_DBFS, dbfs, integrated_lufs, layout_name, true_peak_dbf
 
 logger = logging.getLogger("dw")
 
+
+def _threaded(stream):
+    """A video stream set to decode on every core. libav defaults a
+    software h264 decode to one thread; AUTO lets it pick frame and
+    slice threading for the codec. Header-only reads do not call this."""
+    stream.thread_type = "AUTO"
+    return stream
+
+
 # The most a soundtrack may be as base64 before the gallery route refuses to
 # extract it whole - the twin of dw_mcp/media.py's MAX_RETURNED_BYTES (the
 # MCP package's cap on any inline payload). Two constants because dw_mcp
@@ -345,7 +354,7 @@ def video_shape(path):
         fps = float(stream.average_rate) if stream.average_rate else None
         count = int(stream.frames) if stream.frames else None
         if count is None:
-            count = sum(1 for _ in container.decode(stream))
+            count = sum(1 for _ in container.decode(_threaded(stream)))
         return {
             "frame_count": count,
             "fps": fps,
@@ -383,6 +392,8 @@ def read_frames(path, indexes, fit=None):
     wanted = sorted(set(int(i) for i in indexes))
     found = {}
     with av.open(path) as container:
+        # Not _threaded: frame threads hold frames in flight, and a backward
+        # seek after a decoded frame then yields stale ones (tests/test_media_decode_threads.py)
         stream = container.streams.video[0]
         fps = float(stream.average_rate) if stream.average_rate else None
         start_pts = stream.start_time if stream.start_time is not None else 0
@@ -479,6 +490,8 @@ def read_frame_range(path, start, stop):
         )
     out = None
     with av.open(path) as container:
+        # Not _threaded: frame threads hold frames in flight, and a backward
+        # seek after a decoded frame then yields stale ones (tests/test_media_decode_threads.py)
         stream = container.streams.video[0]
         fps = float(stream.average_rate) if stream.average_rate else None
         start_pts = stream.start_time if stream.start_time is not None else 0
@@ -513,7 +526,7 @@ def count_video_frames(path):
     """The picture frame count of `path`, by decoding every frame rather
     than reading the header. Nothing is held but the frame in hand."""
     with av.open(path) as container:
-        return sum(1 for _ in container.decode(container.streams.video[0]))
+        return sum(1 for _ in container.decode(_threaded(container.streams.video[0])))
 
 
 def decode_audio_video(handle):
@@ -531,7 +544,7 @@ def decode_audio_video(handle):
     sample_rate = None
 
     with av.open(handle) as container:
-        video_stream = container.streams.video[0]
+        video_stream = _threaded(container.streams.video[0])
         frame_rate = (
             float(video_stream.average_rate) if video_stream.average_rate else None
         )
@@ -559,7 +572,10 @@ def decode_rgb_frames(path):
     """Every picture frame of `path` as an (height, width, 3) uint8 array,
     in order."""
     with av.open(path) as container:
-        return [frame.to_ndarray(format="rgb24") for frame in container.decode(video=0)]
+        return [
+            frame.to_ndarray(format="rgb24")
+            for frame in container.decode(_threaded(container.streams.video[0]))
+        ]
 
 
 def read_thumbnails_and_track(path, thumb_width, thumb_height):
@@ -575,7 +591,9 @@ def read_thumbnails_and_track(path, thumb_width, thumb_height):
     thumbs = []
     chunks = []
     with av.open(path) as container:
-        video = container.streams.video[0] if container.streams.video else None
+        video = (
+            _threaded(container.streams.video[0]) if container.streams.video else None
+        )
         audio = container.streams.audio[0] if container.streams.audio else None
         if video is None and audio is None:
             raise ValueError(f"{path} has neither a video nor an audio stream")

dw/pipeline_ownership.py

@@ -62,6 +62,11 @@ class PipelineOwnership:
         # pipeline_reference still address pipelines by the step that made
         # them
         self.keys_by_step = {}
+        # Step name -> the step's pipeline definition as the workflow holds
+        # it (never a loading copy), so a pipeline_reference can put the
+        # referenced step's own scale, alpha and shift back on a model a
+        # step differing only in those shares with it
+        self.definitions_by_step = {}
         # Step name -> _Deferred for each cache hit whose pipeline was not
         # resident and so was not loaded
         self.deferred = {}
@@ -92,9 +97,16 @@ class PipelineOwnership:
             )
         return self.running[step_name]
 
-    def record(self, step_name, key):
-        """Record which cache key a step's pipeline lives under this run."""
+    def record(self, step_name, key, pipeline_definition=None):
+        """Record which cache key a step's pipeline lives under this run,
+        and the definition it was loaded or wrapped from."""
         self.keys_by_step[step_name] = key
+        if pipeline_definition is not None:
+            self.definitions_by_step[step_name] = pipeline_definition
+
+    def definition_for(self, step_name):
+        """The pipeline definition `step_name` recorded this run, or None."""
+        return self.definitions_by_step.get(step_name)
 
     def key_for(self, step_name):
         """The cache key `step_name` recorded this run, or None."""
@@ -286,6 +298,10 @@ def wrap_resident(
             new_pipeline_wrapper.pipeline_definition.get("seed", default_seed)
         )
 
+    # The key the hit matched on is the weights identity: a scale, alpha or
+    # shift may differ from the values the resident model last ran with
+    new_pipeline_wrapper.apply_runtime_settings()
+
     # A cache hit and a cold load look identical from the outside -
     # same step, same dot - and they differ by minutes
     emit_phase("cached", detail=new_pipeline_wrapper.name)

dw/pipeline_processors/adapters.py

@@ -101,11 +101,103 @@ def active_loras(loras):
     ]
 
 
+def adapter_settings(loras):
+    """(adapter_names, adapter_weights, alphas) for the active entries of
+    `loras`. An adapter is named by its own adapter_name or its ORIGINAL
+    index - a nulled entry keeps its slot, so the name a hit re-applies to
+    is the name the load gave. Reads the entries, never pops them.
+
+    `or` on adapter_name, because a variable nulled by the caller arrives as
+    a present None; float() on scale, because the schema takes a 'variable:'
+    reference there, and a variable declared as a string default substitutes
+    as one."""
+    names, weights, alphas = [], [], {}
+    for i, lora in enumerate(loras or []):
+        if not isinstance(lora, dict) or lora.get("model_name") is None:
+            continue
+        name = lora.get("adapter_name") or str(i)
+        names.append(name)
+        scale = lora.get("scale")
+        weights.append(1.0 if scale is None else float(scale))
+        if lora.get("alpha") is not None:
+            alphas[name] = lora["alpha"]
+    return names, weights, alphas
+
+
+def set_adapter_scales(pipeline, names, weights):
+    """Set each named adapter's scale on every loaded layer that carries it,
+    without re-activating the adapters.
+
+    The warm-pipeline path. diffusers' set_adapters() activates as well as
+    scales, and activation goes through peft's set_adapter(), which sets
+    requires_grad on the adapter weights - after a run under model offload
+    those are inference tensors, and torch refuses ("Setting requires_grad=True
+    on inference tensor outside InferenceMode" - seen on a 3090 the first time
+    a scale changed on a warm Flux pipeline, 2026-10-10).
+    A pipeline that already ran holds the adapters active, so a hit only
+    needs each layer's set_scale(), which recomputes scale * alpha / rank and
+    touches no tensor.
+
+    Raises:
+        ValueError: if an adapter is carried by no loaded layer - a scale
+            that applied to nothing would silently run the old value
+    """
+    touched = {name: 0 for name in names}
+    for module in _lora_layers(pipeline):
+        scaling = getattr(module, "scaling", None)
+        if not isinstance(scaling, dict):
+            continue
+        for name, weight in zip(names, weights):
+            if name in scaling:
+                module.set_scale(name, weight)
+                touched[name] += 1
+    missing = [name for name, count in touched.items() if not count]
+    if missing:
+        raise ValueError(
+            f"Cannot set the scale of adapter(s) {missing} - no loaded layer "
+            "carries them. Nothing would have been scaled."
+        )
+
+
+def apply_adapter_settings(loras, pipeline, activate=False):
+    """Set each active LoRA's alpha, then every scale, on a pipeline that
+    already holds the adapters. Alpha first: the scale pass is what recomputes
+    each layer's scaling from it. No-op with no active entry.
+
+    `activate` is the cold path, right after load_lora_weights: diffusers'
+    set_adapters() activates the adapters and sets their scales in one call.
+    A warm pipeline (a cache hit) has them active already and takes the
+    scale-only path - see set_adapter_scales for why it must.
+    """
+    names, weights, alphas = adapter_settings(loras)
+    if not names:
+        return
+    for name, alpha in alphas.items():
+        set_adapter_alpha(pipeline, name, alpha)
+    logger.info(f"Setting adapter weights: {list(zip(names, weights))}")
+    if activate:
+        # Positionally - diffusers' mixin calls the second parameter
+        # 'adapter_weights' while custom pipelines that delegate to the model
+        # (ostris/Krea2OstrisEdit) call it 'weights'
+        pipeline.set_adapters(names, weights)
+    else:
+        set_adapter_scales(pipeline, names, weights)
+
+
 def load_loras(loras, pipeline):
-    """Load and configure LoRA models."""
-    adapter_names = []
-    adapter_weights = []
-    alphas = {}
+    """Load and configure LoRA models.
+
+    Names, scales and alphas come from adapter_settings, read before the
+    entries are popped, so a load and a later cache hit's
+    apply_adapter_settings set the same values on the same names."""
+    # A snapshot of each entry's runtime keys, taken before the pops below
+    settings = [
+        {k: lora.get(k) for k in ("model_name", "adapter_name", "scale", "alpha")}
+        if isinstance(lora, dict)
+        else lora
+        for lora in loras or []
+    ]
+    names = iter(adapter_settings(settings)[0])
 
     for i, lora in enumerate(loras or []):
         if isinstance(lora, dict) and lora.get("model_name") is None:
@@ -117,40 +209,15 @@ def load_loras(loras, pipeline):
         logger.info(f"Loading LoRA: {model_name}")
         emit_phase("loading", detail=f"LoRA: {model_name}")
 
-        # Use provided adapter_name or generate from index - `or`, because a
-        # variable nulled by the caller arrives as a present None
-        adapter_name = lora.pop("adapter_name", None) or str(i)
-        adapter_names.append(adapter_name)
+        # Popped before the load: everything left in the dict is a keyword
+        # argument to load_lora_weights; the scale and alpha are applied to
+        # the layers afterwards rather than passed to it
+        for key in ("adapter_name", "scale", "alpha"):
+            lora.pop(key, None)
 
-        # Extract scale for adapter weights - float() because the schema takes a
-        # 'variable:' reference here, and a variable declared as a string default
-        # substitutes as one
-        scale = lora.pop("scale", None)
-        scale = 1.0 if scale is None else float(scale)
-        adapter_weights.append(scale)
+        pipeline.load_lora_weights(model_name, adapter_name=next(names), **lora)
 
-        # Popped before the load: everything left in the dict is a keyword
-        # argument to load_lora_weights, and the alpha is applied to the layers
-        # afterwards rather than passed to it
-        alpha = lora.pop("alpha", None)
-        if alpha is not None:
-            alphas[adapter_name] = alpha
-
-        # Load the LoRA with the adapter name
-        pipeline.load_lora_weights(model_name, adapter_name=adapter_name, **lora)
-
-    for adapter_name, alpha in alphas.items():
-        set_adapter_alpha(pipeline, adapter_name, alpha)
-
-    # Set adapter weights for all loaded LoRAs
-    if adapter_names:
-        logger.info(
-            f"Setting adapter weights: {list(zip(adapter_names, adapter_weights))}"
-        )
-        # Positionally - diffusers' mixin calls the second parameter 'adapter_weights'
-        # while custom pipelines that delegate to the model (ostris/Krea2OstrisEdit)
-        # call it 'weights'
-        pipeline.set_adapters(adapter_names, adapter_weights)
+    apply_adapter_settings(settings, pipeline, activate=True)
 
 
 def load_ip_adapter(ip_adapter_definition, pipeline):

dw/pipeline_processors/components.py

@@ -447,6 +447,23 @@ def load_and_configure_scheduler(
             ),
         )
 
+    apply_scheduler_shift(scheduler_definition, pipeline, component_name)
+
+
+def apply_scheduler_shift(scheduler_definition, pipeline, component_name="scheduler"):
+    """Set the shift a scheduler definition names on an already-loaded
+    scheduler; nothing when the definition is None or names no shift.
+
+    A load sets it after any scheduler replacement, and a pipeline cache hit
+    sets it again (Pipeline.apply_runtime_settings), because the cache key
+    leaves the shift out - a run that only moves it reuses the warm pipeline.
+
+    Raises:
+        ValueError: if the scheduler is registered but not loaded, or has no
+            set_shift()
+    """
+    if scheduler_definition is None:
+        return
     shift = scheduler_definition.get("shift", None)
     if shift is None:
         return

dw/pipeline_processors/pipeline.py

@@ -9,8 +9,14 @@ from .config_objects import (
     get_quantization_configuration,
     get_cache_configuration,
 )
-from .adapters import active_loras, load_ip_adapter, load_loras
+from .adapters import (
+    active_loras,
+    apply_adapter_settings,
+    load_ip_adapter,
+    load_loras,
+)
 from .components import (
+    apply_scheduler_shift,
     apply_sdnq_optimizations,
     configure_components,
     enable_cache_on_transformer,
@@ -135,6 +141,22 @@ def _loading_copy(pipeline_definition):
     return copied
 
 
+def apply_runtime_settings(pipeline_definition, model):
+    """Set what a pipeline definition states that changes no weights -
+    scheduler and audio_scheduler shift, LoRA scales and alphas - on a model
+    that already holds those weights.
+
+    Takes the definition as the workflow holds it, never a Pipeline's
+    loading copy: load_loras pops each entry's model_name from that copy,
+    and an entry without one reads as switched off and would be skipped.
+    """
+    apply_scheduler_shift(pipeline_definition.get("scheduler"), model)
+    apply_scheduler_shift(
+        pipeline_definition.get("audio_scheduler"), model, "audio_scheduler"
+    )
+    apply_adapter_settings(pipeline_definition.get("loras"), model)
+
+
 class Pipeline:
     """
     Manages pipeline initialization, configuration, and execution.
@@ -303,6 +325,15 @@ class Pipeline:
                 for entry in value:
                     Pipeline._check_trusted_block(entry, key)
 
+    def apply_runtime_settings(self):
+        """Re-apply what a run may have changed without changing the weights:
+        scheduler and audio_scheduler shift, LoRA scales and alphas. The
+        pipeline cache keys on weights_identity, so a hit can carry any of
+        these at a new value; load() applies the same values on its way
+        through, so a cold load and a hit end in the same state. Only for a
+        wrapper that has not loaded (a hit): load() pops from this copy."""
+        apply_runtime_settings(self.pipeline_definition, self.pipeline)
+
     def load(self, shared_components):
         """
         Load and configure the pipeline with all components.

dw/step_cache.py

@@ -121,26 +121,101 @@ def component_names(pipeline_definition, key):
     return list(pipeline_definition.get(key, [])) + list(configuration.get(key, []))
 
 
+RUNTIME_LORA_KEYS = ("scale", "alpha")
+
+
+def weights_identity(pipeline_definition):
+    """The pipeline definition with every runtime-mutable setting removed.
+
+    A LoRA's scale and alpha (set_adapters / set_adapter_alpha) and a
+    scheduler's shift (set_shift) change nothing about what is loaded, so a
+    run that only moves one of them must hit the warm pipeline and re-apply
+    the value (Pipeline.apply_runtime_settings), not reload the stack.
+    Everything else - the model, the LoRA files, quantization, placement,
+    the scheduler type - still changes the key. Returns a new dict; the
+    definition is the workflow's and is not edited.
+
+    An alpha's or a shift's *presence* stays in the identity (as True, never
+    the value). A hit re-applies only what the definition states, and nothing
+    sets an alpha or shift back to the checkpoint's own: a run that drops one
+    (or nulls the variable behind it) must reload to get the default back,
+    where 16 -> 8 just re-applies. A scale needs no marker - an absent scale
+    re-applies as 1.0.
+    """
+    identity = {
+        k: v
+        for k, v in pipeline_definition.items()
+        if k not in ("arguments", "seed", "chain")
+    }
+    loras = identity.get("loras")
+    if isinstance(loras, list):
+        identity["loras"] = [
+            _without_runtime(lora, RUNTIME_LORA_KEYS, "alpha")
+            if isinstance(lora, dict)
+            else lora
+            for lora in loras
+        ]
+    for name in ("scheduler", "audio_scheduler"):
+        scheduler = identity.get(name)
+        if isinstance(scheduler, dict):
+            identity[name] = _without_runtime(scheduler, ("shift",), "shift")
+    return identity
+
+
+def _without_runtime(block, runtime_keys, marked):
+    """`block` without its runtime keys, but with `marked` as True when the
+    block states it - see weights_identity for why its presence counts."""
+    stripped = {k: v for k, v in block.items() if k not in runtime_keys}
+    if block.get(marked) is not None:
+        stripped[marked] = True
+    return stripped
+
+
+def pipeline_definition_key(pipeline_definition):
+    """A hash of everything in a pipeline definition but what varies per call
+    (arguments, seed, chain) - runtime settings included, unlike
+    pipeline_cache_key.
+
+    The step cache keys a borrowing step on this, not on the pipeline cache
+    key: a step that runs on another step's pipeline (pipeline_reference,
+    reused_components) produces a different result when only its source's
+    LoRA scale or shift moves, though the loaded weights - and so the warm
+    pipeline - are the same.
+    """
+    serialized = json.dumps(
+        {
+            k: v
+            for k, v in pipeline_definition.items()
+            if k not in ("arguments", "seed", "chain")
+        },
+        sort_keys=True,
+        default=str,
+    )
+    return hashlib.sha256(serialized.encode()).hexdigest()
+
+
 def pipeline_cache_key(pipeline_definition):
     """Stable identity for a loaded pipeline.
 
-    Hashes everything that shapes loading - configuration, components,
-    quantization, loras - and excludes what varies per call (arguments, seed,
-    chain), so a cache hit means "this exact model stack is already loaded".
-    Keying the cache by identity instead of step name means two workflows
-    whose steps happen to share a name can no longer collide, and a rerun of
-    an edited workflow keeps every pipeline whose definition did not change.
+    Hashes the weights identity - everything that shapes loading:
+    configuration, components, quantization, the LoRA files, the scheduler
+    type - and excludes what varies per call (arguments, seed, chain), so a
+    cache hit means "this exact model stack is already loaded". A LoRA's
+    scale and alpha and a scheduler's shift are excluded too: each is set in
+    place on the loaded model, and a hit re-applies them
+    (Pipeline.apply_runtime_settings), so nudging one between runs costs no
+    reload. Keying the cache by identity instead of step name means two
+    workflows whose steps happen to share a name can no longer collide, and
+    a rerun of an edited workflow keeps every pipeline whose definition did
+    not change.
 
     Computed after variable substitution but the excluded keys keep realized
     per-run values (images, generators) out of the hash; realized types and
     dtypes stringify stably via default=str.
     """
-    load_definition = {
-        k: v
-        for k, v in pipeline_definition.items()
-        if k not in ("arguments", "seed", "chain")
-    }
-    serialized = json.dumps(load_definition, sort_keys=True, default=str)
+    serialized = json.dumps(
+        weights_identity(pipeline_definition), sort_keys=True, default=str
+    )
     return hashlib.sha256(serialized.encode()).hexdigest()
 
 
@@ -170,14 +245,34 @@ def step_pipeline_keys(steps):
     loaded - a deferred cache hit, or the cache_hits probe. A key that has to
     agree across those cases is read from this table, not re-hashed.
     """
+    return _closure_keys(steps, pipeline_cache_key)
+
+
+def step_definition_keys(steps):
+    """Step name -> effective definition key for every pipeline step, taken
+    before any step runs: step_pipeline_keys over pipeline_definition_key.
+
+    What the step cache folds in for a borrowed pipeline
+    (borrowed_pipeline_keys), so a source step whose only change is a LoRA
+    scale, alpha or shift - the same warm pipeline, a different result - is
+    a miss for the steps that borrow it. Pipeline ownership keeps to
+    step_pipeline_keys.
+    """
+    return _closure_keys(steps, pipeline_definition_key)
+
+
+def _closure_keys(steps, own_key_of):
+    """Step name -> the step's own key (`own_key_of` its pipeline
+    definition), or, for a step that reuses components, the hash of the
+    sorted own keys over its reuse closure - see step_pipeline_keys."""
     keys = {}
-    # Step name -> the own pipeline_cache_keys of its reuse closure
+    # Step name -> the own keys of its reuse closure
     closures = {}
     for index, step_data in enumerate(steps):
         if "pipeline" not in step_data:
             continue
         pipeline_definition = step_data["pipeline"]
-        own_key = pipeline_cache_key(pipeline_definition)
+        own_key = own_key_of(pipeline_definition)
         closure = {own_key}
         reused = component_names(pipeline_definition, "reused_components")
         for name in reused:
@@ -215,10 +310,15 @@ def borrowed_pipeline_keys(steps, index, pipeline_keys):
     step's model changes - its own definition never names the model. Folding
     the source steps' keys into the lookup snapshot makes a source model
     change a miss here too, rather than a stale hit that republishes a
-    now-wrong pipeline. The keys are effective keys (step_pipeline_keys), so
-    a change further up a borrow chain than the direct source is a miss too.
+    now-wrong pipeline. The keys are effective keys, so a change further up
+    a borrow chain than the direct source is a miss too.
+
+    The step cache passes step_definition_keys, which also moves with a
+    source's LoRA scale, alpha or shift - a change that keeps the warm
+    pipeline but changes what the borrower produces. Callers that only need
+    which steps are borrowed may pass step_pipeline_keys.
 
-    The keys come from `pipeline_keys` (step_pipeline_keys), computed from
+    The keys come from `pipeline_keys` (one of those tables), computed from
     the definition before any step ran, never from `steps[:index]` as they
     stand now: a load edits its own definition in place, and a source step
     that loaded before this lookup (a cold run) and one that did not (a

dw/tasks/restore_faces.py

@@ -66,15 +66,25 @@ def restore_faces(image, model_name, device="cpu", **kwargs):
         ("restore_faces", model_name, filename, str(device)), load_descriptor
     )
 
-    # Set up facexlib helper
-    face_helper = FaceRestoreHelper(
-        upscale_factor=upscale_factor,
-        face_size=face_size,
-        crop_ratio=(1, 1),
-        det_model="retinaface_resnet50",
-        use_parse=use_parse,
-        device=torch.device(device),
+    # facexlib's helper loads RetinaFace (and ParseNet with use_parse) in
+    # its constructor. per_frame calls this once per frame, so a video was
+    # reloading detector weights for every frame. The helper keeps per-image
+    # state between calls; clean_all() resets it before each read
+    def build_helper():
+        return FaceRestoreHelper(
+            upscale_factor=upscale_factor,
+            face_size=face_size,
+            crop_ratio=(1, 1),
+            det_model="retinaface_resnet50",
+            use_parse=use_parse,
+            device=torch.device(device),
+        )
+
+    face_helper = cached_model(
+        ("restore_faces_helper", upscale_factor, face_size, use_parse, str(device)),
+        build_helper,
     )
+    face_helper.clean_all()
 
     # Convert PIL to BGR numpy (facexlib format)
     input_bgr = np.array(image.convert("RGB"))[:, :, ::-1].copy()

dw/worker.py

@@ -357,15 +357,38 @@ class WorkflowWorker:
         # what runs out of memory
         if identity != self.workflow_identity:
             if self.workflow_identity is not None:
-                self._reply(
-                    Output(message="Workflow changed - releasing cached models...")
-                )
-                self._reply(Output(message=self._cleanup_all()))
+                keep = self._keys_worth_keeping(command, job.workflow)
+                if keep:
+                    self._reply(
+                        Output(
+                            message=f"Workflow changed - keeping {len(keep)} warm "
+                            "model(s) the new workflow loads, releasing the rest..."
+                        )
+                    )
+                else:
+                    self._reply(
+                        Output(message="Workflow changed - releasing cached models...")
+                    )
+                self._reply(Output(message=self._cleanup_all(keep=keep)))
             self.workflow_identity = identity
 
         self._reply(WorkflowLoaded(workflow_name=job.workflow.name))
         self._reply(Output(message=f"Executing workflow: {job.workflow.name}"))
 
+    def _keys_worth_keeping(self, command, workflow):
+        """The resident pipeline keys the next workflow loads anyway. Any
+        failure to prepare the definition answers the empty set - the run
+        itself will report what is wrong, and a full release is the safe
+        default on a card that cannot hold two stacks."""
+        try:
+            wanted = workflow_run.pipeline_keys(
+                workflow, command.get("arguments") or {}
+            )
+        except Exception as e:
+            logger.debug(f"Could not take the next workflow's pipeline keys: {e}")
+            return set()
+        return wanted & set(self.loaded_pipelines)
+
     def _run_job(self, command: Dict[str, Any], job: "_Job"):
         """Phase 3: run the workflow, streaming its events, then reclaim."""
         workflow = job.workflow
@@ -635,10 +658,11 @@ class WorkflowWorker:
 
         logger.debug("Inter-run cleanup complete")
 
-    def _cleanup_all(self):
+    def _cleanup_all(self, keep=frozenset()):
         """
         Complete cleanup - clear all cached models and components.
-        Called when workflow changes or on shutdown.
+        Called when workflow changes or on shutdown. Pipelines whose key is
+        in `keep` survive; with `keep` empty everything goes.
 
         Returns:
             One line saying what host memory looks like on the other side of
@@ -652,11 +676,20 @@ class WorkflowWorker:
         logger.info("Performing full cleanup")
 
         # Clear pipeline cache and any models task handlers cached
+        kept = {k: v for k, v in self.loaded_pipelines.items() if k in keep}
+        dropped = len(self.loaded_pipelines) - len(kept)
+        # Cleared and refilled in place, so the kept entries keep their
+        # identity
         self.loaded_pipelines.clear()
+        self.loaded_pipelines.update(kept)
+        # Every run republishes shared components from the pipelines it hits
+        # (workflow.py: publish_shared_components on a cache hit)
         self.shared_components.clear()
-        # The keys addressed entries that are now gone; keeping them would
-        # have a later step chase a release that has already happened
-        self.prior_step_keys.clear()
+        # A step's prior key addresses an entry that is now gone - unless it
+        # was kept, in which case a redefinition next run still releases it
+        self.prior_step_keys = {
+            name: key for name, key in self.prior_step_keys.items() if key in kept
+        }
         clear_model_cache()
         # Drop cached step results too - stale results would otherwise
         # survive a memory clear and keep getting served for steps whose
@@ -703,9 +736,10 @@ class WorkflowWorker:
             f"Released cached models: host RSS {_mb(stats.get('rss_mb'))}, "
             f"{_mb(stats.get('available_mb'))} available"
             + (f" ({released:.0f} MB returned to the OS)" if released else "")
+            + (f", kept {len(kept)} warm" if kept else "")
         )
 
-        logger.info(f"Full cleanup complete. {summary}")
+        logger.info(f"Full cleanup complete ({dropped} pipeline(s) dropped). {summary}")
         return summary
 
     def _parent_is_dead(self) -> bool:

dw/workflow.py

@@ -27,7 +27,7 @@ from .variables import (
     resolve_variable_values,
     set_variables,
 )
-from .pipeline_processors.pipeline import Pipeline
+from .pipeline_processors.pipeline import Pipeline, apply_runtime_settings
 from .tasks.task import Task
 from . import get_device
 from .pipeline_ownership import (
@@ -730,7 +730,7 @@ class Workflow:
         # Pipelines are cached by what they load, not what step loads them
         ownership = self.pipeline_ownership
         cache_key = ownership.load_key(step_definition)
-        ownership.record(step_name, cache_key)
+        ownership.record(step_name, cache_key, step_definition["pipeline"])
         get_context().touch_pipeline(cache_key)
 
         if cache_hit and cache_key not in previous_pipelines:
@@ -798,6 +798,12 @@ class Workflow:
                 "earlier pipeline step in this run (or it was released)"
             )
         previous_pipeline = previous_pipelines[referenced_key]
+        # Steps whose pipelines differ only in scale, alpha or shift share
+        # one model, and the last of them to run left its values on it: put
+        # the referenced step's own back
+        referenced_definition = self.pipeline_ownership.definition_for(reference_name)
+        if referenced_definition is not None:
+            apply_runtime_settings(referenced_definition, previous_pipeline.pipeline)
         return Pipeline(
             pipeline_reference,
             default_seed,

dw/workflow_run.py

@@ -62,6 +62,7 @@ from .step_cache import (
     reference_resolves_to,
     referenced_result_names,
     step_cache,
+    step_definition_keys,
     step_pipeline_keys,
 )
 from .subfolders import step_subfolder
@@ -138,6 +139,9 @@ class StepLoop:
     hits: set = field(default_factory=set)
     # Final result is the workflow return value
     last_result: object = None
+    # step_definition_keys of `steps`, taken before any step loaded - what
+    # the step cache folds in for a borrowed pipeline (cache_lookup)
+    definition_keys: dict = field(default_factory=dict)
 
 
 def run_base_dir(workflow):
@@ -367,14 +371,16 @@ def cache_lookup(
     step_seed,
     hits_this_run,
     cache_enabled,
-    pipeline_keys,
+    definition_keys,
 ):
     """Whether the step cache serves step `index`, as (cached_result or
     None, the step_data snapshot the entry is keyed on or None, whether
     a later step still reads this one's result, the names later steps
     still reference). Shared by run() and cache_hits() - see
-    prepare_definition for why. `pipeline_keys` is step_pipeline_keys
-    of `steps`, taken before the first step ran.
+    prepare_definition for why. `definition_keys` is step_definition_keys
+    of `steps`, taken before the first step ran - not the pipeline
+    ownership table, whose keys leave out a source's LoRA scale, alpha and
+    shift, each of which changes what a borrowing step produces.
     """
     # What later steps still read, which decides both whether this
     # step's result has to be kept alive after the step (release_unreferenced_results
@@ -411,7 +417,7 @@ def cache_lookup(
             # model - only the source step's does - so without this a
             # source model change would leave the borrowing step's
             # snapshot unchanged and serve a stale hit
-            borrowed = borrowed_pipeline_keys(steps, index, pipeline_keys)
+            borrowed = borrowed_pipeline_keys(steps, index, definition_keys)
             if borrowed:
                 step_data_snapshot["__borrowed_pipelines__"] = borrowed
         except Exception as ex:
@@ -465,7 +471,7 @@ def cache_hits(workflow, arguments):
         realize_args(steps, base_dir)
         # The same table run() takes at the same point, so a borrowed
         # key here is the key the run stored its entry under
-        pipeline_keys = step_pipeline_keys(steps)
+        definition_keys = step_definition_keys(steps)
         hits_this_run = set()
         hits = []
         for index, step_data in enumerate(steps):
@@ -479,7 +485,7 @@ def cache_hits(workflow, arguments):
                 step_seed,
                 hits_this_run,
                 True,
-                pipeline_keys,
+                definition_keys,
             )
             if cached_result is not None:
                 hits_this_run.add(step_data["name"])
@@ -489,6 +495,33 @@ def cache_hits(workflow, arguments):
         deactivate_output_root(output_root_token)
 
 
+def pipeline_keys(workflow, arguments):
+    """The set of pipeline cache keys a run of `workflow` with `arguments`
+    loads its steps under - the table run() and cache_hits() take
+    (step_pipeline_keys over the prepared definition). Prepares the
+    definition exactly as a run does and executes nothing: the worker asks
+    this before releasing the previous workflow's models, so a model the
+    next workflow loads anyway stays warm. A sub-workflow step loads its
+    own pipelines later and is not in the set; an unseeded workflow still
+    answers, since warmth does not depend on the step cache. The probe
+    realizes the steps because the run keys on the realized definition, at
+    the price of loading step media once per switch (the price cache_hits
+    already pays).
+    """
+    output_root_token = activate_output_root(workflow.output_dir)
+    try:
+        workflow_def = copy.deepcopy(workflow.workflow_definition)
+        base_dir = run_base_dir(workflow)
+        workflow_def, _, _ = prepare_definition(
+            workflow, workflow_def, arguments or {}, base_dir
+        )
+        steps = workflow_def.get("steps", [])
+        realize_args(steps, base_dir)
+        return set(step_pipeline_keys(steps).values())
+    finally:
+        deactivate_output_root(output_root_token)
+
+
 def prepare_run(workflow, record):
     """Phase B: the definition as this run works from it, and its seed.
 
@@ -678,6 +711,7 @@ def begin_steps(workflow, prepared, previous_pipelines, run_context):
         prepared.cache_enabled,
         run_context,
         pipelines,
+        definition_keys=step_definition_keys(steps),
     )
 
 
@@ -875,7 +909,7 @@ def run_step(workflow, loop, index, step_data, record):
         step_seed,
         loop.hits,
         loop.cache_enabled,
-        workflow.pipeline_ownership.running,
+        loop.definition_keys,
     )
     # The last step of a composed child whose parent does the
     # saving (#92) - its files are written once, by the parent