FLUX.1 结构条件生成实战指南：用 Canny 边缘与 Depth 深度控制实现精准图像重绘

FLUX.1 结构条件生成实战指南：用 Canny 边缘与 Depth 深度控制实现精准图像重绘

【免费下载链接】fluxOfficial inference repo for FLUX.1 models项目地址: https://gitcode.com/GitHub_Trending/flux49/flux

本文围绕 FLUX.1 官方推理仓库中的结构条件生成（Structural Conditioning）能力展开，系统讲解FLUX.1 Canny [dev]与FLUX.1 Depth [dev]（含两个 LoRA 变体）的模型体系、权重获取、交互式采样命令、关键采样参数与 TensorRT 加速推理方案。读完本文，你将掌握如何在保持原图构图与结构的前提下，通过文本引导完成重纹理化（retexturing）等图像编辑任务，并理解控制信号在生成管线中的底层传递机制。

什么是结构条件生成

结构条件生成（Structural Conditioning）利用Canny 边缘检测或深度估计（Depth Detection）来保持在图像变换过程中的精确控制。其核心思路是：先提取原图的结构信号——Canny 边缘图刻画轮廓走向，深度图刻画空间纵深关系——在后续的文本引导编辑中持续"锚定"这些结构，从而让生成结果在改变纹理、材质、风格等内容属性的同时，维持原图的核心构图不变。这一技术路径对重纹理化（在保持结构的前提下替换物体表面材质，例如把"金属机器人"换成"黄金机器人"）尤为有效。

围绕这一能力，官方仓库共发布了四个变体：

其中两个 LoRA 变体并不包含独立的主模型权重，而是作为 FLUX.1 [dev] 基础模型之上的轻量适配器存在，加载时必须同时下载基础模型，详见下文"LoRA 变体的加载与缩放"一节。

模型清单、许可与校验值

下表汇总了四个变体的模型标识、许可证与sha256sum校验值（用于验证下载权重的完整性，防止文件损坏或被篡改）：

四个变体均采用FLUX.1 [dev] 非商业许可证（完整条款见 model_licenses/LICENSE-FLUX1-dev），适用于个人、科研及按许可证约定范围的用途。

控制信号如何流入生成管线：源码级解读

结构条件生成与普通文生图（Text-to-Image）最本质的区别在于：采样时除了文本条件（T5-XXL + CLIP）和噪声潜变量，还额外注入了一路图像结构条件（img_cond）。整条调用链从 src/flux/cli_control.py 的main()入口出发，最终汇聚到 src/flux/sampling.py 的prepare_control()与denoise()。

控制编码器：CannyImageEncoder 与 DepthImageEncoder

在 src/flux/modules/image_embedders.py 中定义了两个核心编码器，对应两类控制信号：

• CannyImageEncoder：调用 OpenCV 的cv2.Canny做边缘检测，默认双阈值min_t=50、max_t=200（可在构造时调整）。输入图像先被钳制到[-1, 1]并映射回[0, 255]的字节域，边缘检测结果再经x / 127.5 - 1.0归一化，最终扩展为 3 通道张量送入后续流程。
• DepthImageEncoder：基于深度估计模型LiheYoung/depth-anything-large-hf（AutoModelForDepthEstimation）输出predicted_depth深度图，将其复制到 3 个通道，并用bicubic插值（抗锯齿开启）对齐回输入分辨率，同样归一化到[-1, 1]区间。

两个编码器都在torch.no_grad()上下文中执行，随后经由共享的 VAE 编码器压缩为潜空间表示（src/flux/sampling.py#L93-L97）。

条件图像的预处理与打包

prepare_control()（src/flux/sampling.py#L70-L104）承担了完整的前处理：

1. 用 PIL 打开条件图像并转为 RGB；
2. 将图像resize 到与目标生成分辨率一致（以噪声潜变量尺寸 × 8 还原的像素尺寸，采用LANCZOS重采样），保证结构与输出对齐；
3. 归一化到[-1, 1]并调整维度为(1, C, H, W)；
4. 依次经控制编码器与 VAE 编码器，转bfloat16后按 2×2 patch 打包（rearrange），作为img_cond存入返回字典。

通道级注入：为什么 in_channels 是 128

普通FLUX.1 [dev]的 transformer 输入通道为 64（见 src/flux/util.py 中configs的FluxParams），而flux-dev-canny、flux-dev-depth及其 LoRA 变体的in_channels均为128。从源码结构可以推断，多出的 64 通道正是打包后的控制条件img_cond：在denoise()（src/flux/sampling.py#L331-L333）中，每个采样步都会执行img_input = torch.cat((img, img_cond), dim=-1)，将噪声潜变量与控制条件在通道维拼接后送入 transformer，预测出噪声增量后再截取回主序列（pred[:, : img.shape[1]]）。这种"通道级拼接"设计正是结构约束能被保持到最后的原因。

环境准备与权重获取

仓库的安装方式见 README.md：推荐在 Python 3.10 环境创建虚拟环境后执行pip install -e ".[all]"；若需使用 TensorRT 后端，则需按 README 中 TensorRT 支持一节安装（如 NVIDIA PyTorch 容器 +pip install -e ".[tensorrt]"）。

权重的获取有三种方式，启动任意 demo 时系统会自动处理：

1. 自动下载：首次运行 demo 时，权重会自动从 HuggingFace 下载到仓库根目录的checkpoints/下（按模型 ID 规范化后的子目录存放，见 src/flux/util.py 的get_checkpoint_path()）。
2. 手动放置：预先手动下载权重文件放入checkpoints/对应目录，可跳过运行时的下载等待。
3. 环境变量指定路径：手动链接已有权重，通过环境变量覆盖默认位置：

export FLUX_MODEL=<your model path here> export FLUX_AE=<your autoencoder path here> # optional (see below) export FLUX_LORA=<your lora path here>

其中FLUX_MODEL指向主 transformer 权重（safetensors），FLUX_AE指向共享的 autoencoder 权重，FLUX_LORA仅在 LoRA 变体下需要。从 get_checkpoint_path() 的实现看，若环境变量指向的文件不存在，会打印警告并回退到默认位置自动下载；若模型仓库属于 gated（受限）仓库，则会提示通过HF_TOKEN环境变量或huggingface-cli login完成认证后重试。

需要特别注意的是，LoRA 变体（flux-dev-canny-lora、flux-dev-depth-lora）要求先下载基础 FLUX.1 [dev] 模型。从 configs 可以看到，LoRA 变体的repo_id指向基础模型black-forest-labs/FLUX.1-dev，lora_repo_id才是指向 LoRA 适配器仓库——使用这些变体时系统会自动同时下载基础模型与 LoRA 适配器。

交互式采样：python -m flux control

CLI 入口由 src/flux/main.py 提供，control子命令路由到 src/flux/cli_control.py 的main()。启动交互式采样：

python -m flux control --name <name> --loop

其中<name>取值如下，对应上文的四个变体：

• flux-dev-canny
• flux-dev-depth
• flux-dev-canny-lora
• flux-dev-depth-lora

--loop开启交互会话，每次采样后可以连续更换提示词、条件图像等。交互会话支持以下斜杠指令（在提示符输入/h也可随时查看帮助）：

对于条件图像与 LoRA 缩放，交互会话还提供了独立的输入环节：parse_img_cond_path()会询问下一张条件图像路径（接受.jpg/.jpeg/.png/.webp，输入/q退出）；LoRA 变体下parse_lora_scale()会进一步询问 LoRA 缩放系数。

关键采样参数与默认值

cli_control.py 的 main() 签名 定义了完整的命令行参数，下表汇总了与结构条件生成最相关的参数及其默认值：

引导强度（guidance）的默认值按模型自动设置：flux-dev-canny/flux-dev-canny-lora默认30.0，flux-dev-depth/flux-dev-depth-lora默认10.0（见 cli_control.py#L214-L220）。这是因为边缘图与深度图两类控制信号对文本的响应强度不同，官方据此给出了不同的校准值。你可以通过--guidance或交互会话中的/g覆盖默认值，结合具体任务微调"结构保持"与"文本跟随"的平衡。

单次生成（不进入交互循环）的写法，例如：

python -m flux control --name flux-dev-canny --prompt "a golden robot" --img_cond_path assets/robot.webp --guidance 30.0 --num_steps 50

生成结束后，图像会写入output/img_{idx}.jpg：输出经过 NSFW 分类器（Falconsai/nsfw_image_detection，阈值 0.85）过滤，通过后写入 EXIF 元数据（软件标记为AI generated;img2img;flux，制造商 Black Forest Labs，模型名与提示词），并叠加不可见水印（见 save_image()）。

LoRA 变体的加载与缩放

LoRA 变体在代码层面的实现位于 src/flux/model.py 的FluxLoraWrapper：它以 FLUX.1 [dev] 的Flux为基座（lora_rank默认 128），通过replace_linear_with_lora()将全部nn.Linear层替换为 LinearLora。每个LinearLora的前向计算为：

output = base_out + lora_B(lora_A(input)) * scale

即基础权重输出叠加低秩分支（lora_A、lora_B）的增量，增量受scale系数控制。在 CLI 中，模型加载后会对所有含set_scale方法的模块统一设置lora_scale（默认0.85），交互会话中也支持随时输入新的 LoRA 缩放值并热更新，便于实时对比不同强度下的结构保持效果。

需要特别说明的限制：TRT 后端目前不支持 LoRA 变体。源码中对此有显式断言assert not trt, "TRT does not support LORA"（cli_control.py#L205-L206），因此flux-dev-canny-lora、flux-dev-depth-lora只能走原生 PyTorch 推理路径。

TensorRT 加速推理

对于 Canny / Depth 两个全量模型变体，仓库提供了基于 TensorRT 的加速推理支持，导出精度支持BF16、FP8、FP4三档。首先需按 README.md 中 TensorRT 支持一节完成环境安装，然后执行：

python -m flux control --name=<name> --loop --img_cond_path="assets/robot.webp" --trt --static_shape=False --trt_transformer_precision <precision>

其中<precision>为bf16、fp8或fp4之一。相关参数说明：

• --trt：切换到 TensorRT 后端。此时会通过 src/flux/trt/trt_manager.py 的TRTManager加载 CLIP、Transformer、T5、VAE 与 VAE Encoder 五类引擎（引擎目录默认./engines，可用TRT_ENGINE_DIR环境变量覆盖）；
• --static_shape=False：关闭静态形状模式，允许在会话中动态调整分辨率（TRT 引擎构建时使用运行时的宽高）；
• --trt_transformer_precision：指定 transformer 引擎的精度，直接影响显存占用与推理速度的权衡（精度越低通常越快、越省显存）；
• Transformer 的 ONNX 导出模型会自动从black-forest-labs/FLUX.1-Canny-dev-onnx、black-forest-labs/FLUX.1-Depth-dev-onnx等 ONNX 仓库按精度下载（见 download_onnx_models_for_trt()），T5 引擎精度可用TRT_T5_PRECISION环境变量覆盖（默认bf16）。

与 diffusers 生态集成

除本仓库的参考实现外，Flux Control（含两个 LoRA 变体）同样兼容 Python 的diffusers库。diffusers官方为 FLUX 系列提供了对应的 pipeline 文档，你可以直接在该生态中以标准方式加载 Canny / Depth 模型与 LoRA 适配器，将其接入既有的 diffusers 工作流（如与其他调度器、pipeline 组合）。本仓库的 CLI 与diffusers两条路径共用同一套权重与条件编码逻辑，可作为实现上的对照参考。

参考资源

• 本文主体依据：docs/structural-conditioning.md
• 交互式采样入口：src/flux/cli_control.py
• 控制编码器实现：src/flux/modules/image_embedders.py
• 条件图像前处理与去噪：src/flux/sampling.py
• 模型配置与权重下载逻辑：src/flux/util.py
• 安装与 TensorRT 支持说明：README.md
• 许可证：model_licenses/LICENSE-FLUX1-dev

<output文章>

FLUX.1 结构条件生成实战指南：用 Canny 边缘与 Depth 深度控制实现精准图像重绘

本文围绕 FLUX.1 官方推理仓库中的结构条件生成（Structural Conditioning）能力展开，系统讲解FLUX.1 Canny [dev]与FLUX.1 Depth [dev]（含两个 LoRA 变体）的模型体系、权重获取、交互式采样命令、关键采样参数与 TensorRT 加速推理方案。读完本文，你将掌握如何在保持原图构图与结构的前提下，通过文本引导完成重纹理化（retexturing）等图像编辑任务，并理解控制信号在生成管线中的底层传递机制。

什么是结构条件生成

结构条件生成（Structural Conditioning）利用Canny 边缘检测或深度估计（Depth Detection）来保持在图像变换过程中的精确控制。其核心思路是：先提取原图的结构信号——Canny 边缘图刻画轮廓走向，深度图刻画空间纵深关系——在后续的文本引导编辑中持续"锚定"这些结构，从而让生成结果在改变纹理、材质、风格等内容属性的同时，维持原图的核心构图不变。这一技术路径对重纹理化（在保持结构的前提下替换物体表面材质，例如把"金属机器人"换成"黄金机器人"）尤为有效。

围绕这一能力，官方仓库共发布了四个变体：

其中两个 LoRA 变体并不包含独立的主模型权重，而是作为 FLUX.1 [dev] 基础模型之上的轻量适配器存在，加载时必须同时下载基础模型，详见下文"LoRA 变体的加载与缩放"一节。

模型清单、许可与校验值

下表汇总了四个变体的模型标识、许可证与sha256sum校验值（用于验证下载权重的完整性，防止文件损坏或被篡改）：

四个变体均采用FLUX.1 [dev] 非商业许可证（完整条款见 model_licenses/LICENSE-FLUX1-dev），适用于个人、科研及按许可证约定范围的用途。

控制信号如何流入生成管线：源码级解读

结构条件生成与普通文生图（Text-to-Image）最本质的区别在于：采样时除了文本条件（T5-XXL + CLIP）和噪声潜变量，还额外注入了一路图像结构条件（img_cond）。整条调用链从 src/flux/cli_control.py 的main()入口出发，最终汇聚到 src/flux/sampling.py 的prepare_control()与denoise()。

控制编码器：CannyImageEncoder 与 DepthImageEncoder

在 src/flux/modules/image_embedders.py 中定义了两个核心编码器，对应两类控制信号：

• CannyImageEncoder：调用 OpenCV 的cv2.Canny做边缘检测，默认双阈值min_t=50、max_t=200（可在构造时调整）。输入图像先被钳制到[-1, 1]并映射回[0, 255]的字节域，边缘检测结果再经x / 127.5 - 1.0归一化，最终扩展为 3 通道张量送入后续流程。
• DepthImageEncoder：基于深度估计模型LiheYoung/depth-anything-large-hf（AutoModelForDepthEstimation）输出predicted_depth深度图，将其复制到 3 个通道，并用bicubic插值（抗锯齿开启）对齐回输入分辨率，同样归一化到[-1, 1]区间。

两个编码器都在torch.no_grad()上下文中执行，随后经由共享的 VAE 编码器压缩为潜空间表示（src/flux/sampling.py#L93-L97）。

条件图像的预处理与打包

prepare_control()（src/flux/sampling.py#L70-L104）承担了完整的前处理：

1. 用 PIL 打开条件图像并转为 RGB；
2. 将图像resize 到与目标生成分辨率一致（以噪声潜变量尺寸 × 8 还原的像素尺寸，采用LANCZOS重采样），保证结构与输出对齐；
3. 归一化到[-1, 1]并调整维度为(1, C, H, W)；
4. 依次经控制编码器与 VAE 编码器，转bfloat16后按 2×2 patch 打包（rearrange），作为img_cond存入返回字典。

通道级注入：为什么 in_channels 是 128

普通FLUX.1 [dev]的 transformer 输入通道为 64（见 src/flux/util.py 中configs的FluxParams），而flux-dev-canny、flux-dev-depth及其 LoRA 变体的in_channels均为128。从源码结构可以推断，多出的 64 通道正是打包后的控制条件img_cond：在denoise()（src/flux/sampling.py#L331-L333）中，每个采样步都会执行img_input = torch.cat((img, img_cond), dim=-1)，将噪声潜变量与控制条件在通道维拼接后送入 transformer，预测出噪声增量后再截取回主序列（pred[:, : img.shape[1]]）。这种"通道级拼接"设计正是结构约束能被保持到最后的原因。

环境准备与权重获取

仓库的安装方式见 README.md：推荐在 Python 3.10 环境创建虚拟环境后执行pip install -e ".[all]"；若需使用 TensorRT 后端，则需按 README 中 TensorRT 支持一节安装（如 NVIDIA PyTorch 容器 +pip install -e ".[tensorrt]"）。

权重的获取有三种方式，启动任意 demo 时系统会自动处理：

1. 自动下载：首次运行 demo 时，权重会自动从 HuggingFace 下载到仓库根目录的checkpoints/下（按模型 ID 规范化后的子目录存放，见 src/flux/util.py 的get_checkpoint_path()）。
2. 手动放置：预先手动下载权重文件放入checkpoints/对应目录，可跳过运行时的下载等待。
3. 环境变量指定路径：手动链接已有权重，通过环境变量覆盖默认位置：

export FLUX_MODEL=<your model path here> export FLUX_AE=<your autoencoder path here> # optional (see below) export FLUX_LORA=<your lora path here>

其中FLUX_MODEL指向主 transformer 权重（safetensors），FLUX_AE指向共享的 autoencoder 权重，FLUX_LORA仅在 LoRA 变体下需要。从 get_checkpoint_path() 的实现看，若环境变量指向的文件不存在，会打印警告并回退到默认位置自动下载；若模型仓库属于 gated（受限）仓库，则会提示通过HF_TOKEN环境变量或huggingface-cli login完成认证后重试。

需要特别注意的是，LoRA 变体（flux-dev-canny-lora、flux-dev-depth-lora）要求先下载基础 FLUX.1 [dev] 模型。从 configs 可以看到，LoRA 变体的repo_id指向基础模型black-forest-labs/FLUX.1-dev，lora_repo_id才是指向 LoRA 适配器仓库——使用这些变体时系统会自动同时下载基础模型与 LoRA 适配器。

交互式采样：python -m flux control

CLI 入口由 src/flux/main.py 提供，control子命令路由到 src/flux/cli_control.py 的main()。启动交互式采样：

python -m flux control --name <name> --loop

其中<name>取值如下，对应上文的四个变体：

• flux-dev-canny
• flux-dev-depth
• flux-dev-canny-lora
• flux-dev-depth-lora

--loop开启交互会话，每次采样后可以连续更换提示词、条件图像等。交互会话支持以下斜杠指令（在提示符输入/h也可随时查看帮助）：

对于条件图像与 LoRA 缩放，交互会话还提供了独立的输入环节：parse_img_cond_path()会询问下一张条件图像路径（接受.jpg/.jpeg/.png/.webp，输入/q退出）；LoRA 变体下parse_lora_scale()会进一步询问 LoRA 缩放系数。

关键采样参数与默认值

cli_control.py 的 main() 签名 定义了完整的命令行参数，下表汇总了与结构条件生成最相关的参数及其默认值：

引导强度（guidance）的默认值按模型自动设置：flux-dev-canny/flux-dev-canny-lora默认30.0，flux-dev-depth/flux-dev-depth-lora默认10.0（见 cli_control.py#L214-L220）。这是因为边缘图与深度图两类控制信号对文本的响应强度不同，官方据此给出了不同的校准值。你可以通过--guidance或交互会话中的/g覆盖默认值，结合具体任务微调"结构保持"与"文本跟随"的平衡。

单次生成（不进入交互循环）的写法，例如：

python -m flux control --name flux-dev-canny --prompt "a golden robot" --img_cond_path assets/robot.webp --guidance 30.0 --num_steps 50

生成结束后，图像会写入output/img_{idx}.jpg：输出经过 NSFW 分类器（Falconsai/nsfw_image_detection，阈值 0.85）过滤，通过后写入 EXIF 元数据（软件标记为AI generated;img2img;flux，制造商 Black Forest Labs，模型名与提示词），并叠加不可见水印（见 save_image()）。

LoRA 变体的加载与缩放

LoRA 变体在代码层面的实现位于 src/flux/model.py 的FluxLoraWrapper：它以 FLUX.1 [dev] 的Flux为基座（lora_rank默认 128），通过replace_linear_with_lora()将全部nn.Linear层替换为 LinearLora。每个LinearLora的前向计算为：

output = base_out + lora_B(lora_A(input)) * scale

即基础权重输出叠加低秩分支（lora_A、lora_B）的增量，增量受scale系数控制。在 CLI 中，模型加载后会对所有含set_scale方法的模块统一设置lora_scale（默认0.85），交互会话中也支持随时输入新的 LoRA 缩放值并热更新，便于实时对比不同强度下的结构保持效果。

需要特别说明的限制：TRT 后端目前不支持 LoRA 变体。源码中对此有显式断言assert not trt, "TRT does not support LORA"（cli_control.py#L205-L206），因此flux-dev-canny-lora、flux-dev-depth-lora只能走原生 PyTorch 推理路径。

TensorRT 加速推理

对于 Canny / Depth 两个全量模型变体，仓库提供了基于 TensorRT 的加速推理支持，导出精度支持BF16、FP8、FP4三档。首先需按 README.md 中 TensorRT 支持一节完成环境安装，然后执行：

python -m flux control --name=<name> --loop --img_cond_path="assets/robot.webp" --trt --static_shape=False --trt_transformer_precision <precision>

其中<precision>为bf16、fp8或fp4之一。相关参数说明：

• --trt：切换到 TensorRT 后端。此时会通过 src/flux/trt/trt_manager.py 的TRTManager加载 CLIP、Transformer、T5、VAE 与 VAE Encoder 五类引擎（引擎目录默认./engines，可用TRT_ENGINE_DIR环境变量覆盖）；
• --static_shape=False：关闭静态形状模式，允许在会话中动态调整分辨率（TRT 引擎构建时使用运行时的宽高）；
• --trt_transformer_precision：指定 transformer 引擎的精度，直接影响显存占用与推理速度的权衡（精度越低通常越快、越省显存）；
• Transformer 的 ONNX 导出模型会自动从black-forest-labs/FLUX.1-Canny-dev-onnx、black-forest-labs/FLUX.1-Depth-dev-onnx等 ONNX 仓库按精度下载（见 download_onnx_models_for_trt()），T5 引擎精度可用TRT_T5_PRECISION环境变量覆盖（默认bf16）。

与 diffusers 生态集成

除本仓库的参考实现外，Flux Control（含两个 LoRA 变体）同样兼容 Python 的diffusers库。diffusers官方为 FLUX 系列提供了对应的 pipeline 文档，你可以直接在该生态中以标准方式加载 Canny / Depth 模型与 LoRA 适配器，将其接入既有的 diffusers 工作流（如与其他调度器、pipeline 组合）。本仓库的 CLI 与diffusers两条路径共用同一套权重与条件编码逻辑，可作为实现上的对照参考。

参考资源

• 本文主体依据：docs/structural-conditioning.md
• 交互式采样入口：src/flux/cli_control.py
• 控制编码器实现：src/flux/modules/image_embedders.py
• 条件图像前处理与去噪：src/flux/sampling.py
• 模型配置与权重下载逻辑：src/flux/util.py
• 安装与 TensorRT 支持说明：README.md
• 许可证：model_licenses/LICENSE-FLUX1-dev

【免费下载链接】fluxOfficial inference repo for FLUX.1 models项目地址: https://gitcode.com/GitHub_Trending/flux49/flux