fft npainting lama图像修复系统搭建：Python调用避坑指南

Ne0inhk

15 Mar 2026 — 13 min read

FFT Npainting Lama图像修复系统搭建：Python调用避坑指南

1. 引言

你有没有遇到过这样的场景？一张珍贵的照片上有个碍眼的水印，或者合影里有个想“请走”的路人甲。手动用PS修图，费时费力，效果还不一定自然。现在，基于深度学习的图像修复技术，让这件事变得简单多了。

今天要聊的FFT Npainting Lama，就是一个能帮你智能“抹掉”图片中指定物体的工具。它基于LaMa模型，结合了快速傅里叶变换（FFT）来提升修复效果，特别擅长处理大面积的缺失区域。网上有很多关于它的WebUI使用教程，但如果你想把它集成到自己的Python项目里，进行二次开发，可能会遇到不少坑。

这篇文章，我就以一个过来人的身份，带你从零开始，一步步搭建FFT Npainting Lama的Python调用环境，并把那些我踩过的坑、绕过的弯，都给你标出来。目标是让你看完就能跑起来，少走弯路。

2. 环境准备：避开第一个大坑

万事开头难，环境配置往往是第一个拦路虎。FFT Npainting Lama依赖的库版本比较特定，装错了就可能各种报错。

2.1 系统与Python版本

操作系统：推荐使用Ubuntu 20.04或22.04。Windows和macOS理论上也可以，但在处理一些底层依赖（如PyTorch的CUDA）时可能会更麻烦。本文以Ubuntu为例。
Python版本：经过测试，Python 3.8 是最兼容的版本。强烈建议使用conda或venv创建独立的虚拟环境，避免污染系统环境。

# 使用conda创建环境（推荐） conda create -n lama_inpainting python=3.8 conda activate lama_inpainting # 或者使用venv python3.8 -m venv lama_env source lama_env/bin/activate

2.2 核心依赖安装

这里是最容易出问题的地方。很多教程让你直接 pip install -r requirements.txt，但如果那个 requirements.txt 文件里的版本不明确或者有冲突，你就中招了。

下面是我验证过可用的版本组合，请严格按照这个来：

# 首先升级pip和setuptools pip install --upgrade pip setuptools wheel # 安装PyTorch（根据你的CUDA版本选择，以CUDA 11.3为例） # 去PyTorch官网（https://pytorch.org/get-started/previous-versions/）核对版本 pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 torchaudio==0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113 # 如果没有GPU或CUDA，安装CPU版本 # pip install torch==1.12.1 torchvision==0.13.1 torchaudio==0.12.1 # 安装其他关键依赖 pip install opencv-python==4.5.5.64 pip install numpy==1.21.6 # 注意版本，过高可能不兼容 pip install Pillow==9.3.0 pip install omegaconf==2.1.1 pip install yacs==0.1.8 pip install easydict==1.9 pip install scikit-image==0.19.3 pip install tqdm==4.64.0 pip install gradio==3.34.0 # 如果你需要WebUI

避坑指南1：PyTorch版本 一定要匹配你的CUDA版本（nvidia-smi 查看）。版本不匹配会导致无法使用GPU，甚至直接报错 undefined symbol。如果环境复杂，先装PyTorch，再装其他依赖。

避坑指南2：NumPy版本 一些较老的代码可能对高版本NumPy（如1.24+）的API变化不兼容，导致报错。锁定在 1.21.6 是个安全的选择。

3. 获取与理解项目代码

环境好了，接下来是把代码拿到手，并搞清楚它的结构。

3.1 克隆仓库

通常这类项目会在GitHub或Gitee上。假设项目结构如下（根据你提供的截图和手册推测）：

git clone <项目仓库地址> cd cv_fft_inpainting_lama

3.2 项目结构解析

理解项目结构是二次开发的基础。一个典型的FFT Npainting Lama项目可能包含：

cv_fft_inpainting_lama/ ├── app.py # Gradio WebUI主入口文件 ├── start_app.sh # 启动脚本 ├── requirements.txt # 依赖列表（参考用，建议按我们上面的装） ├── model/ # 模型文件存放目录 │ └── lama.pt # 预训练模型权重 ├── networks/ # 网络结构定义 │ └── fft.py # 包含FFT逻辑的核心网络文件 ├── utils/ # 工具函数 │ ├── image_processing.py │ └── ... ├── inference.py # 核心推理脚本（重点！） ├── webui/ # WebUI相关文件 │ ├── css/ │ └── js/ └── outputs/ # 输出目录

关键文件说明：

inference.py：这是你进行Python API调用的核心。里面应该有一个 inpaint 或 predict 函数，接收图像和掩码（mask），返回修复后的图像。
networks/fft.py：实现了结合FFT的修复逻辑，是模型效果的灵魂。
app.py：基于Gradio的Web界面，它底层也是调用 inference.py 中的函数。

4. 核心调用：从WebUI到Python API

WebUI很方便，但我们要的是能集成到自动化流程中的Python接口。目标是把 app.py 中点击按钮背后的逻辑抽离出来。

4.1 分析推理流程

打开 inference.py 或 app.py 中处理图像的部分，核心流程通常是：

加载模型：读取 model/lama.pt 权重文件。
预处理：将输入的RGB图像和掩码（mask）图像转换为模型需要的张量格式（Tensor），并进行归一化等操作。
推理：将预处理后的数据送入模型，得到修复后的张量。
后处理：将模型输出的张量转换回PIL或OpenCV图像格式，并保存或返回。

4.2 封装可调用的函数

我们可以模仿WebUI的逻辑，封装一个简单的函数。假设 inference.py 里已经有现成的类或函数，我们只需正确调用。

# my_inpainter.py - 这是我们自己封装的调用模块 import cv2 import torch import numpy as np from PIL import Image import sys sys.path.append('.') # 将项目根目录加入路径，以便导入内部模块 from inference import LaMaInpainter # 假设推理模块里有这个类 class FFTNpaintingLama: def __init__(self, model_path='model/lama.pt', device='cuda'): """ 初始化修复器 Args: model_path: 模型权重路径 device: 推理设备，'cuda' 或 'cpu' """ self.device = device if torch.cuda.is_available() and device == 'cuda' else 'cpu' print(f"使用设备: {self.device}") # 初始化模型（这里需要根据实际项目代码调整） self.model = LaMaInpainter(model_path).to(self.device) self.model.eval() # 设置为评估模式 def inpaint(self, image_path, mask_path, output_path=None): """ 修复图像 Args: image_path: 原始图像路径 mask_path: 掩码图像路径（白色区域表示要修复） output_path: 输出图像路径，为None则只返回图像数组 Returns: 修复后的图像（numpy数组） """ # 1. 读取图像和掩码 image = cv2.imread(image_path) image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB) # OpenCV是BGR，转为RGB mask = cv2.imread(mask_path, cv2.IMREAD_GRAYSCALE) # 掩码读为灰度图 if image is None or mask is None: raise ValueError("无法读取图像或掩码文件") # 2. 预处理（尺寸对齐、归一化、转Tensor） # 这里需要与训练时保持一致，具体操作参考原项目inference.py # 例如：调整尺寸为64的倍数，归一化到[0,1]或[-1,1] processed_image, processed_mask = self._preprocess(image, mask) # 3. 推理 with torch.no_grad(): # 不计算梯度，加速推理 input_tensor = processed_image.unsqueeze(0).to(self.device) # 增加batch维度 mask_tensor = processed_mask.unsqueeze(0).to(self.device) # 调用模型前向传播 output_tensor = self.model(input_tensor, mask_tensor) # 4. 后处理（Tensor转回图像） result_image = self._postprocess(output_tensor) # 5. 保存或返回 if output_path: cv2.imwrite(output_path, cv2.cvtColor(result_image, cv2.COLOR_RGB2BGR)) print(f"结果已保存至: {output_path}") return result_image def _preprocess(self, image, mask): """预处理函数，需要根据项目实际代码实现""" # 示例：调整尺寸，这里假设模型要求输入尺寸为512x512 target_size = (512, 512) image = cv2.resize(image, target_size, interpolation=cv2.INTER_LINEAR) mask = cv2.resize(mask, target_size, interpolation=cv2.INTER_NEAREST) # 归一化 (示例，具体看模型要求) image_tensor = torch.from_numpy(image).float() / 255.0 mask_tensor = torch.from_numpy(mask).float() / 255.0 # 调整通道顺序 HWC -> CHW image_tensor = image_tensor.permute(2, 0, 1) mask_tensor = mask_tensor.unsqueeze(0) # 灰度图增加通道维度 -> (1, H, W) return image_tensor, mask_tensor def _postprocess(self, tensor): """后处理函数，需要根据项目实际代码实现""" # 示例：将模型输出转换回numpy图像 tensor = tensor.squeeze(0) # 去掉batch维度 tensor = tensor.permute(1, 2, 0) # CHW -> HWC image_np = tensor.cpu().numpy() image_np = np.clip(image_np * 255, 0, 255).astype(np.uint8) # 反归一化并转uint8 return image_np # 使用示例 if __name__ == "__main__": inpainter = FFTNpaintingLama(model_path='model/lama.pt', device='cuda') # 假设我们有一张图片和对应的掩码 result = inpainter.inpaint( image_path='test_image.jpg', mask_path='test_mask.png', # 白色区域是要修复的 output_path='result.jpg' ) print("修复完成！")

避坑指南3：预处理/后处理对齐 这是调用成功的关键！你必须仔细阅读原项目 inference.py 中的 _preprocess 和 _postprocess 函数（或者类似功能的函数），确保你的预处理步骤（如归一化范围、尺寸变换、通道顺序）和它完全一致。一个参数不对，结果就可能全黑或全白。

避坑指南4：掩码（Mask）格式 掩码必须是单通道（灰度）图像，通常白色（255）表示需要修复的区域，黑色（0）表示保留的区域。确保你的掩码图像模式正确。

5. 常见问题与解决方案

在实际搭建和调用过程中，你大概率会遇到下面这些问题。

5.1 模型加载失败

问题：KeyError: 'model' 或 Unexpected key(s) in state_dict。
原因：模型权重文件（.pt或.pth）保存的是整个模型的状态字典，但你的模型类定义可能和保存时不一样，或者你只加载了权重的一部分。

解决：

# 错误的加载方式 # model.load_state_dict(torch.load('model/lama.pt')) # 正确的加载方式（假设权重文件保存的是模型对象） checkpoint = torch.load('model/lama.pt', map_location=self.device) # 查看checkpoint里到底有什么 print(checkpoint.keys()) # 如果是包含'model'键的字典 if 'model' in checkpoint: self.model.load_state_dict(checkpoint['model']) # 如果直接就是state_dict elif 'state_dict' in checkpoint: self.model.load_state_dict(checkpoint['state_dict']) else: # 有时文件直接就是state_dict self.model.load_state_dict(checkpoint)

5.2 显存不足（CUDA out of memory）

问题：处理大图时爆显存。
解决：
1. 缩小输入尺寸：在预处理阶段，将图像和掩码缩放到一个较小尺寸（如512x512）。修复完成后再上采样回原尺寸，虽然会损失一些细节，但能大幅降低显存。
2. 使用CPU：如果对速度要求不高，初始化时设置 device='cpu'。
3. 分块处理：对于超大图，可以将其分割成小块，分别修复后再拼接。但这需要处理边界融合问题，比较复杂。

5.3 修复效果不理想

问题：修复区域出现模糊、颜色不一致或明显的接缝。
原因与解决：
1. 掩码质量：检查你的掩码是否精确覆盖了要修复的区域。边缘可以稍微柔和一些（羽化），但主体区域必须完全覆盖。
2. 图像内容：模型对于具有复杂、非重复纹理的区域（如人脸细节、规则文字）修复能力有限。对于大面积、背景简单的区域效果更好。
3. 迭代修复：对于难修复的区域，可以尝试“分而治之”。先修复一部分，将结果作为输入，再修复剩余部分。

5.4 依赖冲突

问题：AttributeError: module 'cv2' has no attribute 'imread' 或其他奇怪的导入错误。
解决：这通常是虚拟环境混乱或依赖版本冲突。最干净的办法是创建一个全新的虚拟环境，严格按照本文第2部分的版本顺序重新安装。使用 pip list 检查已安装包的版本。

6. 进阶：二次开发与集成

成功调用基础API后，你可以考虑如何将它变得更强大、更易用。

6.1 批量处理

写一个脚本，遍历文件夹内的所有图片和对应的掩码，进行批量修复，大大提高效率。

import os from pathlib import Path def batch_inpaint(image_dir, mask_dir, output_dir, inpainter): image_dir = Path(image_dir) mask_dir = Path(mask_dir) output_dir = Path(output_dir) output_dir.mkdir(parents=True, exist_ok=True) image_files = list(image_dir.glob('*.jpg')) + list(image_dir.glob('*.png')) for img_path in image_files: # 假设掩码文件和图片同名 mask_path = mask_dir / img_path.name if not mask_path.exists(): print(f"警告：未找到掩码文件 {mask_path}") continue output_path = output_dir / f"inpainted_{img_path.name}" try: inpainter.inpaint(str(img_path), str(mask_path), str(output_path)) print(f"已处理: {img_path.name}") except Exception as e: print(f"处理 {img_path.name} 时出错: {e}")

6.2 与Web框架集成

你可以将修复功能封装成一个REST API，方便其他系统调用。使用FastAPI可以快速实现。

# api_server.py from fastapi import FastAPI, File, UploadFile from fastapi.responses import FileResponse import tempfile import uuid from my_inpainter import FFTNpaintingLama # 导入我们封装的类 app = FastAPI() inpainter = FFTNpaintingLama() # 全局加载一次模型 @app.post("/inpaint/") async def inpaint_image( image: UploadFile = File(...), mask: UploadFile = File(...) ): # 保存上传的临时文件 suffix = Path(image.filename).suffix temp_id = uuid.uuid4().hex input_image_path = f"/tmp/{temp_id}_image{suffix}" input_mask_path = f"/tmp/{temp_id}_mask.png" output_path = f"/tmp/{temp_id}_result{suffix}" with open(input_image_path, "wb") as f: f.write(await image.read()) with open(input_mask_path, "wb") as f: f.write(await mask.read()) # 调用修复函数 result = inpainter.inpaint(input_image_path, input_mask_path, output_path) # 返回结果文件 return FileResponse(output_path, media_type="image/png", filename="result.png")

6.3 性能优化

模型量化：使用PyTorch的量化功能，将模型从FP32转换为INT8，可以显著减少模型大小和提升CPU推理速度，对精度影响很小。
ONNX导出：将模型导出为ONNX格式，然后使用ONNX Runtime进行推理，在某些硬件上可能获得更好的性能。
TensorRT加速：如果你有NVIDIA GPU，可以尝试将模型转换为TensorRT引擎，获得极致的推理速度。

7. 总结

搭建和调用FFT Npainting Lama进行Python二次开发，核心就是环境对齐和流程理解。记住这几个关键点：

环境隔离：用虚拟环境，严格按照兼容的版本安装依赖，尤其是PyTorch和NumPy。
流程对齐：深入阅读原项目的推理代码（inference.py），确保你的预处理、后处理逻辑与之一致，这是成功调用的基石。
掩码是关键：一张精准的掩码图是获得好效果的前提。
循序渐进：先从简单的例子跑通，再尝试处理更复杂的图像和集成到更复杂的系统中。

图像修复是一个很有趣且实用的方向。希望这篇避坑指南能帮你顺利搭建起自己的修复工具，无论是用来处理老照片，还是集成到内容审核、电商产品图处理等自动化流程中，都能得心应手。

获取更多AI镜像

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

fft npainting lama图像修复系统搭建：Python调用避坑指南

Ne0inhk