关于

在你的 Mac 上使用原生 MLX，在本地运行最新的最先进生成式图像模型！

目录

• 💡 理念
• 💿 安装
• 🎨 模型
• ✨ 特性
• 🌱 相关项目
• 🙏 致谢
• ⚖️ 许可证

💡 理念

MFLUX 是对来自 Huggingface Diffusers 和 Huggingface Transformers 库中若干最先进的生成式图像模型的逐行 MLX 移植。所有模型均在 MLX 中从头实现，仅使用来自 Huggingface Transformers 库的分词器。MFLUX 有意保持极简和明确，风格类似 @karpathy。

💿 安装

如果你还没有安装，先 安装 uv，然后运行：

uv tool install --upgrade mflux

安装完成后，以下命令会显示所有可用的 MFLUX CLI 命令：

uv tool list 

要使用例如 z-image-turbo 模型生成第一张图片，运行

mflux-generate-z-image-turbo \
  --prompt "一只海鹦站在悬崖上" \
  --width 1280 \
  --height 500 \
  --seed 42 \
  --steps 9 \
  -q 8

第一次运行时，模型会自动下载，这可能需要一些时间。请参阅 模型部分 以了解不同的选项和功能，以及 通用 README 以获取共享的 CLI 模式和示例。

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "mflux",
# ]
# ///
from mflux.models.z_image import ZImageTurbo

model = ZImageTurbo(quantize=8)
image = model.generate_image(
    prompt="一只海鹦站在悬崖上",
    seed=42,
    num_inference_steps=9,
    width=1280,
    height=500,
)
image.save("puffin.png")

uv run generate.py

uv tool install --upgrade mflux --with hf_transfer

uv tool install --python 3.13 mflux

🎨 模型

MFLUX 支持以下模型系列。它们各有优劣；请参阅各模型的 README 以获取完整的使用说明。

✨ 特性

通用

• 量化与本地模型加载
• LoRA 支持（多 LoRA、缩放、库查找）
• 元数据导出 + 重用，以及提示文件支持

模型特定亮点

• 文本到图像及图像到图像生成。
• LoRA 微调
• 上下文编辑、多图像编辑和虚拟试穿
• ControlNet（Canny）、深度条件、填充/修复以及 Redux
• 超分辨率（SeedVR2 和 Flux ControlNet）
• 深度图提取和 FIBO 提示工具（VLM 启发/优化）

请参阅 通用 README 以获取详细的使用方法和示例，并利用上面的模型部分浏览具体模型及其功能。

[!注意] 由于 MFLUX 支持多种 CLI 工具和选项，2026 年导航 CLI 的最简单方式是使用编码助手（如 Cursor、Claude Code 或类似工具）。你可以提问：“你能帮我用 z-image 生成一张图片吗？”

🌱 相关项目

• MindCraft Studio 由 @shaoju 开发
• Mflux-ComfyUI 由 @raysers 开发
• MFLUX-WEBUI 由 @CharafChnioune 开发
• mflux-fasthtml 由 @anthonywu 开发
• mflux-streamlit 由 @elitexp 开发

🙏 致谢

MFLUX 的实现离不开以下团队和个人的杰出工作：

• MLX 团队，感谢他们开发的 MLX 及其 MLX 示例
• Black Forest Labs，感谢他们发起的 FLUX 项目
• Bria，感谢他们推出的 FIBO 项目
• Tongyi Lab，感谢他们研发的 Z-Image 项目
• Qwen 团队，感谢他们推出的 Qwen Image 项目
• 字节跳动、@numz 和 @adrientoupet，感谢他们开发的 SeedVR2 项目
• Hugging Face，感谢他们提供的 Diffusers 库实现
• Depth Pro 的作者们，感谢他们发布的 Depth Pro 模型
• MLX 社区以及所有 贡献者和测试者

⚖️ 许可证

本项目采用 MIT 许可证 进行授权。

MFLUX 快速上手指南

MFLUX 是一个基于 Apple MLX 框架的轻量级开源项目，旨在让 Mac 用户能够在本地原生运行最新的顶级生成式图像模型（如 FLUX、Z-Image 等）。它采用极简设计，代码逐行移植自 Hugging Face Diffusers，适合开发者快速体验和集成。

环境准备

• 操作系统：macOS (推荐 macOS Sonoma 或更高版本)
• 硬件要求：Apple Silicon 芯片 (M1, M2, M3, M4 系列)。虽然支持 NVIDIA DGX，但本项目主要针对 Mac 优化。
• 前置依赖：
  • Python >= 3.10
  • uv：现代化的 Python 包管理器和项目管理器。

注意：请确保已安装 uv。如果尚未安装，请访问 uv 官方安装页面 进行安装。国内用户若下载缓慢，可尝试配置国内镜像源或使用代理加速。

安装步骤

使用 uv 工具一键安装 MFLUX：

uv tool install --upgrade mflux

安装完成后，可通过以下命令查看可用的 CLI 命令列表：

uv tool list 

提示：首次运行生成命令时，模型会自动从 Hugging Face 下载。若遇到 hf_transfer 相关报错或希望加速下载，可使用以下命令重装以包含加速包：

uv tool install --upgrade mflux --with hf_transfer

基本使用

1. 命令行生成图片 (CLI)

以下示例使用 z-image-turbo 模型生成一张图片。首次运行时会自动下载模型文件。

mflux-generate-z-image-turbo \
  --prompt "A puffin standing on a cliff" \
  --width 1280 \
  --height 500 \
  --seed 42 \
  --steps 9 \
  -q 8

• --prompt: 提示词
• --width / --height: 生成图片的分辨率
• --steps: 推理步数（数值越小速度越快）
• -q 8: 启用 8-bit 量化以节省显存并提升速度

2. Python API 调用

你也可以通过 Python 脚本直接调用。创建一个名为 generate.py 的文件，内容如下：

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "mflux",
# ]
# ///
from mflux.models.z_image import ZImageTurbo

model = ZImageTurbo(quantize=8)
image = model.generate_image(
    prompt="A puffin standing on a cliff",
    seed=42,
    num_inference_steps=9,
    width=1280,
    height=500,
)
image.save("puffin.png")

运行脚本：

uv run generate.py

支持的主要模型

MFLUX 支持多种模型家族，可根据需求选择：

更多高级功能（如 LoRA 微调、ControlNet、图生图等）请参考各模型对应的详细文档。