GPEN+Gradio快速搭建Web界面：在线修图工具开发教程
1. 镜像环境说明
本镜像基于GPEN人像修复增强模型构建，预装了完整的深度学习开发环境，集成了推理及评估所需的所有依赖，开箱即用。适用于人脸超分、老照片修复、低质量图像增强等场景，特别适合需要快速部署和测试的开发者。
| 组件 | 版本 |
|---|---|
| 核心框架 | PyTorch 2.5.0 |
| CUDA 版本 | 12.4 |
| Python 版本 | 3.11 |
| 推理代码位置 | /root/GPEN |
主要依赖库：-facexlib: 用于人脸检测与对齐 -basicsr: 基础超分框架支持 -opencv-python,numpy<2.0,datasets==2.21.0,pyarrow==12.0.1-sortedcontainers,addict,yapf
该环境已配置好所有必要组件，用户无需手动安装依赖即可直接运行推理或进行二次开发。
2. 快速上手
2.1 激活环境
在使用前，请先激活预设的 Conda 环境：
conda activate torch25此环境包含 PyTorch 2.5.0 及相关 CUDA 支持，确保 GPU 加速推理正常运行。
2.2 模型推理 (Inference)
进入项目主目录并执行推理脚本：
cd /root/GPEN场景 1：运行默认测试图
python inference_gpen.py该命令将处理内置测试图像Solvay_conference_1927.jpg，输出结果为output_Solvay_conference_1927.png。
场景 2：修复自定义图片
python inference_gpen.py --input ./my_photo.jpg替换my_photo.jpg为你的输入路径，输出文件将自动命名为output_my_photo.jpg。
场景 3：指定输入输出文件名
python inference_gpen.py -i test.jpg -o custom_name.png通过-i和-o参数可灵活控制输入输出路径。
注意：所有推理结果将保存在项目根目录下，建议提前确认图片路径权限。
3. 已包含权重文件
为保障离线可用性和启动效率，镜像中已预下载并缓存以下关键模型权重：
- ModelScope 缓存路径：
~/.cache/modelscope/hub/iic/cv_gpen_image-portrait-enhancement - 包含内容：
- 预训练生成器（Generator）
- 人脸检测器（Face Detection Model）
- 人脸对齐模块（Face Alignment Model）
若首次运行未找到本地权重，系统会自动从 ModelScope 下载至上述路径。后续调用无需重复下载，提升部署效率。
4. 使用 Gradio 构建 Web 交互界面
虽然原生脚本支持命令行推理，但为了实现更友好的用户体验，我们推荐使用 Gradio 快速构建一个可视化 Web 应用，让用户上传图片并实时查看修复效果。
4.1 安装 Gradio
确保当前环境中安装了 Gradio：
pip install gradio4.2 编写 Web 接口代码
创建一个新的 Python 文件app.py，内容如下：
import os import cv2 import numpy as np import gradio as gr from basicsr.utils import img2tensor, tensor2img from facexlib.utils.face_restoration_helper import FaceRestoreHelper from GPEN_model import GPENModel # 假设模型类位于此处 # 初始化模型 def load_model(): model = GPENModel() face_helper = FaceRestoreHelper( upscale_factor=2, face_size=512, crop_ratio=(1, 1), det_model='retinaface_resnet50', save_ext='png', use_parse=True ) return model, face_helper model, face_helper = load_model() def enhance_image(input_img): """接收输入图像，返回修复后的图像""" if input_img is None: return None # 转换为 RGB（Gradio 输出为 BGR） bgr_input = cv2.cvtColor(np.array(input_img), cv2.COLOR_RGB2BGR) # 预处理 face_helper.clean_all() face_helper.read_image(bgr_input) face_helper.get_face_landmarks_5(only_center_face=True) face_helper.align_warp_face() # 单张人脸处理 for cropped_face in face_helper.cropped_faces: # 转为张量 cropped_tensor = img2tensor(cropped_face / 255., bgr2rgb=True, float32=True) normalized = (cropped_tensor - 0.5) * 2 restored_face = model.enhance(normalized.unsqueeze(0))[0] # 反归一化 & 转回图像 restored_face = (restored_face.clamp(-1, 1) + 1) / 2 restored_face = tensor2img(restored_face, rgb2bgr=True, min_max=(0, 1)) # 后处理融合 restored_face = np.clip(restored_face, 0, 255).astype('uint8') face_helper.add_restored_face(restored_face) # 合成最终图像 face_helper.get_inverse_affine(None) output = face_helper.paste_faces_to_input_image() output_rgb = cv2.cvtColor(output, cv2.COLOR_BGR2RGB) return output_rgb # 构建 Gradio 界面 with gr.Blocks(title="GPEN 在线人像修复") as demo: gr.Markdown("# 🖼️ GPEN 人像修复增强工具") gr.Markdown("上传一张模糊或低质的人脸照片，体验高质量修复效果！") with gr.Row(): with gr.Column(): input_image = gr.Image(type="pil", label="原始图像") submit_btn = gr.Button("开始修复", variant="primary") with gr.Column(): output_image = gr.Image(type="numpy", label="修复结果") examples = gr.Examples( examples=[ "./test_images/old_photo_1.jpg", "./test_images/lowres_face.png" ], inputs=input_image ) submit_btn.click(fn=enhance_image, inputs=input_image, outputs=output_image) # 启动服务 if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=True)说明：以上代码假设
GPENModel类已封装好推理逻辑。如需适配原始仓库结构，可参考其inference_gpen.py中的模型加载方式。
4.3 运行 Web 应用
保存后执行：
python app.py应用将在http://0.0.0.0:7860启动，并可通过内网穿透或公网 IP 访问。share=True参数可生成临时外网链接（基于 Gradio Tunnel）。
5. 实践优化建议
5.1 性能调优
- 批量处理：若需支持多图并发，建议启用
batch_size > 1并合理设置显存占用。 - 分辨率选择：优先使用
512x512输入尺寸，过高分辨率可能导致 OOM。 - 缓存机制：对于频繁访问的用户，可在前端加入结果缓存策略。
5.2 用户体验改进
- 添加进度条反馈（Gradio
gr.Progress()） - 支持拖拽上传、裁剪预览
- 输出对比图（side-by-side before/after）
示例对比展示代码片段：
with gr.Row(): gr.Image(value="input.jpg", label="原始图像") gr.Image(value="output.jpg", label="修复结果")5.3 安全与部署
- 关闭
share=True生产环境暴露风险 - 使用 Nginx + Gunicorn + HTTPS 进行生产级部署
- 对上传文件做类型校验（
.jpg,.png），防止恶意注入
6. 常见问题
数据集准备：官方训练基于 FFHQ 数据集。由于 GPEN 采用监督学习范式，需准备高质量-低质量图像对。推荐使用 RealESRGAN 或 BSRGAN 对高清图像降质生成低质样本。
训练流程：提供训练数据路径后，设置目标分辨率（建议 512x512）、调整生成器与判别器学习率（初始值
1e-4）、设定总 epoch 数（通常 100~200），即可开始训练。显存不足：若出现 CUDA Out of Memory，尝试降低 batch size 至 1 或启用梯度检查点（gradient checkpointing）。
人脸错位：确保
facexlib正确安装且检测模型加载成功；可尝试更换det_model参数。
7. 参考资料
- 官方 GitHub 仓库：yangxy/GPEN
- ModelScope 模型页面：iic/cv_gpen_image-portrait-enhancement
- Gradio 官方文档：https://www.gradio.app/docs
8. 引用 (Citation)
@inproceedings{yang2021gpen, title={GAN-Prior Based Null-Space Learning for Consistent Super-Resolution}, author={Yang, Tao and Ren, Peiran and Xie, Xuansong and Zhang, Lei}, booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)}, year={2021} }获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
