Flux 2 Klein 純粋 C 推論

FLUX.2‑klein‑4B Pure C実装

このプログラムは、Black Forest Labs の FLUX.2‑klein‑4B モデルを用いてテキストプロンプト（およびオプションで他の画像）から画像を生成します。
ライブラリとしても利用可能で、C だけで実装されており、標準ライブラリ以外に依存はありません。MPS と BLAS のアクセラレーションは任意ですが推奨です。

概要

• ゼロ行の手作業コードで書かれた最初のオープンソースプロジェクト。すべてのロジックは Claude Code（Claude Max プラン）によって生成されました。
• 量子化やモデル変換は不要です。float 重みを含む safetensors ファイルをそのまま使用します。
• このコードベースは、Python スタックに依存しない推論システムが実用的であることを示し、オープンモデルの利用を解放し AI をより身近なものにしています。

クイックスタート

# ビルド（バックエンドを選択）
make mps        # Apple Silicon (最速)
make blas       # Intel Mac / Linux で OpenBLAS 使用時
make generic    # 純粋 C、依存なし

# モデルダウンロード (~16 GB)
pip install huggingface_hub
python download_model.py

# 画像生成
./flux -d flux-klein-model -p "A woman wearing sunglasses" -o output.png

推論時には Python ランタイム、PyTorch、CUDA ツールキットは不要です。

サンプル出力

./flux -d flux-klein-model \
       -p "A picture of a woman in 1960 America. Sunglasses. ASA 400 film. Black and White." \
       -W 250 -H 250 -o /tmp/woman.png

画像→画像変換：

./flux -d flux-klein-model -i /tmp/woman.png \
       -p "oil painting of woman with sunglasses" -v -H 256 -W 256 \
       -o /tmp/woman2.png

主な機能

使い方

テキスト→画像

./flux -d flux-klein-model \
       -p "A fluffy orange cat sitting on a windowsill" \
       -o cat.png

画像→画像（スタイル転送）

./flux -d flux-klein-model \
       -p "oil painting style" \
       -i photo.png \
       -o painting.png \
       -t 0.7

-t

• 0.0 – 変更なし（出力＝入力）
• 1.0 – 完全生成（入力は構図ヒントのみ）
• 0.7 – スタイル転送に適したバランス

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

-d, --dir PATH

-p, --prompt TEXT

-o, --output PATH

-W, --width N

-H, --height N

-s, --steps N

-S, --seed N

-i, --input PATH

-t, --strength N

-q, --quiet

-v, --verbose

-e, --embeddings PATH

-h, --help

再現性

乱数シードは必ず stderr に出力されます。

$ ./flux -d flux-klein-model -p "a landscape" -o out.png
Seed: 1705612345
out.png

同じ画像を再生成するには、印刷されたシードを使用します：

./flux -d flux-klein-model -p "a landscape" -o out.png -S 1705612345

ビルド

ビルド時にバックエンドを選択

make            # 利用可能なバックエンド一覧表示
make generic    # 純粋 C、依存なし（遅い）
make blas       # BLAS アクセラレーション (~30倍高速)
make mps        # Apple Silicon Metal GPU (最速、macOS 限定)

推奨設定

• macOS Apple Silicon:

  make mps

• macOS Intel:

  make blas

• Linux OpenBLAS 使用時:

  make blas

• Linux で OpenBLAS 未使用時:

  make generic

make blas

（Linux）の手順

# Ubuntu/Debian
sudo apt install libopenblas-dev

# Fedora
sudo dnf install openblas-devel

その他のターゲット

make clean      # ビルドアーティファクトを削除
make info       # このプラットフォームで利用可能なバックエンド表示
make test       # 参照画像テスト実行

モデルダウンロード

モデル重みは HuggingFace から取得します。

pip install huggingface_hub
python download_model.py

これにより

./flux-klein-model

技術詳細

モデル構成

推論は「ディルクションモデル」で 4 ステップ のサンプリングを使用します。

メモリ要件

テキストエンコーダは使用後自動で解放され、ディフュージョン時のピークメモリを削減します。異なるプロンプトで複数画像を生成する際には、エンコーダが再ロードされます。

解像度制限

• 最大: 1024 × 1024 ピクセル（それ以上は膨大なメモリが必要）
• 最小: 64 × 64 ピクセル
• VAE の下り圧縮係数により、寸法は必ず 16 の倍数である必要があります。

C ライブラリ API

libflux.a

flux.h

コア関数

flux_ctx *flux_load_dir(const char *model_dir);   /* モデルをロード、失敗時は NULL */
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);  /* 0=成功、-1=エラー */
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);     /* 手動で ~8 GB を解放（任意） */

パラメータ構造体

typedef struct {
    int width;              /* 出力幅 (デフォルト 256) */
    int height;             /* 出力高さ (デフォルト 256) */
    int num_steps;          /* デノイズステップ数、klein 用は 4 (デフォルト 4) */
    float guidance_scale;   /* CFG スケール、klein 用は 1.0 (デフォルト 1.0) */
    int64_t seed;           /* 乱数シード、-1 はランダム (デフォルト -1) */
    float strength;         /* img2img のみ: 0.0–1.0 (デフォルト 0.75) */
} flux_params;

#define FLUX_PARAMS_DEFAULT { 256, 256, 4, 1.0f, -1, 0.75f }

サンプルプログラム

テキスト→画像生成

#include "flux.h"
#include <stdio.h>

int main(void) {
    flux_ctx *ctx = flux_load_dir("flux-klein-model");
    if (!ctx) {
        fprintf(stderr, "Failed to load model: %s\n", flux_get_error());
        return 1;
    }

    flux_params params = FLUX_PARAMS_DEFAULT;
    params.width = 512;
    params.height = 512;
    params.seed = 42;          /* -1 はランダムシード */

    flux_image *img = flux_generate(ctx,
                                    "A fluffy orange cat in a sunbeam",
                                    &params);
    if (!img) {
        fprintf(stderr, "Generation failed: %s\n", flux_get_error());
        flux_free(ctx);
        return 1;
    }

    flux_image_save(img, "cat.png");
    printf("Saved cat.png (%dx%d)\n", img->width, img->height);

    flux_image_free(img);
    flux_free(ctx);
    return 0;
}

コンパイル例：

# macOS
gcc -o myapp myapp.c -L. -lflux -lm -framework Accelerate

# Linux
gcc -o myapp myapp.c -L. -lflux -lm -lopenblas

画像→画像変換

#include "flux.h"
#include <stdio.h>

int main(void) {
    flux_ctx *ctx = flux_load_dir("flux-klein-model");
    if (!ctx) return 1;

    flux_image *photo = flux_image_load("photo.png");
    if (!photo) {
        fprintf(stderr, "Failed to load image\n");
        flux_free(ctx);
        return 1;
    }

    flux_params params = FLUX_PARAMS_DEFAULT;
    params.strength = 0.7;     /* 0.0: 変更なし、1.0: 完全再生成 */
    params.seed = 123;

    flux_image *painting = flux_img2img(ctx,
                                       "oil painting, impressionist style",
                                       photo,
                                       &params);
    flux_image_free(photo);

    if (!painting) {
        fprintf(stderr, "Transformation failed: %s\n", flux_get_error());
        flux_free(ctx);
        return 1;
    }

    flux_image_save(painting, "painting.png");
    printf("Saved painting.png\n");

    flux_image_free(painting);
    flux_free(ctx);
    return 0;
}

エラーハンドリング

失敗する可能性のある関数は

NULL

flux_get_error()

flux_ctx *ctx = flux_load_dir("nonexistent-model");
if (!ctx) {
    fprintf(stderr, "Error: %s\n", flux_get_error());
    /* 例: "Failed to load VAE - cannot generate images" */
}

ライセンス

MIT © Salvatore
すべてのソースファイルは MIT ライセンスで公開されています。