Skip to content
LakonikPublic

Latest commit

 

History

117 Commits

Folders and files

Repository files navigation

LakonLab: Official Codebase for pi-H3, AsymFlow, pi-Flow, and GMFlow

Official PyTorch implementation of the following projects:

🔥News

  • [Nov 21, 2026] pi-H3 is released, the fastest MiniMax H3, with ComfyUI support. Try the pi-H3 Demo🤗.

  • [May 20, 2026] AsymFlow is now supported in our ComfyUI extension.

  • [May 14, 2026] AsymFlow is released.

  • [Dec 12, 2025] pi-FLUX.2 is now available for 4-step image generation and editing. Check out the pi-FLUX.2 Demo🤗. Please re-install the latest version of LakonLab (this repository) to use pi-FLUX.2.

  • [Nov 7, 2025] ComfyUI-piFlow is now available. Supports 4-step sampling of Qwen-Image and Flux.1 dev using 8-bit models on a single consumer-grade GPU, powered by ComfyUI.

Installation

The code has been tested in the following environment:

  • Linux (tested on Ubuntu 20 and above)
  • PyTorch 2.9+ (most tested on 2.10 and 2.11)

With the above prerequisites and setuptools installed, run pip install -e . --no-build-isolation from the repository root to install the LakonLab codebase and its dependencies.

An example of installation commands is shown below:

# Move to this repository (the folder with setup.py) after cloning
cd <PATH_TO_YOUR_LOCAL_REPO>

# Create uv environment (uv's managed Python includes the headers needed to build CUDA extensions)
uv venv --python 3.10 --managed-python
source .venv/bin/activate

# Install the build tool required by --no-build-isolation
uv pip install "setuptools<74"

# Install Pytorch. Goto https://pytorch.org/get-started/previous-versions/ to select the appropriate version
uv pip install torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128

# Install LakonLab in editable mode
uv pip install -e . --no-build-isolation

Additional notes:

  • If LD_LIBRARY_PATH points to a system CUDA installation of a different version than your PyTorch build, PyTorch may load mismatched cuBLAS libraries and fail with CUBLAS_STATUS_INVALID_VALUE. Remove those paths from LD_LIBRARY_PATH in that case.

  • Building CUDA extensions from source requires a CUDA toolkit with nvcc that supports your PyTorch build and target GPU, and a C++ compiler supported by that toolkit.

  • The CUDA extensions under lakonlab/ops are optional and compile on first use. The quant extension (INT8 GEMM, currently Hopper only) also needs a CUTLASS checkout at CUTLASS_PATH, otherwise Triton kernels are used. To prebuild the extensions at install time, set BUILD_EXT:

    CUTLASS_PATH=<PATH_TO_CUTLASS> BUILD_EXT=quant,gmflow_ops uv pip install -e . --no-build-isolation
  • To use the optional GMuon optimizer, install LakonLab with the gmuon extra.

  • To access FLUX models, please accept the FLUX.2 klein Base 9B conditions and FLUX.1 dev conditions, and then run hf auth login to login with your HuggingFace account.

Sol-Attn

Install the optional sol extra from the repository root to enable Sol-Attn sparse attention on supported GPUs.

uv pip install -e '.[sol]' --no-build-isolation

With a CUDA 13 build of PyTorch, also add 'nvidia-cutlass-dsl[cu13]' to that command to install the CUDA 13 CuTe runtime (see the CuTe DSL installation guide).

Codebase

LakonLab is a high-performance codebase for experimenting with large diffusion models. Key features of LakonLab include:

  • Performance optimizations:

    • Parallelism: Seamless switching between DDP, FSDP, and FSDP2, all supporting gradient accumulation and mixed precision.
    • Compilation: torch.compile is opt-in per module (compile_forward), with warmup support (bucket_warmup) so that every shape variant is compiled up front rather than mid-run.
    • Attention backends: Alternative attention backends such as FlashAttention and SageAttention are supported per module via the attention_backend_config model setting.
    • 8-bit quantization: Frozen linear layers can be quantized to W8A8 types. Supports fp8, fp8_blockwise, int8, int8_smoothquant, int8_convrot. Enabled via the freeze_quant_config model setting.
    • Weight tying: For LoRA fine-tuning, the base weights of the teacher, student, and EMA models are tied, sharing the same underlying memory. This is compatible with DDP and FSDP.
  • Advanced flow solvers:

    • FlowSDEScheduler: Generic flow SDE solver with an adjustable stochasticity parameter h, following
      $$dx_t=\left(f_t x_t - \frac{1 + h^2}{2} g_t^2 s_t(x_t)\right) dt + h g_t d \bar w_t ,$$
      where $s_t=\nabla\log p_t$, $f_t=-1/(1-t)$, and $g_t=\sqrt{2t/(1-t)}$. h=0 gives a flow ODE, h=1 a standard flow SDE, and h='inf' full re-noising.
    • FlowMapSDEScheduler: Generic flow SDE solver for few-step flow map models, with the same adjustable stochasticity parameter h.
  • Storage backends: Most I/O operations (e.g., dataloaders, checkpoint I/O) support both local filesystems and AWS S3. In addition, model checkpoints can be loaded from HuggingFace (link format huggingface://<HF_REPO_NAME>/<PATH_TO_MODEL>) and HTTP/HTTPS URLs directly.

  • Streamlined training and evaluation: Supports online evaluation using common metrics, including FID, KID, IS, Precision, Recall, CLIP similarity, VQAScore, HPSv2, and HPSv3. Supports exporting results to offline evaluators, including HPSv3 Benchmark, DPG-Bench, GenEval and LongText-Bench.

  • 3rd-party model inference reproduction:

LakonLab uses the configuration system and code structure from MMCV.

Acknowledgments

Citation

@misc{chen2026pih3,
  title        = {{pi-H3: Video Generation in 2–4 Steps Without a VAE Decoder}},
  author       = {Hansheng Chen and Shengqu Cai and Jiaming Song and Gordon Wetzstein and Xinchen Yan and Leonidas Guibas},
  year         = {2026},
  month        = nov,
  howpublished = {\url{https://hanshengchen.com/blog/pi-h3/}}
}

@article{chen2026decoding,
  title={Decoding Without a Decoder: Direct Pixel Prediction from Diffusion Transformers},
  author={Hansheng Chen and Shengqu Cai and Jan Ackermann and Rayhan Zirvi and Gordon Wetzstein and Xinchen Yan and Leonidas Guibas},
  journal={arXiv preprint arXiv:2611.22287},
  url={https://arxiv.org/abs/2611.22287},
  year={2026},
}

@article{asymflow,
  title={Asymmetric Flow Models},
  author={Hansheng Chen and Jan Ackermann and Minseo Kim and Gordon Wetzstein and Leonidas Guibas},
  url={https://arxiv.org/abs/2605.12964},
  journal={arXiv preprint arXiv:2605.12964},
  year={2026},
}

@article{piflow,
  title={pi-Flow: Policy-Based Few-Step Generation via Imitation Distillation}, 
  author={Hansheng Chen and Kai Zhang and Hao Tan and Leonidas Guibas and Gordon Wetzstein and Sai Bi},
  url={https://arxiv.org/abs/2510.14974}, 
  journal={arXiv preprint arXiv:2510.14974},
  year={2025},
}

@article{gmflow,
  title={Gaussian Mixture Flow Matching Models},
  author={Hansheng Chen and Kai Zhang and Hao Tan and Zexiang Xu and Fujun Luan and Leonidas Guibas and Gordon Wetzstein and Sai Bi},
  url={https://arxiv.org/abs/2504.05304}, 
  journal={arXiv preprint arXiv:2504.05304},
  year={2025},
}

Releases

Packages

Used by

Contributors

Languages