老照片修复Python源码包部署指南：从环境搭建到参数调优

简介：基于深度学习实现的老照片修复项目，带可直接使用的Web交互页面，适合计算机、电子信息等专业学生作为课程设计、期末大作业或毕业设计参考。代码核心基于推理封装，通过简单命令即可启动本地服务，在网页上传破损或褪色照片，利用预训练模型完成划痕去除、色彩还原等操作。压缩包共20个文件，主要包括7个Python脚本、3个HTML模板、若干图片示例与说明文档，整体仅2.1MB，结构紧凑：Python脚本承担模型加载与图像处理逻辑，HTML页面提供前端交互入口，图片文件可用于效果对比，README则介绍使用方式。项目从上传到输出结果链路完整，适合需要快速搭建图像修复Demo或深入理解深度学习应用流程的学习者。目前已有306人学习下载，资源轻量易部署，适合在此基础上二次开发或替换自有模型，作为学习参考资料价值较高。

1. 老照片修复的 python 源码包：先分清它是“训练框架”还是“推理工具箱”

拿到一个名为“基于深度学习的老照片修复python源码（自带web页面超级简单）.zip”的压缩包，大多数人的第一反应是解压、双击、看到界面。实际接手这类项目时，你得先搞清楚它是用来“训练模型”还是“调用模型”的。标题里强调“自带web页面”，说明作者已经把推理流程封装成了可视化工具，我们只需要把它跑起来，而不是重新训练一个深度神经网络。这个定位一旦确认，后续的依赖安装、参数调整和排错方向就完全不同了。

这类老照片修复项目，核心是把划痕、噪点、褪色、低分辨率这类退化问题，交给一个预训练好的深度神经网络去还原。常见做法是借用超分辨率或图像复原领域的开源模型，比如 Real-ESGAN、GFPGAN、SwinIR 这类结构，再套一层 web 界面。源码包里大概率有模型权重文件、Python 推理脚本、依赖清单和web应用入口。本文的目标只有一个：让这套源码在你的机器上顺利跑起来，并且告诉你哪些参数值得调、哪些坑必须避开。我会从拆包、环境搭建、启动页面、核心链路到接口化改造，按实际动手顺序讲完。

2. 拆包与首次运行：跑通自带 Web 页面之前，先搞懂这三层文件结构

2.1 压缩包里常见的目录长什么样，哪些文件决定能不能启动

解压 zip 后，先别急着执行任何命令。用文件管理器或者tree命令扫一眼目录结构，心里就有数了。通常这个压缩包解压出来会是这样的布局：

photo_restore/ ├── app.py # Web 入口，一般是 Flask 或 Gradio ├── requirements.txt # Python 依赖清单 ├── models/ # 预训练权重存放目录 │ ├── restore_model.pth │ └── face_enhance.pth ├── utils/ │ ├── __init__.py │ ├── image_io.py # 图片读取、缩放、保存 │ └── inference.py # 推理封装，调用模型 ├── static/ # 如果 app.py 用的是 Flask，这里放前端资源 │ ├── css/ │ └── js/ ├── templates/ # Flask 的 HTML 模板 │ └── index.html ├── uploads/ # 临时存放用户上传的图片 └── results/ # 修复结果输出目录

# 在 Linux / macOS 终端查看目录树 tree -L 2 photo_restore

逻辑说明：app.py是入口，它决定了你访问本地页面时看到什么；requirements.txt是环境基础，缺一个依赖都可能让模型跑不起来；models目录里的权重文件是核心资产，没有它们代码只是空壳。参数说明：-L 2表示只显示两层目录，够用；如果tree命令不存在，用find photo_restore -maxdepth 2 -type f代替。

很多下载包会把权重文件单独放在网盘或者模型站里，zip 里只留下空目录和 download 脚本。看到models/*.pth文件大小只有几 KB，那很可能是占位文件，真实权重需要手动下载。这种情况并不算翻车，但要先确认权重文件与代码匹配，否则修复效果会非常玄学——模型张量维度对不上，直接报错。

2.2 建立虚拟环境：Python 版本与依赖安装的兼容性检查

我一般建议用虚拟环境隔离依赖，避免把系统 Python 环境搞乱。清晰的第一步是检查 Python 版本，再创建虚拟环境并激活。

# 检查 Python 版本，推荐 3.8 ~ 3.10 python --version # 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Windows PowerShell: venv\Scripts\Activate.ps1 # Linux / macOS: source venv/bin/activate

逻辑说明：深度学习推理代码大量使用 PyTorch 和 NumPy，这两个库对新老 Python 版本的支持差异很大。Python 3.12 刚发布时，很多老版本 PyTorch 还没有对应的预编译轮子，很容易安装失败。参数说明：虚拟环境名venv可随你改动，但记得把它写进.gitignore，否则在版本管理时会不分青红皂白地包含几百 MB 的库文件。激活成功后，终端提示符前面会出现(venv)字样，这是后面安装依赖的前提。

接下来安装依赖。源码包里的requirements.txt有直接的版本约束，这是第一选择；如果里面没有任何约束，则按这个组合安装：

pip install --upgrade pip pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install opencv-python numpy Pillow flask gradio

逻辑说明：--index-url指定 PyTorch 官方源，这是为了避免在默认 PyPI 源上拉错 CPU 版或者版本不兼容的轮子。cu118对应 CUDA 11.8，如果你用的是 NVIDIA 显卡且驱动较新，这套组合很稳定。没有 NVIDIA 显卡的话，把--index-url去掉，默认安装 CPU 版即可，但推理速度会慢一个数量级。参数说明：opencv-python用来自动解码各种图片格式；flask和gradio都是 web 框架，具体用哪个取决于源码app.py的 import 语句。如果你发现安装torch时提示内存不足，可以换成pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu，牺牲性能换稳定。

2.3 启动 Flask 版还是 Gradio 版：自带 Web 页面的两种入口写法

这部分是要害。自带 web 页面有两种主流形态，源码里只有一种，识别错了会白折腾。

第一种是 Flask 版。app.py里通常长这样：

from flask import Flask, render_template, request, send_from_directory import os from utils.inference import restore_image app = Flask(__name__) UPLOAD_FOLDER = "uploads" RESULT_FOLDER = "results" os.makedirs(UPLOAD_FOLDER, exist_ok=True) os.makedirs(RESULT_FOLDER, exist_ok=True) @app.route("/", methods=["GET", "POST"]) def index(): if request.method == "POST": file = request.files.get("image") if file and file.filename: input_path = os.path.join(UPLOAD_FOLDER, file.filename) output_path = os.path.join(RESULT_FOLDER, "restored_" + file.filename) file.save(input_path) restore_image(input_path, output_path) return send_from_directory(RESULT_FOLDER, "restored_" + file.filename) return render_template("index.html") if __name__ == "__main__": app.run(host="0.0.0.0", port=5000, debug=True)

逻辑说明：GET请求返回上传页面，POST请求处理图片上传并调用restore_image。restore_image里面封装了模型的加载和推理，对 web 层来说就是一个黑匣子。参数说明：host="0.0.0.0"表示允许局域网内其他机器访问，如果只在本机调试，改成host="127.0.0.1"更安全；debug=True便于开发时热重载，但公网部署时必须设为False，否则攻击者可能通过调试器执行任意代码。

第二种是 Gradio 版，app.py会像这样写：

import gradio as gr from utils.inference import restore_image demo = gr.Interface( fn=restore_image, inputs=gr.Image(type="filepath", label="上传老照片"), outputs=gr.Image(type="filepath", label="修复结果"), title="老照片修复" ) if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=False)

逻辑说明：Gradio 把前后端都封装好了，inputs定义上传控件，outputs定义结果展示，fn传入的是推理函数。它比 Flask 省事太多，适合只想快速验证效果的场景。参数说明：share=False表示不生成公网链接，只在本地访问；有的人习惯设置share=True来临时分享给外网用户，但这个动作会通过第三方服务器转发流量，项目数据会经过中间链路，需要注意数据安全边界。我自己的做法是：内部演示用share=False，着急远程看效果时才临时开share=True，用完立刻关。

2.4 最小烟雾测试：几分钟后能否访问 localhost

依赖装好、入口确认后，执行启动命令：

# 在项目根目录，确保虚拟环境已激活 python app.py

如果看到类似Running on http://127.0.0.1:5000的输出，说明 web 服务器已经起来了。接下来打开浏览器，访问http://127.0.0.1:5000。页面里能正常上传图片并返回修复结果，就算整套链路打通了。这一步的重点不是功能多完整，而是确认模型加载、图像读写、web 路由三个环节都没断。如果页面显示 500 错误，回到终端看堆栈信息，绝大部分问题都出在模型加载或依赖缺失上，后面第四章专门讲坑。

3. 核心修复链路：深度学习模型如何去掉划痕和噪点，参数应该怎么调

3.1 灰度图与彩色图的修复差异，以及代码里的通道处理逻辑

老照片修复程序拿到的输入图片不一定是干净的 RGB 三通道图。有的老照片是灰度扫描件，有的虽然是彩色但已经严重偏色，还有的带着白色边框和撕裂痕迹。代码里通常先用 OpenCV 做预处理，核心操作是通道归一化和尺寸对齐。

import cv2 import numpy as np def preprocess_image(image_path, target_size=512): img = cv2.imread(image_path) if img is None: raise ValueError(f"无法读取图片: {image_path}") # 如果是灰度图，转成三通道，保持模型输入形态一致 if len(img.shape) == 2: img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR) h, w = img.shape[:2] # 按长边缩放，保持宽高比，短边用边缘填充 scale = target_size / max(h, w) new_h, new_w = int(h * scale), int(w * scale) img = cv2.resize(img, (new_w, new_h), interpolation=cv2.INTER_LINEAR) top = (target_size - new_h) // 2 bottom = target_size - new_h - top left = (target_size - new_w) // 2 right = target_size - new_w - left img = cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=(0, 0, 0)) # 转为 RGB，并归一化到 [0, 1] img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img_rgb = img_rgb.astype(np.float32) / 255.0 # PyTorch 模型输入是 [N, C, H, W]，这里补一个 batch 维度 tensor = np.transpose(img_rgb, (2, 0, 1))[None, ...] return tensor, (new_h, new_w), (top, bottom, left, right)

逻辑说明：模型训练时通常固定输入尺寸，执行时不满足就缩放加填充。这里的target_size=512是常见预设值，更大尺寸能保留细节但显存占用更高。灰度图转三通道是为了让模型输入张量固定为[1, 3, 512, 512]，避免个别模型只接受单通道导致维度报错。参数说明：BORDER_CONSTANT用黑色像素填充边缘，修复完成后要按(top, bottom, left, right)把填充部分裁掉，否则输出图四周会出现黑边，这也是很多新手在调用修复结果时容易忽视的一个细节。

3.2 三个必调参数：修复强度、去噪阈值、人脸增强开关

推理函数内部，模型权重加载后通常有三个参数值得动，它们的含义直接影响修复风格。我以最常见的封装方式为例，把它写成可配置的：

def restore_image( input_path, output_path, model_path="models/restore_model.pth", denoise_strength=0.5, face_enhance=True, tile_size=512, ):

逻辑说明：denoise_strength控制模型对噪点和划痕的抑制力度，取值范围一般是 0 到 1。设太大，画面会变得过度平滑，人物皮肤像塑料；设太小，背景里的颗粒感和划痕残留明显。face_enhance控制是否启用专门的人脸增强分支，老照片里若有合影，这个分支能改善五官清晰度，但也会在极端角度下产生五官畸变。tile_size控制分块推理的边长，高分辨率大图要靠它切块处理，否则显存直接爆掉。

参数调整没有固定公式，我的经验是：先固定tile_size=512，把denoise_strength在 0.3、0.5、0.7 三个值各跑一遍，选视觉上折中的结果。人脸特写照片就把face_enhance=True打开；如果照片里只有远距离风景，打开人脸增强反而会引入多余的纹理，这时候关掉更稳妥。代码层面，可以在 web 页面里暴露这些参数，让使用者自己滑动设置，这也是很多“超级简单”版本里常见的做法——它只是把推理封装得更好看，底层原理还是这一套。

3.3 改模型路径和默认参数，实际上改的是哪几行代码

真正动手改源码，不建议在推理函数内部直接硬编码写死路径。我会把配置单独抽出来，避免用户以后换模型时到处翻代码。

# config.py MODEL_PATH = "models/restore_model.pth" FACE_MODEL_PATH = "models/face_enhance.pth" DENOISE_STRENGTH = 0.5 USE_FACE_ENHANCE = True TILE_SIZE = 512 DEVICE = "cuda" # 没有 NVIDIA GPU 时改成 "cpu"

# utils/inference.py 中加载模型的片段 import torch from config import MODEL_PATH, FACE_MODEL_PATH, DEVICE def load_models(): restore_net = torch.load(MODEL_PATH, map_location=DEVICE) restore_net.eval() if USE_FACE_ENHANCE: face_net = torch.load(FACE_MODEL_PATH, map_location=DEVICE) face_net.eval() return restore_net, face_net return restore_net, None

逻辑说明：把路径和参数集中放在config.py，改配置时不必动业务代码。torch.load的map_location参数决定了权重加载到 CPU 还是 GPU。很多报错的根源就是这台机器没有 CUDA 设备，但模型默认加载到了cuda:0，加了map_location后它会自动做设备映射。参数说明：eval()必须调用，它把模型切到推理模式，关闭 dropout 层和 batch normalization 的统计值更新。漏掉这一步，同一张照片每次跑出来的结果可能会有微小差异，虽然不至于完全崩坏，但在对比效果时会发现数值不稳定。

4. 避坑排查专题：依赖包冲突、内存不足、模型下载失败的三类高频问题

4.1 现象：提示torch.cuda.OutOfMemoryError，批处理到一半进程直接崩溃

原因：显存被中间计算过程占满，尤其是高分辨率图片直接整图放大，模型注意力机制会把中间特征图体积撑得很大。解决：把tile_size从 512 降到 256，或者放弃整图推理，改用按块推理再拼接。常见做法是在推理循环里写一个滑动窗口，重叠区域做线性融合，避免拼接处出现接缝。

def restore_tiled(model, tensor, tile=512, overlap=32): _, _, h, w = tensor.shape out = torch.zeros_like(tensor) count = torch.zeros_like(tensor) stride = tile - overlap for y in range(0, h, stride): for x in range(0, w, stride): y_end = min(y + tile, h) x_end = min(x + tile, w) patch = tensor[:, :, y:y_end, x:x_end] with torch.no_grad(): result = model(patch) out[:, :, y:y_end, x:x_end] += result count[:, :, y:y_end, x:x_end] += 1 return out / count

逻辑说明：这种做法把一张大图切成多个重叠小图，逐块推理后累加再取平均。重叠区的像素被重复推理了两次，除以计数后完成平滑过渡。参数说明：overlap=32是常用值，太小会导致拼接边界明显，太大会增加计算量。我用这种方法在 8GB 显存的显卡上处理 4000x3000 像素的图片，能稳定跑完不翻车。

4.2 现象：模型加载时报结构错误，提示state_dict里的 key 对不上

原因：模型权重和代码里的网络定义不是同一个版本。网上很多修复模型权重不止一版，训练时用了不同的 backbone，保存的字典 key 名字自然不同。解决：先打印权重文件的 key，和网络定义的 key 做对比，而不是盲目改代码去匹配。

checkpoint = torch.load("models/restore_model.pth", map_location="cpu") print(list(checkpoint.keys())[:20]) if "state_dict" in checkpoint: state_dict = checkpoint["state_dict"] else: state_dict = checkpoint model.load_state_dict(state_dict, strict=False)

逻辑说明：strict=False允许缺失或多余的 key，这样至少能加载出相同名称的层。参数说明：如果打印出来的 key 和网络定义明显不像，比如权重里是一层module.backbone.0.weight，而网络定义里没有module前缀，可以在加载前加一个strip_prefix操作，把module.去掉。这个改法很常见，很多用DataParallel训练出来保存的权重都有这个前缀问题。

4.3 现象：zip 解压后没有模型文件，运行时自动下载模型却超时失败

原因：很多开源项目为了减小 zip 体积，不内置权重文件，而是让程序第一次运行的时候从网上下载。如果你的网络到下载源的路由不通或者太慢，训练权重拉不下来，程序就会卡在初始化阶段或者直接报DownloadException。解决：手动去模型托管平台把对应权重下载好，放到models/目录里。关键在于确定文件名和哈希，避免下到损坏文件。

# 校验下载文件的完整性，确保与源码 README 中标注的 SHA256 一致 sha256sum models/restore_model.pth

逻辑说明：校验哈希能排除下载被截断的情况；如果发现哈希不一致，优先换个网络再下载，而不是强行加载半截文件。参数说明：对于老照片修复项目的模型，文件名可能是restore_model.pth、face_enhance.pth、modern.pth这类，实际以源码里torch.load的路径为准。如果手头有 Linux 环境，用wget -c支持断点续传是更稳妥的办法；Windows 下可以用支持断点续传的下载工具，避免下载到一半断掉。

4.4 现象：CPU 机器上推理耗时特别长，一张照片几分钟都没出结果

原因：深度学习修复模型动辄上亿参数，CPU 并行能力有限，整图推理慢是正常现象。解决：调低tile_size并开启torch.set_num_threads，让 CPU 有限的多核心忙起来而不是被频繁的线程切换拖慢。

import torch torch.set_num_threads(4) # 按 CPU 核心数调整

逻辑说明：这个设置会把 PyTorch 的线程池限制在 4 个线程。设置太小浪费多核性能，设置太大又可能因超线程竞争反而变慢。参数说明：在设备管理器里确认逻辑核心数后，取一半作为线程数往往比较合理。另外，把输入尺寸从 1024 降到 512，虽然会丢失部分细节，但速度提升不止四倍。如果你的目的是快速验证修复效果，先用低分辨率跑通，确认满意后再放大输出。

4.5 现象：web 页面能打开，但上传图片后报cv2.error: OpenCV(4.x) ...

原因：OpenCV 版本与图像解码库冲突，最常见的是libpng或libjpeg版本不兼容。解决：先升级 pip 基础工具，然后强制安装与当前平台匹配的 OpenCV 版本，并且在代码里加上图片读取失败后的日志输出。

import cv2 print(cv2.__version__)

pip install opencv-python-headless==4.8.1.78

逻辑说明：opencv-python-headless不依赖 GUI 相关的动态库，在服务器和容器环境里更稳定，跟 Flask/Gradio 这类 web 服务搭配使用很顺手。参数说明：版本号可以按需调整，但不要直接装最新版而不看兼容性；我遇到过4.9.0在旧版 glibc 的 Linux 上无法加载的情况，退回4.8系列就正常了。这个问题在当前项目里算是高频，十次里有三次是它引起的。

5. 进阶用法：把修复源码改造成本地 HTTP 服务，并用 PSNR 和 SSIM 验证效果

5.1 从if __name__ == "__main__"开始，让修复接口服务化

web 页面适合人工操作，但你要是想批量处理几十张照片，或者把修复能力嵌进自己的工具链，就需要一个不带页面的 HTTP 接口。改造思路很直接：复用已有的restore_image函数，用 Flask 开一个 API 端口，接收图片文件、返回修复结果。

# api.py from flask import Flask, request, send_file import os import tempfile from utils.inference import restore_image app = Flask(__name__) @app.route("/restore", methods=["POST"]) def restore(): file = request.files.get("image") if file is None: return {"error": "missing image"}, 400 tmp_dir = tempfile.mkdtemp() input_path = os.path.join(tmp_dir, "input.jpg") output_path = os.path.join(tmp_dir, "output.jpg") file.save(input_path) try: restore_image(input_path, output_path) return send_file(output_path, mimetype="image/jpeg") except Exception as e: return {"error": str(e)}, 500 finally: # 这里不立即清理，否则 send_file 可能读不到文件 pass if __name__ == "__main__": app.run(host="0.0.0.0", port=8080)

逻辑说明：tempfile.mkdtemp为每个请求创建独立临时目录，避免并发时文件名冲突。注释里提到不能立即清理临时文件，原因是send_file在响应发送完成前需要读取磁盘文件；若追求严格清理，可以改用after_request钩子延迟删除。参数说明：接口路径/restore和端口8080都可以自由改，但它需要和项目里的app.py端口区分开，避免两个服务抢同一个端口。

用命令行实测一下接口是否工作：

curl -X POST http://127.0.0.1:8080/restore \ -F "image=@old_photo.jpg" \ -o restored.jpg

逻辑说明：-F表示以表单形式提交文件字段，字段名image必须和代码里request.files.get("image")对应。参数说明：-o restored.jpg把响应体写入本地文件，而不是打印到终端。如果你测试时返回 400，先检查字段名是否一致；返回 500，回到服务端看堆栈，很多问题在图片解码阶段就崩了。这个接口化改造最大的价值是解耦前端页面与推理逻辑，后续加批量处理、加队列、接其他系统都非常顺手。

5.2 评估修复效果：SSIM、PSNR 和文件大小，哪个指标能说明“修好了”

主观感受容易骗人，尤其是处理强噪声图片时，模型可能把纹理抹平了，看起来干净却丢失了细节。我用三个量化指标来把关。

import cv2 import numpy as np def calculate_metrics(original, restored): """original 和 restored 是同一尺寸的 RGB 图像数组且取值范围为 [0, 255]""" original_gray = cv2.cvtColor(original, cv2.COLOR_RGB2GRAY) restored_gray = cv2.cvtColor(restored, cv2.COLOR_RGB2GRAY) psnr = cv2.PSNR(original_gray, restored_gray) ssim = 0.0 # 计算每个通道的 SSIM，然后取平均，人眼对亮度通道变化最敏感 for i in range(3): ssim += cv2.compareSSIM(original[:, :, i], restored[:, :, i]) ssim /= 3.0 return psnr, ssim

逻辑说明：cv2.PSNR在两张图一致时返回无穷大，常见实现会用float('inf')处理，实际项目中打印时需要注意。SSIM 的计算有很多版本，OpenCV 自带的接口能覆盖大多数场景。参数说明：在对比时，一定要确保修复图和原图尺寸完全一致，否则指标没有意义；很多修复算法会输出放大后的图像，比如 512x512 变 1024x1024，这时要先做降采样或裁剪再计算指标。我通常还会保存修复前后的缩略图放在同一张画布里，用视觉检查代写结论，防止指标高但观感差的情况。

5.3 把修复工作流变成定时任务，批量跑完一个文件夹

对于一堆扫描件，手动一张张上传太原始。我习惯在 API 服务之外再备一个命令行脚本，通过遍历目录批量处理，输出路径自动生成。这样既不用起 web 服务，也能复用同一个推理函数。

# 批量处理照片，输出到 output_dir 目录 python batch_restore.py input_dir output_dir

# batch_restore.py import argparse import os import glob from utils.inference import restore_image def main(): parser = argparse.ArgumentParser() parser.add_argument("input_dir") parser.add_argument("output_dir") args = parser.parse_args() os.makedirs(args.output_dir, exist_ok=True) for ext in ("*.jpg", "*.png", "*.jpeg", "*.bmp"): for path in glob.glob(os.path.join(args.input_dir, ext)): out_path = os.path.join(args.output_dir, "restored_" + os.path.basename(path)) restore_image(path, out_path) print(f"完成: {path} -> {out_path}") if __name__ == "__main__": main()

逻辑说明：glob按扩展名收集文件，避免一个不存在的*.jpeg把程序拖垮。argparse解析命令参数，比在代码里硬编码路径更灵活。参数说明：输出文件名加了restored_前缀，防止覆盖原图；如果你在 Windows 下跑，记得路径别带中文空格，否则编码问题可能让cv2.imread读取失败。这个脚本做批量验证特别实用，修复完一个文件夹，再运行上一小节的指标脚本，整体效果一目了然。

最后说点我的工作习惯：每次调试这类源码包，我都会先把config.py里的路径和参数固定下来，再动业务逻辑；遇到环境问题优先看 stack trace 里第一个 TypeError 或者 ImportError，而不是满屏搜索。希望这篇笔记能帮你把这个“超级简单”的 web 修复项目平稳落地，少走几个我当年踩过的坑。

本文还有配套的精品资源，点击获取