简介基于深度学习的图像修复算法Python源码与项目说明面向计算机相关专业正在准备毕业设计、课程设计或期末大作业的学生也适合需要实战练习的初学者。项目经导师指导并认可评审分数99分代码完整、可直接运行降低了上手门槛。压缩包共14个文件体积约5.33MB包含两个不同复杂度的Python脚本分别对应从基础到进阶的修复策略8张修复效果对比图和2张原始测试图片可直观验证算法表现1份README项目说明详细讲解环境配置、运行方式与实现思路结构清晰便于二次开发。目前已有177人学习资源涵盖深度学习图像修复的完整流程从数据准备、模型推理到结果可视化均有对应模块帮助学习者快速掌握领域核心思想也能直接用于课程展示或毕业答辩。1. 拿到一个图像修复源码包先别急着解压跑训练“基于深度学习的图像修复算法python源码项目说明.zip”这类压缩包在 GitHub 和各类源码站上很常见。它本质上是一个完整的工程交付物算法模型、训练代码、推理脚本和项目说明文档被打包在一起。我下载过不少这种包第一反应通常是想立刻 pip install 然后跑个 demo 看看效果但实际上手后才发现真正花时间的不是算法本身而是把“别人的环境”搬到“自己的机器”上的过程。图像修复Image Inpainting / Restoration解决的是两类问题一类是生成式填补比如老照片上的划痕、破损区域、被遮挡的文字模型要根据周围像素“猜”出缺失内容另一类是质量恢复比如去噪、去模糊、超分辨率。这个源码包大概率是把生成式填补作为核心算法来做的因为这是深度学习图像修复里最典型、也最能出效果的方向。这篇文章会沿着“算法原理 → 环境搭建 → 数据准备 → 训练推理 → 踩坑排查”这条线把这个 zip 里的内容讲透让新手能跑通让熟手能调到可用状态。2. 图像修复算法在解决什么问题从数学填补到语义生成2.1 基于深度学习的图像修复与传统方法的本质区别在深度学习普及之前图像修复主要靠插值和偏微分方程。OpenCV 里至今还保留着两种经典算法INPAINT_TELEA 和 INPAINT_NS。Telea 算法的思路是把缺失像素看作等值线从边界向内一层层扩散Navier-Stokes 算法则是用流体力学方程来模拟颜色流的传播。这类方法对细小的划痕、文字水印效果不错但一旦缺失区域超过几十个像素结果就是一团模糊的色块——因为传统方法没有“语义理解”能力它不知道缺失区域里是一只猫还是一辆车。深度学习模型之所以能在这方面翻盘是因为它学会了“先理解、再生成”。以 GAN 为核心的修复模型生成器拿到一张带 mask 的破损图先通过编码器提取全局特征再在缺失区域内部生成与上下文语义一致的内容。比如 DeepFillv2、EdgeConnect 这类模型生成的结果不仅有正确的颜色和纹理连物体的结构、边缘、光影关系都能猜个八九不离十。这个源码包里的模型大概率走的也是这条路线——要么是 U-Net 加 GAN 的判别器结构要么是引入注意力机制的改进版本。2.2 三种主流技术路线的选型取舍我在实际项目中评估过三类修复方案这里给出一个可以直接抄作业的对比表技术路线代表方案修复质量训练成本推理速度适合场景传统插值Telea / NS差仅细小区域无需训练毫秒级划痕、噪点CNN GANU-Net PatchGAN、DeepFillv2较好语义合理中单卡可训快人像、风景、老照片扩散模型RePaint、Stable Diffusion Inpainting最好细节丰富高需多卡或大显存慢迭代采样需要高质量填充的场景如果你手里的 zip 包注释里写了“支持人像修复”“去水印”这类关键词基本可以判定是 CNN GAN 路线。这类模型最大的优点是训练成本可控——一张 8GB 显存的消费级显卡就能跑起来而扩散模型动辄需要 16GB 以上显存或者靠 CPU 硬扛几百步采样速度让人崩溃。2.3 为什么 mask 的生成方式直接决定模型效果不管源码包里用的是哪种模型有一点是所有图像修复算法的共同命门训练时用的 mask损坏区域标记是怎么生成的。最常见的做法是随机生成不规则多边形、笔画或者矩形块把它们叠加在完整图像上模拟破损。但这里有个隐藏的坑如果训练数据和推理场景的 mask 分布不一致模型效果会大打折扣。比如你训练时用的全是小面积矩形 mask模型只见过 5% 区域的缺损部署时却要修复 50% 面积的破损生成结果会出现明显的“脏涂抹”现象。源码包的 data 目录里一般会有一个 mask 生成脚本我建议拿到包的第一件事不是跑训练而是仔细看这个脚本它生成了什么形状、什么尺寸分布、是否支持自定义 mask 输入。这一步能帮你省掉后面大量的反复训练时间。3. 把 zip 解压成可运行的工程环境搭建与目录结构解读3.1 Python 环境准备虚拟环境是后悔药这类深度学习源码包最怕的就是“直接往系统 Python 里装依赖”。不同项目的 torch、cuda、numpy 版本要求各不相同直接装会把环境搞得一团糟。我一般会为每个源码包单独建一个虚拟环境这样卸载重来都不心疼算是在环境配置上给自己留一颗后悔药。# 创建 Python 3.8 虚拟环境注意不是 conda纯 venv 足够 python -m venv inpaint_env # 激活虚拟环境 # Windows: inpaint_env\Scripts\activate # Linux / macOS: source inpaint_env/bin/activate # 确认环境内的 Python 版本 python --version pip --version逻辑说明venv 会在当前目录创建一个独立的 Python 环境所有通过 pip 安装的包都会放在 inpaint_env 目录下不会污染系统 Python。激活后终端提示符前面会出现(inpaint_env)字样看到它就知道当前处于虚拟环境内。参数说明Python 版本选择 3.8 是我经过多次踩坑后的折中选择——太老的版本3.6 以下不支持新版 torch太新的版本3.10又容易遇到某些老源码包编译时报错。如果你的源码包项目说明里写明了 Python 版本要求以说明为准。3.2 解压 zip 后应该先看这三个文件拿到“python源码项目说明.zip”先别急着跑。我会先把压缩包里的目录结构完整看一遍重点关注三个东西# 解压用 unzip 命令Windows 下用 7-Zip 或 WinRAR unzip python_source_inpaint.zip -d inpaint_project # 进入项目根目录 cd inpaint_project # 查看目录树Linux/macOS 用 tree没有就安装apt install tree 或 brew install tree tree -L 2逻辑说明unzip的解压参数和文件名的中文或空格兼容性不太好如果遇到解压失败可以先确认文件编码。Windows 上我见过很多 zip 包是 GBK 编码的目录名解压到 Linux 上会变成乱码用unzip -O gbk可以解决。解压后第一件事是找requirements.txt或environment.yml这是项目的依赖清单第二是找README.md或项目说明.pdf里面通常写了环境版本要求、数据集格式和训练命令第三是找config/或options/目录网络结构参数、训练参数都在这里。这三个文件决定了你后面的所有操作路径。如果项目说明和实际代码对不上——这太常见了比如说明里写了 CUDA 10.2代码里却是新版的 torch API——以代码为准说明文档只能当参考。3.3 依赖安装先把 torch 版本锁死大多数图像修复源码包的核心依赖就三件套torch、torchvision、opencv-python。但版本组合很有讲究。以我的经验先装 PyTorch 再装其他依赖可以避免 pip 自作主张把 torch 升级到不兼容版本。# 先安装 PyTorch以 CUDA 11.8 为例无 GPU 的机器装 CPU 版 pip install torch1.13.1cu117 torchvision0.14.1cu117 --extra-index-url https://download.pytorch.org/whl/cu117 # 再安装项目其余依赖 pip install -r requirements.txt # 验证安装结果 python -c import torch; print(torch.__version__, torch.cuda.is_available())逻辑说明先指定版本装 torch 是为了固定 CUDA 运行时版本后面requirements.txt里即使写了torch1.8pip 检测到已安装的 torch 满足条件就不会再动它。最后一行验证代码打印出 torch 版本号和 CUDA 是否可用如果输出True说明 GPU 可用False说明只能 CPU 跑。参数说明--extra-index-url指向 PyTorch 官方 wheel 源。如果你的机器没有 NVIDIA 显卡把 torch 换成torch1.13.1的 CPU 版即可但训练速度会慢 20 倍以上建议先用 CPU 跑通流程真正训练还是找个 GPU 云服务器。4. 跑通第一个 Demo从预训练权重到图像修复输出4.1 项目说明文档里通常藏着的预训练权重下载方式这类源码包一般不会把训练好的权重文件直接塞进 zip——因为一个模型文件动辄几百 MB压缩包会变得巨大。更常见的做法是项目说明文档里给出百度网盘或 Google Drive 链接或者让用户从 GitHub Releases 页面下载。我拿到包后会先在整个项目目录里搜一遍.pth、.ckpt、.pt后缀的文件如果有说明权重已被包含那可以直接跳到推理环节。如果没有找到预训练权重就需要从零开始训练。这里有一个重要的心态建设不要指望一上来就训练出和论文效果一样的模型。图像修复模型的训练需要精心调参没有几万步迭代不可能收敛。正确的路径是先下载能用的预训练权重 → 跑通 demo 验证整体流程 → 再微调训练。权重文件下载完成后放置位置也有讲究。我见过太多源码包代码默认路径是./checkpoints/model.pth但用户把权重放在了别的目录导致加载时报错。解决方法是去options/或config/里搜checkpoints或pretrained字段看看代码默认读哪个路径然后把权重放过去或者修改配置文件里的路径。4.2 推理脚本拆解mask、输入输出路径、关键参数假设这个源码包是常规的 CNN GAN 结构推理脚本一般长这样。我给出一个典型的骨架代码并逐行解释它在干什么# inference.py import torch import cv2 import numpy as np from models.network import InpaintModel def load_mask(mask_path): 读取 mask 文件二值化处理 mask cv2.imread(mask_path, cv2.IMREAD_GRAYSCALE) # 将所有非零像素统一为 255白色代表损坏区域 mask np.where(mask 10, 255, 0).astype(np.uint8) return mask def main(): # 配置参数 checkpoint_path checkpoints/epoch_100.pth image_path samples/input.jpg mask_path samples/mask.png output_path samples/output.jpg device torch.device(cuda if torch.cuda.is_available() else cpu) # 加载模型 model InpaintModel() state_dict torch.load(checkpoint_path, map_locationdevice) model.load_state_dict(state_dict) model.to(device) model.eval() # 读取输入 image cv2.imread(image_path) # BGR, HxWx3 mask load_mask(mask_path) # HxW # 归一化并转成网络输入格式 image_norm image.astype(np.float32) / 127.5 - 1.0 # 转 [-1, 1] mask_norm mask.astype(np.float32) / 255.0 # 转 [0, 1] # 拼接网络输入是 [原图 mask] 四通道 input_tensor np.concatenate([image_norm, mask_norm[:, :, None]], axis2) input_tensor torch.from_numpy(input_tensor.transpose(2, 0, 1))[None, :, :, :] input_tensor input_tensor.to(device) # 前向推理 with torch.no_grad(): output model(input_tensor) # 输出转回图像 output_image output[0].cpu().numpy().transpose(1, 2, 0) output_image (output_image 1.0) * 127.5 output_image np.clip(output_image, 0, 255).astype(np.uint8) # 保存结果 cv2.imwrite(output_path, output_image) print(fSaved to {output_path}) if __name__ __main__: main()逻辑说明这个推理脚本的核心是输入拼接。图像修复模型通常接受四通道输入——前三个通道是破损原图第四个通道是 mask 图mask 上白色1.0代表需要修复的区域黑色0.0代表保留区域。模型在内部通过 mask 把破损区域的特征“挖掉”再让生成器重新预测这些位置的特征值。torch.no_grad()会在推理时关闭梯度计算节省显存并提高速度。参数说明map_locationdevice是加载权重时最关键的参数——如果训练时用的是 GPU你的机器没有 GPU不加这个参数直接torch.load会报错加上它就能把权重映射到 CPU 上。/ 127.5 - 1.0这个归一化手法很常见目的是把像素值从[0, 255]映射到[-1, 1]这是 GAN 生成器常见的输入范围。如果输出图像颜色发暗或发灰多半是这个归一化和反归一化没有对齐。4.3 用自己的一张图片快速验证修复效果跑通脚本后找一张自己的真实图片去测试是最有成就感的时刻。我建议准备三样素材一张有划痕的老照片、一张带文字水印的截图、一张用程序随机挖掉一块区域的图片。这样能快速摸清模型的泛化边界# 把测试图片放到 samples 目录 cp ~/Desktop/old_photo.jpg samples/input.jpg cp ~/Desktop/mask.png samples/mask.png # 执行推理 python inference.py # 对比前后效果用系统自带图片查看器 open samples/output.jpg # macOS xdg-open samples/output.jpg # Linux如果输出结果看起来“糊了一坨”别急着怀疑模型有问题。先检查 maskmask 必须精确标记出损坏区域如果 mask 比实际损坏区域大很多模型会把周围完好的像素也一起重绘结果自然是模糊的。一个好习惯是用图像编辑工具按照损坏区域的轮廓精细涂抹 mask而不是随手画个大圆。验证输出后你基本就跑通了整个推理链路。到这一步这个 zip 包的核心价值你已经拿到手了——剩下的就是根据需求决定是继续微调训练还是直接用在业务场景里。5. 训练自己的修复模型数据准备和三个必调参数5.1 数据从哪里来开源数据集和自建数据集的取舍源码包里一般会说明训练数据的格式。图像修复任务的标准数据格式是“完整图 对应 mask”的配对形式完整图可以是任何自然图像mask 则标注了哪些区域被视为“损坏”。最常用的开源数据集包括 Places365、ImageNet 的子集以及专门为修复任务构建的异常遮挡数据集。如果你有自己的数据比如公司里的老照片存档、产品图库训练效果会比公开数据集好得多。但自建数据集有两个代价标注成本和时间成本。图像修复的“标注”不是画 bounding box而是为每张图生成对应的 mask。好在大部分源码包都提供自动 mask 生成脚本基于随机形状生成器就能批量产出训练对。# generate_masks.py import cv2 import numpy as np from random import randint, choice def generate_random_mask(height, width, max_ratio0.3): 生成随机不规则 mask mask np.zeros((height, width), dtypenp.uint8) num_shapes randint(2, 8) for _ in range(num_shapes): # 随机选择形状矩形、椭圆或折线描边 shape_type choice([rectangle, ellipse, stroke]) center_x, center_y randint(0, width), randint(0, height) w randint(20, int(width * max_ratio)) h randint(20, int(height * max_ratio)) if shape_type rectangle: cv2.rectangle(mask, (center_x, center_y), (min(center_xw, width), min(center_yh, height)), 255, -1) elif shape_type ellipse: cv2.ellipse(mask, (center_x, center_y), (w//2, h//2), 0, 0, 360, 255, -1) else: # 模拟划过一道的长条痕迹 pts np.array([[center_x, center_y], [center_xrandint(30,80), center_yrandint(-20,20)], [center_xrandint(60,120), center_yrandint(-10,10)]]) cv2.polylines(mask, [pts], False, 255, thicknessrandint(5, 20)) return mask逻辑说明这段代码生成的是训练时用的随机 mask。cv2.rectangle、cv2.ellipse、cv2.polylines分别生成矩形、椭圆和不规则线条三种损坏形状组合起来模拟真实世界的划痕、遮挡和水印。randint(2, 8)控制一张图上叠加几处损坏数值越大训练难度越高。参数说明max_ratio0.3是关键参数控制单块损坏区域占图像宽或高的最大比例。0.3 意味着损坏区域理论上最多占整张边界的 30%超过这个比例模型生成难度陡增。训练初期建议设为 0.2 以下等模型收敛稳定后再逐步提高到 0.4。如果你要修复的是大面积水印这个参数必须调大否则训练时模型根本没见过大块 mask。5.2 训练启动命令batch size、学习率、损失权重图像修复模型的训练目标不是简单地让输出图像接近原图而是要同时做到“内容合理”和“边界流畅”。因此损失函数往往由多项组成重建损失L1 或 L2保证像素级接近感知损失保证特征级语义一致对抗损失保证输出分布像真实图像。# 启动训练以单卡 GPU 为例 python train.py \ --data_root ./datasets/places256 \ --mask_root ./datasets/masks \ --batch_size 8 \ --lr 0.0002 \ --epochs 200 \ --save_interval 5 \ --lambda_rec 10.0 \ --lambda_adv 1.0 \ --lambda_perceptual 0.1逻辑说明train.py是源码包里的训练入口脚本。--data_root指向完整图像数据集目录--mask_root指向对应的 mask 目录两者一一对应。每轮训练迭代中模型从数据目录随机取一张图、从 mask 目录随机取一张 mask将 mask 叠加在图像上构造破损样本然后让生成器预测修复结果判别器判断“修复图和原图”哪个是真的。两个网络交替优化直到判别器分不出修复结果和真实图像的差别。参数说明--batch_size 8在 8GB 显存下是安全值如果显存报错就降到 4。--lr 0.0002是 GAN 训练的经典学习率比普通分类任务的 0.001 更低因为对抗训练对学习率极其敏感调大一点就容易震荡甚至崩溃。--lambda_rec 10.0是重建损失的权重这个值必须给得比较大否则生成器会只顾着骗过判别器而忽略了对原图的忠实度输出“漂移”的内容。5.3 训练过程中实时监控哪些指标图像修复不像分类任务有明确的 accuracy 可以看训练过程更像是在“猜”。我一般同时观察三个信号生成器损失值、判别器损失值、以及定时保存的验证集可视化结果。生成器损失G loss趋势是缓慢下降。如果这个值剧烈波动比如从 200 跳到 50000 再跳回 100大概率是学习率过高或判别器太强。判别器损失D loss理想状态是围绕一个恒定值小幅波动因为判别器在对抗中始终“略强于”生成器。如果 D loss 趋近于 0说明生成器已经完全不是对手图像质量会很差。可视化结果项目说明里一般会写“每 N 轮保存一组修复前后的对比图”。我习惯用--save_interval 5每 5 个 epoch 看一次效果。重点看修复区域的边缘是否与周围纹理自然衔接如果边界有明显锯齿或色块感说明模型过拟合到了训练 mask 的分布需要增加 mask 的随机性。6. 图像修复训练与推理的避坑手册我踩过六次以上的坑6.1 解压出来跑不起来路径里的中文名和空格现象Python 报错ModuleNotFoundError或FileNotFoundError但明明文件就在眼前。原因项目目录放在了带中文或空格的路径下比如C:\Users\张三\我的项目\inpaint或者压缩包本身的文件编码是 GBK解压在 Linux 上成了乱码目录名。源码包里有些脚本用相对路径硬编码了目录名路径一乱就找不到模块。解决把整个项目移动到一个纯英文、无空格的路径下比如/home/user/projects/inpaint或D:\inpaint。解压时如果文件名乱码Linux 上用unzip -O gbkWindows 上先用 7-Zip 解压到临时目录再改名。6.2 报错 OSError: [Errno 13] Permission denied现象训练脚本在写入 checkpoint 时突然报权限错误但同一个目录下其他文件能正常写。原因项目是从网盘下载的 zip 包解压后文件的 owner 和权限位可能不正确或者当前用户对目录没有写权限。解决在项目根目录执行chmod -R uw .和chown -R $(whoami) .把文件 owner 改回当前用户。Windows 上没这个问题Linux 上几乎是血泪教训——每次解压异地打包的 zip 都要习惯性补一条权限修复命令。6.3 CUDA out of memory显存不够不是玄学现象训练跑了几百步后突然报CUDA out of memory之前明明没问题。原因批量产生的数据显示单个 batch 里随机 mask 面积偏大时输入张量的有效计算区域变大中间特征图的显存占用可能骤增。另外torch 的缓存机制不会自动释放之前占用的显存如果你中途尝试过多次调试显存碎片堆积也会触发 OOM。解决先降 batch size。从 8 降到 4 再降到 2这是最直接的办法。如果还不行检查代码里是否有torch.cuda.empty_cache()的调用在验证步骤前加一行。终极办法是在训练脚本里加梯度累积# 梯度累积示例batch_size 2累积 4 步等效于 batch_size 8 accumulation_steps 4 optimizer.zero_grad() for i, (image, mask) in enumerate(dataloader): loss compute_loss(image, mask) loss loss / accumulation_steps # 平均梯度 loss.backward() if (i 1) % accumulation_steps 0: optimizer.step() optimizer.zero_grad()逻辑说明梯度累积的原理是每几个 mini-batch 才做一次参数更新等效增大了 batch size 但对显存要求不变。代码中loss loss / accumulation_steps是为了让梯度均值与等效大 batch 一致。注意 PyTorch 的优化器会在optimizer.step()之后再原地修改参数所以累加的是梯度不是 loss。6.4 修复结果颜色发灰发暗现象模型输出的图像整体偏暗像是上了一层灰色蒙版尤其是天空、白色墙面的区域颜色明显不对。原因训练数据的归一化方式和推理时的反归一化方式不匹配。大部分 GAN 模型使用[0, 1]或[-1, 1]归一化而 OpenCV 默认读取的图像是 BGR 顺序且值域为[0, 255]。如果推理脚本把图像值域缩放到[0, 1]后输入模型输出也是[0, 1]但保存时忘了乘回 255就会出现灰蒙蒙的效果。解决检查推理代码里是否包含反归一化要么在cv2.imwrite前乘以 255要么用torvision.utils.save_image这个工具函数。另外确认通道顺序OpenCV 是 BGRPyTorch tensor 是 RGB输出前需要cv2.cvtColor(output, cv2.COLOR_BGR2RGB)。6.5 训练 loss 震荡得像过山车现象生成器 loss 一会降一会升判别器 loss 直接打到 0 附近。原因学习率过大对抗失衡。判别器太强导致它迅速区分出真实图和生成图生成器梯度瞬间消失无法学到有效信息。反过来如果生成器太强判别器会一直无法收敛。解决把生成器和判别器的学习率分开设置生成器lr1e-4判别器lr4e-5让判别器“慢半拍”这是从不少开源项目里验证过的稳定组合。如果仍然震荡把训练计划的 betas 参数从默认的(0.9, 0.999)改成(0.5, 0.999)这个技巧能显著提升 GAN 训练的稳定性。6.6 项目说明文档和代码版本对不上现象项目说明写着“支持 Python 3.6”代码里却用了torch.utils.tensorboard这在 3.6 上装不上或者说明里写了训练命令是python train.py --gpu_ids 0实际代码的参数名却是--gpu。原因很多源码包是作者边写论文边发的时间跨度过大代码迭代了但说明文档没同步更新。尤其常见的是项目说明基于旧版 PyTorch 写的代码已经迁移到了新版 API。解决把项目说明当作辅助指南遇到报错时优先用python train.py --help查看当前代码实际支持的参数列表。--help是源码包自带的“讲真话的文档”它直接打印参数解析器里注册的所有可选参数、默认值和类型比任何说明文档都可靠。修改参数时同步更新说明文档也算是在给别人留下一颗后悔药。7. 进阶玩法用感知质量和推理速度两个维度评估修复效果跑通训练只是第一步真正决定这个项目能否落地的是修复质量的评估方法。PSNR 和 SSIM 虽然是论文里最常用的指标但在实际业务中未必准确反映人的主观感受。一张修复图 PSNR 28dB、SSIM 0.95看起来很漂亮但人眼可能一眼就看出五官畸形相反PSNR 只有 25dB 的图像人眼却觉得质量不俗。所以我现在评估修复效果的习惯是“三看”第一看边界连续性。把修复区域和原图边界的像素差值画成热力图如果边界处有厚厚的“接缝线”说明模型的边缘感知能力不足。第二看纹理一致性。用 LPIPSLearned Perceptual Image Patch Similarity指标它基于预训练网络提取的高层特征计算距离对纹理细节更敏感。第三看语义合理性。直接肉眼观察对人物、文字这类高语义敏感区域逐个检查——人脸的五官是否歪斜、文字的横竖撇捺是否连贯。在推理速度上如果要把模型部署到端侧设备TensorRT 或 ONNX Runtime 是绕不开的。常见做法是把训练好的 PyTorch 权重导出为 ONNX再用 TensorRT 做 INT8 量化推理速度能提升 3 到 5 倍。但这步的坑在于修复模型的输入是动态形状的因为 mask 大小不固定ONNX 导出时要把 input 的宽高固定或者显式声明动态轴否则部署时一遇到不同分辨率的图就崩。我个人的习惯是先固定推理分辨率比如统一缩放到 512×512 或 256×256再走导出流程等稳定了再研究动态形状的支持。如果你准备用这个项目长期做图像修复业务另一件值得投入的事是给你的模型构建一套“边界 case 测试集”。拿 100 张不同场景的图片在每张上故意挖不同比例、不同形状的 mask记录模型在每个样本上的修复效果按失败案例归因是 mask 形状没见过的泛化问题还是训练数据中该场景占比过少的欠拟合问题。有了这份记录后续微调训练才有的放矢而不是盲目加训练轮数碰运气。我自己处理这些源码包时有一个固定习惯拿到 zip 先解压到英文路径、看完--help、跑通推理 demo、再做训练。这套流程帮我避开了大半的翻车情况也省掉了大量 Google 报错的时间。希望这篇笔记能让你少走几趟弯路祝顺利。本文还有配套的精品资源点击获取
深度学习图像修复实战：源码包解析、环境搭建与训练避坑指南
简介基于深度学习的图像修复算法Python源码与项目说明面向计算机相关专业正在准备毕业设计、课程设计或期末大作业的学生也适合需要实战练习的初学者。项目经导师指导并认可评审分数99分代码完整、可直接运行降低了上手门槛。压缩包共14个文件体积约5.33MB包含两个不同复杂度的Python脚本分别对应从基础到进阶的修复策略8张修复效果对比图和2张原始测试图片可直观验证算法表现1份README项目说明详细讲解环境配置、运行方式与实现思路结构清晰便于二次开发。目前已有177人学习资源涵盖深度学习图像修复的完整流程从数据准备、模型推理到结果可视化均有对应模块帮助学习者快速掌握领域核心思想也能直接用于课程展示或毕业答辩。1. 拿到一个图像修复源码包先别急着解压跑训练“基于深度学习的图像修复算法python源码项目说明.zip”这类压缩包在 GitHub 和各类源码站上很常见。它本质上是一个完整的工程交付物算法模型、训练代码、推理脚本和项目说明文档被打包在一起。我下载过不少这种包第一反应通常是想立刻 pip install 然后跑个 demo 看看效果但实际上手后才发现真正花时间的不是算法本身而是把“别人的环境”搬到“自己的机器”上的过程。图像修复Image Inpainting / Restoration解决的是两类问题一类是生成式填补比如老照片上的划痕、破损区域、被遮挡的文字模型要根据周围像素“猜”出缺失内容另一类是质量恢复比如去噪、去模糊、超分辨率。这个源码包大概率是把生成式填补作为核心算法来做的因为这是深度学习图像修复里最典型、也最能出效果的方向。这篇文章会沿着“算法原理 → 环境搭建 → 数据准备 → 训练推理 → 踩坑排查”这条线把这个 zip 里的内容讲透让新手能跑通让熟手能调到可用状态。2. 图像修复算法在解决什么问题从数学填补到语义生成2.1 基于深度学习的图像修复与传统方法的本质区别在深度学习普及之前图像修复主要靠插值和偏微分方程。OpenCV 里至今还保留着两种经典算法INPAINT_TELEA 和 INPAINT_NS。Telea 算法的思路是把缺失像素看作等值线从边界向内一层层扩散Navier-Stokes 算法则是用流体力学方程来模拟颜色流的传播。这类方法对细小的划痕、文字水印效果不错但一旦缺失区域超过几十个像素结果就是一团模糊的色块——因为传统方法没有“语义理解”能力它不知道缺失区域里是一只猫还是一辆车。深度学习模型之所以能在这方面翻盘是因为它学会了“先理解、再生成”。以 GAN 为核心的修复模型生成器拿到一张带 mask 的破损图先通过编码器提取全局特征再在缺失区域内部生成与上下文语义一致的内容。比如 DeepFillv2、EdgeConnect 这类模型生成的结果不仅有正确的颜色和纹理连物体的结构、边缘、光影关系都能猜个八九不离十。这个源码包里的模型大概率走的也是这条路线——要么是 U-Net 加 GAN 的判别器结构要么是引入注意力机制的改进版本。2.2 三种主流技术路线的选型取舍我在实际项目中评估过三类修复方案这里给出一个可以直接抄作业的对比表技术路线代表方案修复质量训练成本推理速度适合场景传统插值Telea / NS差仅细小区域无需训练毫秒级划痕、噪点CNN GANU-Net PatchGAN、DeepFillv2较好语义合理中单卡可训快人像、风景、老照片扩散模型RePaint、Stable Diffusion Inpainting最好细节丰富高需多卡或大显存慢迭代采样需要高质量填充的场景如果你手里的 zip 包注释里写了“支持人像修复”“去水印”这类关键词基本可以判定是 CNN GAN 路线。这类模型最大的优点是训练成本可控——一张 8GB 显存的消费级显卡就能跑起来而扩散模型动辄需要 16GB 以上显存或者靠 CPU 硬扛几百步采样速度让人崩溃。2.3 为什么 mask 的生成方式直接决定模型效果不管源码包里用的是哪种模型有一点是所有图像修复算法的共同命门训练时用的 mask损坏区域标记是怎么生成的。最常见的做法是随机生成不规则多边形、笔画或者矩形块把它们叠加在完整图像上模拟破损。但这里有个隐藏的坑如果训练数据和推理场景的 mask 分布不一致模型效果会大打折扣。比如你训练时用的全是小面积矩形 mask模型只见过 5% 区域的缺损部署时却要修复 50% 面积的破损生成结果会出现明显的“脏涂抹”现象。源码包的 data 目录里一般会有一个 mask 生成脚本我建议拿到包的第一件事不是跑训练而是仔细看这个脚本它生成了什么形状、什么尺寸分布、是否支持自定义 mask 输入。这一步能帮你省掉后面大量的反复训练时间。3. 把 zip 解压成可运行的工程环境搭建与目录结构解读3.1 Python 环境准备虚拟环境是后悔药这类深度学习源码包最怕的就是“直接往系统 Python 里装依赖”。不同项目的 torch、cuda、numpy 版本要求各不相同直接装会把环境搞得一团糟。我一般会为每个源码包单独建一个虚拟环境这样卸载重来都不心疼算是在环境配置上给自己留一颗后悔药。# 创建 Python 3.8 虚拟环境注意不是 conda纯 venv 足够 python -m venv inpaint_env # 激活虚拟环境 # Windows: inpaint_env\Scripts\activate # Linux / macOS: source inpaint_env/bin/activate # 确认环境内的 Python 版本 python --version pip --version逻辑说明venv 会在当前目录创建一个独立的 Python 环境所有通过 pip 安装的包都会放在 inpaint_env 目录下不会污染系统 Python。激活后终端提示符前面会出现(inpaint_env)字样看到它就知道当前处于虚拟环境内。参数说明Python 版本选择 3.8 是我经过多次踩坑后的折中选择——太老的版本3.6 以下不支持新版 torch太新的版本3.10又容易遇到某些老源码包编译时报错。如果你的源码包项目说明里写明了 Python 版本要求以说明为准。3.2 解压 zip 后应该先看这三个文件拿到“python源码项目说明.zip”先别急着跑。我会先把压缩包里的目录结构完整看一遍重点关注三个东西# 解压用 unzip 命令Windows 下用 7-Zip 或 WinRAR unzip python_source_inpaint.zip -d inpaint_project # 进入项目根目录 cd inpaint_project # 查看目录树Linux/macOS 用 tree没有就安装apt install tree 或 brew install tree tree -L 2逻辑说明unzip的解压参数和文件名的中文或空格兼容性不太好如果遇到解压失败可以先确认文件编码。Windows 上我见过很多 zip 包是 GBK 编码的目录名解压到 Linux 上会变成乱码用unzip -O gbk可以解决。解压后第一件事是找requirements.txt或environment.yml这是项目的依赖清单第二是找README.md或项目说明.pdf里面通常写了环境版本要求、数据集格式和训练命令第三是找config/或options/目录网络结构参数、训练参数都在这里。这三个文件决定了你后面的所有操作路径。如果项目说明和实际代码对不上——这太常见了比如说明里写了 CUDA 10.2代码里却是新版的 torch API——以代码为准说明文档只能当参考。3.3 依赖安装先把 torch 版本锁死大多数图像修复源码包的核心依赖就三件套torch、torchvision、opencv-python。但版本组合很有讲究。以我的经验先装 PyTorch 再装其他依赖可以避免 pip 自作主张把 torch 升级到不兼容版本。# 先安装 PyTorch以 CUDA 11.8 为例无 GPU 的机器装 CPU 版 pip install torch1.13.1cu117 torchvision0.14.1cu117 --extra-index-url https://download.pytorch.org/whl/cu117 # 再安装项目其余依赖 pip install -r requirements.txt # 验证安装结果 python -c import torch; print(torch.__version__, torch.cuda.is_available())逻辑说明先指定版本装 torch 是为了固定 CUDA 运行时版本后面requirements.txt里即使写了torch1.8pip 检测到已安装的 torch 满足条件就不会再动它。最后一行验证代码打印出 torch 版本号和 CUDA 是否可用如果输出True说明 GPU 可用False说明只能 CPU 跑。参数说明--extra-index-url指向 PyTorch 官方 wheel 源。如果你的机器没有 NVIDIA 显卡把 torch 换成torch1.13.1的 CPU 版即可但训练速度会慢 20 倍以上建议先用 CPU 跑通流程真正训练还是找个 GPU 云服务器。4. 跑通第一个 Demo从预训练权重到图像修复输出4.1 项目说明文档里通常藏着的预训练权重下载方式这类源码包一般不会把训练好的权重文件直接塞进 zip——因为一个模型文件动辄几百 MB压缩包会变得巨大。更常见的做法是项目说明文档里给出百度网盘或 Google Drive 链接或者让用户从 GitHub Releases 页面下载。我拿到包后会先在整个项目目录里搜一遍.pth、.ckpt、.pt后缀的文件如果有说明权重已被包含那可以直接跳到推理环节。如果没有找到预训练权重就需要从零开始训练。这里有一个重要的心态建设不要指望一上来就训练出和论文效果一样的模型。图像修复模型的训练需要精心调参没有几万步迭代不可能收敛。正确的路径是先下载能用的预训练权重 → 跑通 demo 验证整体流程 → 再微调训练。权重文件下载完成后放置位置也有讲究。我见过太多源码包代码默认路径是./checkpoints/model.pth但用户把权重放在了别的目录导致加载时报错。解决方法是去options/或config/里搜checkpoints或pretrained字段看看代码默认读哪个路径然后把权重放过去或者修改配置文件里的路径。4.2 推理脚本拆解mask、输入输出路径、关键参数假设这个源码包是常规的 CNN GAN 结构推理脚本一般长这样。我给出一个典型的骨架代码并逐行解释它在干什么# inference.py import torch import cv2 import numpy as np from models.network import InpaintModel def load_mask(mask_path): 读取 mask 文件二值化处理 mask cv2.imread(mask_path, cv2.IMREAD_GRAYSCALE) # 将所有非零像素统一为 255白色代表损坏区域 mask np.where(mask 10, 255, 0).astype(np.uint8) return mask def main(): # 配置参数 checkpoint_path checkpoints/epoch_100.pth image_path samples/input.jpg mask_path samples/mask.png output_path samples/output.jpg device torch.device(cuda if torch.cuda.is_available() else cpu) # 加载模型 model InpaintModel() state_dict torch.load(checkpoint_path, map_locationdevice) model.load_state_dict(state_dict) model.to(device) model.eval() # 读取输入 image cv2.imread(image_path) # BGR, HxWx3 mask load_mask(mask_path) # HxW # 归一化并转成网络输入格式 image_norm image.astype(np.float32) / 127.5 - 1.0 # 转 [-1, 1] mask_norm mask.astype(np.float32) / 255.0 # 转 [0, 1] # 拼接网络输入是 [原图 mask] 四通道 input_tensor np.concatenate([image_norm, mask_norm[:, :, None]], axis2) input_tensor torch.from_numpy(input_tensor.transpose(2, 0, 1))[None, :, :, :] input_tensor input_tensor.to(device) # 前向推理 with torch.no_grad(): output model(input_tensor) # 输出转回图像 output_image output[0].cpu().numpy().transpose(1, 2, 0) output_image (output_image 1.0) * 127.5 output_image np.clip(output_image, 0, 255).astype(np.uint8) # 保存结果 cv2.imwrite(output_path, output_image) print(fSaved to {output_path}) if __name__ __main__: main()逻辑说明这个推理脚本的核心是输入拼接。图像修复模型通常接受四通道输入——前三个通道是破损原图第四个通道是 mask 图mask 上白色1.0代表需要修复的区域黑色0.0代表保留区域。模型在内部通过 mask 把破损区域的特征“挖掉”再让生成器重新预测这些位置的特征值。torch.no_grad()会在推理时关闭梯度计算节省显存并提高速度。参数说明map_locationdevice是加载权重时最关键的参数——如果训练时用的是 GPU你的机器没有 GPU不加这个参数直接torch.load会报错加上它就能把权重映射到 CPU 上。/ 127.5 - 1.0这个归一化手法很常见目的是把像素值从[0, 255]映射到[-1, 1]这是 GAN 生成器常见的输入范围。如果输出图像颜色发暗或发灰多半是这个归一化和反归一化没有对齐。4.3 用自己的一张图片快速验证修复效果跑通脚本后找一张自己的真实图片去测试是最有成就感的时刻。我建议准备三样素材一张有划痕的老照片、一张带文字水印的截图、一张用程序随机挖掉一块区域的图片。这样能快速摸清模型的泛化边界# 把测试图片放到 samples 目录 cp ~/Desktop/old_photo.jpg samples/input.jpg cp ~/Desktop/mask.png samples/mask.png # 执行推理 python inference.py # 对比前后效果用系统自带图片查看器 open samples/output.jpg # macOS xdg-open samples/output.jpg # Linux如果输出结果看起来“糊了一坨”别急着怀疑模型有问题。先检查 maskmask 必须精确标记出损坏区域如果 mask 比实际损坏区域大很多模型会把周围完好的像素也一起重绘结果自然是模糊的。一个好习惯是用图像编辑工具按照损坏区域的轮廓精细涂抹 mask而不是随手画个大圆。验证输出后你基本就跑通了整个推理链路。到这一步这个 zip 包的核心价值你已经拿到手了——剩下的就是根据需求决定是继续微调训练还是直接用在业务场景里。5. 训练自己的修复模型数据准备和三个必调参数5.1 数据从哪里来开源数据集和自建数据集的取舍源码包里一般会说明训练数据的格式。图像修复任务的标准数据格式是“完整图 对应 mask”的配对形式完整图可以是任何自然图像mask 则标注了哪些区域被视为“损坏”。最常用的开源数据集包括 Places365、ImageNet 的子集以及专门为修复任务构建的异常遮挡数据集。如果你有自己的数据比如公司里的老照片存档、产品图库训练效果会比公开数据集好得多。但自建数据集有两个代价标注成本和时间成本。图像修复的“标注”不是画 bounding box而是为每张图生成对应的 mask。好在大部分源码包都提供自动 mask 生成脚本基于随机形状生成器就能批量产出训练对。# generate_masks.py import cv2 import numpy as np from random import randint, choice def generate_random_mask(height, width, max_ratio0.3): 生成随机不规则 mask mask np.zeros((height, width), dtypenp.uint8) num_shapes randint(2, 8) for _ in range(num_shapes): # 随机选择形状矩形、椭圆或折线描边 shape_type choice([rectangle, ellipse, stroke]) center_x, center_y randint(0, width), randint(0, height) w randint(20, int(width * max_ratio)) h randint(20, int(height * max_ratio)) if shape_type rectangle: cv2.rectangle(mask, (center_x, center_y), (min(center_xw, width), min(center_yh, height)), 255, -1) elif shape_type ellipse: cv2.ellipse(mask, (center_x, center_y), (w//2, h//2), 0, 0, 360, 255, -1) else: # 模拟划过一道的长条痕迹 pts np.array([[center_x, center_y], [center_xrandint(30,80), center_yrandint(-20,20)], [center_xrandint(60,120), center_yrandint(-10,10)]]) cv2.polylines(mask, [pts], False, 255, thicknessrandint(5, 20)) return mask逻辑说明这段代码生成的是训练时用的随机 mask。cv2.rectangle、cv2.ellipse、cv2.polylines分别生成矩形、椭圆和不规则线条三种损坏形状组合起来模拟真实世界的划痕、遮挡和水印。randint(2, 8)控制一张图上叠加几处损坏数值越大训练难度越高。参数说明max_ratio0.3是关键参数控制单块损坏区域占图像宽或高的最大比例。0.3 意味着损坏区域理论上最多占整张边界的 30%超过这个比例模型生成难度陡增。训练初期建议设为 0.2 以下等模型收敛稳定后再逐步提高到 0.4。如果你要修复的是大面积水印这个参数必须调大否则训练时模型根本没见过大块 mask。5.2 训练启动命令batch size、学习率、损失权重图像修复模型的训练目标不是简单地让输出图像接近原图而是要同时做到“内容合理”和“边界流畅”。因此损失函数往往由多项组成重建损失L1 或 L2保证像素级接近感知损失保证特征级语义一致对抗损失保证输出分布像真实图像。# 启动训练以单卡 GPU 为例 python train.py \ --data_root ./datasets/places256 \ --mask_root ./datasets/masks \ --batch_size 8 \ --lr 0.0002 \ --epochs 200 \ --save_interval 5 \ --lambda_rec 10.0 \ --lambda_adv 1.0 \ --lambda_perceptual 0.1逻辑说明train.py是源码包里的训练入口脚本。--data_root指向完整图像数据集目录--mask_root指向对应的 mask 目录两者一一对应。每轮训练迭代中模型从数据目录随机取一张图、从 mask 目录随机取一张 mask将 mask 叠加在图像上构造破损样本然后让生成器预测修复结果判别器判断“修复图和原图”哪个是真的。两个网络交替优化直到判别器分不出修复结果和真实图像的差别。参数说明--batch_size 8在 8GB 显存下是安全值如果显存报错就降到 4。--lr 0.0002是 GAN 训练的经典学习率比普通分类任务的 0.001 更低因为对抗训练对学习率极其敏感调大一点就容易震荡甚至崩溃。--lambda_rec 10.0是重建损失的权重这个值必须给得比较大否则生成器会只顾着骗过判别器而忽略了对原图的忠实度输出“漂移”的内容。5.3 训练过程中实时监控哪些指标图像修复不像分类任务有明确的 accuracy 可以看训练过程更像是在“猜”。我一般同时观察三个信号生成器损失值、判别器损失值、以及定时保存的验证集可视化结果。生成器损失G loss趋势是缓慢下降。如果这个值剧烈波动比如从 200 跳到 50000 再跳回 100大概率是学习率过高或判别器太强。判别器损失D loss理想状态是围绕一个恒定值小幅波动因为判别器在对抗中始终“略强于”生成器。如果 D loss 趋近于 0说明生成器已经完全不是对手图像质量会很差。可视化结果项目说明里一般会写“每 N 轮保存一组修复前后的对比图”。我习惯用--save_interval 5每 5 个 epoch 看一次效果。重点看修复区域的边缘是否与周围纹理自然衔接如果边界有明显锯齿或色块感说明模型过拟合到了训练 mask 的分布需要增加 mask 的随机性。6. 图像修复训练与推理的避坑手册我踩过六次以上的坑6.1 解压出来跑不起来路径里的中文名和空格现象Python 报错ModuleNotFoundError或FileNotFoundError但明明文件就在眼前。原因项目目录放在了带中文或空格的路径下比如C:\Users\张三\我的项目\inpaint或者压缩包本身的文件编码是 GBK解压在 Linux 上成了乱码目录名。源码包里有些脚本用相对路径硬编码了目录名路径一乱就找不到模块。解决把整个项目移动到一个纯英文、无空格的路径下比如/home/user/projects/inpaint或D:\inpaint。解压时如果文件名乱码Linux 上用unzip -O gbkWindows 上先用 7-Zip 解压到临时目录再改名。6.2 报错 OSError: [Errno 13] Permission denied现象训练脚本在写入 checkpoint 时突然报权限错误但同一个目录下其他文件能正常写。原因项目是从网盘下载的 zip 包解压后文件的 owner 和权限位可能不正确或者当前用户对目录没有写权限。解决在项目根目录执行chmod -R uw .和chown -R $(whoami) .把文件 owner 改回当前用户。Windows 上没这个问题Linux 上几乎是血泪教训——每次解压异地打包的 zip 都要习惯性补一条权限修复命令。6.3 CUDA out of memory显存不够不是玄学现象训练跑了几百步后突然报CUDA out of memory之前明明没问题。原因批量产生的数据显示单个 batch 里随机 mask 面积偏大时输入张量的有效计算区域变大中间特征图的显存占用可能骤增。另外torch 的缓存机制不会自动释放之前占用的显存如果你中途尝试过多次调试显存碎片堆积也会触发 OOM。解决先降 batch size。从 8 降到 4 再降到 2这是最直接的办法。如果还不行检查代码里是否有torch.cuda.empty_cache()的调用在验证步骤前加一行。终极办法是在训练脚本里加梯度累积# 梯度累积示例batch_size 2累积 4 步等效于 batch_size 8 accumulation_steps 4 optimizer.zero_grad() for i, (image, mask) in enumerate(dataloader): loss compute_loss(image, mask) loss loss / accumulation_steps # 平均梯度 loss.backward() if (i 1) % accumulation_steps 0: optimizer.step() optimizer.zero_grad()逻辑说明梯度累积的原理是每几个 mini-batch 才做一次参数更新等效增大了 batch size 但对显存要求不变。代码中loss loss / accumulation_steps是为了让梯度均值与等效大 batch 一致。注意 PyTorch 的优化器会在optimizer.step()之后再原地修改参数所以累加的是梯度不是 loss。6.4 修复结果颜色发灰发暗现象模型输出的图像整体偏暗像是上了一层灰色蒙版尤其是天空、白色墙面的区域颜色明显不对。原因训练数据的归一化方式和推理时的反归一化方式不匹配。大部分 GAN 模型使用[0, 1]或[-1, 1]归一化而 OpenCV 默认读取的图像是 BGR 顺序且值域为[0, 255]。如果推理脚本把图像值域缩放到[0, 1]后输入模型输出也是[0, 1]但保存时忘了乘回 255就会出现灰蒙蒙的效果。解决检查推理代码里是否包含反归一化要么在cv2.imwrite前乘以 255要么用torvision.utils.save_image这个工具函数。另外确认通道顺序OpenCV 是 BGRPyTorch tensor 是 RGB输出前需要cv2.cvtColor(output, cv2.COLOR_BGR2RGB)。6.5 训练 loss 震荡得像过山车现象生成器 loss 一会降一会升判别器 loss 直接打到 0 附近。原因学习率过大对抗失衡。判别器太强导致它迅速区分出真实图和生成图生成器梯度瞬间消失无法学到有效信息。反过来如果生成器太强判别器会一直无法收敛。解决把生成器和判别器的学习率分开设置生成器lr1e-4判别器lr4e-5让判别器“慢半拍”这是从不少开源项目里验证过的稳定组合。如果仍然震荡把训练计划的 betas 参数从默认的(0.9, 0.999)改成(0.5, 0.999)这个技巧能显著提升 GAN 训练的稳定性。6.6 项目说明文档和代码版本对不上现象项目说明写着“支持 Python 3.6”代码里却用了torch.utils.tensorboard这在 3.6 上装不上或者说明里写了训练命令是python train.py --gpu_ids 0实际代码的参数名却是--gpu。原因很多源码包是作者边写论文边发的时间跨度过大代码迭代了但说明文档没同步更新。尤其常见的是项目说明基于旧版 PyTorch 写的代码已经迁移到了新版 API。解决把项目说明当作辅助指南遇到报错时优先用python train.py --help查看当前代码实际支持的参数列表。--help是源码包自带的“讲真话的文档”它直接打印参数解析器里注册的所有可选参数、默认值和类型比任何说明文档都可靠。修改参数时同步更新说明文档也算是在给别人留下一颗后悔药。7. 进阶玩法用感知质量和推理速度两个维度评估修复效果跑通训练只是第一步真正决定这个项目能否落地的是修复质量的评估方法。PSNR 和 SSIM 虽然是论文里最常用的指标但在实际业务中未必准确反映人的主观感受。一张修复图 PSNR 28dB、SSIM 0.95看起来很漂亮但人眼可能一眼就看出五官畸形相反PSNR 只有 25dB 的图像人眼却觉得质量不俗。所以我现在评估修复效果的习惯是“三看”第一看边界连续性。把修复区域和原图边界的像素差值画成热力图如果边界处有厚厚的“接缝线”说明模型的边缘感知能力不足。第二看纹理一致性。用 LPIPSLearned Perceptual Image Patch Similarity指标它基于预训练网络提取的高层特征计算距离对纹理细节更敏感。第三看语义合理性。直接肉眼观察对人物、文字这类高语义敏感区域逐个检查——人脸的五官是否歪斜、文字的横竖撇捺是否连贯。在推理速度上如果要把模型部署到端侧设备TensorRT 或 ONNX Runtime 是绕不开的。常见做法是把训练好的 PyTorch 权重导出为 ONNX再用 TensorRT 做 INT8 量化推理速度能提升 3 到 5 倍。但这步的坑在于修复模型的输入是动态形状的因为 mask 大小不固定ONNX 导出时要把 input 的宽高固定或者显式声明动态轴否则部署时一遇到不同分辨率的图就崩。我个人的习惯是先固定推理分辨率比如统一缩放到 512×512 或 256×256再走导出流程等稳定了再研究动态形状的支持。如果你准备用这个项目长期做图像修复业务另一件值得投入的事是给你的模型构建一套“边界 case 测试集”。拿 100 张不同场景的图片在每张上故意挖不同比例、不同形状的 mask记录模型在每个样本上的修复效果按失败案例归因是 mask 形状没见过的泛化问题还是训练数据中该场景占比过少的欠拟合问题。有了这份记录后续微调训练才有的放矢而不是盲目加训练轮数碰运气。我自己处理这些源码包时有一个固定习惯拿到 zip 先解压到英文路径、看完--help、跑通推理 demo、再做训练。这套流程帮我避开了大半的翻车情况也省掉了大量 Google 报错的时间。希望这篇笔记能让你少走几趟弯路祝顺利。本文还有配套的精品资源点击获取
