Developer docs / AI Fabric tutorials
Batch image upscaling (4x) on GPU
- GPU
- Batch / map
- Image DSL
- Volume
Upscaling one image is easy; upscaling a thousand is a throughput problem. A 4x super-resolution transformer can grind for tens of seconds per image on a CPU, but a GPU does the same work in well under a second, and AI Fabric lets you run a whole batch of them at the same time, one container per image.
In this tutorial you'll upscale a batch of images 4x with Swin2SR on RTX A4500 GPUs, fanned out across the fleet with .map(). Each image gets its own container, all running in parallel, and the model weights are cached on a Volume so the download happens once. Billing is per started minute and stops when containers exit, so an idle fleet costs nothing.
Before you start
You need the AI Fabric CLI installed and authenticated: run blade setup once. The function asks for a single RTX A4500 per image and builds on fabric/torch, the catalog image with CUDA, PyTorch and Python 3.12 already baked in. Swin2SR ships in 🤗 transformers, so it's pure pip: no git checkout, no compilation.
Set up the app, Volume, and image
Create a file called upscale_batch.py. Declare the App, a Volume to cache weights across runs, and the container image. The Swin2SR x4 weights are only ~50 MB, but caching them on the Volume still means later runs skip the download entirely; pointing HF_HOME at /hf-cache is what routes them there.
import time
import bladekit
app = bladekit.app("upscale-batch")
# Cache HF model weights across runs (downloaded once, reused forever).
hf_cache = bladekit.Volume.from_name("hf-cache", create_if_missing=True)
# fabric/torch = CUDA + PyTorch + Python 3.12 (AI Fabric catalog, no build of its own).
# Swin2SR ships in 🤗 transformers: pure pip, no git / basicsr / compilation.
image = (
bladekit.Image.from_catalog("fabric/torch")
.pip_install("transformers", "pillow", "numpy")
.env({"HF_HOME": "/hf-cache"})
)Pick a model and some sample images
Name the Swin2SR 4x checkpoint, and a few sample image URLs to upscale. The samples come from Lorem Picsum. They're fetched inside the container, so there are no local files to stage before you run.
MODEL_ID = "caidas/swin2SR-classical-sr-x4-64" # 4x super-resolution
# A few small sample images from Lorem Picsum (reliable, any size, no hotlink
# limits). Each is fetched inside the container, so there are NO local files.
SAMPLE_URLS = [
"https://picsum.photos/seed/forge1/256",
"https://picsum.photos/seed/forge2/256",
"https://picsum.photos/seed/forge3/256",
]
# Loaded once per container, reused across every call that lands on it.
_proc = None
_model = NoneLoad the model once per container
Request the GPU, the image, and the Volume on the function. The _model global makes a warm container cheap: the first call on a container loads Swin2SR onto the GPU, and every call after that reuses it. Weights auto-cache to /hf-cache, so even the load is fast once the Volume is warm.
@app.function(
gpu="RTX-A4500",
image=image,
timeout=900,
volumes={"/hf-cache": hf_cache},
)
def upscale_4x(url: str) -> dict:
"""Download one image, upscale it 4x on the GPU, return size + timing info."""
global _model
import io
import time as _t
import urllib.request
import numpy as np
import torch
from PIL import Image as PILImage
from transformers import Swin2SRForImageSuperResolution
device = "cuda" if torch.cuda.is_available() else "cpu"
# Load the model once per container; weights auto-cache to /hf-cache. We do
# the (trivial) preprocessing by hand so we don't need torchvision (which the
# transformers image processor would pull in), which keeps the image lean.
if _model is None:
t_load = _t.perf_counter()
_model = Swin2SRForImageSuperResolution.from_pretrained(MODEL_ID).to(device).eval()
print(f"[remote] model loaded on {device} in {_t.perf_counter() - t_load:.1f}s")Fetch, preprocess, and upscale
Each call downloads its own image into memory, with no local files. The preprocessing is done by hand (RGB uint8 → float, HWC → NCHW on the GPU) deliberately, so the image doesn't have to pull in torchvision and stays lean. The upscale itself runs under torch.no_grad(), and torch.cuda.synchronize() makes the timing honest by waiting for the GPU to actually finish.
# Fetch the sample image into memory (no local files required).
req = urllib.request.Request(url, headers={"User-Agent": "fabric-tutorial/1.0"})
with urllib.request.urlopen(req, timeout=30) as resp:
raw = resp.read()
src = PILImage.open(io.BytesIO(raw)).convert("RGB")
# Manual preprocess: RGB uint8 -> float[0,1], HWC -> 1,C,H,W on the GPU.
px = np.asarray(src).astype("float32") / 255.0
pixel_values = torch.from_numpy(px).permute(2, 0, 1).unsqueeze(0).to(device)
# Upscale 4x on the GPU and time just the inference.
t0 = _t.perf_counter()
with torch.no_grad():
out = _model(pixel_values=pixel_values)
if device == "cuda":
torch.cuda.synchronize()
gpu_seconds = _t.perf_counter() - t0Encode the result and report
The model's reconstruction tensor is a float image; convert it back to a uint8 PNG and return a small dict of facts: input and output sizes, byte count, and the measured GPU time. Returning metrics instead of raw bytes keeps the .map() results light and lets the entrypoint print a tidy summary.
# reconstruction: (1,C,H,W) float in [0,1] → HWC uint8 PNG
arr = out.reconstruction.data.squeeze().float().cpu().clamp_(0, 1).numpy()
arr = np.moveaxis(arr, 0, -1)
out_img = PILImage.fromarray((arr * 255.0).round().astype(np.uint8))
buf = io.BytesIO()
out_img.save(buf, format="PNG")
png = buf.getvalue()
return {
"url": url,
"in_size": list(src.size), # (W, H) before
"out_size": list(out_img.size), # (W, H) after, ~4x each side
"out_megapixels": round(out_img.size[0] * out_img.size[1] / 1e6, 2),
"png_bytes": len(png),
"gpu_seconds": round(gpu_seconds, 3),
"device": device,
} Fan the batch out with .map()
The local_entrypoint runs on your laptop. upscale_4x.map(SAMPLE_URLS, ...) launches one GPU container per URL, all at once, and collects the results in input order. return_exceptions=True means a single bad URL is reported rather than cancelling the whole batch, and the timing print shows how much faster the GPU is than a CPU.
@app.local_entrypoint()
def main():
print(f"Upscaling {len(SAMPLE_URLS)} images 4x, fanning out across the fleet...\n")
t0 = time.perf_counter()
# One GPU container per image, all in parallel. return_exceptions keeps a
# single bad URL from cancelling the rest of the batch.
results = list(upscale_4x.map(SAMPLE_URLS, return_exceptions=True))
wall = time.perf_counter() - t0Run it
Run the program with the AI Fabric CLI:
blade run upscale_batch.pyUpscaled 3/3 images in ~Ns wall (avg ~1.5s GPU/image, all in parallel).The first run downloads the Swin2SR weights into the Volume; later runs skip it. Because the containers ran at once and billing is per started minute, each image bills about one GPU-minute from its container's start. To run this on your own images, point SAMPLE_URLS at them, or read them from a Volume or object store.
Take it for a spin
Everything above in one file, ready to run.
"""Batch image super-resolution (4x) on the GPU fleet.
Fetch a handful of small public sample images, upscale each one 4x on an
RTX-A4500 with Swin2SR, and fan the batch out across the fleet with ``.map()``,
one GPU container per image, all running at once. The function prints per-image
timing so you can see the GPU do in well under a second what a CPU grinds on for
tens of seconds.
blade run upscale_batch.py
The Swin2SR x4 weights (~50 MB) download once from the Hugging Face Hub and are
cached on a Volume, so later runs skip the download. The model fits easily in the
A4500's 20 GB.
"""
import time
import bladekit
app = bladekit.app("upscale-batch")
# Cache HF model weights across runs (downloaded once, reused forever).
hf_cache = bladekit.Volume.from_name("hf-cache", create_if_missing=True)
# fabric/torch = CUDA + PyTorch + Python 3.12 (AI Fabric catalog, no build of its own).
# Swin2SR ships in 🤗 transformers: pure pip, no git / basicsr / compilation.
image = (
bladekit.Image.from_catalog("fabric/torch")
.pip_install("transformers", "pillow", "numpy")
.env({"HF_HOME": "/hf-cache"})
)
MODEL_ID = "caidas/swin2SR-classical-sr-x4-64" # 4x super-resolution
# A few small sample images from Lorem Picsum (reliable, any size, no hotlink
# limits). Each is fetched inside the container, so there are NO local files.
SAMPLE_URLS = [
"https://picsum.photos/seed/forge1/256",
"https://picsum.photos/seed/forge2/256",
"https://picsum.photos/seed/forge3/256",
]
# Loaded once per container, reused across every call that lands on it.
_proc = None
_model = None
@app.function(
gpu="RTX-A4500",
image=image,
timeout=900,
volumes={"/hf-cache": hf_cache},
)
def upscale_4x(url: str) -> dict:
"""Download one image, upscale it 4x on the GPU, return size + timing info."""
global _model
import io
import time as _t
import urllib.request
import numpy as np
import torch
from PIL import Image as PILImage
from transformers import Swin2SRForImageSuperResolution
device = "cuda" if torch.cuda.is_available() else "cpu"
# Load the model once per container; weights auto-cache to /hf-cache. We do
# the (trivial) preprocessing by hand so we don't need torchvision (which the
# transformers image processor would pull in), which keeps the image lean.
if _model is None:
t_load = _t.perf_counter()
_model = Swin2SRForImageSuperResolution.from_pretrained(MODEL_ID).to(device).eval()
print(f"[remote] model loaded on {device} in {_t.perf_counter() - t_load:.1f}s")
# Fetch the sample image into memory (no local files required).
req = urllib.request.Request(url, headers={"User-Agent": "fabric-tutorial/1.0"})
with urllib.request.urlopen(req, timeout=30) as resp:
raw = resp.read()
src = PILImage.open(io.BytesIO(raw)).convert("RGB")
# Manual preprocess: RGB uint8 -> float[0,1], HWC -> 1,C,H,W on the GPU.
px = np.asarray(src).astype("float32") / 255.0
pixel_values = torch.from_numpy(px).permute(2, 0, 1).unsqueeze(0).to(device)
# Upscale 4x on the GPU and time just the inference.
t0 = _t.perf_counter()
with torch.no_grad():
out = _model(pixel_values=pixel_values)
if device == "cuda":
torch.cuda.synchronize()
gpu_seconds = _t.perf_counter() - t0
# reconstruction: (1,C,H,W) float in [0,1] → HWC uint8 PNG
arr = out.reconstruction.data.squeeze().float().cpu().clamp_(0, 1).numpy()
arr = np.moveaxis(arr, 0, -1)
out_img = PILImage.fromarray((arr * 255.0).round().astype(np.uint8))
buf = io.BytesIO()
out_img.save(buf, format="PNG")
png = buf.getvalue()
return {
"url": url,
"in_size": list(src.size), # (W, H) before
"out_size": list(out_img.size), # (W, H) after, ~4x each side
"out_megapixels": round(out_img.size[0] * out_img.size[1] / 1e6, 2),
"png_bytes": len(png),
"gpu_seconds": round(gpu_seconds, 3),
"device": device,
}
@app.local_entrypoint()
def main():
print(f"Upscaling {len(SAMPLE_URLS)} images 4x, fanning out across the fleet...\n")
t0 = time.perf_counter()
# One GPU container per image, all in parallel. return_exceptions keeps a
# single bad URL from cancelling the rest of the batch.
results = list(upscale_4x.map(SAMPLE_URLS, return_exceptions=True))
wall = time.perf_counter() - t0
ok = []
for url, res in zip(SAMPLE_URLS, results):
name = url.rsplit("/", 1)[-1]
if isinstance(res, Exception):
print(f" FAILED {name}: {res}")
continue
ok.append(res)
print(
f" {name}: {tuple(res['in_size'])} -> {tuple(res['out_size'])} "
f"({res['out_megapixels']} MP, {res['png_bytes'] / 1e6:.1f} MB PNG) "
f"in {res['gpu_seconds']}s on {res['device']}"
)
if ok:
avg_gpu = sum(r["gpu_seconds"] for r in ok) / len(ok)
print(
f"\nUpscaled {len(ok)}/{len(SAMPLE_URLS)} images in {wall:.1f}s wall "
f"(avg {avg_gpu:.2f}s GPU/image, all in parallel)."
)
print(
"On a CPU the same 4x transformer upscale runs tens of seconds PER "
"image; the GPU is roughly 30-100x faster here."
)
print(
"Billing is per started minute: each image bills about one GPU-minute "
"from its container's start, and the containers ran at once."
)Concepts used: GPU, Run, Volume