From f7abcbfeaf1d28a2b4173158bf9d02373ce619a1 Mon Sep 17 00:00:00 2001 From: "yiyi@huggingface.co" Date: Sun, 15 Feb 2026 02:40:32 +0000 Subject: [PATCH 1/7] update --- .../modular_diffusers/auto_pipeline_blocks.md | 77 ++++++++++++++++++- 1 file changed, 73 insertions(+), 4 deletions(-) diff --git a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md index 2d4d82c735bd..28fea81f0943 100644 --- a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md +++ b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md @@ -121,7 +121,7 @@ from diffusers.modular_pipelines import AutoPipelineBlocks class AutoImageBlocks(AutoPipelineBlocks): # List of sub-block classes to choose from - block_classes = [block_inpaint_cls, block_i2i_cls, block_t2i_cls] + block_classes = [InpaintBlock, ImageToImageBlock, TextToImageBlock] # Names for each block in the same order block_names = ["inpaint", "img2img", "text2img"] # Trigger inputs that determine which block to run @@ -129,8 +129,8 @@ class AutoImageBlocks(AutoPipelineBlocks): # - "image" triggers img2img workflow (but only if mask is not provided) # - if none of above, runs the text2img workflow (default) block_trigger_inputs = ["mask", "image", None] - # Description is extremely important for AutoPipelineBlocks + @property def description(self): return ( "Pipeline generates images given different types of conditions!\n" @@ -141,7 +141,7 @@ class AutoImageBlocks(AutoPipelineBlocks): ) ``` -It is **very** important to include a `description` to avoid any confusion over how to run a block and what inputs are required. While [`~modular_pipelines.AutoPipelineBlocks`] are convenient, it's conditional logic may be difficult to figure out if it isn't properly explained. +It is **very** important to include a `description` to avoid any confusion over how to run a block and what inputs are required. While [`~modular_pipelines.AutoPipelineBlocks`] are convenient, its conditional logic may be difficult to figure out if it isn't properly explained. Create an instance of `AutoImageBlocks`. @@ -152,5 +152,74 @@ auto_blocks = AutoImageBlocks() For more complex compositions, such as nested [`~modular_pipelines.AutoPipelineBlocks`] blocks when they're used as sub-blocks in larger pipelines, use the [`~modular_pipelines.SequentialPipelineBlocks.get_execution_blocks`] method to extract the a block that is actually run based on your input. ```py -auto_blocks.get_execution_blocks("mask") +auto_blocks.get_execution_blocks(mask=True) +``` + +## ConditionalPipelineBlocks + +[`~modular_pipelines.AutoPipelineBlocks`] is a special case of [`~modular_pipelines.ConditionalPipelineBlocks`]. While [`~modular_pipelines.AutoPipelineBlocks`] selects blocks based on whether a trigger input is provided or not, [`~modular_pipelines.ConditionalPipelineBlocks`] lets you implement a `select_block` method with any custom selection logic. + +Here is the same example written using [`~modular_pipelines.ConditionalPipelineBlocks`] directly: + +```py +from diffusers.modular_pipelines import ConditionalPipelineBlocks + +class AutoImageBlocks(ConditionalPipelineBlocks): + block_classes = [block_inpaint_cls, block_i2i_cls, block_t2i_cls] + block_names = ["inpaint", "img2img", "text2img"] + block_trigger_inputs = ["mask", "image"] + default_block_name = "text2img" + + @property + def description(self): + return ( + "Pipeline generates images given different types of conditions!\n" + + "This is an auto pipeline block that works for text2img, img2img and inpainting tasks.\n" + + " - inpaint workflow is run when `mask` is provided.\n" + + " - img2img workflow is run when `image` is provided (but only when `mask` is not provided).\n" + + " - text2img workflow is run when neither `image` nor `mask` is provided.\n" + ) + + def select_block(self, mask=None, image=None) -> str | None: + if mask is not None: + return "inpaint" + if image is not None: + return "img2img" + return None # falls back to default_block_name ("text2img") +``` + +The inputs listed in `block_trigger_inputs` are passed as keyword arguments to `select_block()`. When `select_block` returns `None`, it falls back to `default_block_name`. If `default_block_name` is also `None`, the entire conditional block is skipped — this is useful for optional processing steps that should only run when specific inputs are provided. + +## Workflows + +Pipelines that contain conditional blocks ([~modular_pipelines.AutoPipelineBlocks] or [~modular_pipelines.ConditionalPipelineBlocks]) can support multiple workflows — for example, our SDXL modular pipeline supports a dozen workflows all in one pipeline. But this also means it can be confusing for users to know what workflows are supported and how to run them. For pipeline builders, it's useful to be able to extract only the blocks relevant to a specific workflow. + +We recommend defining a `_workflow_map` to give each workflow a name and explicitly list the inputs it requires. + +```py +from diffusers.modular_pipelines import SequentialPipelineBlocks + +class MyPipelineBlocks(SequentialPipelineBlocks): + block_classes = [TextEncoderBlock, AutoImageBlocks, DecodeBlock] + block_names = ["text_encoder", "auto_image", "decode"] + + _workflow_map = { + "text2image": {"prompt": True}, + "image2image": {"image": True, "prompt": True}, + "inpaint": {"mask": True, "image": True, "prompt": True}, + } +``` + + All of our built-in modular pipelines come with workflows defined. You can list them all supported workflows like this: + +```py +pipeline_blocks = MyPipelineBlocks() +pipeline_blocks.available_workflows +# ['text2image', 'image2image', 'inpaint'] +``` + +And retrieve the execution blocks for a specific workflow. This returns a [`~modular_pipelines.SequentialPipelineBlocks`] containing only the blocks that would actually execute for that workflow, which is useful for inspecting and debugging. + +```py +pipeline_blocks.get_workflow("inpaint") ``` \ No newline at end of file From 2a11fa56ef013c25492622456ff02287b0939c57 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Sat, 14 Feb 2026 16:42:34 -1000 Subject: [PATCH 2/7] Apply suggestion from @yiyixuxu --- docs/source/en/modular_diffusers/auto_pipeline_blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md index 28fea81f0943..fbdcd9dc7e0f 100644 --- a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md +++ b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md @@ -165,7 +165,7 @@ Here is the same example written using [`~modular_pipelines.ConditionalPipelineB from diffusers.modular_pipelines import ConditionalPipelineBlocks class AutoImageBlocks(ConditionalPipelineBlocks): - block_classes = [block_inpaint_cls, block_i2i_cls, block_t2i_cls] + block_classes = [InpaintBlock, ImageToImageBlock, TextToImageBlock] block_names = ["inpaint", "img2img", "text2img"] block_trigger_inputs = ["mask", "image"] default_block_name = "text2img" From 2bac8e0d85b5a53e044c0b82eba0f4e9b3482c50 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 26 Feb 2026 20:48:18 -1000 Subject: [PATCH 3/7] Update docs/source/en/modular_diffusers/auto_pipeline_blocks.md Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> --- docs/source/en/modular_diffusers/auto_pipeline_blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md index fbdcd9dc7e0f..358200adf6f6 100644 --- a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md +++ b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md @@ -157,7 +157,7 @@ auto_blocks.get_execution_blocks(mask=True) ## ConditionalPipelineBlocks -[`~modular_pipelines.AutoPipelineBlocks`] is a special case of [`~modular_pipelines.ConditionalPipelineBlocks`]. While [`~modular_pipelines.AutoPipelineBlocks`] selects blocks based on whether a trigger input is provided or not, [`~modular_pipelines.ConditionalPipelineBlocks`] lets you implement a `select_block` method with any custom selection logic. +[`~modular_pipelines.AutoPipelineBlocks`] is a special case of [`~modular_pipelines.ConditionalPipelineBlocks`]. While [`~modular_pipelines.AutoPipelineBlocks`] selects blocks based on whether a trigger input is provided or not, [`~modular_pipelines.ConditionalPipelineBlocks`] is able to select a block based on custom selection logic provided in the `select_block` method. Here is the same example written using [`~modular_pipelines.ConditionalPipelineBlocks`] directly: From 5168edcb0a9eb5e3b056bb1eacea27e71341259e Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 26 Feb 2026 20:48:29 -1000 Subject: [PATCH 4/7] Update docs/source/en/modular_diffusers/auto_pipeline_blocks.md Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> --- docs/source/en/modular_diffusers/auto_pipeline_blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md index 358200adf6f6..c950323b4454 100644 --- a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md +++ b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md @@ -192,7 +192,7 @@ The inputs listed in `block_trigger_inputs` are passed as keyword arguments to ` ## Workflows -Pipelines that contain conditional blocks ([~modular_pipelines.AutoPipelineBlocks] or [~modular_pipelines.ConditionalPipelineBlocks]) can support multiple workflows — for example, our SDXL modular pipeline supports a dozen workflows all in one pipeline. But this also means it can be confusing for users to know what workflows are supported and how to run them. For pipeline builders, it's useful to be able to extract only the blocks relevant to a specific workflow. +Pipelines that contain conditional blocks ([`~modular_pipelines.AutoPipelineBlocks`] or [`~modular_pipelines.ConditionalPipelineBlocks]`) can support multiple workflows — for example, our SDXL modular pipeline supports a dozen workflows all in one pipeline. But this also means it can be confusing for users to know what workflows are supported and how to run them. For pipeline builders, it's useful to be able to extract only the blocks relevant to a specific workflow. We recommend defining a `_workflow_map` to give each workflow a name and explicitly list the inputs it requires. From 62c1372b5fed6ef8c8d3ab41de7ff604091cdc86 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 26 Feb 2026 20:48:39 -1000 Subject: [PATCH 5/7] Update docs/source/en/modular_diffusers/auto_pipeline_blocks.md Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> --- docs/source/en/modular_diffusers/auto_pipeline_blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md index c950323b4454..087b87e34c0c 100644 --- a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md +++ b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md @@ -210,7 +210,7 @@ class MyPipelineBlocks(SequentialPipelineBlocks): } ``` - All of our built-in modular pipelines come with workflows defined. You can list them all supported workflows like this: +All of our built-in modular pipelines come with pre-defined workflows. The `available_workflows` property lists all supported workflows: ```py pipeline_blocks = MyPipelineBlocks() From a0976321fe59a9eced6dbd215e94b0598c397fa3 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 26 Feb 2026 20:48:50 -1000 Subject: [PATCH 6/7] Update docs/source/en/modular_diffusers/auto_pipeline_blocks.md Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> --- docs/source/en/modular_diffusers/auto_pipeline_blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md index 087b87e34c0c..1bcf1d691036 100644 --- a/docs/source/en/modular_diffusers/auto_pipeline_blocks.md +++ b/docs/source/en/modular_diffusers/auto_pipeline_blocks.md @@ -218,7 +218,7 @@ pipeline_blocks.available_workflows # ['text2image', 'image2image', 'inpaint'] ``` -And retrieve the execution blocks for a specific workflow. This returns a [`~modular_pipelines.SequentialPipelineBlocks`] containing only the blocks that would actually execute for that workflow, which is useful for inspecting and debugging. +Retrieve a specific workflow with `get_workflow` to inspect and debug a specific block that executes the workflow. ```py pipeline_blocks.get_workflow("inpaint") From ce3aa7b6b16f71e3074945465743ff93f1bbcae7 Mon Sep 17 00:00:00 2001 From: "yiyi@huggingface.co" Date: Fri, 27 Feb 2026 20:39:05 +0000 Subject: [PATCH 7/7] add to api --- docs/source/en/api/modular_diffusers/pipeline_blocks.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/source/en/api/modular_diffusers/pipeline_blocks.md b/docs/source/en/api/modular_diffusers/pipeline_blocks.md index 8ad581e679ac..4808f2cf3bbe 100644 --- a/docs/source/en/api/modular_diffusers/pipeline_blocks.md +++ b/docs/source/en/api/modular_diffusers/pipeline_blocks.md @@ -14,4 +14,8 @@ ## AutoPipelineBlocks -[[autodoc]] diffusers.modular_pipelines.modular_pipeline.AutoPipelineBlocks \ No newline at end of file +[[autodoc]] diffusers.modular_pipelines.modular_pipeline.AutoPipelineBlocks + +## ConditionalPipelineBlocks + +[[autodoc]] diffusers.modular_pipelines.modular_pipeline.ConditionalPipelineBlocks \ No newline at end of file