README.md

metadata

title: Flux2
emoji: 🏆
colorFrom: yellow
colorTo: yellow
sdk: gradio
sdk_version: 6.2.0
python_version: 3.11.6
app_file: app.py
pinned: false
license: mit

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

FLUX.2 Inference

FLUX.2 のオープンウェイトモデルをローカルで実行するための推論コードです。画像生成・編集に対応し、テキストエンコードから画像生成まで完全にローカルで処理できます。

by Black Forest Labs: https://bfl.ai API ドキュメント: https://docs.bfl.ai

概要

• 完全ローカル実行: テキストエンコーダー（Mistral3 Small）、フローモデル、オートエンコーダーをすべてローカルGPUで実行
• プロンプトアップサンプリング: ローカルまたはOpenRouter経由でプロンプトを拡張（任意）
• モデル自動取得: Hugging Face Hub から black-forest-labs/FLUX.2-dev を自動ダウンロード、または手元の weights/ を利用
• 柔軟な実行方法: CLI（対話モード・単発実行）、Diffusers パイプライン、Jupyter Notebook

動作要件

• Python: 3.10以上、3.13未満（推奨: 3.11）
• GPU: CUDA対応GPU（推奨）
  • VRAM: 約20GB以上（4-bit量子化構成）
  • VRAM不足時: --cpu_offloading=True でCPUへ一部オフロード可能
• OS: Linux / macOS / Windows（WSL2推奨）

環境構築

uvによるセットアップ（推奨）

# uvのインストール（未インストールの場合）
pip install uv
# 依存関係のインストール
uv sync

# 仮想環境の有効化
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

Hugging Face ログイン

モデルを自動取得する場合、Hugging Face へのログインが必要です:

# gated モデルへのアクセス承認を事前に取得
# https://huggingface.co/black-forest-labs/FLUX.2-dev

uv run hf auth login

モデルウェイトの指定（任意）

同梱の weights/ ディレクトリを利用する場合、環境変数で指定できます:

export FLUX2_MODEL_PATH="$(pwd)/weights/flux2-dev.safetensors"
export AE_MODEL_PATH="$(pwd)/weights/ae.safetensors"

自動ダウンロード時のキャッシュ場所:

~/.cache/huggingface/hub/

カスタムキャッシュディレクトリを使う場合:

export HF_HOME=/path/to/custom/cache

デモの利用方法

詳細はFlux2 READMEを参照。

Diffusers パイプライン（Python）

ローカルでテキストエンコードを実行する例: GPUのVRAMが24~32GBの場合は、以下の4bit量子化したモデルで完全にローカル環境で実行可能。

import torch
from diffusers import Flux2Pipeline
from PIL import Image

repo_id = "diffusers/FLUX.2-dev-bnb-4bit"
device = "cuda:0"
torch_dtype = torch.bfloat16

# パイプラインの初期化
pipe = Flux2Pipeline.from_pretrained(
    repo_id, torch_dtype=torch_dtype
).to(device)

# メモリ最適化（任意）
pipe.enable_model_cpu_offload()

# 画像生成
prompt = "a photo of a forest with mist swirling around the tree trunks"
input_image = Image.open("input.jpg")  # 任意

image = pipe(
    prompt=prompt,
    image=[input_image],  # 省略可能
    generator=torch.Generator(device=device).manual_seed(42),
    num_inference_steps=28,
    guidance_scale=4.0,
).images[0]

image.save("output.png")

4. Jupyter Notebook

プロジェクト内の test.ipynb にサンプルコードがあります:

uv run jupyter notebook test.ipynb

パラメータ説明

パラメータ	説明	デフォルト
prompt	生成する画像の説明文	-
width / height	出力画像サイズ（ピクセル）	1360 / 768
num_steps	デノイジングステップ数	50
guidance	ガイダンススケール（高いほどプロンプトに忠実）	4.0
seed	乱数シード（再現性確保）	ランダム
input_images	入力画像パス（編集モード）	なし
match_image_size	入力画像のサイズに合わせる（インデックス指定）	なし
upsample_prompt_mode	プロンプト拡張モード: none / local / openrouter	none
cpu_offloading	CPUオフロード有効化	False

参考ドキュメント

• Diffusers経由の利用方法
• プロンプトアップサンプリング解説
• オリジナルREADME（存在する場合）