SKILL.md — mflux

名称

mflux

描述

通过 mflux 的 MLX 实现，在 Apple Silicon 设备上本地生成图像。支持 FLUX.2-klein-4B（默认，最快 4 步生成，Apache 2.0 许可）和 Z-Image-Turbo（6B，最高画质）。所有处理均在设备端完成——无需云端服务、无需 API 密钥、您的数据不会离开 Mac。

系统要求

• Apple Silicon Mac（M1 或更新机型）
• Python 3.10+
• macOS 13.5+
• 建议：16GB+ 内存（8GB 可通过量化支持）

安装

1. 安装 mflux（推荐使用 uv）

uv tool install --upgrade mflux --prerelease=allow

启用更快的模型下载（可选）：

uv tool install --upgrade mflux --with hf_transfer --prerelease=allow

2. 替代方式：通过 pip 安装

pip install -U mflux

3. 验证安装

mflux-generate --help
mflux-generate-z-image-turbo --help
mflux-generate-flux2 --help

Python API 使用方法

快速开始 — FLUX.2 Klein 4B（默认，最快）

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="一座宁静的日式庭院，盛开着樱花，沐浴在金色的午后阳光中",
    num_inference_steps=4,  # 仅需 4 步！
    width=1024,
    height=768,
    seed=42,
)
image.save("garden.png")

Z-Image Turbo（最高画质）

from mflux.models.z_image import ZImage
from mflux.models.common.config import ModelConfig

model = ZImage(
    model_config=ModelConfig.z_image_turbo(),
    model_path="filipstrand/Z-Image-Turbo-mflux-4bit",  # 4-bit 量化
)
image = model.generate_image(
    prompt="一只雄伟的鹰在日落时分翱翔于雪山之巅",
    num_inference_steps=9,
    width=1280,
    height=720,
    seed=42,
)
image.save("eagle.png")

启用量化（降低内存占用）

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(
    model_config=ModelConfig.flux2_klein_4b(),
    quantize=8,  # 8-bit 量化
)
# ... 生成图像

图生图（Image-to-Image）

from PIL import Image
from mflux.models.flux2.variants import Flux2Klein

model = Flux2Klein(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="转换为水彩画风格",
    num_inference_steps=4,
    init_image=Image.open("source.jpg"),
    init_image_strength=0.3,  # 0.0–1.0，数值越高变化越显著
)
image.save("watercolor.png")

FLUX.2 图像编辑

from mflux.models.flux2.variants import Flux2KleinEdit
from mflux.models.common.config import ModelConfig

model = Flux2KleinEdit(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="让人物戴上太阳镜",
    image_paths=["person.jpg", "sunglasses.jpg"],
    num_inference_steps=4,
    seed=42,
)
image.save("edited.png")

LoRA 支持

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(
    model_config=ModelConfig.flux2_klein_4b(),
    lora_paths=["path/to/lora.safetensors"],
    lora_scales=[0.8],
)
# ... 生成图像

支持的模型

CLI 参考

使用 FLUX.2 Klein 生成图像

# 默认 4B 模型，4 步
mflux-generate-flux2 
  --prompt "一位睿智老水手的写实肖像" 
  --width 1024 
  --height 768 
  --steps 4 
  --seed 42

# 使用 9B 模型获取更高画质
mflux-generate-flux2 
  --model flux2-klein-9b 
  --prompt "霓虹灯辉映的赛博朋克城市景观" 
  --steps 4

# 使用基础模型（非蒸馏版，需更多步数）
mflux-generate-flux2 
  --model flux2-klein-base-4b 
  --prompt "一幅细节丰富的森林油画" 
  --steps 50 
  --guidance 1.5

使用 Z-Image Turbo 生成图像

mflux-generate-z-image-turbo 
  --prompt "一家咖啡馆的极简主义 Logo 设计" 
  --width 1280 
  --height 720 
  --steps 9 
  --seed 42

# 启用 LoRA
mflux-generate-z-image-turbo 
  --prompt "新艺术风格女性肖像" 
  --steps 9 
  --lora-paths "renderartist/Art-Nouveau-Style" 
  --lora-scales 0.7

启用量化

mflux-generate-flux2 
  --prompt "一幅宁静的风景" 
  --quantize 8  # 8-bit 量化（降低内存占用）

# 或使用 4-bit 以实现最低内存占用
mflux-generate-flux2 
  --prompt "一幅宁静的风景" 
  --quantize 4

参数说明

推荐宽高比（尺寸）

性能与内存使用指南

模型权重

模型将在首次使用时自动下载：

• FLUX.2-klein-4b：约 15GB
• FLUX.2-klein-9b：约 32GB
• Z-Image-Turbo（量化版）：约 8GB

缓存路径：~/.cache/huggingface/

对比：如何选择合适模型

选择 FLUX.2-klein-4b 的场景：

• 优先考虑生成速度（4 步，约 5–8 秒）
• 需要 Apache 2.0 许可（支持商用）
• 需批量快速生成图像
• 设备具备 8GB+ 内存

选择 Z-Image-Turbo 的场景：

• 优先考虑画质
• 对真实感要求极高
• 设备具备 16GB+ 内存
• 单张图像生成时间可接受

选择 FLUX.2-klein-9b 的场景：

• 需 Apache 许可模型中的最佳画质
• 设备具备 16GB+ 内存
• 必须满足商用需求

错误处理