imaginAIry 图像超分辨率放大指南：Python API 与 `aimg upscale` 命令全解析

AI 应用媒体生成【免费下载链接】imaginAIryPythonic AI generation of images and videos项目地址https://gitcode.com/gh_mirrors/im/imaginAIry点击查看免费下载导读本文围绕 imaginAIry 的 Python APIimaginairy.api.upscale.upscale_image及其对应的 CLI 命令aimg upscale系统讲解如何在 AI 图像生成工作流中完成图片的超分辨率放大。你将掌握如何通过 Python 代码或命令行放大本地图片、远程 URL 图片与 PIL Image 对象如何切换 RealESRGAN / ESRGAN / HAT 等不同放大模型以及如何利用分块tiling、多次放大repetition与可选的人脸修复功能获得更高质量的放大结果。一、API 速览upscale_image函数签名关联文档 docs/docs/Python/upscale.md 以 mkdocstrings 指令引用了imaginairy.api.upscale.upscale_image该函数的完整签名与 docstring 定义在 imaginairy/api/upscale.pydef upscale_image( img: Union[LazyLoadingImage, Image.Image, str], upscale_model: str DEFAULT_UPSCALE_MODEL, tile_size: int 512, tile_pad: int 50, repetition: int 1, deviceNone, ) - Image.Image:参数类型默认值说明imgLazyLoadingImage \| Image.Image \| str必填输入图片支持LazyLoadingImage实例、PILImage对象或字符串https://开头的 URL 或本地文件路径upscale_modelstrrealesrgan-x2-plus使用的放大模型名称见下文模型库也可以直接传模型文件的 HTTP 下载地址或本地路径tile_sizeint512分块处理时每块tile的边长设为0表示不分块整图一次性送入模型tile_padint50每块四周的额外填充像素用于消除块与块之间的接缝伪影repetitionint1放大重复次数1 时以前一次放大结果为输入再次放大device设备对象None计算设备CPU/GPU为None时自动选择当前可用设备默认模型常量定义于 imaginairy/config.pyDEFAULT_UPSCALE_MODEL realesrgan-x2-plus。该 API 是纯封装层它会先把各种输入形式统一转换为LazyLoadingImage字符串 URL 走LazyLoadingImage(url...)文件路径走LazyLoadingImage(filepath...)PIL 图走LazyLoadingImage(img...)再委托给 imaginairy/enhancers/upscale.py 中的同名核心实现完成实际放大最终返回 PILImage对象。二、支持的放大模型库核心实现 imaginairy/enhancers/upscale.py 中定义了upscale_model_lookup字典即内置模型清单首次使用时按需自动下载并缓存模型键名架构放大倍率说明ultrasharpRealESRGAN 变体4x-UltraSharp4x侧重观感锐化的社区模型权重realesrgan-x4-plusRealESRGAN4x官方 x4 通用放大模型默认 CLI 帮助文本中的4x即指此类realesrgan-x2-plusRealESRGAN2x官方 x2 放大模型也是全局默认模型esrgan-x4ESRGAN4x经典 ESRGAN SRx4 权重real-hatHAT4x基于 Transformer 的 HAT GAN 模型real-hat-sharperHAT4xHAT 锐化增强版权重4xNomos8kHAT-LHAT4x面向 8K 输出的 HAT-L 大模型权重除了使用上述键名upscale_model还支持两种灵活传参方式见 imaginairy/enhancers/upscale.py 的解析逻辑直接传模型文件的 HTTP/HTTPS 下载地址程序会通过get_cached_url_path下载并缓存直接传本地模型文件路径程序将按文件路径直接加载。模型文件统一通过spandrel库的ModelLoader().load_from_file(...)加载加载完成后会被转换为ImageModelDescriptor其scale属性决定放大倍率因此最终输出尺寸由模型自身决定而非固定值。在命令行中可用aimg upscale --list-models随时查看全部可用模型键名。三、Python API 实战示例3.1 放大本地文件from imaginairy.api.upscale import upscale_image result upscale_image(photos/landscape.jpg) result.save(photos/landscape_upscaled.png)默认使用realesrgan-x2-plus2x模型512像素分块、50像素填充。3.2 放大网络图片result upscale_image(https://example.com/pic.jpg)只要字符串以https://开头就会被识别为远程图片并按 URL 惰性加载见 imaginairy/api/upscale.py。3.3 放大 PIL Image 对象from PIL import Image from imaginairy.api.upscale import upscale_image img Image.open(photos/portrait.jpg) result upscale_image(img, upscale_modelultrasharp) result.save(photos/portrait_4x.png)3.4 指定模型与设备# 使用 4x 模型 result upscale_image(img.png, upscale_modelrealesrgan-x4-plus) # 指定计算设备如 CPU result upscale_image(img.png, devicecpu)device为None时由 imaginairy/utils 的get_device()自动选择优先 CUDA/MPS其次 CPU。3.5 多次放大与分块参数# 连续放大 3 次例如 2x 模型可得到 8x 效果 result upscale_image(img.png, repetition3) # 超大图可缩小分块以控制显存并加大填充减少接缝 result upscale_image(huge.png, tile_size256, tile_pad64)repetition的实现位于 imaginairy/enhancers/upscale.py在torch.no_grad()上下文中循环执行每次都以当前结果作为下一次的输入相当于链式级联放大tile_size 0时走分块路径否则整图一次推理。四、底层原理分块放大与模型加载4.1 模型加载与推理核心实现在 imaginairy/enhancers/upscale.py。流程为根据upscale_model从upscale_model_lookup或 URL/本地路径解析出模型文件路径用spandrel的ModelLoader加载模型并断言为ImageModelDescriptor将模型转移到目标设备并设为eval()模式把输入图片经transforms.ToTensor()转换为[1, C, H, W]的张量见同文件load_image在torch.no_grad()中按repetition循环调用tile_process或直接推理结果张量squeeze(0)后经F.to_pil_image转回 PIL 图并按模型 scale精确重设为最终尺寸。4.2 分块tiling如何工作分块逻辑位于 imaginairy/utils/tile_up.py 的tile_process函数输入张量按tile_size划分为ceil(width/tile_size) × ceil(height/tile_size)个块逐块送入模型每个块在送入前会向四周扩展tile_pad像素的上下文在边界处自动裁剪推理后再只截取块的核心区域回填到输出张量对应位置输出张量预先按模型scale分配为(batch, channel, height*scale, width*scale)因此拼接后即为完整放大图。这种带重叠上下文的分块推理既降低了超大图的显存占用也通过上下文重叠显著减少块与块之间的接缝tile_pad越大相邻块的上下文重叠越多、接缝越不明显但计算量也相应增加。4.3 其他放大实现历史参考仓库中还存在两套更早的放大实现可作为了解项目演进的参考imaginairy/enhancers/upscale_realesrgan.py基于 RealESRGAN 的RRDBNet与RealESRGANer支持ultrasharp开关模型通过memory_managed_model(realesrgan_upsampler, memory_usage_mb70)进行内存托管imaginairy/enhancers/upscale_riverwing.py基于 k-diffusion 的潜在空间latent文本条件放大模型支持从k_euler到k_dpm_adaptive等多种采样器属于扩散式放大方案。五、CLI 命令aimg upscale对应命令行实现位于 imaginairy/cli/upscale.pyCLI 文档见 docs/docs/CLI/upscale.md。基本用法aimg upscale image_path_or_url [options]支持一次传入多个文件路径或 URLnargs-1并支持 glob 通配符展开内部调用glob_expand_paths。5.1 常用选项选项默认值说明--outdir dir./outputs/upscaled输出目录使用默认文件名模板时输出会写到原图所在目录--upscale-model namerealesrgan-x2-plus可重复指定多个模型多个模型会依次链式放大每个模型以前一模型的输出为输入--list-models关闭列出全部可用放大模型键名后退出--fix-faces关闭放大后对图中人脸进行 CodeFormer 增强修复--fix-faces-fidelity1.0人脸修复保真度1 最大程度保留原貌0 追求最好看的脸--format template{original_filename}.upscaled{file_extension}输出文件名模板详见下文5.2 完整示例# 单图默认放大2x输出到原图目录 aimg upscale photos/landscape.jpg # 指定输出目录并放大到 4x aimg upscale photos/landscape.jpg --outdir ./outputs/upscaled --upscale-model realesrgan-x4-plus # 多模型链式放大先 2x 再 4x合计 8x aimg upscale photos/landscape.jpg --upscale-model realesrgan-x2-plus --upscale-model realesrgan-x4-plus # 放大并修复人脸保真度 0.8 aimg upscale photos/portrait.jpg --fix-faces --fix-faces-fidelity 0.8 # 批量放大目录内所有 jpgglob 展开并采用自定义文件名 aimg upscale photos/*.jpg --format {original_filename}_{algorithm}_x2{file_extension}CLI 中多个模型逐级放大的执行顺序可见 imaginairy/cli/upscale.py循环内img upscale_image(img, model)后可选执行enhance_faces(img, fidelity...)最后按模板落盘并打印实际放大倍率scale img.height / orig_height。六、输出文件名模板--formatCLI 支持高度可定制的文件名模板见 imaginairy/cli/upscale.py占位符如下占位符含义{original_filename}原文件名不含扩展名{file_extension}原文件扩展名含点{file_sequence_number:pad}输出目录中的序号可零填充如06表示 6 位数字{algorithm}本次使用的放大模型名若模型为 URL 则取 URL 中的文件名{now:%Y-%m-%d:%H-%M-%S}当前 UTC 时间支持标准strftime格式码两个快捷值--format DEV等价于{file_sequence_number:06}_{algorithm}_{original_filename}.upscaled{file_extension}imaginAIry 标准命名格式--format DEFAULT等价于默认模板{original_filename}.upscaled{file_extension}此时输出会写入原图所在目录imaginairy/cli/upscale.py。七、测试与验证仓库通过 tests/test_enhancers/test_upscale.py 对 CLI 行为进行验证例如test_upscale_cmd_format_option使用 Click 的CliRunner以tests/data/sand_upscale_difficult.jpg为输入、传入自定义--format {original_filename}_upscaled_{file_sequence_number}_{algorithm}_{now}断言命令退出码为 0、输出日志包含 saved to 且图片save被调用。放大功能的端到端效果在仓库中也有真实产物可查tests/expected_output/upscaled/目录下的测试放大图如将 576x448 的森林图放大为 2304x1792即 4x以及docs/assets/中 512x512 的彩色烟雾图与 2048x2048 放大版的对比图见文首配图。八、注意事项与最佳实践模型自动下载模型权重首次使用时自动下载并缓存get_cached_url_path请确保网络可访问模型源--list-models可提前确认可用模型。显存管理大图建议保持默认分块tile_size512若显存紧张可减小tile_size、适当增大tile_pad以兼顾质量与接缝tile_size0会在超大图上直接整图推理可能造成显存溢出。放大倍率与模型 scale 绑定最终放大倍数由所选模型的scale决定x2 或 x4CLI 帮助文本中的4x仅为默认描述如需更高倍率可通过repetition多次放大或多个--upscale-model链式放大。人脸场景人像放大后若面部细节不足配合--fix-faces或 Python 侧在放大后调用 imaginairy/enhancers/face_restoration_codeformer.py 的enhance_faces可获得更佳效果注意用--fix-faces-fidelity权衡保真度与美观度。输出位置使用默认文件名模板时结果写回原图目录使用自定义--outdir或自定义模板时结果写入指定目录避免混淆。赞分享AI 应用媒体生成【免费下载链接】imaginAIryPythonic AI generation of images and videos项目地址https://gitcode.com/gh_mirrors/im/imaginAIry点击查看免费下载相关推荐如何在 Ignite 中使用 Reactotron 调试应用并添加自定义调试命令如何在 Ignite 中使用 Reactotron 调试应用并添加自定义调试命令 如果你在基于 Ignite 模板的 React Native 项目里需要查看AI 应用媒体生成AI图像放大神器Cupscale智能超分辨率完全指南AI图像放大神器Cupscale智能超分辨率完全指南 还在为模糊图片发愁想要让低分辨率图像焕发新生Cupscale作为一款基于AI技术的图像超分辨率工具ComfyUI Ultimate SD Upscale 超分辨率工具完全指南ComfyUI Ultimate SD Upscale 超分辨率工具完全指南 开启AI图像超分辨率新纪元 ComfyUI Ultimate SD Upsc人工智能计算机视觉图像处理媒体生成上一篇RootBeerAndroid设备Root状态检测的技术实现与安全实践下一篇dnd-kit自定义拖拽动画曲线easing函数应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考