# Flow-Factory: one fine-tuning harness for diffusion and flow matching models

> Flow-Factory is a Python framework that puts online reinforcement learning and offline fine-tuning behind one interface for diffusion and flow-matching image and video models, covering GRPO, DPO, offline DPO, TDM, DMD2, DGPO, AWM and SFT across families from FLUX and Qwen-Image to Wan and LTX-2. It ships as a research alpha, and a few of its most recent models depend on a pinned Diffusers submodule rather than the published package.

**X-GenGroup/Flow-Factory** — A unified framework for easy fine-tuning in Flow-Matching models

- Repository: https://github.com/X-GenGroup/Flow-Factory
- Stars: 734 · Forks: 62
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/x-gengroup-flow-factory

## One trainer for many diffusion model families

The headline of the project is a unified framework for easy fine-tuning in flow-matching models, and the subtitle spells out the scope: unified online RL and offline fine-tuning for diffusion and flow-matching models.

The model table is the evidence. The supported list runs from stable-diffusion-3.5-medium and large at 2.5B and 8.1B parameters, through FLUX.1-dev at 13B, Z-Image-Turbo and Z-Image at 6B, Qwen-Image and Qwen-Image-2512 at 20B, FLUX.1-Kontext-dev, Qwen-Image-Edit-2509 and 2511, and up to FLUX.2-dev at 32B with the FLUX.2-klein variants at 4B and 9B, plus the FLUX.3 image klein base and step-distilled models at 5.5B, BAGEL-7B-MoT, the SenseNova-U1 models, and Qwen-Image 2.1 at 7B. Video runs through Wan2.1 and Wan2.2 in text-to-video and image-to-video, and the audio-video work covers LTX-2 and MiniMax H3.

Each entry carries a model type key, for example sd3-5, flux1, flux2, flux3, qwen-image, z-image, bagel, sensenova and wan2_t2v. That key is the hook the rest of the framework hangs on, and it is what lets a single configuration file address a model family rather than a specific checkpoint.

The audience is research teams who fine-tune image and video generators and want to move between algorithms without rewriting their scaffolding.

## The algorithm list is the real feature

The examples directory is where the framework's scope becomes concrete, because each subdirectory is an algorithm or a workflow rather than a model. The list runs awm, crd, dgpo, dmd2, dpo, dppo, grpo, nft, offline_dpo, opd, prompt_enhance, sft, tdm, tdm_r1 and template.

That is a wide spread of reinforcement learning and preference methods for generative models, and it is the part that distinguishes Flow-Factory from a training script for one model. GRPO is the online reinforcement learning workhorse, and it appears in per-model recipes. DPO and offline DPO cover preference optimisation with static data, and TDM and TDM_r1 sit alongside. DMD2, DGPO, AWM, CRD, DPPO, NFT and OPD fill in the rest of the online and offline space.

The SFT and template entries matter too. SFT is the supervised fine-tuning baseline, and template is what you copy when you add a model.

The structure implied by the examples is a matrix. Model family on one axis, algorithm on the other, and a configuration file at each cell, such as the GRPO plus LoRA recipe for FLUX.3 and the one for Qwen-Image 2.1. For a team that has already written its own trainer for one model, the value of adopting this is that the second model is a configuration change rather than a rewrite.

## Diffusion models that need a pinned Diffusers

The most recent entries in the news section reveal a constraint that catches people out.

The FLUX.3 Image Klein entry, dated 2026-10-16, says that both the base model and the step-distilled flow-map model can be trained with the GRPO plus LoRA recipe, and that it requires the pinned Diffusers submodule. The Qwen-Image 2.1 entry, dated 2026-09-20, carries the same requirement.

This is a real fork in the road. The project names the submodule explicitly in its readme, with a link to the pinned Diffusers section, and the repository layout shows why: there is a diffusers entry at the top level alongside .gitmodules, so the upstream Diffusers source is vendored into the tree rather than taken from the package index.

The dependency list in pyproject.toml explains why. It asks for diffusers>=0.40.0 and transformers>=4.57.1, with a comment noting compatibility with both v4.x and v5.x, and the readme says the pinned submodule is required for FLUX.3 and Qwen-Image 2.1. A published Diffusers release that does not yet know about a model architecture cannot load that architecture, no matter what the version constraint says.

The practical consequence is that a checkout of this repository, with its submodule initialised, gives you a working environment for the newest models, while a plain pip install of flow-factory may not.

## The acceleration block and the attention backend choice

Since 2026-02-01 the project supports multiple attention backends, and the configuration is a single block that can be combined with torch.compile and feature caching:

```yaml
acceleration:
  shared:
    - name: attention_backend
      params: { backend: "flash_hub" } # e.g. "native", "xformers", "flash_hub", "_flash_3_hub", "_flash_3_varlen_hub"
```

The name is forwarded to the Diffusers method transformer.set_attention_backend, and the readme links to the official list of available backends and to the acceleration guide in the guidance directory.

The recommendation is worth repeating because it saves a common afternoon. The project recommends installing kernels with pip install kernels and using a hub backend rather than building Flash-Attention yourself. Building Flash-Attention from source is a well known way to lose an afternoon to a compiler version mismatch, and the hub backends exist to avoid exactly that.

The configuration shape is the other point. Attention backend selection is a named entry in a shared list, with a params map, rather than a flat key. That is a schema designed to be extended, which matters for a framework whose model list is still growing.

## Datasets, prompt rewriting and the reward server

The readme organises the data side into a dataset section with subsections for offline SFT and preference data, text-to-image and text-to-video, and image-to-image and image-to-video, so the same training objective has to be fed the same shape of data whichever modality you are on.

The most recent news entry, dated 2026-10-17, adds prompt enhancement as a separate step. The ff-prompt-enhance tool rewrites a dataset's prompts with a model's prompt enhancer, which the entry lists as FLUX.3 pup, FLUX.2, LTX-2, the Qwen-Image-2.1 T2I and I2I rewriters, or any OpenAI-compatible server, and writes a new dataset whose prompts training then uses verbatim. A dedicated guidance page, guidance/prompt_enhance.md, covers it, and there is a matching examples/prompt_enhance/ directory.

Separating the rewrite into its own step is the significant design choice. Rewriting prompts inside the training loop means the dataset changes between runs, so a training run is not reproducible from its inputs alone. Writing a new dataset makes the rewrite an auditable artefact that can be inspected, diffed and reused.

The reward server lives in its own top-level reward_server/ directory, which is what makes online reinforcement learning possible in the first place, since a policy gradient method needs something to score generations. The readme's table of contents has a dedicated reward model section, and the repository keeps the server, the dataset tooling and the inference code in separate directories alongside src/, examples/, config/, guidance/, scripts/, tests/ and docker/.

## Packaging, the dependency floor and what alpha means here

The package is flow-factory, version 0.1.0, built with setuptools, requiring Python 3.10 or above and classified as Development Status 3 - Alpha with an audience of science and research. The licence is Apache-2.0.

The dependency list is long but not surprising for the domain. The deep learning core asks for torch at 2.10.0 or above, torchvision, torchaudio and torchcodec. The Hugging Face ecosystem brings transformers, diffusers, accelerate, peft, datasets, tokenizers and huggingface-hub. There are extras for T5 and Flux support with protobuf and sentencepiece, and a comment that ftfy is required by Diffusers Wan prompt normalization, which is the kind of note that only exists because a Wan run failed without it.

Optional extras cover two heavier dependencies: deepspeed for ZeRO optimization and bitsandbytes for 8-bit and 4-bit quantization. A comment in the manifest explains the absence of an acceleration extra group, because the diffusers_cache rollout feature is diffusers-native and needs no extra dependency.

Alpha is the honest word here, and it comes with a single tagged release, v0.1.0 from 2026-08-10, against a last push of 2026-10-20. The pace of work is high, with model support arriving roughly monthly across FLUX, Qwen, LTX and MiniMax, and the readme includes an acknowledgements section and a citation request, so this is research code with a citation culture rather than a product.

## Conclusion

Adopt Flow-Factory if you are fine-tuning a diffusion or flow-matching model with reinforcement learning and want one configuration format across GRPO, DPO, TDM, DMD2 and the offline variants, because the examples directory shows a recipe per algorithm and per model family rather than one script per experiment. Do not adopt it expecting a stable package, since the project is classified as an alpha with a single 0.1.0 release, or if you need a model whose Diffusers support is not yet pinned, because FLUX.3 and Qwen-Image 2.1 require the bundled submodule. Before you start, confirm that the diffusers directory in the repository is the pinned version your target model needs, check the reward server requirements for GRPO, and read the guidance pages named in the readme rather than assuming a default configuration is right for your model.

## FAQ

### What is Flow-Factory and which models does it support?

It is a unified framework for online RL and offline fine-tuning of diffusion and flow-matching models. The supported list covers stable-diffusion-3.5, FLUX.1, FLUX.2, FLUX.3, Qwen-Image and Qwen-Image-Edit, Z-Image, BAGEL-7B-MoT, SenseNova-U1, Wan2.1 and Wan2.2 for video, and LTX-2 and MiniMax H3 for audio-video.

### Which reinforcement learning algorithms does Flow-Factory implement?

The examples directory covers awm, crd, dgpo, dmd2, dpo, dppo, grpo, nft, offline_dpo, opd, sft, tdm and tdm_r1, each as a separate recipe directory, with prompt_enhance and template as the supporting workflows.

### Why does Flow-Factory require a pinned Diffusers submodule for some models?

The readme states that FLUX.3 Image Klein and Qwen-Image 2.1 support requires the pinned Diffusers submodule, because the published Diffusers release does not yet know those architectures. The repository carries the upstream source in a diffusers directory with a .gitmodules file, so a checkout with its submodule initialised gives a working environment for the newest models.

### How do I choose an attention backend in Flow-Factory?

Set the name attention_backend with a params map in the unified acceleration block, for example params: { backend: "flash_hub" }. The name is forwarded to the Diffusers transformer.set_attention_backend method, and the project recommends installing kernels with pip install kernels and using a hub backend rather than building Flash-Attention yourself.

### What licence and status does Flow-Factory have?

Apache-2.0, with the package version at 0.1.0 and the classifier Development Status 3 - Alpha, requiring Python 3.10 or above. The only tagged release is v0.1.0 from 2026-08-10, while the last push to the repository was on 2026-10-20.

## Sources

- [Issues](https://github.com/X-GenGroup/Flow-Factory/issues)
- [License: Apache-2.0](https://github.com/X-GenGroup/Flow-Factory/blob/main/LICENSE)
- [README](https://github.com/X-GenGroup/Flow-Factory/blob/main/README.md)
- [Releases](https://github.com/X-GenGroup/Flow-Factory/releases)
- [X-GenGroup/Flow-Factory on GitHub](https://github.com/X-GenGroup/Flow-Factory)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/x-gengroup-flow-factory