mflux
v.0.4.1
基於擁抱面擴散器實現的MLX通量端口。
從Mac上本地的Black Forest Labs運行強大的通量模型！
MFLUX是在擁抱面擴散器庫中逐行實現的逐線端口。 MFLUX有目的地保持最小和顯式 - 網絡架構是硬編碼，除了令牌外，沒有使用配置文件。目的是擁有一個微小的代碼庫，其目的是表達這些模型（從而避免了太多的抽象）。儘管MFLUX優先級在一般性和性能上可讀性，但它仍然可以非常快，甚至更快地量化。
所有模型均在MLX中從頭開始實現，並且僅通過HuggingFace Transformers庫使用了標記器。除此之外，只有最小的依賴性（例如Numpy和枕頭）可用於簡單的圖像後處理。
對於用戶，安裝MFLUX的最簡單方法是使用uv tool ：如果您已經安裝了uv ，則簡單地：
uv tool install --upgrade mflux獲取mflux-generate和相關的命令行可執行文件。您可以跳過下面的使用指南。
T5編碼器取決於句子，截至2024年11月，python 3.13都沒有可安裝的輪飾。直到Google出版3.13輪轂，您需要使用官方構建指令或方便.whl來構建自己的輪子由撰稿人@anthonywu預先建造。儘管您的系統可能會有所不同，但以下步驟應適用於大多數開發人員。
uv venv --python 3.13
python -V # e.g. Python 3.13.0rc2
source .venv/bin/activate
# for your convenience, you can use the contributor wheel
uv pip install https://github.com/anthonywu/sentencepiece/releases/download/0.2.1-py13dev/sentencepiece-0.2.1-cp313-cp313-macosx_11_0_arm64.whl
# enable the pytorch nightly
uv pip install --pre --extra-index-url https://download.pytorch.org/whl/nightly -e . mkdir -p mflux && cd mflux && python3 -m venv .venv && source .venv/bin/activate
這會在mflux文件夾中創建並激活虛擬環境。之後，通過PIP安裝MFLUX：
pip install -U mflux
git clone [email protected]:filipstrand/mflux.git make install make testmake lint並make format安裝並使用ruff 。您可以將編輯器/IDE設置為棉布/格式，或使用我們提供的make ：make format - 格式化您的代碼make lint - 顯示您的棉絨錯誤和警告，但沒有自動修復make check - 通過pre-commit掛鉤，格式化您的代碼，並嘗試自動修復棉絨錯誤ruff文檔通過指定提示和模型以及一些可選參數來運行命令mflux-generate 。例如，在這裡，我們使用2個步驟的schnell模型的量化版本：
mflux-generate --model schnell --prompt " Luxury food photograph " --steps 2 --seed 2 -q 8此示例使用25個時間步驟的更強大的dev模型：
mflux-generate --model dev --prompt " Luxury food photograph " --steps 25 --seed 2 -q 8默認情況下，模型文件將下載到主目錄中的.cache文件夾。例如，在我的設置中，路徑看起來像這樣：
/Users/filipstrand/.cache/huggingface/hub/models--black-forest-labs--FLUX.1-dev
要更改此默認行為，您可以通過修改HF_HOME環境變量來做到這一點。有關如何調整此設置的更多詳細信息，請參考擁抱面部文檔。
Flux.1-DEV當前需要授予其對擁抱面回購的訪問。有關故障排除，請參閱問題跟踪器
--prompt （必需， str ）：要生成的圖像的文本描述。
--model或-m （必需， str ）：用於生成的模型（ "schnell"或"dev" ）。
--output （可選， str ，默認值： "image.png" ）：輸出圖像文件名。
--seed （可選， int ，默認值： None ）：隨機數生成的種子。默認值是基於時間的。
--height （可選， int ，默認值： 1024 ）：以像素為單位的輸出圖像的高度。
--width （可選， int ，默認值： 1024 ）：以像素為單位的輸出圖像的寬度。
--steps （可選， int ，默認值： 4 ）：推理步驟的數量。
--guidance （可選， float ，默認值： 3.5 ）：指導量表（僅用於"dev"模型）。
--path （可選， str ，默認值： None ）：磁盤上本地模型的路徑。
--quantize或-q （可選， int ，默認值： None ）：量化（在4或8之間選擇）。
--lora-paths （可選， [str] ，默認值： None ）：通往洛拉重量的路徑。
--lora-scales （可選， [float] ，默認值： None ）：每個相應的lora的比例（如果未指定，將默認為1.0 ，並且只加載了一個lora重量。）
--metadata （可選）：導出一個.json文件，其中包含具有相同名稱的圖像的元數據。 （即使沒有此標誌，也可以保存圖像元數據，並可以使用exiftool image.png查看）
--controlnet-image-path （必需， str ）：控製網絡使用的局部圖像的路徑，用於引導輸出生成。
--controlnet-strength （可選， float ，默認值： 0.4 ）：控製圖像對輸出的影響程度。範圍從0.0 （無影響）到1.0 （完全影響）。
--controlnet-save-canny （可選，布爾，默認值：false）：如果設置，則保存ControlNet使用的Canny Edge檢測參考圖像。
--init-image-path （可選， str ，默認值： None ）：圖像到圖像生成的初始圖像的本地路徑。
--init-image-strength （可選， float ，默認值： 0.4 ）：控制初始圖像對輸出圖像的影響程度。值為0.0表示沒有影響。 （默認為0.4 ）
--config-from-metadata或-C （可選， str ）：[實驗]通往通過--metadata保存的先驗文件或兼容的手工製作的配置文件，這些文件貼在預期的args架構上。
{
"$schema" : " http://json-schema.org/draft-07/schema# " ,
"type" : " object " ,
"properties" : {
"seed" : {
"type" : [ " integer " , " null " ]
},
"steps" : {
"type" : [ " integer " , " null " ]
},
"guidance" : {
"type" : [ " number " , " null " ]
},
"quantize" : {
"type" : [ " null " , " string " ]
},
"lora_paths" : {
"type" : [ " array " , " null " ],
"items" : {
"type" : " string "
}
},
"lora_scales" : {
"type" : [ " array " , " null " ],
"items" : {
"type" : " number "
}
},
"prompt" : {
"type" : [ " string " , " null " ]
}
}
}{
"model" : " dev " ,
"seed" : 42 ,
"steps" : 8 ,
"guidance" : 3.0 ,
"quantize" : 4 ,
"lora_paths" : [
" /some/path1/to/subject.safetensors " ,
" /some/path2/to/style.safetensors "
],
"lora_scales" : [
0.8 ,
0.4
],
"prompt" : " award winning modern art, MOMA "
}或者，使用正確的Python環境，創建並運行單獨的腳本如下：
from mflux import Flux1 , Config
# Load the model
flux = Flux1 . from_alias (
alias = "schnell" , # "schnell" or "dev"
quantize = 8 , # 4 or 8
)
# Generate an image
image = flux . generate_image (
seed = 2 ,
prompt = "Luxury food photograph" ,
config = Config (
num_inference_steps = 2 , # "schnell" works well with 2-4 steps, "dev" works well with 20-25 steps
height = 1024 ,
width = 1024 ,
)
)
image . save ( path = "image.png" )有關如何配置MFLUX的更多選項，請參見Generate.py。
這些數字基於非量化的schnell模型，並在下面的代碼段中提供了配置。為了計算機計時，請運行以下內容：
time mflux-generate
--prompt " Luxury food photograph "
--model schnell
--steps 2
--seed 2
--height 1024
--width 1024要找出計算機的規格（包括CPU核心，GPU內核和內存的數量，請運行以下命令：
system_profiler SPHardwareDataType SPDisplaysDataType| 裝置 | M系列 | 用戶 | 報告的時間 | 筆記 |
|---|---|---|---|---|
| Mac Studio | 2023 m2 Ultra | @Awni | <15s | |
| MacBook Pro | 2024 M4 Max（128GB） | @ivanfioravanti | 〜19S | |
| MacBook Pro | 2023 M3 Max | @karpathy | 〜20s | |
| - | 2023 m2 max（96GB） | @explorigin | 〜25s | |
| Mac mini | 2024 M4 Pro（64GB） | @stoobs | 〜34 | |
| Mac mini | 2023 M2 Pro（32GB） | @leekichko | 〜54 | |
| - | 2022 M1 max（64GB） | @bosseparra | 〜55s | |
| MacBook Pro | 2023 m2 max（32GB） | @FilipStrand | 〜70年代 | |
| - | 2023 M3 Pro（36GB） | @Kush-Gupt | 〜80年代 | |
| MacBook Pro | 2021 M1 Pro（32GB） | @FilipStrand | 〜160年代 | |
| - | 2021 M1 Pro（16GB） | @qw-in | 〜175s | 可能會凍結您的Mac |
| MacBook Air | 2020 M1（8GB） | @mbvillaverde | 〜335s | 分辨率512 x 512 |
請注意，這些數字包括從頭開始啟動應用程序，這意味著執行模型I/O，設置/量化權重等。如果我們假設模型已經加載，則可以使用exiftool image.png檢查圖像元數據，並查看Total denoising循環的持續時間（不包括文本嵌入）。
這些基準不是很科學的，只旨在給出球場數字。它們是在不同的時間與不同的MFLUX和MLX反面等。其他硬件信息（例如GPU內核，Mac設備等）的其他硬件。
生成圖像時只有一個隨機性的來源：初始潛在數組。在此實現中，該初始潛在由輸入seed參數完全決定性地控制。但是，如果我們要從擴散器實現中得出此潛在數組的固定實例，則MFLUX將與擴散器實現產生相同的圖像（假設固定提示並使用擴散器設置中的默認參數設置）。
下圖說明了這種對等。在所有情況下，Schnell模型均可進行2個時間步驟。擴散器實現以CPU模式運行。可以在配置類中設置MFLUX的精度。在16位和32位精度之間切換時，最終圖像通常會有明顯但很小的差異。
Luxury food photograph
detailed cinematic dof render of an old dusty detailed CRT monitor on a wooden desk in a dim room with items around, messy dirty room. On the screen are the letters "FLUX" glowing softly. High detail hard surface render
photorealistic, lotr, A tiny red dragon curled up asleep inside a nest, (Soft Focus) , (f_stop 2.8) , (focal_length 50mm) macro lens f/2. 8, medieval wizard table, (pastel) colors, (cozy) morning light filtering through a nearby window, (whimsical) steam shapes, captured with a (Canon EOS R5) , highlighting (serene) comfort, medieval, dnd, rpg, 3d, 16K, 8K
A weathered fisherman in his early 60s stands on the deck of his boat, gazing out at a stormy sea. He has a thick, salt-and-pepper beard, deep-set blue eyes, and skin tanned and creased from years of sun exposure. He's wearing a yellow raincoat and hat, with water droplets clinging to the fabric. Behind him, dark clouds loom ominously, and waves crash against the side of the boat. The overall atmosphere is one of tension and respect for the power of nature.
Luxury food photograph of an italian Linguine pasta alle vongole dish with lots of clams. It has perfect lighting and a cozy background with big bokeh and shallow depth of field. The mood is a sunset balcony in tuscany. The photo is taken from the side of the plate. The pasta is shiny with sprinkled parmesan cheese and basil leaves on top. The scene is complemented by a warm, inviting light that highlights the textures and colors of the ingredients, giving it an appetizing and elegant look.
Mflux支持以4位或8位量化模式運行通量。運行量化版本可以大大加快生成過程，並減少幾GB。量化模型還佔用磁盤空間較少。
mflux-generate
--model schnell
--steps 2
--seed 2
--quantize 8
--height 1920
--width 1024
--prompt " Tranquil pond in a bamboo forest at dawn, the sun is barely starting to peak over the horizon, panda practices Tai Chi near the edge of the pond, atmospheric perspective through the mist of morning dew, sunbeams, its movements are graceful and fluid — creating a sense of harmony and balance, the pond’s calm waters reflecting the scene, inviting a sense of meditation and connection with nature, style of Howard Terpning and Jessica Rossier " 
在此示例中，重量在運行時進行量化 - 如果您不想將權重量化為磁盤，這很方便，但仍然希望從潛在的速度和減少量的量化量化中受益。
通過選擇--quantize或-q標誌為4或完全刪除8 ，我們可以在上面獲取所有3張圖像。可以看出，圖像之間幾乎沒有差異（尤其是在8位和非量化結果之間）。此示例中的圖像生成時間基於2021 M1 Pro（32GB）機器。即使圖像幾乎相同，也通過在該特定計算機上運行8位量化版本的速度約為2倍。與非量化版本不同，對於8位版本，交換內存使用量大大降低，並且在整個一代中，GPU利用率接近100％。此處的結果可能在不同的機器上有所不同。
schnell和dev在各種量化水平上的模型大小如下：
| 4位 | 8位 | 原始（16位） |
|---|---|---|
| 9.85GB | 18.16GB | 33.73GB |
重量大小未完全切成兩半的原因是，少量的重量未被量化並保持完全精確。
要保存量化權重的本地副本，請這樣運行mflux-save命令：
mflux-save
--path " /Users/filipstrand/Desktop/schnell_8bit "
--model schnell
--quantize 8請注意，保存量化版本時，您將需要原始的HuggingFace權重。
保存模型時，也可以指定Lora適配器
mflux-save
--path " /Users/filipstrand/Desktop/schnell_8bit "
--model schnell
--quantize 8
--lora-paths " /path/to/lora.safetensors "
--lora-scales 0.7當使用這樣的模型生成圖像時，由於已經烘烤到已保存的量化權重中，因此不需要指定Lora適配器。
要從量化模型中生成新圖像，只需提供一個--path將其保存的位置提供：
mflux-generate
--path " /Users/filipstrand/Desktop/schnell_8bit "
--model schnell
--steps 2
--seed 2
--height 1920
--width 1024
--prompt " Tranquil pond in a bamboo forest at dawn, the sun is barely starting to peak over the horizon, panda practices Tai Chi near the edge of the pond, atmospheric perspective through the mist of morning dew, sunbeams, its movements are graceful and fluid — creating a sense of harmony and balance, the pond’s calm waters reflecting the scene, inviting a sense of meditation and connection with nature, style of Howard Terpning and Jessica Rossier "注意：從磁盤加載量化的模型時，無需傳遞-q標誌，因為我們可以從重量元數據中推斷出來。
另請注意：一旦我們通過--path參數指定了本地模型（是否量化），則不需要huggingface緩存模型來啟動模型。換句話說，您可以通過從擁抱面緩存中刪除完整的16位模型來回收34GB磁盤（每個模型）。
如果您不想下載完整的型號並自己量化它們，則可以在此處提供4位權重以供直接下載：
Mflux還直接從自定義位置運行非量化模型。在下面的示例中，將模型放置在/Users/filipstrand/Desktop/schnell中：
mflux-generate
--path " /Users/filipstrand/Desktop/schnell "
--model schnell
--steps 2
--seed 2
--prompt " Luxury food photograph "請注意，從磁盤加載模型時，必須設置--model標誌。
另請注意，與使用典型的alias初始化模型（內部處理所需資源的下載）不同，當直接從磁盤加載模型時，我們要求下載的模型看起來如下：
.
├── text_encoder
│ └── model.safetensors
├── text_encoder_2
│ ├── model-00001-of-00002.safetensors
│ └── model-00002-of-00002.safetensors
├── tokenizer
│ ├── merges.txt
│ ├── special_tokens_map.json
│ ├── tokenizer_config.json
│ └── vocab.json
├── tokenizer_2
│ ├── special_tokens_map.json
│ ├── spiece.model
│ ├── tokenizer.json
│ └── tokenizer_config.json
├── transformer
│ ├── diffusion_pytorch_model-00001-of-00003.safetensors
│ ├── diffusion_pytorch_model-00002-of-00003.safetensors
│ └── diffusion_pytorch_model-00003-of-00003.safetensors
└── vae
└── diffusion_pytorch_model.safetensors
這反映瞭如何將資源放置在Flux.1的HuggingFace Repo中。與直接從該項目導出的量化量子不同的擁抱面權重必須以不同的方式處理，這就是為什麼我們需要上面的結構。
調節圖像生成的一種方法是從現有圖像開始，讓MFLUX產生新的變體。使用--init-image-path標誌指定參考圖像，以及--init-image-strength以控制參考圖像應指導生成多少。例如，給定下面的參考圖像，以下命令使用草圖Lora產生了第一個圖像：
mflux-generate
--prompt " sketching of an Eiffel architecture, masterpiece, best quality. The site is lit by lighting professionals, creating a subtle illumination effect. Ink on paper with very fine touches with colored markers, (shadings:1.1), loose lines, Schematic, Conceptual, Abstract, Gestural. Quick sketches to explore ideas and concepts. "
--init-image-path " reference.png "
--init-image-strength 0.3
--lora-paths Architectural_Sketching.safetensors
--lora-scales 1.0
--model dev
--steps 20
--seed 43
--guidance 4.0
--quantize 8
--height 1024
--width 1024與ControlNet一樣，此技術與Lora適配器很好地結合在一起：
在上面的示例中，使用了素描，使用動畫鏡頭和磁帶 - 膠卷相機。
MFLUX支持裝載訓練有素的LORA適配器（即將到來的實際培訓支持）。
以下示例the_hound lora來自@thelastben：
mflux-generate --prompt " sandor clegane " --model dev --steps 20 --seed 43 -q 8 --lora-paths " sandor_clegane_single_layer.safetensors " 
以下示例是 @norod78的flux_1_dev_lora_paper-cutout-cutout-style lora：
mflux-generate --prompt " pikachu, Paper Cutout Style " --model schnell --steps 4 --seed 43 -q 8 --lora-paths " Flux_1_Dev_LoRA_Paper-Cutout-Style.safetensors " 
請注意，洛拉訓練的權重通常是用觸發單詞或短語訓練的。例如，在後一種情況下，該句子應包括“紙張切割樣式”一詞。
另請注意，相同的洛拉（Lora）權重可以與schnell和dev型號都很好地工作。請參閱原始的Lora存儲庫，以查看訓練哪種模式。
可以發送多個Loras來結合各個適配器的效果。以下示例結合了上述兩個洛拉斯：
mflux-generate
--prompt " sandor clegane in a forest, Paper Cutout Style "
--model dev
--steps 20
--seed 43
--lora-paths sandor_clegane_single_layer.safetensors Flux_1_Dev_LoRA_Paper-Cutout-Style.safetensors
--lora-scales 1.0 1.0
-q 8
只是為了查看差異，此圖像顯示了四種情況：一種使兩個適配器完全活躍，部分活躍並且根本沒有Lora。上面的示例還顯示了--lora-scales標誌的用法。
由於不同的微調服務可以使用不同的通量實現，因此在這些服務上訓練的相應的LORA權重可以彼此不同。 Mflux的目的是支持最常見的。下表顯示了當前受支持格式：
| 支持 | 姓名 | 例子 | 筆記 |
|---|---|---|---|
| ✅ | BFL | Civitai-印象派 | Civitai上的許多事情似乎有效 |
| ✅ | 擴散器 | flux_1_dev_lora_paper-cutout風格 | |
| XLABS-AI | 通量現實的洛拉 |
要報告其他格式，示例或其他與LORA格式支持有關的建議，請參見第47期。
Mflux具有控製網絡的支持，以對圖像生成進行更細粒度的控制。通過通過--controlnet-image-path提供參考圖像和通過--controlnet-strength強度參數，您可以將生成引導到參考圖像。
mflux-generate-controlnet
--prompt " A comic strip with a joker in a purple suit "
--model dev
--steps 20
--seed 1727047657
--height 1066
--width 692
-q 8
--lora-paths " Dark Comic - s0_8 g4.safetensors "
--controlnet-image-path " reference.png "
--controlnet-strength 0.5
--controlnet-save-canny
此示例將ControlNet參考圖像與Lora Dark Comic Flux結合在一起。
generate-controlnet命令自動發生。目前，使用的控製網是Instantx/flux.1-dev-controlnet-canne，該canne是dev模型的訓練。它可以與schnell合作，但不能保證性能。
ControlNet也可以與Lora適配器一起工作。在下面的示例中，相同的參考圖像用作具有不同提示和洛拉適配器的控製網絡輸入。
export HF_HUB_DISABLE_PROGRESS_BARS=1--argsalias mflux-dev='mflux-generate --model dev'alias mflux-schnell='mflux-generate --model schnell --metadata'該項目已根據MIT許可獲得許可。
