fft npainting lama本地部署全流程，附常见错误解决方案

fft npainting lama本地部署全流程，附常见错误解决方案

本文带你从零开始完成 fft npainting lama 图像修复系统的本地部署，覆盖环境准备、服务启动、WebUI使用、效果调优及高频报错的根因分析与实操解法。全程不依赖云服务，所有操作均在 Linux 服务器（Ubuntu/CentOS）或 WSL2 环境下验证通过，适配 NVIDIA GPU（CUDA 11.8+），无 Docker 基础亦可顺利完成。

1. 系统与硬件准备

1.1 最低运行要求

验证 GPU 状态：执行nvidia-smi，确认显示 CUDA 版本（如CUDA Version: 11.8）且无No devices were found报错。

1.2 必备软件预装

# 更新系统并安装基础工具 sudo apt update && sudo apt upgrade -y sudo apt install -y git curl wget vim htop python3-pip python3-venv build-essential libgl1-mesa-glx # 安装 NVIDIA 驱动（若未安装） # 请先访问 https://www.nvidia.com/Download/index.aspx 下载匹配显卡型号的 .run 文件 # 执行：sudo ./NVIDIA-Linux-x86_64-*.run --no-opengl-files --no-x-check # 安装 CUDA 11.8（官方推荐版本，兼容性最佳） wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run --silent --toolkit --override # 配置环境变量（写入 ~/.bashrc） echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc # 验证 CUDA nvcc --version # 应输出：nvcc: release 11.8, V11.8.89

1.3 Python 环境隔离（关键步骤）

# 创建独立虚拟环境，避免与系统 Python 冲突 python3 -m venv /root/fft-lama-env source /root/fft-lama-env/bin/activate # 升级 pip 并安装 PyTorch（CUDA 11.8 版本） pip install --upgrade pip pip install torch==2.0.1+cu118 torchvision==0.15.2+cu118 --extra-index-url https://download.pytorch.org/whl/cu118 # 验证 GPU 可见性 python3 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'Device count: {torch.cuda.device_count()}')" # 输出应为：CUDA available: True，Device count: 1

注意：必须使用torch==2.0.1+cu118，高版本（如 2.1+）会导致 Lama 模型加载失败或推理崩溃；低版本（<2.0）则不支持部分算子。

2. 镜像拉取与项目初始化

2.1 获取镜像源码（非 Docker 部署）

该镜像为“二次开发构建版”，不提供 Dockerfile，而是直接交付可运行的完整项目目录结构。需手动下载并校验：

# 进入工作目录 cd /root # 下载项目压缩包（由科哥提供，假设已上传至私有存储） wget https://mirror.example.com/fft_npainting_lama_v1.0.0.tar.gz # 校验完整性（MD5 值以实际文档为准，此处为示例） echo "d41d8cd98f00b204e9800998ecf8427e fft_npainting_lama_v1.0.0.tar.gz" | md5sum -c # 输出应为：fft_npainting_lama_v1.0.0.tar.gz: OK # 解压并重命名（统一路径便于后续维护） tar -xzf fft_npainting_lama_v1.0.0.tar.gz mv cv_fft_inpainting_lama fft-lama-prod

2.2 目录结构说明

/root/fft-lama-prod/ ├── app.py # WebUI 主程序（FastAPI + Gradio） ├── models/ # 模型权重目录 │ ├── big-lama/ # 主力修复模型（LaMa + FFT 增强） │ │ ├── checkpoint.pth # 训练好的权重文件 │ │ └── config.yaml # 模型超参配置 │ └── default/ # 备用轻量模型（CPU 可跑） ├── start_app.sh # 一键启动脚本（核心！） ├── requirements.txt # Python 依赖清单 ├── outputs/ # 自动创建，修复结果默认保存路径 └── assets/ # 前端资源（CSS/JS/图标）

提示：models/big-lama/checkpoint.pth是整个系统的核心，大小约 3.18GB，首次运行时会自动加载到 GPU 显存中（约占用 4.2GB）。

3. 依赖安装与服务启动

3.1 安装 Python 依赖（跳过冗余包）

# 激活虚拟环境 source /root/fft-lama-env/bin/activate # 进入项目目录 cd /root/fft-lama-prod # 安装精简依赖（移除文档中未使用的包，加速安装） pip install -r requirements.txt --no-cache-dir # 强制安装关键视觉库（避免 Pillow 与 OpenCV 版本冲突） pip uninstall -y pillow opencv-python pip install pillow==9.5.0 opencv-python==4.8.1.78 # 验证关键库版本 python3 -c " import torch, cv2, PIL print(f'PyTorch: {torch.__version__}') print(f'OpenCV: {cv2.__version__}') print(f'PIL: {PIL.__version__}') " # 输出应为：PyTorch: 2.0.1+cu118，OpenCV: 4.8.1.78，PIL: 9.5.0

3.2 启动 WebUI 服务（含端口与日志管理）

# 赋予启动脚本执行权限 chmod +x start_app.sh # 查看脚本内容（了解其行为） cat start_app.sh # 输出关键行： # nohup python3 app.py --host 0.0.0.0 --port 7860 --share false > logs/app.log 2>&1 & # 启动服务（后台运行，日志自动记录） ./start_app.sh # 检查进程是否存活 ps aux | grep "app.py" | grep -v grep # 应看到类似：/root/fft-lama-env/bin/python3 app.py --host 0.0.0.0 --port 7860 ... # 实时查看启动日志（等待出现 "Running on public URL"） tail -f logs/app.log | grep -E "(Running on|Uvicorn running)"

成功标志：日志末尾出现Running on public URL: http://0.0.0.0:7860，且无ImportError、CUDA out of memory或OSError: [Errno 98] Address already in use报错。

3.3 防火墙与网络访问配置

# 开放 7860 端口（Ubuntu） sudo ufw allow 7860 # 或 CentOS（firewalld） sudo firewall-cmd --permanent --add-port=7860/tcp sudo firewall-cmd --reload # 验证端口监听状态 ss -tuln | grep :7860 # 应输出：tcp LISTEN 0 5 *:7860 *:*

访问方式：在浏览器中输入http://<你的服务器IP>:7860，即可打开 WebUI 界面。若为本地 WSL2，使用http://localhost:7860。

4. WebUI 核心功能实操指南

4.1 界面分区与交互逻辑

WebUI 采用左右分栏设计，所有操作均在单页内完成，无需刷新：

• 左侧「图像编辑区」

  • 支持拖拽上传、点击上传、Ctrl+V 粘贴三种方式
  • 工具栏含：画笔（Brush）、橡皮擦（Eraser）、撤销（Undo）、清除（Clear）
  • 画笔大小滑块：1–50px 连续调节，小尺寸用于精细边缘，大尺寸用于快速覆盖

• 右侧「修复结果区」

  • 实时显示修复后图像（非实时预览，点击“ 开始修复”后生成）
  • 状态栏显示：处理中...→完成！已保存至: /root/fft-lama-prod/outputs/outputs_20240520143022.png
  • 输出路径固定，文件名含时间戳，避免覆盖

注意：界面右上角显示webUI二次开发 by 科哥 | 微信：312088415，此为版权标识，不可删除，否则部分功能将被禁用（防破解机制）。

4.2 修复流程四步法（附避坑要点）

步骤一：上传图像（格式与尺寸建议）

• 推荐格式：PNG（无损，保留 Alpha 通道）
• 慎用 JPG：压缩导致边缘锯齿，修复后易出现色块或模糊
• 分辨率建议：
• 最佳：1024×768 ~ 1920×1080（平衡质量与速度）
• 可接受：≤ 2560×1440（处理时间 ≤ 25 秒）
• 避免：＞ 3000px 边长（显存溢出风险高，易触发CUDA error: out of memory）

步骤二：精准标注（决定修复成败的关键）

• 白色即“待修复”：仅涂抹需移除/修复区域，背景无需涂白
• 技巧：
  • 水印/文字：沿边缘外扩 3–5px，确保完全覆盖
  • 人物移除：先涂主体，再用橡皮擦微调发丝、衣纹等过渡区
  • 复杂物体（如电线、树枝）：分段多次涂抹，避免一笔带过漏标

❌ 常见错误：涂满整张图（系统误判为全图重绘，结果失真）；只涂中心不扩边（修复后留白或硬边）。

步骤三：启动修复（参数静默优化）

• 点击开始修复后，界面自动锁定，状态栏显示：
  初始化...→加载模型权重→执行推理...→后处理（FFT增强）→完成！
• 全程无参数调整项：该镜像已固化最优配置（big-lama模型 + FFT 频域补偿），用户无需干预。

步骤四：结果验收与导出

• 修复图自动显示于右侧，对比原图方法：
  • 刷新页面重新上传原图（左）→ 修复图（右）
  • 或使用系统自带的Split View（需在Settings中启用，非默认）
• 下载方式：
  • 点击右上角Download按钮（直接触发浏览器下载）
  • 或登录服务器执行：cp /root/fft-lama-prod/outputs/*.png ~/Downloads/

5. 高频错误诊断与实战解决方案

5.1 错误代码CUDA out of memory（显存不足）

现象：点击修复后，WebUI 卡在执行推理...，日志报RuntimeError: CUDA out of memory

根因：

• 图像过大（＞2560px）+ 模型权重（3.2GB）+ PyTorch 缓存，总显存需求超 GPU 容量
• 其他进程（如 Xorg、docker）占用显存

解法（按优先级排序）：

1. 立即降分辨率：用convert命令压缩图像

   # 安装 ImageMagick sudo apt install -y imagemagick # 将 input.jpg 缩放到长边 2000px，保持比例 convert input.jpg -resize "2000x2000>" output.jpg

2. 释放 GPU 占用：

   # 查看显存占用 nvidia-smi # 杀死无关进程（如残留的 python 进程） sudo fuser -v /dev/nvidia* # 查看占用进程 sudo kill -9 <PID>

3. 终极方案（修改模型加载策略）：
   编辑/root/fft-lama-prod/app.py，搜索device = torch.device("cuda")，改为：

   device = torch.device("cuda" if torch.cuda.is_available() else "cpu") # 并注释掉所有 .cuda() 调用（共 3 处）

   后果：修复速度下降 5–8 倍，但可保底运行（CPU 模式）。

5.2 错误代码OSError: [Errno 98] Address already in use

现象：执行./start_app.sh后提示端口被占，WebUI 无法访问

根因：前次服务未正常退出，app.py进程仍在后台运行

解法：

# 查找并终止所有 app.py 进程 pkill -f "app.py" # 或精确查找（推荐） ps aux | grep "app.py" | grep -v grep | awk '{print $2}' | xargs kill -9 # 验证端口空闲 lsof -ti:7860 # 无输出即为空闲

5.3 修复后图像发灰/偏色

现象：结果图整体亮度降低，色彩饱和度丢失，尤其人像肤色失真

根因：输入图像为 BGR 格式（OpenCV 默认）但模型期望 RGB；或 PNG 透明通道未正确处理

解法：

• 上传前转换色彩空间（命令行批量处理）：

  # 安装 opencv-python-headless（无 GUI 依赖） pip install opencv-python-headless==4.8.1.78 # 转换脚本 convert_to_rgb.py python3 -c " import cv2, sys img = cv2.imread(sys.argv[1]) img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) cv2.imwrite(sys.argv[1].replace('.jpg', '_rgb.jpg'), img_rgb) " # 执行：python3 convert_to_rgb.py input.jpg

• 或直接在 WebUI 中上传前勾选Auto-convert to RGB（该镜像 UI 已内置此开关，位于设置齿轮图标内）

5.4 修复区域边缘出现明显“接缝”

现象：修复后物体边缘有亮线/暗线，与周围不融合

根因：标注未外扩，模型缺乏足够上下文进行纹理合成

解法：

• 重标时扩大 5–8px：拖动画笔大小滑块至 15–25px，沿原区域外缘再涂一圈
• 启用“边缘羽化”：在 WebUI 设置中开启Soft Mask Edge（默认关闭，开启后自动添加 3px 渐变过渡）
• 进阶技巧：对同一图像分两次修复——第一次粗标大范围，下载后二次上传，精细标边缘

5.5 无法连接 WebUI（空白页/ERR_CONNECTION_REFUSED）

现象：浏览器打不开http://IP:7860，提示连接被拒绝

排查链路：

1. curl -v http://127.0.0.1:7860（本机测试）→ 若失败，服务未启动
2. curl -v http://<服务器IP>:7860（局域网测试）→ 若失败，防火墙/路由问题
3. telnet <服务器IP> 7860（端口连通性）→ 若超时，检查云服务器安全组是否放行 7860

终极修复命令：

# 强制重启服务（清理所有残留） pkill -f "app.py"; rm -f logs/app.log; ./start_app.sh # 检查日志最后 10 行 tail -10 logs/app.log

6. 生产环境加固建议

6.1 服务自启与崩溃恢复

# 创建 systemd 服务文件 sudo tee /etc/systemd/system/fft-lama.service > /dev/null << 'EOF' [Unit] Description=FFT LaMa Image Inpainting Service After=network.target [Service] Type=simple User=root WorkingDirectory=/root/fft-lama-prod ExecStart=/root/fft-lama-env/bin/python3 /root/fft-lama-prod/app.py --host 0.0.0.0 --port 7860 Restart=always RestartSec=10 Environment="PATH=/root/fft-lama-env/bin:/usr/local/bin:/usr/bin:/bin" [Install] WantedBy=multi-user.target EOF # 启用并启动 sudo systemctl daemon-reload sudo systemctl enable fft-lama.service sudo systemctl start fft-lama.service # 查看状态 sudo systemctl status fft-lama.service

6.2 输出目录自动清理（防磁盘爆满）

# 创建清理脚本 /root/fft-lama-prod/clean_outputs.sh cat > /root/fft-lama-prod/clean_outputs.sh << 'EOF' #!/bin/bash # 保留最近 7 天的输出文件，其余删除 find /root/fft-lama-prod/outputs/ -name "*.png" -mtime +7 -delete EOF chmod +x /root/fft-lama-prod/clean_outputs.sh # 每日凌晨 2 点执行 (crontab -l 2>/dev/null; echo "0 2 * * * /root/fft-lama-prod/clean_outputs.sh") | crontab -

6.3 多用户访问支持（反向代理）

# 安装 Nginx sudo apt install -y nginx # 配置反向代理（/etc/nginx/sites-available/fft-lama） sudo tee /etc/nginx/sites-available/fft-lama > /dev/null << 'EOF' server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:7860; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } EOF sudo ln -sf /etc/nginx/sites-available/fft-lama /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl restart nginx

完成后，用户可通过http://your-domain.com访问，无需暴露 7860 端口。

7. 总结：为什么选择这个二次开发版？

fft npainting lama 不是简单套壳，而是针对中文用户场景深度优化的生产级工具：

• 修复质量更稳：在原 LaMa 基础上注入 FFT 频域约束，显著提升纹理连续性，尤其对规则图案（格子、条纹、文字）修复更自然；
• 操作门槛更低：去除所有命令行参数，WebUI 一步到位，小白 5 分钟上手；
• 国产化适配好：微信技术支持直达开发者（科哥），问题响应快于 GitHub issue；
• 部署更轻量：无需 Docker，纯 Python 环境，WSL2、物理机、云服务器全兼容；
• 扩展性强：源码开放，可轻松接入企业 NAS 存储、对接 OA 审批流、嵌入内部 CMS 系统。

你不需要理解傅里叶变换如何增强修复，只需知道——涂白，点击，等待，下载。剩下的，交给 FFT 和 LaMa。

--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。