FLUX：黑森林实验室开源文生图像模型安装与使用指南

官方信息

项目背景

FLUX.1 是由 Black Forest Labs（黑森林实验室）发布的开源文生图像模型，创始团队来自Stable Diffusion的原始开发人员（Robin Rombach、Patrick Esser等）。自2024年8月首次发布以来，FLUX 在公开评测中多次超越 Midjourney v6、DALL-E 3 等闭源模型，被公认为当前开源文生图领域的"天花板"级别模型。

FLUX 提供三个主要版本：FLUX.1 [schnell] 是快速蒸馏版，1-4步即可出图，速度极快，适合实时预览；FLUX.1 [dev] 是高质量开发版，需要20-50步采样，画面细节和文字渲染能力远超SDXL；FLUX.1 [pro] 是闭源商用API版本，质量最高。本仓库官方推理代码支持 dev 和 schnell 两个开源版本。

FLUX 采用 Transformer 架构而非传统UNet，文本编码器使用双T5+CLIP方案，参数量达120亿。这使得它在文字准确性、复杂构图、人物一致性方面都有质的飞跃。配合 ComfyUI、WebUI Forge、Diffusers 等前端，FLUX 已经成为AI绘画创作者的首选模型。

核心特性

• 双版本开源：dev（高质量50步）和 schnell（极速4步）双权重发布，满足不同场景
• 120亿参数Transformer架构：远超SDXL的26亿，画面细节、光影、纹理更真实
• 原生文字渲染：能直接在图片中生成可读的英文文字，这是之前所有开源模型都做不到的
• 双文本编码器：CLIP-L + T5-XXL 联合编码，对长提示词理解更精准
• 官方Diffusers支持：提供HuggingFace Diffusers Pipeline，3行代码即可推理
• 多种量化部署：支持FP8、GGUF、NF4等量化方案，最低8GB显存可跑dev版
• 可商用授权：schnell版采用Apache 2.0协议可直接商用，dev版采用非商业许可

环境要求

详细部署步骤

方式一：Diffusers Pipeline（最简方式）

如果你只想用代码调用，不想搭GUI，这是最快的方式。

1. 创建虚拟环境

   conda create -n flux python=3.10 -y
   conda activate flux
   # 或使用venv
   python -m venv venv
   source venv/bin/activate  # Linux
   # venv\Scripts\activate  # Windows

2. 安装PyTorch（CUDA 12.1）

   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

3. 安装Diffusers及依赖

   pip install diffusers transformers accelerate sentry-sdk safetensors
   pip install -U "diffusers[torch]"

4. 登录HuggingFace（dev版需要授权）

   pip install huggingface_hub
   huggingface-cli login
   # 输入你的HF Token（需要先在 https://huggingface.co/black-forest-labs/FLUX.1-dev 页面同意协议）

5. 推理脚本（schnell快速版）

   import torch
   from diffusers import FluxPipeline
   
   pipe = FluxPipeline.from_pretrained(
       "black-forest-labs/FLUX.1-schnell",
       torch_dtype=torch.bfloat16
   )
   pipe.enable_model_cpu_offload()  # 显存不足时开启
   
   image = pipe(
       prompt="A cat holding a sign that says hello world, cinematic lighting",
       guidance_scale=0.0,  # schnell版guidance_scale设为0
       num_inference_steps=4,
       max_sequence_length=256,
       generator=torch.Generator("cuda").manual_seed(42)
   ).images[0]
   
   image.save("flux_schnell_output.png")

   schnell版不需要HuggingFace授权，可直接下载。

6. 推理脚本（dev高质量版）

   import torch
   from diffusers import FluxPipeline
   
   pipe = FluxPipeline.from_pretrained(
       "black-forest-labs/FLUX.1-dev",
       torch_dtype=torch.bfloat16
   )
   pipe.enable_model_cpu_offload()
   
   image = pipe(
       prompt="A surreal painting of a floating island with a waterfall, oil paint style",
       guidance_scale=3.5,
       num_inference_steps=50,
       max_sequence_length=512,
       generator=torch.Generator("cuda").manual_seed(0)
   ).images[0]
   
   image.save("flux_dev_output.png")

方式二：官方仓库源码部署

1. 克隆官方仓库

   git clone https://github.com/black-forest-labs/flux.git
   cd flux

2. 安装依赖

   python -m venv .venv
   source .venv/bin/activate
   pip install -e .  # 安装项目本身
   pip install -r dev-requirements.txt  # 开发依赖（可选）

3. 下载模型权重
   官方仓库不直接包含权重，需要从HuggingFace下载：

   # 创建模型目录
   mkdir -p models/flux1-dev models/flux1-schnell
   
   # 使用huggingface-cli下载
   # dev版（约23GB FP16）
   huggingface-cli download black-forest-labs/FLUX.1-dev --local-dir models/flux1-dev
   
   # schnell版（约23GB FP16）
   huggingface-cli download black-forest-labs/FLUX.1-schnell --local-dir models/flux1-schnell

4. 运行T2I示例（schnell版）

   python src/flux/cli_demo.py \
     --config src/flux/configs/schnell-dev.yaml \
     --ckpt_path models/flux1-schnell/flux1-schnell.safetensors \
     --prompt "A photo of a dragon flying over a medieval castle, golden hour" \
     --width 1024 \
     --height 1024 \
     --steps 4 \
     --output flux_output.png

5. 运行T2I示例（dev版）

   python src/flux/cli_demo.py \
     --config src/flux/configs/dev-template.yaml \
     --ckpt_path models/flux1-dev/flux1-dev.safetensors \
     --prompt "An astronaut riding a horse on Mars, cinematic" \
     --width 1024 \
     --height 1024 \
     --steps 50 \
     --guidance 3.5 \
     --output flux_dev_output.png

方式三：ComfyUI 中使用FLUX（推荐GUI方式）

1. 下载FLUX模型文件
   从 Comfy-Org镜像 下载合并后的单文件：
   • dev版：flux1-dev-fp8.safetensors（约12GB，FP8量化，8GB显存可跑）
   • schnell版：flux1-schnell-fp8.safetensors（约12GB）
   放到 ComfyUI/models/checkpoints/ 目录。
2. 下载T5文本编码器
   下载 t5xxl_fp8_e4m3fn.safetensors 放到 ComfyUI/models/clip/。
3. 下载VAE
   下载 ae.safetensors 放到 ComfyUI/models/vae/。
4. 加载工作流
   在ComfyUI中拖拽官方示例工作流（可从ComfyWorkflows搜索FLUX），选择对应模型即可出图。

方式四：Docker部署

docker run -d --name flux \
  --gpus all \
  -p 7860:7860 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v /data/flux_outputs:/workspace/outputs \
  us-docker.pkg.dev/flux-1234/flux/flux-schnell:latest

使用方法

基础参数说明

• guidance_scale：dev版推荐3.5，schnell版设为0.0（蒸馏模型不需要）
• num_inference_steps：dev版推荐20-50步，schnell版4步足够
• max_sequence_length：提示词token数，默认256，长提示词设为512
• 分辨率：推荐1024×1024或1024×1536，太小会丢失细节

显存优化技巧

• 使用 pipe.enable_model_cpu_offload()：将不活跃的层放到CPU，24GB显存可跑
• 使用 pipe.enable_vae_offload()：VAE解码时才放到GPU
• FP8量化版：8GB显存即可跑dev版，速度略慢但质量几乎无损
• GGUF量化版：4-6GB显存可跑，适合老显卡

常见问题（FAQ）

Q1: dev版需要HuggingFace授权，怎么申请？

前往 FLUX.1-dev页面，登录账号后点击"Agree and access repository"，填写简单的用途说明即可即时获得授权。然后在本地执行 huggingface-cli login 输入Token。

Q2: 显存只有8GB能跑FLUX吗？

可以。使用FP8量化版本（flux1-dev-fp8.safetensors）配合 enable_model_cpu_offload()，在8GB显存上可以正常生成1024×1024图片，单张约1-2分钟。如果是schnell版4步，速度会更快。

Q3: FLUX和SDXL有什么区别？

FLUX是120亿参数的Transformer架构，SDXL是26亿参数的UNet架构。FLUX在以下方面显著优于SDXL：文字渲染、复杂构图、人物手指、光影真实感、长提示词理解。速度上schnell版4步出图比SDXL快得多。

Q4: 生成的图片文字不准确怎么办？

FLUX对英文文字渲染已经很好，中文文字支持还在改进中。建议：提示词中明确写出要渲染的文字内容，用引号包裹，例如 a poster with the text "HELLO WORLD" in big letters。同时提高步数到50步以上。

Q5: FLUX可以商用吗？

FLUX.1 [schnell] 采用Apache 2.0协议，可免费商用。FLUX.1 [dev] 采用non-commercial许可，仅可用于非商业用途。商用请使用schnell版或FLUX.1 [pro] API。

跳转链接

• GitHub 仓库：https://github.com/black-forest-labs/flux
• 官网：https://blackforestlabs.ai
• HuggingFace模型页（dev）：https://huggingface.co/black-forest-labs/FLUX.1-dev
• HuggingFace模型页（schnell）：https://huggingface.co/black-forest-labs/FLUX.1-schnell
• ComfyUI FLFP8模型：https://huggingface.co/Comfy-Org/flux1-dev
• FLUX.1 [pro] API：https://docs.bfl.ai