Qwen-Image-Layered: guida pratica alla decomposizione delle immagini

Gli utenti di Photoshop passano ore a creare maschere manualmente e a dipingere gli sfondi. Qwen-Image-Layered, un nuovo modello del team Qwen di Alibaba, lo fa in automatico: gli dai una singola immagine e lui restituisce più livelli RGBA con sfondi trasparenti.

Questo tutorial spiega cos'è Qwen-Image-Layered, in cosa differisce da strumenti di segmentazione come SAM e come eseguirlo in Python. Scomporrai un'immagine in livelli, poi modificherai e ricombinerai quei livelli in un nuovo composito. Alla fine avrai un flusso di lavoro funzionante per l'editing di immagini via codice che evita del tutto la mascheratura manuale.

Se sei alle prime armi con la gestione dei dati immagine e della trasparenza nel codice, dai un'occhiata al nostro corso Image Processing in Python per costruire solide basi prima di iniziare. Ti consiglio anche di leggere la nostra guida sull'ultimo modello di generazione di immagini di Google, Nano Banana 2.

Che cos'è Qwen-Image-Layered?

Qwen-Image-Layered è costruito su Qwen2.5-VL, un modello visione-linguaggio di Alibaba. Il backbone VL significa che il modello comprende semanticamente cosa c'è in un'immagine: può distinguere un prodotto dalla sua ombra e dalla superficie su cui poggia, non solo rilevare i bordi. Come i Vision Transformers, elabora le immagini tramite meccanismi di attenzione anziché con approcci convoluzionali tradizionali.

Quando esegui l'inferenza, specifichi quante layer vuoi. Chiedi 4 e il modello distribuisce il contenuto dell'immagine su 4 output RGBA. Ne chiedi 8 e ottieni una separazione più fine. Il modello decide cosa va dove in base alla struttura della scena.

Esempio visivo

Ecco come appare la decomposizione nell' annuncio di Qwen:

Il modello prende un'immagine composita e la separa in livelli RGBA singolarmente modificabili con trasparenza.

L'immagine promozionale delle caramelle si scompone in quattro layer distinti: lo sfondo a raggiera, la persona in arancione, il testo e il branding "Sour Candy" e i singoli pezzi di caramella. Ogni livello esce con uno sfondo trasparente (indicato dal pattern a scacchiera), pronto per essere modificato o riordinato.

Il modello distribuisce gli elementi visivi tra i layer in base alla profondità e alla comprensione semantica. Le grafiche di sfondo vanno al livello 0, il soggetto principale (la persona) al livello 1, le sovrapposizioni di testo al livello 2 e i piccoli oggetti in primo piano (i pezzi di caramella) al livello 3. Ogni elemento è separato in modo pulito con trasparenza corretta.

Qwen-Image-Layered vs Segment Anything Model

Se hai già lavorato con la segmentazione di immagini, potresti chiederti come Qwen-Image-Layered si confronta con gli strumenti esistenti, in particolare il Segment Anything Model (SAM).

SAM e modelli di segmentazione simili producono maschere: mappe binarie di quali pixel appartengono a quale oggetto. Utili, ma una maschera ti dice solo dove si trova qualcosa. Estrarre l'oggetto lascia comunque un buco nell'immagine originale.

Qwen-Image-Layered, invece, produce layer completi. L'oggetto in primo piano esce con trasparenza e il livello di sfondo dietro è già riempito. Quando in seguito elimini o sposti un livello, non c'è nulla da rattoppare.

SAM usa un approccio discriminativo, analizzando i pixel esistenti per definire con precisione i confini degli oggetti. Qwen-Image-Layered, al contrario, impiega un'architettura generativa basata sulla diffusione che ricostruisce le regioni occluse o nascoste tramite generazione di immagini appresa. 

Mentre SAM produce maschere che definiscono cosa rimuovere, Qwen-Image-Layered genera contenuti di sfondo plausibili per completare la decomposizione in layer. Vale la pena notare che SAM può ottenere un riempimento di sfondo simile se combinato con modelli di inpainting dedicati, ma Qwen-Image-Layered integra questa capacità end-to-end all'interno del processo di decomposizione.

Anche il meccanismo di controllo dell'input è diverso: SAM si affida a prompt interattivi precisi, richiedendo di cliccare punti o disegnare riquadri per selezionare un target specifico. Qwen-Image-Layered opera in modo più olistico, permettendoti semplicemente di specificare un numero di layer desiderato (ad esempio, "dividi in 4 layer") per organizzare automaticamente l'intera struttura dell'immagine.

Dobbiamo notare che SAM 2 è esplicitamente progettato per i video, in grado di tracciare oggetti nelle sequenze usando un'architettura di streaming con memoria aumentata (mantiene ~6 frame recenti) con elevata coerenza temporale. Qwen-Image-Layered è specializzato per la decomposizione di immagini statiche e al momento non offre tracciamento oggetti nativo per l'editing video.

Scomporre un'immagine con Qwen-Image-Layered

Passiamo alla pratica. Prima di scrivere codice, c'è una considerazione pratica: dove eseguire il modello.

Perché usare un'API?

Qwen-Image-Layered richiede oltre 57 GB di pesi del modello e una GPU di fascia alta con molta VRAM. 

Ho provato a eseguirlo in locale su Google Colab con una GPU T4 e la sessione ha esaurito la RAM prima ancora che il modello finisse di scaricarsi. L'uso del disco è salito a 90 GB dei 112 GB disponibili nel runtime GPU. Il modello è semplicemente troppo grande per gli ambienti cloud gratuiti. 

I grandi modelli generativi come Stable Diffusion affrontano sfide di hosting simili, motivo per cui le API hosted sono diventate comuni.

Per questo tutorial useremo l'API hosted di Replicate. Ogni decomposizione costa circa $0,03, che ti garantisce un'esecuzione stabile e riproducibile senza preoccuparti di limiti di memoria o conflitti di dipendenze. Se vuoi solo provare il modello senza scrivere codice, la Hugging Face Space offre un'interfaccia web gratuita in cui puoi caricare immagini e scaricare i layer manualmente.

L'Hugging Face Space ti permette di testare il modello senza codice, ma l'API ti dà controllo programmatico.

Configurare l'ambiente

Crea una nuova directory di progetto e installa i pacchetti richiesti:

pip install replicate python-dotenvOfferto da

Ottieni il tuo token API dalle impostazioni account di Replicate e salvalo in un file .env:

REPLICATE_API_TOKEN=your_token_hereOfferto da

L'immagine sorgente

Gli annunci ufficiali dei modelli di solito mostrano esempi selezionati in cui il modello rende al meglio. Testiamo invece con un'immagine reale per vedere prestazioni realistiche.

Questa è l'immagine che scomporremo in layer:

Foto di Karola G su Pexels

La foto mostra tre prodotti per la cura della pelle su una superficie menta contro uno sfondo lavanda: una scatola regalo bianca con nastro nero, una boccetta di siero rosa e un piccolo vasetto di crema. Composizione pulita, oggetti distinti, ombre delicate. Un buon caso di test per la separazione in layer.

Eseguire l'inferenza

import replicate
from dotenv import load_dotenv

load_dotenv()

with open("data/healthcare_products.jpg", "rb") as f:
	output = replicate.run(
         "qwen/qwen-image-layered",
     	    input={
         	"image": f,
         	"num_layers": 4,
         	"go_fast": True,
         	"output_format": "png",
         	"seed": 42,
     	    }
	)Offerto da

Il parametro num_layers controlla quanto finemente il modello suddivide l'immagine. I valori possono variare da 2 a 8. Con 4 layer ottieni un buon equilibrio tra granularità e gestibilità. Impostare seed a un valore fisso rende l'output riproducibile.

L'API accetta anche direttamente URL, quindi puoi saltare la gestione dei file se la tua immagine è ospitata altrove:

output = replicate.run(
	"qwen/qwen-image-layered",
	input={
     	  "image": "https://example.com/photo.jpg",
     	  "num_layers": 4,
     	  "go_fast": True,
     	  "output_format": "png",
	}
)Offerto da

Salvare i layer

L'API restituisce una lista di oggetti FileOutput. Ognuno ha un metodo .read() che ti fornisce i byte dell'immagine:

for i, layer in enumerate(output):
	with open(f"layer_{i}.png", "wb") as f:
     	  f.write(layer.read())Offerto da

I layer sono ordinati dal basso verso l'alto: l'indice 0 è lo sfondo e gli indici superiori si sovrappongono. Ogni PNG è un'immagine RGBA con trasparenza, dove gli altri layer traspariranno.

Ecco il risultato:

Il modello ha posizionato lo sfondo (parete lavanda e superficie menta) sul livello 0, il vasetto di crema sul livello 1, la scatola regalo sul livello 2 e la boccetta di siero sul livello 3. Ogni prodotto è uscito con bordi puliti e trasparenza accurata.

Osserva però il livello di sfondo e noterai deboli residui di ombra dove prima c'erano i prodotti. Questo è emerso costantemente nei miei test: il modello gestisce bene l'isolamento degli oggetti, ma fatica nella ricostruzione dello sfondo quando ci sono ombre.

Più sono evidenti le ombre nell'immagine di partenza, più visibili diventano questi artefatti. È il primo modello del suo genere, quindi aspettati che il team Qwen affini questo aspetto nei prossimi aggiornamenti.

Ricomporre i layer con Qwen-Image-Layered

La decomposizione è solo metà del flusso di lavoro. I layer diventano utili quando li modifichi e li riassembli in qualcosa di nuovo.

Sostituire lo sfondo

I fotografi di prodotto spesso necessitano dello stesso scatto con sfondi diversi per A/B test, campagne stagionali o esigenze di piattaforma. Con i layer separati, bastano poche righe di codice.

from PIL import Image

# Load the decomposed layers
layers = [Image.open(f"layer_{i}.png") for i in range(4)]

# Create a new background (solid coral)
new_bg = Image.new("RGBA", layers[0].size, (255, 180, 162, 255))

# Replace the original background layer
layers[0] = new_bg

# Composite from bottom to top
result = layers[0]
for layer in layers[1:]:
	result = Image.alpha_composite(result, layer)

result.save("coral_background.png")Offerto da

La funzione alpha_composite() gestisce automaticamente il blending RGBA. Rispetta la trasparenza di ogni layer, così gli oggetti in primo piano si posano in modo naturale su qualsiasi sfondo tu fornisca. 

PIL rende la manipolazione delle immagini semplice e, se ti servono trasformazioni più complesse, le funzionalità di elaborazione immagini di PyTorch si integrano bene con i flussi di lavoro basati su PIL.

Ecco il risultato:

Stessi prodotti, ambiente diverso, niente mascheratura manuale. Puoi inserire un gradiente, una texture o un'altra foto interamente. Il processo non cambia: sostituisci il layer 0 e componi gli altri sopra.

Rimuovere o riposizionare oggetti

Lo stesso schema vale per altre modifiche. Rimuovi un oggetto saltando il suo layer:

# Composite without the cream jar (layer 1)
layers_without_jar = [layers[0], layers[2], layers[3]]

result = layers_without_jar[0]
for layer in layers_without_jar[1:]:
	result = Image.alpha_composite(result, layer)Offerto da

Per riposizionare un oggetto incollandolo a coordinate diverse, usa il metodo paste() con l'offset x/y scelto:

# Move the serum bottle 50 pixels left
 canvas = Image.new("RGBA", layers[0].size, (0, 0, 0, 0))
 canvas.paste(layers[3], (-50, 0), layers[3])
 layers[3] = canvas

 # Then composite as usualOfferto da

Il flusso di lavoro è sempre lo stesso: 

1. Modifica i layer che ti interessano: ridimensiona, ricolora, elimina, riordina.
2. Poi ricomponi tutto. 

Ogni operazione avviene su un layer isolato, quindi le modifiche restano circoscritte.

Creare un editor Qwen-Image-Layered con Streamlit

Eseguire queste operazioni in un notebook va bene per modifiche una tantum, ma il ciclo di feedback è lento. Scrivi il codice, esegui una cella, controlli l'output, regoli, ripeti. Per il lavoro iterativo in cui vuoi attivare/disattivare layer, confrontare composizioni e scaricare i risultati senza rieseguire le celle, ha più senso una GUI leggera.

Costruiremo un'app Streamlit in circa 160 righe che ti permette di caricare un'immagine, scomporla, attivare/disattivare i layer e vedere un'anteprima live. Crea un file chiamato streamlit_app.py nella directory del progetto.

Configurare Streamlit

Inizia con gli import e la configurazione di base:

import os
import io
import time
from typing import List
import streamlit as st
from PIL import Image, ImageDraw
from dotenv import load_dotenv
import replicate

load_dotenv()

# Constants
MAX_LAYERS, MIN_LAYERS, DEFAULT_LAYERS = 8, 2, 4
THUMBNAIL_SIZE = (150, 150)

# Initialize session state
if "layers" not in st.session_state:
	st.session_state.layers = []
	st.session_state.layer_visibility = []
	st.session_state.original_image = None

st.set_page_config(page_title="Qwen-Image-Layered", page_icon="🎨", layout="wide")
st.title("🎨 Qwen-Image-Layered")
st.markdown("Decompose images into editable RGBA layers")Offerto da

Lo stato di sessione persiste tra le riesecuzioni di Streamlit. Senza di esso, i tuoi layer scomparirebbero ogni volta che qualcuno clicca un pulsante.

Controllo del token API

Prima di chiamare Replicate, assicurati che il token esista:

token = os.environ.get("REPLICATE_API_TOKEN")
if not token:
	st.error("REPLICATE_API_TOKEN not found. Set it in your .env file.")
	st.code("export REPLICATE_API_TOKEN=your_token_here", language="bash")
	st.stop()Offerto da

st.stop() interrompe l'esecuzione se manca il token. Non ha senso renderizzare il resto della UI.

Funzione di decomposizione con cache

L'API di decomposizione costa $0,03 a chiamata e impiega 30–60 secondi. La cache evita chiamate ridondanti:

@st.cache_data(show_spinner=False)
def decompose_image(_image_bytes: bytes, num_layers: int, seed: int) -> List[bytes]:
    """Call Replicate API with retry logic for 502 errors."""
    for attempt in range(3):
        try:
            output = replicate.run(
                "qwen/qwen-image-layered",
                input={
                    "image": io.BytesIO(_image_bytes),
                    "num_layers": num_layers,
                    "go_fast": True,
                    "output_format": "png",
                    "seed": seed,
                },
            )
            return [layer.read() for layer in output]
        except Exception as e:
            if attempt < 2 and ("502" in str(e) or "Replicate" in str(type(e).__name__)):
                time.sleep(5)
                continue
            raiseOfferto da

Il prefisso underscore in _image_bytes indica a Streamlit di non fare l'hash di quel parametro (l'hash dei byte è costoso). Il ciclo di retry gestisce gli occasionali errori 502 di Replicate attendendo 5 secondi e provando fino a 3 volte.

Visualizzazione e composizione immagini

Definiamo poi piccole utility per la visualizzazione e la composizione:

def create_checkerboard(size: tuple) -> Image.Image:
    """Create a checkerboard pattern to show transparency."""
    img = Image.new("RGBA", size, (220, 220, 220, 255))
    draw = ImageDraw.Draw(img)

    square = 10
    for y in range(0, size[1], square):
        for x in range(0, size[0], square):
            if (x // square + y // square) % 2:
                draw.rectangle(
                    [x, y, x + square, y + square],
                    fill=(255, 255, 255, 255),
                )

    return img


def composite_layers(
    layers: List[Image.Image],
    visibility: List[bool],
) -> Image.Image:
    """Composite visible layers from bottom to top."""
    if not layers or not any(visibility):
        return Image.new(
            "RGBA",
            layers[0].size if layers else (400, 400),
            (0, 0, 0, 0),
        )

    result = None
    for layer, visible in zip(layers, visibility):
        if visible:
            result = layer.copy() if result is None else Image.alpha_composite(result, layer)

    return result or Image.new("RGBA", layers[0].size, (0, 0, 0, 0))Offerto da

La scacchiera rende visibile la trasparenza (convenzione standard dei software di editing). La funzione di composizione replica ciò che abbiamo fatto nel notebook, ora guidata dallo stato delle checkbox.

Upload immagine e impostazioni di decomposizione

La sidebar gestisce l'upload dell'immagine e le impostazioni di decomposizione:

with st.sidebar:
    st.header("🖼️ Image Upload")
    uploaded_file = st.file_uploader(
        "Choose an image",
        type=["png", "jpg", "jpeg"],
        help="Upload an image to decompose",
    )

    if uploaded_file is not None:
        st.session_state.original_image = uploaded_file
        st.image(uploaded_file, caption="Uploaded", use_container_width=True)

    st.divider()

    st.header("⚙️ Settings")
    num_layers = st.slider(
        "Number of layers",
        MIN_LAYERS,
        MAX_LAYERS,
        DEFAULT_LAYERS,
    )
    seed = st.number_input(
        "Random seed",
        0,
        999999,
        42,
        help="For reproducibility",
    )

    # Decompose button
    if st.button(
        "🔄 Decompose Image",
        disabled=uploaded_file is None,
        use_container_width=True,
        type="primary",
    ):
        if st.session_state.original_image is not None:
            image_bytes = st.session_state.original_image.getvalue()

            with st.spinner(f"Decomposing into {num_layers} layers... (30-60s)"):
                try:
                    layer_bytes = decompose_image(image_bytes, num_layers, seed)
                    st.session_state.layers = [
                        Image.open(io.BytesIO(lb)).convert("RGBA") for lb in layer_bytes
                    ]
                    st.session_state.layer_visibility = [True] * len(
                        st.session_state.layers
                    )
                    st.success(
                        f"Decomposed into {len(st.session_state.layers)} layers!"
                    )
                except Exception as e:
                    if "502" in str(e):
                        st.error(
                            "Replicate API error (502). Try again or use fewer layers."
                        )
                    else:
                        st.error(f"Error: {e}")

    # Reset button
    if st.session_state.layers and st.button("🗑️ Reset", use_container_width=True):
        st.session_state.layers = []
        st.session_state.layer_visibility = []
        st.session_state.original_image = None
        st.rerun()Offerto da

Il pulsante di decomposizione è disabilitato finché non viene caricata un'immagine. In caso di successo, i layer vengono salvati nello stato di sessione e tutte le opzioni di visibilità sono impostate su True per default.

Aggiungere i controlli dei layer immagine

Due colonne mostrano i controlli dei layer e l'anteprima live:

col1, col2 = st.columns([1, 1])  # two equal-width columns [web:61]

with col1:
    st.subheader("📑 Layers")

    if not st.session_state.layers:
        st.info("Upload an image and decompose to see layers here.")
    else:
        st.caption("Toggle layers on/off. Layer 0 is the background.")

        cols = st.columns(min(len(st.session_state.layers), 4))
        for i, layer in enumerate(st.session_state.layers):
            with cols[i % 4]:
                thumb = layer.copy()
                thumb.thumbnail(THUMBNAIL_SIZE)

                checkerboard = create_checkerboard(thumb.size)
                display = Image.alpha_composite(checkerboard, thumb)

                st.image(display, caption=f"Layer {i}", use_container_width=True)

                st.session_state.layer_visibility[i] = st.checkbox(
                    f"Show Layer {i}",
                    value=st.session_state.layer_visibility[i],
                    key=f"layer_{i}",
                )

with col2:
    st.subheader("👁️ Preview")

    if not st.session_state.layers:
        st.info("Composite preview will appear here.")
    else:
        composite = composite_layers(
            st.session_state.layers,
            st.session_state.layer_visibility,
        )
        visible = sum(st.session_state.layer_visibility)

        st.caption(f"Showing {visible} of {len(st.session_state.layers)} layers")
        st.image(composite, caption="Composite result", use_container_width=True)

        if visible > 0:
            buf = io.BytesIO()
            composite.save(buf, format="PNG")

            st.download_button(
                "⬇️ Download Result",
                data=buf.getvalue(),
                file_name="composite.png",
                mime="image/png",
                use_container_width=True,
            )Offerto da

Quando deselezioni un layer, Streamlit riesegue lo script. La checkbox aggiorna layer_visibility, la funzione di composizione ricalcola l'anteprima e la UI si aggiorna automaticamente.

Eseguire l'app

Salva il file ed esegui:

streamlit run streamlit_app.pyOfferto da

L'app ha un'immagine scomposta. Disattiva i layer per rimuovere oggetti dall'anteprima.

Carica un'immagine, clicca su decompose, poi attiva/disattiva i layer. L'anteprima si aggiorna all'istante. Scarica il risultato quando trovi una composizione che ti piace. L'intero flusso avviene nel browser senza rieseguire le celle del notebook.

Conclusione

Qwen-Image-Layered adotta un approccio diverso all'editing di immagini: invece di mascherare i pixel, separa i contenuti in layer RGBA completi con sfondi ricostruiti. Ottieni l'isolamento degli oggetti senza il lavoro di pulizia. Il modello ha difficoltà con artefatti di ombra in scene complesse, ma l'estrazione degli oggetti in sé funziona bene.

Il flusso di lavoro Python è lineare. Chiami l'API di Replicate, ottieni una lista di layer e li componi con PIL. La sostituzione degli sfondi e la rimozione degli oggetti diventano poche righe di codice. L'app Streamlit incapsula quella logica in una GUI per iterare più velocemente.

Questo è il primo modello del suo genere. Il team Qwen rilascia aggiornamenti rapidamente, quindi aspettati miglioramenti nella ricostruzione dello sfondo e una gestione migliore delle immagini con ombre marcate. Il paper di ricerca illustra l'architettura se vuoi capire come funziona la decomposizione a numero variabile di layer sotto il cofano.

Pronto a esplorare altri modelli open source di AI? Padroneggia l'ecosistema dietro Qwen seguendo lo skill track Hugging Face Fundamentals su DataCamp.