black-forest-labs/flux

⭐ 22,764 🍴 1,621 Python📄 Apache License 2.0（コード）、モデルごとに異なるライセンス GitHubで見る →

主な特徴

  • 120億パラメータの大規模モデル
  • 整流フロー（Rectified Flow）による効率的な生成
  • 多様なモデルバリアント（高速版、高品質版、編集特化版）
  • ガイダンス蒸留による推論ステップの削減
  • TensorRT対応による高速推論

リポジトリ解析: black-forest-labs/flux

基本情報

  • リポジトリ名: black-forest-labs/flux
  • 主要言語: Python
  • スター数: 22,764
  • フォーク数: 1,621
  • 最終更新: 継続的に更新中
  • ライセンス: Apache License 2.0（コード）、モデルごとに異なるライセンス
  • トピックス: image generation, diffusion models, text-to-image, AI art, machine learning

概要

一言で言うと

Black Forest Labsが開発した最先端の画像生成モデルファミリー「FLUX」の公式推論リポジトリ。高品質なテキストから画像への生成と高度な画像編集機能を提供。

詳細説明

FLUXは、120億パラメータの整流フロー変換器（Rectified Flow Transformer）をベースとした次世代の画像生成モデルです。従来の拡散モデルよりも効率的な整流フローアプローチを採用し、高速な推論と高品質な画像生成を実現しています。テキストから画像への生成だけでなく、インペインティング、アウトペインティング、構造条件付き生成、画像バリエーション生成など、包括的な画像生成・編集機能を提供します。

主な特徴

  • 120億パラメータの大規模モデル
  • 整流フロー（Rectified Flow）による効率的な生成
  • 多様なモデルバリアント（高速版、高品質版、編集特化版）
  • ガイダンス蒸留による推論ステップの削減
  • TensorRT対応による高速推論

使用方法

インストール

前提条件

  • Python 3.10以上
  • CUDA対応GPU（推奨：24GB以上のVRAM）
  • PyTorch 2.0以上
  • 最低16GBのシステムRAM

インストール手順

# 方法1: 標準インストール
cd $HOME && git clone https://github.com/black-forest-labs/flux
cd $HOME/flux
python3.10 -m venv .venv
source .venv/bin/activate
pip install -e ".[all]"

# 方法2: 最小インストール（基本機能のみ）
pip install -e .

# 方法3: TensorRT対応インストール
# NVIDIA Container Toolkitが必要
# 詳細は公式ドキュメント参照

基本的な使い方

Hello World相当の例

# インタラクティブモードで画像生成
python -m flux t2i --name flux-schnell --loop

# 単一画像の生成
python -m flux t2i --name flux-dev \
  --prompt "a serene landscape with mountains and lake during sunset" \
  --width 1024 --height 1024 \
  --output output.png

実践的な使用例

# Pythonスクリプトでの使用
from flux.util import load_flow_model, load_ae, load_t5, load_clip
from flux.sampling import prepare, denoise, unpack
import torch

# モデルのロード
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = load_flow_model("flux-dev", device)
ae = load_ae("flux-dev", device)
t5 = load_t5(device)
clip = load_clip(device)

# プロンプトの準備
prompt = "a futuristic cityscape with flying cars"
noise = torch.randn(1, 16, 128, 128).to(device)

# 画像生成
inp = prepare(t5, clip, noise, prompt)
timesteps = get_schedule(50, inp["img"].shape, shift=True)
x = denoise(model, **inp, timesteps=timesteps, guidance=3.5)
image = ae.decode(unpack(x, 1024, 1024))

# CLIでの高度な使用
# インペインティング
python -m flux fill \
  --img_cond_path original.png \
  --img_mask_path mask.png \
  --prompt "replace with beautiful flowers" \
  --name flux-fill-dev

# 構造条件付き生成（Cannyエッジ）
python -m flux control \
  --img_cond_path reference.jpg \
  --control_type canny \
  --prompt "anime style character" \
  --name flux-canny-dev

高度な使い方

# Kontextを使用した高度な画像編集
python -m flux kontext \
  --img_cond_path scene.jpg \
  --img_mask_path edit_area.png \
  --prompt "replace the logo with text 'FLUX'" \
  --rf_kwargs_override '{"map_all": false, "norm_cond": false}'

# Reduxを使用した画像バリエーション生成
python -m flux redux \
  --img_cond_path style_reference.jpg \
  --prompt "a portrait in the same artistic style" \
  --img_cond_strength 0.7

# Streamlitデモの起動
streamlit run demo_st.py

# バッチ処理スクリプト
for prompt in "forest" "ocean" "desert"; do
  python -m flux t2i \
    --name flux-schnell \
    --prompt "beautiful ${prompt} landscape" \
    --seed 42 \
    --output ${prompt}.png
done

# TensorRT最適化版の実行（高速推論）
python -m flux.trt.build_engine \
  --model flux-schnell \
  --precision fp16 \
  --batch_size 1

ドキュメント・リソース

公式ドキュメント

サンプル・デモ

  • demo_gr.py: Gradioベースのインタラクティブデモ
  • demo_st.py: Streamlitベースのテキスト生成デモ
  • demo_st_fill.py: インペインティング専用デモ
  • assets/: サンプル画像と結果例
  • APIプロバイダー: bfl.ml、Replicate、fal.aiでのホスト版

チュートリアル・ガイド

  • 基本的な画像生成ワークフロー
  • カスタムLoRAアダプターの使用
  • 商用利用のためのトラッキング設定
  • TensorRT最適化ガイド
  • ComfyUIとの統合方法

技術的詳細

アーキテクチャ

全体構造

FLUXは、整流フロー（Rectified Flow）アプローチを採用した120億パラメータのトランスフォーマーモデルです。従来の拡散モデルと異なり、より直線的な軌道で画像を生成することで、少ないステップで高品質な結果を実現します。

ディレクトリ構成

src/flux/
├── __main__.py           # CLIエントリーポイント
├── cli.py                # テキスト生成CLI
├── cli_control.py        # 構造条件付き生成
├── cli_fill.py           # インペインティング
├── cli_kontext.py        # 高度な編集
├── cli_redux.py          # 画像バリエーション
├── model.py              # コアモデル実装
├── sampling.py           # サンプリングロジック
├── math.py               # 数学的操作
├── util.py               # ユーティリティ関数
├── modules/              # モデルコンポーネント
│   ├── autoencoder.py    # VAE実装
│   ├── conditioner.py    # テキストエンコーダー
│   ├── layers.py         # トランスフォーマー層
│   ├── lora.py           # LoRAアダプター
│   └── image_embedders.py # 画像エンベッダー
└── trt/                  # TensorRT最適化

主要コンポーネント

  • Fluxモデル: ダブルストリームとシングルストリームのトランスフォーマーブロック

    • 場所: model.py
    • 機能: RoPE位置エンコーディング、注意機構、MLPレイヤー
    • パラメータ: 120億（12B）

  • テキストエンコーダー: T5とCLIPの組み合わせ

    • T5: 詳細なテキスト理解
    • CLIP: セマンティックな画像-テキスト対応
    • 統合: HFEmbedderによる統一処理

  • オートエンコーダー（VAE）: 潜在空間での処理

    • エンコーダー: 画像を潜在表現に変換
    • デコーダー: 潜在表現から画像を再構成
    • 圧縮率: 8x8

技術スタック

コア技術

  • 言語: Python 3.10+
  • フレームワーク:
    • PyTorch 2.0+（深層学習）
    • Transformers（テキストエンコーダー）
    • Diffusers（統合サポート）
  • 主要ライブラリ:
    • einops: テンソル操作
    • safetensors: モデル保存
    • sentencepiece: T5トークナイザー
    • fire: CLIインターフェース

開発・運用ツール

  • 最適化: TensorRT（BF16、FP8、FP4精度）
  • デモ: Gradio、Streamlit
  • デプロイ: Docker、クラウドAPI
  • 監視: 商用使用トラッキング

設計パターン・手法

  • 整流フロー: 効率的な生成軌道
  • ガイダンス蒸留: 推論ステップの削減
  • モジュラー設計: タスク別の専用モデル
  • プログレッシブ生成: 段階的な品質向上

データフロー・処理フロー

  1. テキストプロンプトの入力
  2. T5/CLIPによるテキストエンコーディング
  3. ノイズの初期化（ガウス分布）
  4. 整流フローによるデノイジング
  5. 潜在表現の生成
  6. VAEデコーダーによる画像再構成
  7. 後処理とコンテンツフィルタリング

API・インターフェース

公開API

CLIインターフェース

  • 目的: コマンドラインからの画像生成・編集
  • 主要コマンド:
# テキストから画像
flux t2i [OPTIONS]

# 構造条件付き生成
flux control [OPTIONS]

# インペインティング
flux fill [OPTIONS]

# 高度な編集
flux kontext [OPTIONS]

# 画像バリエーション
flux redux [OPTIONS]

Python API

# 基本的な使用例
from flux import Flux

# モデルの初期化
flux = Flux(model_name="flux-dev", device="cuda")

# 画像生成
image = flux.generate(
    prompt="a beautiful sunset",
    width=1024,
    height=1024,
    num_steps=50,
    guidance=3.5,
    seed=42
)

設定・カスタマイズ

主要パラメータ

# 生成パラメータ
--prompt           # テキストプロンプト
--width/--height   # 画像サイズ（64の倍数）
--num_steps        # サンプリングステップ数
--guidance         # ガイダンス強度
--seed             # ランダムシード
--init_image       # 初期画像（img2img）
--image_prompt     # 画像プロンプト（Redux）

# 高度な設定
--offload          # CPU/GPUメモリ管理
--lora_paths       # カスタムLoRAパス
--track_usage      # 商用利用トラッキング
--content_filter   # NSFWフィルタリング

拡張・プラグイン開発

  • カスタムLoRAアダプターの追加
  • 新しい画像エンベッダーの実装
  • サンプリング戦略のカスタマイズ
  • ComfyUIノードの開発

パフォーマンス・スケーラビリティ

パフォーマンス特性

  • FLUX.1 [schnell]: 1-4ステップで高速生成
  • FLUX.1 [dev]: 50ステップで高品質
  • メモリ使用量: 24GB VRAM推奨（CPUオフロード対応）
  • TensorRT最適化: 最大10倍の高速化

スケーラビリティ

  • バッチ処理対応
  • 分散推論サポート
  • クラウドAPIによるスケーリング
  • エッジデバイス向け量子化

制限事項

  • 高いVRAM要求（最小16GB）
  • 商用利用には使用追跡が必要（一部モデル）
  • 公人や著作権コンテンツのフィルタリング
  • dev版は非商用ライセンス

評価・所感

技術的評価

強み

  • 最先端の画像品質とプロンプト追従性
  • 整流フローによる効率的な生成
  • 包括的な画像編集機能
  • 優れたドキュメントとサンプルコード
  • 活発な開発とコミュニティサポート

改善の余地

  • メモリ要求の削減
  • より多様なモデルサイズの提供
  • リアルタイム生成の実現
  • エッジデバイス対応の強化

向いている用途

  • 高品質な画像生成が必要なプロジェクト
  • クリエイティブなコンテンツ制作
  • 研究開発（オープンウェイトモデル）
  • プロトタイピングとコンセプトデザイン
  • 画像編集とリタッチング

向いていない用途

  • リアルタイム生成が必要なアプリケーション
  • 低スペックデバイスでの動作
  • 完全な商用利用（dev版）
  • 大規模バッチ処理（コスト面）

総評

FLUXは、画像生成AI分野において重要な技術的進歩を示すプロジェクトです。整流フローアプローチの採用により、従来の拡散モデルよりも効率的で高品質な生成を実現しています。特に、モジュラーなアーキテクチャにより、様々な画像生成・編集タスクに対応できる点が優れています。オープンウェイトモデルの提供により、研究コミュニティにも大きく貢献しており、商用利用とオープンソースのバランスを取った賢明なライセンシング戦略も評価できます。今後のさらなる最適化と機能拡張により、画像生成AIの標準的なツールとなる可能性を秘めています。