# Flux 镜像运行简明指南
本说明如何运行Flux镜像的必要步骤。
## 1.Dockerfile 构建并运行
- 构建镜像：
```bash
docker build -t flux-dev:latest -f Dockerfile .
```
## 2.运行容器（本仓库中含有 docker-compose.yml目录）
```bash
docker compose up -d
```
### docker-compose.yml说明
- /apps/juanquan/models/FLUX.1-dev:/apps/juanquan/models/FLUX.1-dev #此挂载文件为模型权重文件
```
下载位置：https://www.modelscope.cn/models/MusePublic/489_ckpt_FLUX_1/summary?version=2172
```
- /apps/juanquan/code/FLUX.1-dev:/apps/juanquan/code/FLUX.1-dev #此挂载文件为仓库代码：
```bash
git clone https://modelers.cn/models/MindIE/FLUX.1-dev/tree/main
```
## 3.进入容器
```bash
docker compose exec flux-dev bash
```
## 4.进入后如何使用
- 进入容器后，切到挂载目录 /apps/juanquan/code/FLUX.1-dev ，按项目脚本执行测试：
### 测试脚本的环境变量说明
- CPU_AFFINITY_CONF=2：CPU 核心绑定策略 ：CPU 亲和性配置(0：关闭 CPU 亲和性绑定/1：绑定到单个 CPU 核心/2：绑定到 NPU 对应的 CPU NUMA 节点（多核)
- TASK_QUEUE_ENABLE=2：推理任务队列模式 (0：关闭任务队列，同步执行/1：开启单队列模式/2：开启多队列分层调度)
```python
source /root/.conda/envs/py310/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/mindie/set_env.sh
export model_path="/apps/juanquan/models/FLUX.1-dev"
export CPU_AFFINITY_CONF=2
export TASK_QUEUE_ENABLE=2
python inference_flux.py \
--path ${model_path} \
--save_path "./images" \
--device_id 4 \
--device "npu" \
--prompt_path "./prompts.txt" \
--width 1024 \
--height 1024 \
--infer_steps 50 \
--use_cache \
--seed 42 \
--batch_size 1
```
## 5.成功运行后
- 图片会保存在 该目录下 ：--save_path "./images"
# FLUX.1-dev 模型在 NPU 上的部署与测试
## 一、背景
- FLUX.1-dev 的出现，正是这一趋势下的关键突破——它不仅具备出色的细节还原能力，更在提示词理解、复杂概念组合和多模态交互方面树立了新标杆。作为 Black Forest Labs 推出的 Flow Transformer 架构代表作，这款120亿参数的开源文生图模型，正迅速成为研究者与开发者的首选实验平台。
- 我现在需要在 NPU-910b 上部署 FLUX.1-dev 模型，以充分利用 NPU 的并行计算能力。
## 二、环境准备-部署过程
### 1.创建虚拟环境
```python
conda create -n flux_env python=3.10
conda activate flux_env
```
### 2.虚拟环境内安装CANN、MindIE、torch_npu (并验证是否安装成功)
- mindie和torch_npu、CANN都是在晟腾官网手动下载依赖包，手动执行安装
#### 2.1安装CANN
```python
# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构，{soc}表示昇腾AI处理器的版本。
chmod +x ./Ascend-cann-toolkit_{version}_linux-{arch}.run
chmod +x ./Ascend-cann-kernels-{soc}_{version}_linux.run
# 校验软件包安装文件的一致性和完整性
./Ascend-cann-toolkit_{version}_linux-{arch}.run --check
./Ascend-cann-kernels-{soc}_{version}_linux.run --check
# 安装
./Ascend-cann-toolkit_{version}_linux-{arch}.run --install
./Ascend-cann-kernels-{soc}_{version}_linux.run --install
# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
```
#### 2.2安装MindIE
```python
Ascend-mindie_1.0.0_linux-aarch64.run
chmod +x ./Ascend-mindie_${version}_linux-${arch}.run
./Ascend-mindie_${version}_linux-${arch}.run --check
./Ascend-mindie_${version}_linux-${arch}.run --install
```
#### 2.3安装torch_npu
```python
{version}表示软件版本号，{arch}表示CPU架构。
pip install torch-${version}-cp310-cp310-linux_${arch}.whl
```
#### 2.4验证是否安装成功
```python
python -c "
import torch
import mindie
# 验证torch_npu是否可用
print('✅ torch版本:', torch.__version__)
print('✅ torch_npu是否生效:', torch.npu.is_available())
# 验证MindIE是否可用+绑定NPU
print('✅ MindIE版本:', mindie.__version__)
print('✅ MindIE NPU适配是否生效:', mindie.check_npu_available())
"
```
### 3.下载本仓库
```
git clone https://modelers.cn/models/MindIE/FLUX.1-dev/tree/main
```
#### 3.1.安装-依赖包requestment.txt（昇腾适配版）
```python
pip install -r requestment.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```
## 三、权重下载
### 1.准备模型
```https://www.modelscope.cn/models/MusePublic/489_ckpt_FLUX_1/summary?version=2172```
### 2.修改权重配置文件
```vi ${model_path}/model_index.json```
- 做如下修改：
```json
{
"_class_name": "FluxPipeline",
"_diffusers_version": "0.30.0.dev0",
"scheduler": [
"diffusers",
"FlowMatchEulerDiscreteScheduler"
],
"text_encoder": [
"transformers",
"CLIPTextModel"
],
"text_encoder_2": [
"transformers",
"T5EncoderModel"
],
"tokenizer": [
"transformers",
"CLIPTokenizer"
],
"tokenizer_2": [
"transformers",
"T5TokenizerFast"
],
"transformer": [
"FLUX1dev",
"FluxTransformer2DModel"
],
"vae": [
"diffusers",
"AutoencoderKL"
]
}
```
## 四、运行测试脚本
### 测试脚本的环境变量说明
- CPU_AFFINITY_CONF=2：CPU 核心绑定策略 ：CPU 亲和性配置(0：关闭 CPU 亲和性绑定/1：绑定到单个 CPU 核心/2：绑定到 NPU 对应的 CPU NUMA 节点（多核)
- TASK_QUEUE_ENABLE=2：推理任务队列模式 (0：关闭任务队列，同步执行/1：开启单队列模式/2：开启多队列分层调度)
```python
source /root/.conda/envs/py310/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/mindie/set_env.sh
export model_path="/apps/juanquan/models/FLUX.1-dev"
export CPU_AFFINITY_CONF=2
export TASK_QUEUE_ENABLE=2
python inference_flux.py \
--path ${model_path} \
--save_path "./images" \
--device_id 4 \
--device "npu" \
--prompt_path "./prompts.txt" \
--width 1024 \
--height 1024 \
--infer_steps 50 \
--use_cache \
--seed 42 \
--batch_size 1
```
## 五、安装过程中的问题
### 1.unrecognized arguments: --device_type → 删除无效参数
- python脚本无这个参数
### 2.numpy=2.4.1版本冲突 → 强制锁定 numpy=1.26.4
- 适配其他包，降级到1.26版本
### 3.torch_npu安装失败
- 适配 torch=2.1.0+torch_npu=2.1.0.post12,在晟腾官网，手动下载安装torch_npu，适配torch版本号
### 4.mindiesd加载失败
- 1.容器中遇到加载失败，缺少find包，yum install -y findutils && yum clean all,再安装mindie包
- 2.重新安装一遍: ./软件包名.run --install --quiet 配置环境变量source /usr/local/Ascend/mindie/set_env.sh
### 5.ModuleNotFoundError: decorator → 补全昇腾依赖
### 6.ValueError: sentencepiece缺失 → 安装分词器依赖
## 总结：
- 1.cann torch_npu mindie包都在官网找适配的版本号，不进行工具安装
- 2.版本依赖很强，按照官方每一步运行
)
