概要

• FLUX.2-klein-4B はBlack Forest Labsによる、完全C言語実装のテキスト→画像生成モデル
• 外部依存ゼロ （標準Cのみ）、MPSやBLASによる高速化も可能
• テキストから画像／画像から画像 生成に対応、Qwen3-4Bエンコーダー内蔵
• モデル変換・量子化不要、safetensors形式をそのまま利用
• Cライブラリとして統合可能、CLIツールも同梱

FLUX.2-klein-4B Pure C 実装の特徴

• 完全C言語実装、外部依存なし（C標準ライブラリのみ）
• MPS（Apple Silicon）やBLAS による高速化が可能
• テキストから画像生成 （text-to-image）機能
• 画像から画像生成 （image-to-image）機能
• Qwen3-4Bエンコーダー内蔵、外部で埋め込み計算不要
• モデル変換不要、safetensors形式のままfloatで利用
• 量子化なし、精度維持
• メモリ効率化 ：エンコーダー利用後に自動解放（約8GB節約）
• CLIツールおよびCライブラリ として利用可能

開発背景

• AIによるコード生成の実験 として週末プロジェクトで開発
• Claude Code（Claude Maxプラン） を活用し、全コードをAIで生成
• Pythonスタック非依存 の推論システムでAIの普及を目指す
• 既存のC/C++実装（GGMLベース） に対し、より簡潔な新規実装に挑戦

クイックスタート

• ビルド方法（バックエンド選択）
  • make mps：Apple Silicon（最速）
  • make blas：Intel Mac/Linux（OpenBLAS必須）
  • make generic：純C（依存なし、遅い）
• モデルダウンロード
  • pip install huggingface_hub
  • python download_model.py（約16GB）
• 画像生成例
  • ./flux -d flux-klein-model -p "A woman wearing sunglasses" -o output.png
• Python, PyTorch, CUDA不要 で推論可能

主な機能

• ゼロ依存 ：純C実装、スタンドアロン動作
• BLAS高速化 ：最大約30倍高速化（Apple Accelerate, OpenBLAS）
• Metal GPU自動対応 ：Apple Silicon Macで自動利用
• テキスト→画像生成
• 画像→画像生成 （プロンプトで変換）
• 統合テキストエンコーダー ：Qwen3-4B内蔵
• メモリ効率 ：自動エンコーダー解放

コマンドラインオプション

• 必須
  • -d, --dir PATH：モデルディレクトリ
  • -p, --prompt TEXT：生成プロンプト
  • -o, --output PATH：出力画像パス（.png/.ppm）
• 生成関連
  • -W, --width N：幅（デフォルト256）
  • -H, --height N：高さ（デフォルト256）
  • -s, --steps N：サンプリングステップ（デフォルト4）
  • -S, --seed N：ランダムシード
• 画像→画像関連
  • -i, --input PATH：入力画像
  • -t, --strength N：変換強度（0.0-1.0、デフォルト0.75）
• 出力・その他
  • -q, --quiet：静音モード
  • -v, --verbose：詳細表示
  • -e, --embeddings PATH：事前計算済み埋め込み利用
  • -h, --help：ヘルプ表示

再現性・シード管理

• 生成時のシード は常にstderrに出力
• 同じシード を指定すれば完全再現可能

ビルド方法

• バックエンド選択
  • make：利用可能なバックエンド表示
  • make generic：純C（遅い）
  • make blas：BLAS高速化
  • make mps：Apple Silicon Metal GPU
• 推奨環境
  • macOS Apple Silicon：make mps
  • macOS Intel/Linux（OpenBLAS）：make blas
  • Linux（OpenBLASなし）：make generic
• OpenBLASインストール例
  • Ubuntu/Debian：sudo apt install libopenblas-dev
  • Fedora：sudo dnf install openblas-devel
• その他
  • make clean：ビルド成果物削除
  • make info：バックエンド情報表示
  • make test：リファレンス画像テスト

モデルダウンロード内容

• HuggingFace経由で約16GB
  • VAE（約300MB）
  • Transformer（約4GB）
  • Qwen3-4B Text Encoder（約8GB）
  • Tokenizer

技術詳細

• モデル構成
  • Transformer：5ダブルブロック＋20シングルブロック、3072隠れ次元、24ヘッド
  • VAE：AutoencoderKL、128チャネル、8倍圧縮
  • Text Encoder：Qwen3-4B、36層、2560隠れ次元
• 推論ステップ ：4ステップで高品質画像生成
• メモリ要件
  • テキストエンコード時：約8GB
  • Diffusion時：約8GB（トランスフォーマー＋VAE＋アクティベーション）
  • ピーク時：約16GB
• エンコーダーは自動解放、複数プロンプト時は自動再ロード

ベンチマーク

• Apple M3 Max（128GB RAM）での生成速度
  • 512x512：C(MPS) 49.6s、C(BLAS) 51.9s、PyTorch(MPS) 5.4s
  • 256x256：C(MPS) 32.4s、C(BLAS) 29.7s、PyTorch(MPS) 3.0s
  • 64x64：C(MPS) 25.0s、C(BLAS) 23.5s、C(Generic) 605.6s、PyTorch(MPS) 2.2s
• 解像度制限
  • 最大：1024x1024ピクセル
  • 最小：64x64ピクセル（16の倍数必須）

CライブラリAPI

• libflux.aをリンク、flux.hをインクルード
• 主な関数
  • flux_ctx *flux_load_dir(const char *model_dir);：モデル読み込み
  • void flux_free(flux_ctx *ctx);：リソース解放
  • flux_image *flux_generate(flux_ctx *ctx, const char *prompt, const flux_params *params);：テキスト→画像生成
  • flux_image *flux_img2img(flux_ctx *ctx, const char *prompt, const flux_image *input, const flux_params *params);：画像→画像生成
  • flux_image *flux_image_load(const char *path);：画像読み込み（PNG/PPM）
  • int flux_image_save(const flux_image *img, const char *path);：画像保存
  • flux_image *flux_image_resize(const flux_image *img, int new_w, int new_h);：リサイズ
  • void flux_image_free(flux_image *img);：画像解放
  • void flux_set_seed(int64_t seed);：シード設定
  • const char *flux_get_error(void);：エラー取得
  • void flux_release_text_encoder(flux_ctx *ctx);：エンコーダー手動解放
• パラメータ構造体
  • width：画像幅
  • height：画像高さ
  • num_steps：ステップ数
  • guidance_scale：CFGスケール
  • seed：シード
  • strength：img2img用強度

利用例（プログラム断片）

• テキスト→画像生成
  • モデルロード、パラメータ設定、画像生成、保存、解放
• 画像→画像変換
  • 入力画像ロード、プロンプト指定、強度設定、変換、保存
• 複数画像生成
  • 同一プロンプト・異なるシードで繰り返し生成

エラーハンドリング

• 失敗時はNULL返却、flux_get_error()で詳細取得

---

この内容により、 FLUX.2-klein-4B の特徴・使い方・技術的背景が把握可能。 C言語での高速・省依存AI画像生成 に興味がある開発者・研究者に最適なプロジェクト。