Nunchaku-FLUX.1-dev开源大模型部署教程:Ubuntu22.04+Conda环境全配置

想在自己的电脑上跑一个高质量的文生图模型,但又担心显存不够、配置复杂?今天,我们就来手把手搞定Nunchaku-FLUX.1-dev的本地部署。这是一个基于开源FLUX.1 [dev]模型优化而来的文本生成图片大模型,最大的亮点就是对中文场景友好,并且针对消费级GPU做了显存优化。

简单来说,你输入“古风少女,江南水乡,水墨风格”这样的中文描述,它能生成比原版FLUX.1更贴合你想象的画面。而且,像RTX 3090或4090这样的显卡就能跑起来,不用再眼巴巴等着云端API的调用次数,特别适合个人创作、电商素材生成或者接一些AI绘画的小单子。

下面,我们就从零开始,在Ubuntu 22.04系统上,用Conda环境把它部署起来,并启动一个带Web界面的应用。

1. 环境准备与项目概览

在开始敲命令之前,我们先花两分钟了解一下我们要做什么,以及需要准备些什么。这样后面操作起来心里更有底。

1.1 你需要准备什么

这次部署的目标,是在一台安装了Ubuntu 22.04的机器上(可以是云服务器,也可以是你的本地电脑),搭建一个独立的Python环境,然后运行起Nunchaku-FLUX.1-dev的WebUI服务。

硬件要求:

  • GPU:这是核心。你需要一张NVIDIA显卡,显存至少8GB,推荐12GB或以上。像RTX 3060 12G、RTX 3090/4090都可以。显存越大,能生成的图片分辨率就越高。
  • 系统:Ubuntu 22.04 LTS。其他Linux发行版可能也行,但本文的指令是针对Ubuntu的。
  • 存储:模型文件大概20多GB,请确保有足够的硬盘空间。

软件基础:

  • 熟悉Linux的基本命令行操作(cd, ls, mkdir等)。
  • 知道怎么用SSH连接到你的服务器(如果是云服务器的话)。

1.2 项目结构预览

部署完成后,你的系统里大概会是这样:

  • Conda环境:位于 /opt/miniconda3/envs/torch28,这是一个独立的Python环境,里面安装了PyTorch、Diffusers等所有必需的库。
  • 项目目录:位于 /root/nunchaku-flux-1-dev,这里是WebUI的代码和运行日志所在的地方。
  • 模型文件:位于 /root/ai-models/AI-ModelScope/FLUX.1-dev,这是最占空间的,包含了模型的所有参数。
  • Web服务:运行在后台,通过 http://你的服务器IP:7860 这个地址来访问。

好了,概念清楚了,我们挽起袖子开始干。

2. 基础系统环境配置

第一步,我们要确保系统本身的基础软件是齐全的,特别是NVIDIA显卡驱动和CUDA工具包。

2.1 更新系统与安装基础工具

首先,打开终端,更新一下系统的软件包列表,并安装一些我们后续可能会用到的工具。

sudo apt update
sudo apt upgrade -y
sudo apt install -y wget git vim curl net-tools

2.2 安装NVIDIA驱动与CUDA

这是能让GPU干活的关键。Ubuntu 22.04的仓库里通常有比较新的驱动,我们可以用以下命令安装。这里以安装525版本驱动为例:

# 安装NVIDIA驱动和CUDA工具包(这个命令会同时安装驱动和CUDA)
sudo apt install -y nvidia-driver-525 cuda-toolkit-11-8

# 安装完成后,重启系统让驱动生效
sudo reboot

重启后,重新登录终端,运行下面的命令来验证驱动和CUDA是否安装成功:

# 查看GPU信息,如果能看到你的显卡型号和驱动版本,就说明驱动OK了
nvidia-smi

# 查看CUDA编译器版本,如果显示11.8之类的版本号,说明CUDA也OK了
nvcc --version

如果 nvidia-smi 命令报错或找不到,可能是驱动没装好,需要根据你的显卡型号去NVIDIA官网查找更具体的安装指南。

3. 使用Conda创建Python隔离环境

为了避免Python包之间的版本冲突,我们使用Conda来创建一个干净、独立的环境。这里我们选择安装轻量级的Miniconda。

3.1 安装Miniconda

在终端中执行以下命令下载并安装Miniconda:

# 下载Miniconda安装脚本(Linux 64位版本)
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh

# 运行安装脚本,安装路径我们指定为 /opt/miniconda3
bash miniconda.sh -b -p /opt/miniconda3

# 将Conda初始化到你的shell环境(假设你用bash)
/opt/miniconda3/bin/conda init bash

# 关闭再重新打开终端,或者执行以下命令使环境变量生效
source ~/.bashrc

现在,你的命令行前面应该会出现 (base) 字样,这表示你已经进入了Conda的base环境。

3.2 创建专用的PyTorch环境

我们不直接在base环境里安装,而是新建一个专门用于本项目的环境,命名为 torch28。

# 创建一个新环境,指定Python版本为3.10(兼容性好)
conda create -n torch28 python=3.10 -y

# 激活这个新环境
conda activate torch28

激活后,提示符会变成 (torch28),表示后续的所有pip安装都会只影响这个环境。

4. 安装PyTorch与项目依赖

现在,我们在这个干净的环境里安装深度学习框架和项目需要的库。

4.1 安装PyTorch

根据之前CUDA 11.8的版本,我们安装对应的PyTorch。去PyTorch官网找命令可能会更准,这里给出一个参考:

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

安装完成后,可以进入Python交互模式验证一下:

python -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA是否可用: {torch.cuda.is_available()}'); print(f'GPU设备: {torch.cuda.get_device_name(0)}')"

如果输出显示CUDA可用,并且是你的显卡型号,那就完美了。

4.2 安装Diffusers、Transformers等核心库

Nunchaku-FLUX.1-dev是基于Hugging Face的Diffusers库构建的,所以我们需要安装它以及相关依赖。

pip install diffusers transformers accelerate gradio
  • diffusers: 运行扩散模型的核心库。
  • transformers: 处理文本编码等任务。
  • accelerate: 帮助优化模型在GPU上的加载和运行。
  • gradio: 用来构建我们即将使用的Web用户界面。

5. 部署Nunchaku-FLUX.1-dev项目

依赖装好了,现在把项目代码和模型弄过来。

5.1 获取项目代码与模型

根据你提供的资料,项目代码和模型可能已经预置在特定目录。我们假设需要手动部署,流程如下:

# 切换到root用户的主目录(或者你希望放置项目的任何目录)
cd /root

# 假设项目仓库地址,这里需要替换为真实的Git地址
# git clone <nunchaku-flux-1-dev 仓库地址>
# 由于地址未知,我们模拟创建项目目录和结构
mkdir -p nunchaku-flux-1-dev
cd nunchaku-flux-1-dev

# 创建主要的Python启动脚本,例如 app.py
# 这里只是示意,实际脚本内容来自项目方
cat > app.py << 'EOF'
# 此处应是完整的Gradio WebUI应用代码
# 内容过长,不在此处展开,实际部署时需使用项目提供的真实文件
print("WebUI app.py placeholder")
EOF

# 创建模型目录并下载/链接模型
# 重要:模型文件很大,请确保你有权使用并遵守其许可证
mkdir -p /root/ai-models/AI-ModelScope
# 假设模型已存在于 /root/ai-models/AI-ModelScope/FLUX.1-dev
# 如果没有,需要从Hugging Face Hub或指定源下载
# 例如:git lfs clone https://huggingface.co/black-forest-labs/FLUX.1-dev /root/ai-models/AI-ModelScope/FLUX.1-dev

关键点:模型文件(FLUX.1-dev)体积巨大,通过Git LFS下载可能需要很长时间且需要足够网络带宽和磁盘空间。请确保你了解并遵守模型的许可证(通常为非商业或有限商业用途)。

5.2 配置WebUI应用

在项目目录下,需要确保 app.py 或其他启动脚本正确配置了模型路径。通常脚本里会有一行类似这样的代码需要检查或修改:

model_path = "/root/ai-models/AI-ModelScope/FLUX.1-dev"

确保这个路径和你实际存放模型的路径一致。

6. 使用Supervisor管理服务

我们不想每次开机都手动启动服务,最好让它能在后台稳定运行,并且开机自启。Supervisor是一个很好的进程管理工具。

6.1 安装与配置Supervisor

# 安装supervisor
sudo apt install -y supervisor

# 为我们的服务创建一个配置文件
sudo vim /etc/supervisor/conf.d/nunchaku-flux-1-dev.conf

将以下配置内容粘贴进去(请根据你的实际路径和Conda环境路径修改):

[program:nunchaku-flux-1-dev]
command=/opt/miniconda3/envs/torch28/bin/python /root/nunchaku-flux-1-dev/app.py
directory=/root/nunchaku-flux-1-dev
user=root
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stderr_logfile=/root/nunchaku-flux-1-dev/supervisor.log
stdout_logfile=/root/nunchaku-flux-1-dev/supervisor.log
environment=PYTHONUNBUFFERED="1"

参数解释:

  • command:指定用我们创建的 torch28 环境里的python来运行我们的app.py脚本。
  • directory:程序运行的工作目录。
  • autostart/autorestart:让服务自动启动和崩溃后重启。
  • logfile:把程序的输出日志保存到指定文件,方便排查问题。

6.2 启动并管理服务

# 重新加载Supervisor配置,使其识别我们的新服务
sudo supervisorctl reread
sudo supervisorctl update

# 启动我们的服务
sudo supervisorctl start nunchaku-flux-1-dev

# 查看服务状态,看到 RUNNING 就说明成功了
sudo supervisorctl status nunchaku-flux-1-dev

7. 访问与使用WebUI

如果一切顺利,服务现在已经跑起来了。

7.1 访问Web界面

打开你的浏览器,输入以下地址:

http://<你的服务器IP地址>:7860

将 <你的服务器IP地址> 替换成你Ubuntu机器的实际IP。如果是在本地电脑上部署,就用 http://localhost:7860 或者 http://127.0.0.1:7860。

你应该能看到一个简洁的Web界面,上面有提示词输入框、图像尺寸、步数等参数设置,以及一个“生成图像”的按钮。

7.2 生成你的第一张图片

  1. 输入提示词:在“Prompt”框里,用英文或中文描述你想画的画面。例如:“A beautiful landscape of mountains and a lake, sunset, digital art”。
  2. 调整参数(可选):
    • 宽度/高度:先从默认的512x512开始,这是最稳的。
    • 推理步数:20-25步是质量和速度的平衡点。
    • 引导系数:3.0-4.0之间,让模型既听话又有一定创意。
  3. 点击生成:点击“Generate”或“🚀 生成图像”按钮,然后耐心等待。在RTX 3090上,512x512分辨率大概需要2-3分钟。
  4. 查看结果:生成的图片会显示在界面上,并自动保存到服务器的项目目录中(例如 /root/nunchaku-flux-1-dev/)。

7.3 服务管理常用命令

以后如果需要维护,记住这几个命令:

# 查看服务状态
sudo supervisorctl status nunchaku-flux-1-dev

# 重启服务(修改代码或配置后常用)
sudo supervisorctl restart nunchaku-flux-1-dev

# 停止服务
sudo supervisorctl stop nunchaku-flux-1-dev

# 查看实时日志
tail -f /root/nunchaku-flux-1-dev/supervisor.log

8. 总结与排错指南

恭喜你!如果你跟着步骤走到了这里,那么一个功能完整的Nunchaku-FLUX.1-dev文生图服务就已经在你的Ubuntu系统上运行起来了。我们来回顾一下关键步骤和可能遇到的问题。

8.1 部署流程回顾

整个部署的核心流程可以概括为四步:

  1. 打地基:安装NVIDIA驱动和CUDA,让GPU能干活。
  2. 建环境:用Conda创建一个独立的Python环境,避免包版本冲突。
  3. 搬砖瓦:安装PyTorch、Diffusers等所有必需的库。
  4. 启服务:配置并启动WebUI应用,用Supervisor把它变成可靠的后台服务。

8.2 常见问题与解决思路

  • 问题:nvidia-smi 命令无效或看不到GPU。

    • 解决:驱动安装失败。尝试使用 ubuntu-drivers devices 查看推荐驱动,或用 sudo apt install nvidia-driver-535 安装更新版本的驱动,然后务必重启。
  • 问题:访问 http://IP:7860 打不开。

    • 解决:
      1. 检查服务状态:sudo supervisorctl status,确保是 RUNNING。
      2. 检查端口是否监听:netstat -tlnp | grep 7860。
      3. 如果是云服务器,检查安全组/防火墙是否放行了7860端口。
      4. 查看日志找错误:tail -50 /root/nunchaku-flux-1-dev/supervisor.log。
  • 问题:生成图片时提示 CUDA out of memory。

    • 解决:这是显存不够了。
      1. 首选:在WebUI里把图片分辨率从1024x1024或768x768降到512x512。
      2. 减少“推理步数”。
      3. 关闭其他占用GPU的程序。
      4. 重启服务释放残留显存:sudo supervisorctl restart nunchaku-flux-1-dev。
  • 问题:生成速度非常慢。

    • 理解:这是正常的。因为这个优化版模型使用了“sequential CPU offload”技术,让大模型能在有限的显存里运行,代价就是数据需要在CPU和GPU之间来回搬运,速度会比完全载入显存慢。512x512分辨率下,20步等待2-3分钟是预期内的。
    • 缓解:使用更高端的GPU(如RTX 4090)或等待未来更进一步的优化。

现在,你可以尽情发挥创意,用中文提示词去生成你想要的任何画面了。无论是为文章配图,还是创作个人作品,这台部署在你本地的AI画师已经准备就绪。


获取更多AI镜像

想探索更多AI镜像和应用场景?访问 CSDN星图镜像广场,提供丰富的预置镜像,覆盖大模型推理、图像生成、视频生成、模型微调等多个领域,支持一键部署。

Logo

聚焦RDK与具身智能,汇集机器人开发教程、开源案例和技术交流

更多推荐