mflux
v.0.4.1
Un puerto MLX de Flux basado en la implementación de difusores de Huggingface.
¡Ejecute los poderosos modelos de flujo de Black Forest Labs localmente en su Mac!
MFLUX es un puerto de línea por línea de la implementación de flujo en la Biblioteca de difusores Huggingface a Apple MLX. MFLUX se mantiene a propósito mínimo y explícito: las arquitecturas de red están codificadas y no se utilizan archivos de configuración, excepto los tokenizers. El objetivo es tener una pequeña base de código con el único propósito de expresar estos modelos (evitando así demasiadas abstracciones). Si bien la legibilidad de las prioridades de MFLUX sobre la generalidad y el rendimiento, aún puede ser bastante rápido e incluso cuantificada más rápida.
Todos los modelos se implementan desde cero en MLX y solo se utilizan los tokenizadores a través de la biblioteca Huggingface Transformers. Aparte de eso, solo hay dependencias mínimas como numpy y almohada para el procesamiento de imágenes simples.
Para los usuarios, la forma más fácil de instalar MFLUX es usar uv tool : si ha instalado uv , simplemente:
uv tool install --upgrade mflux Para obtener los ejecutables de línea de comandos mflux-generate y relacionados. Puedes saltar a las guías de uso a continuación.
El codificador T5 depende de la pieza de oración, que no tiene un artefacto de rueda instalable para Python 3.13 a partir de noviembre de 2024. Hasta que Google publique una rueda 3.13, debe construir su propia rueda con instrucciones de construcción oficiales o para su conveniencia, use un .whl Pre-construido por el colaborador @anthonywu. Los siguientes pasos deberían funcionar para la mayoría de los desarrolladores, aunque su sistema puede variar.
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
Esto crea y activa un entorno virtual en la carpeta mflux . Después de eso, instale MFLUX a través de PIP:
pip install -U mflux
git clone [email protected]:filipstrand/mflux.git make install make testmake lint recomendada y make format se instalan y usan ruff . Puede configurar su editor/IDE en la pelusa/formato automáticamente, o usar nuestros make proporcionados:make format : formatea su códigomake lint : muestra los errores y advertencias de su pelusa, pero no se corrige automáticamentemake check : a través de ganchos pre-commit , formatea su código e intenta arreglar automáticamente los errores de pelusaruff sobre usos avanzados Ejecute el comando mflux-generate especificando un aviso y el modelo y algunos argumentos opcionales. Por ejemplo, aquí usamos una versión cuantificada del modelo schnell para 2 pasos:
mflux-generate --model schnell --prompt " Luxury food photograph " --steps 2 --seed 2 -q 8 Este ejemplo utiliza el modelo dev más potente con 25 pasos de tiempo:
mflux-generate --model dev --prompt " Luxury food photograph " --steps 25 --seed 2 -q 8 Por defecto, los archivos de modelo se descargan en la carpeta .cache dentro de su directorio de inicio. Por ejemplo, en mi configuración, el camino se ve así:
/Users/filipstrand/.cache/huggingface/hub/models--black-forest-labs--FLUX.1-dev
Para cambiar este comportamiento predeterminado, puede hacerlo modificando la variable de entorno HF_HOME . Para obtener más detalles sobre cómo ajustar esta configuración, consulte la documentación facial de abrazos .
Flux.1-Dev actualmente requiere acceso otorgado a su repositorio de Huggingface. Para la resolución de problemas, consulte el rastreador de problemas
--prompt (requerido, str ): descripción de texto de la imagen para generar.
--model o -m (requerido, str ): modelo para usar para generación ( "schnell" o "dev" ).
--output (Opcional, str , predeterminado: "image.png" ): Nombre de archivo de imagen de salida.
--seed (opcional, int , predeterminado: None ): semilla para la generación de números aleatorios. El valor predeterminado está basado en el tiempo.
--height (Opcional, int , predeterminado: 1024 ): Altura de la imagen de salida en píxeles.
--width (opcional, int , predeterminado: 1024 ): ancho de la imagen de salida en píxeles.
--steps (opcional, int , predeterminado: 4 ): número de pasos de inferencia.
--guidance (opcional, float , predeterminado: 3.5 ): Escala de orientación (solo se usa para el modelo "dev" ).
--path (Opcional, str , predeterminado: None ): Ruta a un modelo local en el disco.
--quantize o -q (opcional, int , predeterminado: None ): cuantificación (elija entre 4 u 8 ).
--lora-paths (opcional, [str] , predeterminado: None ): las rutas a los pesos de lora.
--lora-scales (opcional, [float] , predeterminado: None ): la escala para cada lora respectiva (será predeterminado a 1.0 si no se especifica y solo se carga un peso de Lora).
--metadata (opcional): exporta un archivo .json que contiene los metadatos para la imagen con el mismo nombre. (Incluso sin esta bandera, los metadatos de la imagen se guarda y se pueden ver con exiftool image.png )
--controlnet-image-path (requerido, str ): ruta a la imagen local utilizada por Controlnet para guiar la generación de salida.
--controlnet-strength (opcional, float , predeterminado: 0.4 ): Grado de influencia que la imagen de control tiene en la salida. Varía de 0.0 (sin influencia) a 1.0 (influencia completa).
--controlnet-save-canny (opcional, bool, predeterminado: falso): si se establece, guarda la imagen de referencia de detección de borde canny utilizada por Controlnet.
--init-image-path (opcional, str , predeterminado: None ): ruta local a la imagen inicial para la generación de imagen a imagen.
--init-image-strength (opcional, float , predeterminado: 0.4 ): controla cuán fuertemente la imagen inicial influye en la imagen de salida. Un valor de 0.0 significa que no hay influencia. (El valor predeterminado es 0.4 )
--config-from-metadata o -C (opcional, str ): ruta [experimental] a un archivo anterior guardado a través de --metadata , o un archivo de configuración artesanal compatible que se adhiere al esquema ARGS esperado.
{
"$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 "
}O, con el entorno Python correcto activo, cree y ejecute un script separado como el siguiente:
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" )Para obtener más opciones sobre cómo configurar MFLUX, consulte Generate.py.
Estos números se basan en el modelo schnell no cuantizado , con la configuración proporcionada en el fragmento de código a continuación. Para cronometrar su máquina, ejecute lo siguiente:
time mflux-generate
--prompt " Luxury food photograph "
--model schnell
--steps 2
--seed 2
--height 1024
--width 1024Para conocer la especificación de su máquina (incluido el número de núcleos de CPU, los núcleos de GPU y la memoria, ejecute el siguiente comando:
system_profiler SPHardwareDataType SPDisplaysDataType| Dispositivo | M-Serie | Usuario | Tiempo reportado | Notas |
|---|---|---|---|---|
| Mac Studio | 2023 m2 Ultra | @Awni | <15s | |
| MacBook Pro | 2024 M4 MAX (128 GB) | @ivanfioravanti | ~ 19s | |
| MacBook Pro | 2023 m3 max | @Karpathy | ~ 20s | |
| - | 2023 m2 max (96 GB) | @explorigin | ~ 25s | |
| Mac Mini | 2024 M4 Pro (64 GB) | @Stoobs | ~ 34s | |
| Mac Mini | 2023 M2 Pro (32 GB) | @leekichko | ~ 54s | |
| - | 2022 M1 Max (64 GB) | @Bosseparra | ~ 55s | |
| MacBook Pro | 2023 m2 max (32GB) | @FilipStrand | ~ 70s | |
| - | 2023 M3 Pro (36 GB) | @Kush-Gupt | ~ 80s | |
| MacBook Pro | 2021 M1 Pro (32 GB) | @FilipStrand | ~ 160s | |
| - | 2021 M1 Pro (16 GB) | @QW-In | ~ 175s | Podría congelar tu mac |
| MacBook Air | 2020 M1 (8GB) | @mbvillaverde | ~ 335s | Con resolución 512 x 512 |
Tenga en cuenta que estos números incluyen iniciar la aplicación desde cero, lo que significa hacer E/S del modelo, configurar/cuantificar pesos, etc. Si suponemos que el modelo ya está cargado, puede inspeccionar los metadatos de la imagen utilizando exiftool image.png y ver el total Duración del bucle de renovación (excluyendo la incrustación de texto).
Estos puntos de referencia no son muy científicos y solo tiene la intención de dar números de estadio. Se realizaron durante diferentes momentos con diferentes versiones MFLUX y MLX, etc. No siempre se conoce información de hardware adicional, como el número de núcleos de GPU, el dispositivo Mac, etc.
Solo hay una sola fuente de aleatoriedad al generar una imagen: la matriz latente inicial. En esta implementación, este latente inicial está completamente controlado por el parámetro seed de entrada. Sin embargo, si tuviéramos que importar una instancia fija de esta matriz latente guardada de la implementación de difusores, entonces MFLUX producirá una imagen idéntica a la implementación de difusores (suponiendo un aviso fijo y utilizando la configuración de parámetros predeterminada en la configuración de difusores).
Las imágenes a continuación ilustran esta equivalencia. En todos los casos, el modelo Schnell se ejecutó durante 2 pasos de tiempo. La implementación de difusores se ejecutó en modo CPU. La precisión para MFLUX se puede configurar en la clase de configuración. Por lo general, hay una diferencia notable pero muy pequeña en la imagen final cuando se cambia entre la precisión de 16 bits y 32 bits.
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 es compatible con el flujo en modo cuantificado de 4 bits o 8 bits. Ejecutar una versión cuantificada puede acelerar en gran medida el proceso de generación y reducir el consumo de memoria en varios gigabytes. Los modelos cuantificados también ocupan menos espacio en disco.
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 " 
En este ejemplo, los pesos se cuantifican en tiempo de ejecución : esto es conveniente si no desea guardar una copia cuantificada de los pesos en el disco, pero aún desea beneficiarse de la posible aceleración y la cuantización de reducción de RAM podría traer.
Al seleccionar la bandera --quantize o -q para ser 4 , 8 , o eliminarla por completo, obtenemos las 3 imágenes arriba. Como se puede ver, hay muy poca diferencia entre las imágenes (especialmente entre los 8 bits y el resultado no cuantizado). Los tiempos de generación de imágenes en este ejemplo se basan en una máquina 2021 M1 Pro (32GB). Aunque las imágenes son casi idénticas, hay una aceleración de ~ 2x al ejecutar la versión cuantificada de 8 bits en esta máquina en particular. A diferencia de la versión no cuantiada, para la versión de 8 bits, el uso de la memoria de intercambio se reduce drásticamente y la utilización de GPU es cercana al 100% durante toda la generación. Los resultados aquí pueden variar en diferentes máquinas.
Los tamaños del modelo para schnell y dev en varios niveles de cuantización son los siguientes:
| 4 bits | 8 bits | Original (16 bit) |
|---|---|---|
| 9.85GB | 18.16GB | 33.73GB |
La razón por la cual los tamaños de pesas no se cortan por completo a la mitad se debe a que un pequeño número de pesos no se cuantifica y se mantienen a toda precisión.
Para guardar una copia local de los pesos cuantizados, ejecute el comando mflux-save como así:
mflux-save
--path " /Users/filipstrand/Desktop/schnell_8bit "
--model schnell
--quantize 8Tenga en cuenta que al guardar una versión cuantificada, necesitará los pesos originales de Huggingface.
También es posible especificar adaptadores de lora al guardar el modelo, por ejemplo,
mflux-save
--path " /Users/filipstrand/Desktop/schnell_8bit "
--model schnell
--quantize 8
--lora-paths " /path/to/lora.safetensors "
--lora-scales 0.7Al generar imágenes con un modelo como este, no es necesario especificar ningún adaptador Lora, ya que ya está horneado en los pesos cuantificados guardados.
Para generar una nueva imagen del modelo cuantificado, simplemente proporcione un --path de donde se guardó:
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 " Nota: Al cargar un modelo cuantificado del disco, no hay necesidad de pasar en la bandera -q , ya que podemos inferir esto en los metadatos de peso.
También tenga en cuenta: Una vez que tenemos un modelo local (cuantificado o no) especificado a través del argumento --path , los modelos de caché Huggingface no son necesarios para iniciar el modelo. En otras palabras, puede reclamar el espacio de disco de 34 GB (por modelo) eliminando el modelo completo de 16 bits del caché de la cara de abrazo si lo desea.
Si no desea descargar los modelos completos y cuantificarlos usted mismo, los pesos de 4 bits están disponibles aquí para una descarga directa:
MFLUX también admite ejecutar un modelo no cuantizado directamente desde una ubicación personalizada. En el siguiente ejemplo, el modelo se coloca en /Users/filipstrand/Desktop/schnell :
mflux-generate
--path " /Users/filipstrand/Desktop/schnell "
--model schnell
--steps 2
--seed 2
--prompt " Luxury food photograph " Tenga en cuenta que el indicador --model debe establecerse al cargar un modelo desde el disco.
También tenga en cuenta que, a diferencia de cuando se usa la forma típica de alias de inicializar el modelo (que maneja internamente que los recursos requeridos se descargan), al cargar un modelo directamente desde el disco, requerimos que los modelos descargados se vean como lo siguiente:
.
├── 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
Esto refleja cómo se colocan los recursos en el repositorio de Huggingface para Flux.1. Los pesos de la cara de abrazos, a diferencia de los cuantizados exportados directamente de este proyecto, deben procesarse de manera un poco diferente, por lo que requerimos esta estructura anterior.
Una forma de acondicionar la generación de imágenes es comenzar desde una imagen existente y dejar que MFlux produzca nuevas variaciones. Use el indicador --init-image-path para especificar la imagen de referencia y la --init-image-strength para controlar cuánto debe guiar la generación. Por ejemplo, dada la imagen de referencia a continuación, el siguiente comando produjo la primera imagen usando el boceto 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 1024Al igual que con Controlnet, esta técnica se combina bien con los adaptadores de Lora:
En los ejemplos anteriores, se utilizan los siguientes loras, se usan boceto, se usan disparos de animación y cámaras de flujo de flujo.
Soporte de MFLUX Carga de adaptadores Lora capacitados (se acerca el soporte de entrenamiento real).
El siguiente ejemplo The_Hound Lora de @thelastben:
mflux-generate --prompt " sandor clegane " --model dev --steps 20 --seed 43 -q 8 --lora-paths " sandor_clegane_single_layer.safetensors " 
El siguiente ejemplo es flux_1_dev_lora_paper-cutout estilo lora de @norod78:
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 " 
Tenga en cuenta que los pesos entrenados en Lora generalmente se entrenan con una palabra o frase de activación . Por ejemplo, en el último caso, la oración debe incluir la frase "estilo de recorte de papel" .
También tenga en cuenta que los mismos pesos de Lora pueden funcionar bien con los modelos schnell y dev . Consulte el repositorio de Lora original para ver para qué modo estaba entrenado.
Se pueden enviar múltiples loras para combinar los efectos de los adaptadores individuales. El siguiente ejemplo combina las dos loras anteriores:
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
Solo para ver la diferencia, esta imagen muestra los cuatro casos: uno de los dos adaptadores completamente activos, parcialmente activos y sin lora en absoluto. El ejemplo anterior también muestra el uso de la bandera --lora-scales .
Dado que diferentes servicios de ajuste fino pueden usar diferentes implementaciones de flujo, los pesos de Lora correspondientes capacitados en estos servicios pueden ser diferentes entre sí. El objetivo de MFLUX es admitir los más comunes. La siguiente tabla muestra los formatos compatibles actuales:
| Compatible | Nombre | Ejemplo | Notas |
|---|---|---|---|
| ✅ | Bfl | Civitai - Impresionismo | Muchas cosas en Civitai parecen funcionar |
| ✅ | Difusor | Flux_1_dev_lora_paper-cutout-style | |
| Xlabs-ai | flux-realismlora |
Para informar formatos adicionales, ejemplos u otras sugerencias relacionadas con el soporte del formato LORA, consulte el número 47.
MFLUX tiene soporte Controlnet para un control aún más de grano fino de la generación de imágenes. Al proporcionar una imagen de referencia a través de --controlnet-image-path y un parámetro de resistencia a través de --controlnet-strength , puede guiar la generación hacia la imagen de referencia.
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
Este ejemplo combina la imagen de referencia de ControlNet con el flujo cómico Lora Dark .
generate-controlnet . En este momento, el control de control utilizado es instantx/flux.1-dev-Controlnet-canny, que fue entrenado para el modelo dev . Puede funcionar bien con schnell , pero el rendimiento no está garantizado.
Controlnet también puede funcionar bien junto con los adaptadores Lora. En el ejemplo a continuación, la misma imagen de referencia se usa como entrada de Netnet con diferentes indicaciones y adaptadores Lora activos.
export HF_HUB_DISABLE_PROGRESS_BARS=1--argsalias mflux-dev='mflux-generate --model dev'alias mflux-schnell='mflux-generate --model schnell --metadata'Este proyecto tiene licencia bajo la licencia MIT.
