Worker ZeroGPU do Conecta Primo

README.md

@@ -1,13 +1,39 @@
 ---
-title: Conecta Primo Gpu
-emoji: 🏆
+title: Conecta Primo GPU
+emoji: 🎛️
 colorFrom: indigo
-colorTo: yellow
+colorTo: blue
 sdk: gradio
-sdk_version: 6.26.0
-python_version: '3.12'
+sdk_version: "5.9.1"
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Conecta Primo — worker de GPU (ZeroGPU)
+
+Este Space é o **adapter ZeroGPU** do Conecta Primo AI: a mesma plataforma de
+geração do repositório principal, rodando os mesmos modelos
+(`modelos/` — Z-Image, Qwen3-TTS, ACE-Step, Wan 2.2) na GPU temporária do
+Hugging Face. Ele atende **somente** o backend do app, autenticado por
+segredo — a página não tem controles de propósito.
+
+O guia completo (criar o Space, secrets, conectar ao Render, testar) está em
+`docs/ZEROGPU.md` no repositório principal. O resumo:
+
+1. Crie um Space **Gradio** com hardware **ZeroGPU**.
+2. Publique estes arquivos MAIS `modelos/` e `armazenamento.py` do
+   `services/gpu-worker/` (o `publicar.sh` faz os dois passos).
+3. Em *Settings → Variables and secrets*:
+   - secret `WORKER_SECRET` — o mesmo valor que irá no Render;
+   - secret `HF_TOKEN` — se algum modelo for *gated*;
+   - secrets `STORAGE_*` — recomendado (obrigatório na prática para vídeo);
+   - variables `IMAGE_GPU_SECONDS` / `TTS_GPU_SECONDS` /
+     `MUSIC_GPU_SECONDS` / `VIDEO_GPU_SECONDS` — duração de GPU por tipo
+     (padrões: 60/60/180/300).
+4. No Render: `GPU_MODE=zerogpu`, `WORKER_URL=https://<user>-<space>.hf.space`
+   e `WORKER_SECRET` com o mesmo valor.
+
+A quota do ZeroGPU é **diária e acaba** — o backend trata isso como
+indisponibilidade (degrada para os geradores locais, ou segura a fila com
+`GERACAO_SO_WORKER=1`), nunca como erro para quem usa o app.

app.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+"""
+A CASCA GRADIO DO ADAPTER ZEROGPU — o que o Hugging Face executa.
+
+Este arquivo é fino de propósito: toda a lógica mora em `nucleo.py` (testado
+no repositório, sem Gradio). Aqui só se faz o que EXIGE o ambiente do Space:
+
+  - decorar a geração com `@spaces.GPU(duration=...)` — é o decorator que
+    faz o ZeroGPU alocar a placa durante a chamada, e a duração é POR TIPO
+    (IMAGE_GPU_SECONDS etc., lidas no nucleo);
+  - expor as funções como API do Gradio (`api_name=...`), que é o único
+    transporte que um Space ZeroGPU oferece: POST → event_id → SSE. Os
+    yields do gerador viram eventos `generating` (o progresso do app);
+  - manter a PÁGINA do Space inofensiva: quem abrir a URL num navegador vê
+    um aviso, não um formulário que gasta quota — gerar exige o segredo, e a
+    conferência roda ANTES do decorator de GPU ser invocado.
+
+Fora do Space (sem `spaces` instalado) o decorator vira identidade e o
+WORKER_MOCK=1 permite subir a casca inteira num notebook para teste.
+"""
+from __future__ import annotations
+
+import gradio as gr
+
+import nucleo
+
+try:
+    import spaces
+    _GPU = spaces.GPU
+except ImportError:              # fora do Hugging Face: sem decorator
+    def _GPU(*a, **k):
+        def envolve(fn):
+            return fn
+        return envolve
+
+
+def _fazer_endpoint(tipo: str):
+    """Uma função por tipo, porque a DURAÇÃO da GPU é do decorator e vídeo
+    não pode viver com o prazo de imagem (abortaria no meio, com a quota já
+    gasta)."""
+
+    @_GPU(duration=nucleo.duracao_gpu(tipo))
+    def _na_gpu(params_json: str):
+        yield from nucleo.gerar(tipo, params_json)
+
+    def endpoint(segredo: str, params_json: str):
+        # A porta fica AQUI FORA: recusar antes de `_na_gpu` significa que a
+        # chamada sem segredo não aloca GPU e não consome quota de ninguém.
+        recusa = nucleo.autenticar(segredo)
+        if recusa:
+            yield {"erro": recusa}
+            return
+        yield from _na_gpu(params_json)
+
+    return endpoint
+
+
+def _saude(segredo: str):
+    recusa = nucleo.autenticar(segredo)
+    if recusa:
+        return {"erro": recusa}
+    return nucleo.saude()
+
+
+with gr.Blocks(title="Conecta Primo — GPU") as demo:
+    # A página humana diz o mínimo. Nada aqui dispara geração: os botões nem
+    # existem — só a API, e ela pede o segredo.
+    gr.Markdown("## Conecta Primo — worker de GPU\n"
+                "Este Space atende **somente** o backend do aplicativo, "
+                "autenticado por segredo. Não há nada para usar nesta página.")
+
+    segredo_in = gr.Textbox(visible=False)
+    params_in = gr.Textbox(visible=False)
+    saida = gr.JSON(visible=False)
+
+    # gr.api registra função como endpoint puro (Gradio >= 4.44). Os botões
+    # invisíveis são a forma equivalente que funciona em toda versão 4/5 —
+    # ficam os dois? Não: DOIS caminhos para a mesma função é o defeito de
+    # sempre. Fica o dos componentes, que é o estável.
+    for _tipo, _nome in (("image", "gerar_imagem"), ("voice", "gerar_fala"),
+                         ("music", "gerar_musica"), ("video", "gerar_video")):
+        _btn = gr.Button(visible=False)
+        _btn.click(_fazer_endpoint(_tipo), inputs=[segredo_in, params_in],
+                   outputs=[saida], api_name=_nome)
+
+    _btn_saude = gr.Button(visible=False)
+    _btn_saude.click(_saude, inputs=[segredo_in], outputs=[saida],
+                     api_name="saude")
+
+if __name__ == "__main__":
+    # Fila do Gradio LIGADA com concorrência 1: no ZeroGPU cada chamada é uma
+    # alocação de GPU, e duas em paralelo é OOM ou quota dobrada — a mesma
+    # decisão do MAX_CONCURRENT_JOBS=1 do worker CUDA, no dialeto do Gradio.
+    demo.queue(default_concurrency_limit=1, max_size=16)
+    demo.launch(show_api=False)

armazenamento.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""
+O STORAGE DO LADO DO WORKER.
+
+O vídeo pronto tem dezenas de MB, e o caminho dele até a tela decide tudo:
+com S3 configurado, o worker sobe o arquivo e devolve SÓ a URL — o backend e
+o Firestore nunca carregam os bytes. Sem S3, volta base64 (funciona, mas
+esbarra no teto de 1 MB do documento; o job store do backend já sabe marcar
+`resultado_grande`). O DEPLOYMENT.md manda configurar S3 para vídeo, e este
+comentário é o porquê.
+
+Cópia deliberadamente PEQUENA do armazenamento do backend, e não um import
+dele: os dois serviços têm deploys separados, e um worker que importa código
+do backend acopla os ciclos de vida — a primeira mudança lá derruba cá.
+O contrato compartilhado é o FORMATO da resposta ({url} ou {base64}), que é
+minúsculo e está testado dos dois lados.
+"""
+from __future__ import annotations
+
+import base64
+import logging
+import os
+import secrets
+import time
+
+logger = logging.getLogger("worker.armazenamento")
+
+_EXTENSAO = {"image/png": ".png", "image/webp": ".webp", "image/jpeg": ".jpg",
+             "audio/wav": ".wav", "audio/mpeg": ".mp3", "video/mp4": ".mp4"}
+
+
+def _s3_configurado() -> bool:
+    return bool(os.getenv("STORAGE_ENDPOINT", "").strip()
+                and os.getenv("STORAGE_BUCKET", "").strip())
+
+
+def como_url_ou_base64(conteudo: bytes, mime: str) -> dict:
+    if _s3_configurado():
+        try:
+            import boto3  # type: ignore
+            nome = (f"ger/{time.strftime('%Y%m')}/"
+                    f"{secrets.token_urlsafe(16)}{_EXTENSAO.get(mime, '.bin')}")
+            cliente = boto3.client(
+                "s3", endpoint_url=os.getenv("STORAGE_ENDPOINT"),
+                aws_access_key_id=os.getenv("STORAGE_ACCESS_KEY", ""),
+                aws_secret_access_key=os.getenv("STORAGE_SECRET_KEY", ""),
+                region_name=os.getenv("STORAGE_REGION", "auto"))
+            cliente.put_object(Bucket=os.getenv("STORAGE_BUCKET"), Key=nome,
+                               Body=conteudo, ContentType=mime)
+            base_url = os.getenv("STORAGE_URL_PUBLICA", "").strip().rstrip("/")
+            if base_url:
+                return {"url": f"{base_url}/{nome}", "mime": mime}
+            url = cliente.generate_presigned_url(
+                "get_object",
+                Params={"Bucket": os.getenv("STORAGE_BUCKET"), "Key": nome},
+                ExpiresIn=int(os.getenv("STORAGE_LINK_VALIDADE", "604800")))
+            return {"url": url, "mime": mime}
+        except Exception as e:
+            # Storage caído não joga fora uma geração que custou GPU: cai
+            # para o base64 e registra — a criação chega, só que pesada.
+            logger.warning("S3 falhou (%s); devolvendo embutido", str(e)[:120])
+    return {"base64": "data:%s;base64,%s" % (mime,
+                                             base64.b64encode(conteudo).decode()),
+            "mime": mime}

modelos/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+"""Os modelos do worker. Import tardio SEMPRE — o worker sobe e responde
+/health mesmo sem torch instalado; o peso só entra quando um job pede."""

modelos/ace_step.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+"""
+MÚSICA — ACE-Step 1.5, rodando na GPU do worker.
+
+É a primeira vez que este app tem MÚSICA de verdade sem provedor pago: a
+trilha do `midia_livre` é síntese de acordes (e a tela sempre disse isso);
+o ACE-Step compõe — com letra, inclusive. Quando o worker está de pé, é ele
+quem responde "music"; quando dorme, a trilha sintetizada volta a valer, e a
+diferença de qualidade é o preço anunciado da GPU gratuita.
+
+`lyrics` aceita o formato de seções do projeto ([Verse]/[Chorus]); sem letra
+vai "[instrumental]" — mandar string vazia faz alguns checkpoints alucinarem
+voz. A chamada usa o pacote `acestep` (pip) e a API de pipeline dele; como no
+TTS, a chamada exata deve ser conferida no primeiro deploy com GPU (o
+MODELS.md marca), porque este ambiente não alcança os pesos.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from typing import Dict, Optional
+
+from . import base
+
+logger = logging.getLogger("worker.ace_step")
+
+VRAM_MINIMA_GB = 10
+
+_pipe = None
+_modelo_carregado = ""
+
+
+def _modelo() -> str:
+    return os.getenv("MUSIC_MODEL", "ACE-Step/ACE-Step-v1.5").strip()
+
+
+def carregar(progresso: base.Progresso) -> None:
+    global _pipe, _modelo_carregado
+    if base.modo_mock():
+        _pipe = "mock"
+        return
+    if _pipe is not None and _modelo_carregado == _modelo():
+        return
+    progresso(None, "Carregando o modelo de música…")
+    from acestep.pipeline_ace_step import ACEStepPipeline
+    _pipe = ACEStepPipeline(checkpoint_dir=os.getenv("ACE_CHECKPOINT_DIR")
+                            or None, dtype="bfloat16")
+    _modelo_carregado = _modelo()
+
+
+def gerar(params: Dict, progresso: base.Progresso) -> base.Saida:
+    if base.modo_mock():
+        return base.wav_silencio(0.5), "audio/wav"
+
+    prompt = (params.get("prompt") or "").strip()
+    estilo = (params.get("style") or "").strip()
+    if estilo:
+        prompt = f"{estilo}, {prompt}"
+    letra = (params.get("lyrics") or "").strip() or "[instrumental]"
+    # Duração com teto: cada segundo é tempo de GPU, e um pedido de "3600"
+    # vindo de um cliente forjado não pode virar uma hora de placa ocupada.
+    duracao = max(10, min(int(params.get("duration") or 60),
+                          int(os.getenv("MUSIC_MAX_SEGUNDOS", "240"))))
+
+    progresso(5, "Compondo…")
+    with tempfile.TemporaryDirectory() as pasta:
+        saida = os.path.join(pasta, "musica.wav")
+        _pipe(prompt=prompt, lyrics=letra, audio_duration=duracao,
+              save_path=saida)
+        progresso(95, "Finalizando…")
+        with open(saida, "rb") as f:
+            return f.read(), "audio/wav"
+
+
+def descarregar() -> None:
+    global _pipe
+    _pipe = None
+    base.limpar_vram()
+
+
+def config_menor(params: Dict) -> Optional[Dict]:
+    p = dict(params)
+    dur = int(p.get("duration") or 60)
+    if dur > 30:
+        p["duration"] = 30
+        return p
+    return None

modelos/base.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""
+O CONTRATO DE UM MODELO DENTRO DO WORKER.
+
+Cada modelo é um módulo com quatro deveres, e o gerenciador só conversa por
+eles:
+
+  carregar()        — traz os pesos para a GPU. Import de torch/diffusers é
+                      feito AQUI DENTRO, nunca no topo do arquivo: o worker
+                      precisa subir e responder /health mesmo numa máquina
+                      sem as bibliotecas pesadas instaladas.
+  gerar(params, progresso) — produz bytes + mime. `progresso(pct, etapa)` é
+                      chamado quando o modelo sabe onde está (a difusão sabe
+                      o passo; TTS muitas vezes não — aí não chama).
+  descarregar()     — devolve a VRAM. É o gerenciador que decide QUANDO.
+  config_menor(params) — a versão do pedido que cabe em menos VRAM (menos
+                      passos, resolução menor, duração menor). Devolve None
+                      quando não há o que reduzir — aí o OOM vira falha limpa
+                      em vez de tentativa infinita.
+
+E um modo de MENTIRA declarada: com WORKER_MOCK=1 os modelos devolvem
+arquivos minúsculos válidos (PNG 1x1, WAV de silêncio, MP4 de um quadro) sem
+tocar em GPU nenhuma. Ele existe para os testes automatizados e para subir a
+pilha inteira num notebook sem CUDA — e o resultado DIZ que é mock no
+metadado, porque fingir inferência real é o tipo de mentira que este projeto
+não conta.
+"""
+from __future__ import annotations
+
+import os
+import struct
+from typing import Callable, Dict, Optional, Tuple
+
+Progresso = Callable[[Optional[int], str], None]
+
+# bytes, mime
+Saida = Tuple[bytes, str]
+
+
+def modo_mock() -> bool:
+    return os.getenv("WORKER_MOCK", "").strip() == "1"
+
+
+# ---------------------------------------------------------------------------
+# Os arquivos mínimos do modo mock — válidos de verdade (abrem em qualquer
+# visualizador), só que vazios de conteúdo.
+# ---------------------------------------------------------------------------
+PNG_1X1 = bytes.fromhex(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489"
+    "0000000d4944415478da63fcffff3f0300050201f34d31b20000000049454e44ae426082")
+
+
+def wav_silencio(segundos: float = 0.2, taxa: int = 16000) -> bytes:
+    n = int(segundos * taxa)
+    dados = b"\x00\x00" * n
+    return (b"RIFF" + struct.pack("<I", 36 + len(dados)) + b"WAVEfmt "
+            + struct.pack("<IHHIIHH", 16, 1, 1, taxa, taxa * 2, 2, 16)
+            + b"data" + struct.pack("<I", len(dados)) + dados)
+
+
+def vram_livre_gb() -> Optional[float]:
+    """Quanta VRAM sobra agora. None = sem CUDA (aí ninguém decide por VRAM)."""
+    try:
+        import torch
+        if not torch.cuda.is_available():
+            return None
+        livre, _total = torch.cuda.mem_get_info()
+        return livre / (1024 ** 3)
+    except Exception:
+        return None
+
+
+def limpar_vram() -> None:
+    """Solta o que der: cache de CUDA e lixo do Python. Chamado pelo
+    gerenciador depois de descarregar e depois de um OOM — nas duas horas em
+    que 'quase liberado' e 'liberado' são a diferença entre caber e não."""
+    import gc
+    gc.collect()
+    try:
+        import torch
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+            torch.cuda.ipc_collect()
+    except Exception:
+        pass
+
+
+def dispositivo() -> str:
+    try:
+        import torch
+        return "cuda" if torch.cuda.is_available() else "cpu"
+    except Exception:
+        return "cpu"
+
+
+def semente(params: Dict):
+    """torch.Generator com a seed pedida — ou None para o aleatório de
+    sempre. Seed existe para 'gera de novo IGUAL', então ela é respeitada em
+    todo modelo que aceita generator."""
+    seed = params.get("seed")
+    if seed in (None, ""):
+        return None
+    try:
+        import torch
+        return torch.Generator(device=dispositivo()).manual_seed(int(seed))
+    except Exception:
+        return None

modelos/ltx.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+"""
+VÍDEO (FUTURO) — LTX-2.3: o lugar dele já existe, o modelo ainda não entrou.
+
+A arquitetura pedida deixa o LTX "pronto para": este módulo cumpre o contrato
+(carregar/gerar/descarregar/config_menor) e está REGISTRADO no gerenciador,
+mas desligado — `disponivel()` responde False até alguém implementar o
+`gerar` de verdade e ligar `LTX_ATIVO=1`.
+
+Por que um arquivo que recusa, em vez de arquivo nenhum: quando o LTX entrar,
+quem o implementa preenche DUAS funções aqui dentro e troca VIDEO_MODEL — sem
+tocar no gerenciador, no app.py, no backend nem no frontend. E até lá,
+qualquer pedido que aponte para ele falha ALTO com esta explicação, em vez de
+falhar baixo com um ImportError misterioso.
+"""
+from __future__ import annotations
+
+import os
+from typing import Dict, Optional
+
+from . import base
+
+VRAM_MINIMA_GB = 20
+
+
+def disponivel() -> bool:
+    return os.getenv("LTX_ATIVO", "").strip() == "1"
+
+
+def carregar(progresso: base.Progresso) -> None:
+    if base.modo_mock():
+        return
+    raise NotImplementedError(
+        "LTX-2.3 ainda não foi implementado neste worker. O lugar dele é "
+        "este arquivo (services/gpu-worker/modelos/ltx.py): preencha "
+        "carregar()/gerar() com o pipeline do LTX, ligue LTX_ATIVO=1 e "
+        "aponte VIDEO_MODEL para o checkpoint. Nada mais precisa mudar.")
+
+
+def gerar(params: Dict, progresso: base.Progresso) -> base.Saida:
+    if base.modo_mock():
+        return b"", "video/mp4"
+    raise NotImplementedError("ver carregar()")
+
+
+def descarregar() -> None:
+    base.limpar_vram()
+
+
+def config_menor(params: Dict) -> Optional[Dict]:
+    return None

modelos/qwen3_tts.py

@@ -0,0 +1,135 @@
+# -*- coding: utf-8 -*-
+"""
+NARRAÇÃO — Qwen3-TTS (variantes 0.6B / 1.7B), rodando na GPU do worker.
+
+O contrato de fora é o de sempre: texto entra, WAV sai. `voice` escolhe um
+timbre nomeado; `voice_reference` (um WAV curto em base64) liga o VOICE
+CLONING quando o modelo o suporta — o campo já existe no contrato para a
+tela não precisar de rota nova no dia em que for oferecido.
+
+HONESTIDADE DE CARGA: a chamada exata de geração (nomes de método e de
+parâmetro) tem de ser conferida contra o model card da versão baixada — o
+projeto Qwen troca detalhes entre releases, e este ambiente de desenvolvimento
+não alcança os pesos para provar a chamada. O que está aqui segue a API
+publicada do projeto; o MODELS.md marca este arquivo como "validar no primeiro
+deploy com GPU". Errar isso quebra ALTO (exceção no primeiro uso), não baixo —
+que é o jeito certo de errar.
+"""
+from __future__ import annotations
+
+import base64 as b64
+import io
+import logging
+import os
+from typing import Dict, Optional
+
+from . import base
+
+logger = logging.getLogger("worker.qwen3_tts")
+
+VRAM_MINIMA_GB = 4
+
+_modelo_obj = None
+_modelo_carregado = ""
+
+# Timbres nomeados → os "speakers" do modelo. A tela mostra nomes nossos
+# (regra da casa: nome de provedor não chega à tela); a tradução mora aqui.
+_VOZES = {"default": "Vivian", "feminina": "Vivian", "masculina": "Ethan"}
+
+
+def _modelo() -> str:
+    return os.getenv("TTS_MODEL", "Qwen/Qwen3-TTS-1.7B").strip()
+
+
+def carregar(progresso: base.Progresso) -> None:
+    global _modelo_obj, _modelo_carregado
+    if base.modo_mock():
+        _modelo_obj = "mock"
+        return
+    if _modelo_obj is not None and _modelo_carregado == _modelo():
+        return
+    progresso(None, "Carregando o modelo de voz…")
+    import torch
+    from transformers import AutoModel, AutoProcessor
+    # trust_remote_code: o Qwen3-TTS traz o código de inferência junto dos
+    # pesos. É código de terceiro rodando NO WORKER — que não tem segredo
+    # nenhum do app (ver GPU_WORKER.md); ainda assim, fixe a revisão em
+    # produção (TTS_MODEL_REV) para o código não trocar sob os seus pés.
+    rev = os.getenv("TTS_MODEL_REV") or None
+    _modelo_obj = {
+        "proc": AutoProcessor.from_pretrained(_modelo(), revision=rev,
+                                              trust_remote_code=True,
+                                              token=os.getenv("HF_TOKEN") or None),
+        "model": AutoModel.from_pretrained(_modelo(), revision=rev,
+                                           torch_dtype=torch.bfloat16,
+                                           trust_remote_code=True,
+                                           token=os.getenv("HF_TOKEN") or None
+                                           ).to(base.dispositivo()).eval(),
+    }
+    _modelo_carregado = _modelo()
+
+
+def gerar(params: Dict, progresso: base.Progresso) -> base.Saida:
+    if base.modo_mock():
+        return base.wav_silencio(), "audio/wav"
+
+    texto = (params.get("text") or "").strip()
+    if not texto:
+        raise ValueError("nada para narrar")
+    voz = _VOZES.get((params.get("voice") or "default").lower(),
+                     params.get("voice") or "Vivian")
+    idioma = params.get("language") or "pt-BR"
+
+    progresso(None, "Gerando a narração…")
+    modelo, proc = _modelo_obj["model"], _modelo_obj["proc"]
+
+    referencia = None
+    if params.get("voice_reference"):
+        # Voice cloning: o WAV de referência chega em base64 pelo backend.
+        referencia = io.BytesIO(b64.b64decode(
+            params["voice_reference"].split(",")[-1]))
+
+    import torch
+    with torch.no_grad():
+        if referencia is not None and hasattr(modelo, "clone"):
+            onda, taxa = modelo.clone(text=texto, reference=referencia,
+                                      language=idioma)
+        else:
+            entradas = proc(text=texto, speaker=voz, language=idioma,
+                            return_tensors="pt").to(base.dispositivo())
+            saida = modelo.generate(**entradas)
+            onda = saida.audio if hasattr(saida, "audio") else saida[0]
+            taxa = getattr(saida, "sampling_rate", 24000)
+
+    return _wav_de(onda, taxa), "audio/wav"
+
+
+def descarregar() -> None:
+    global _modelo_obj
+    _modelo_obj = None
+    base.limpar_vram()
+
+
+def config_menor(params: Dict) -> Optional[Dict]:
+    # TTS de 1.7B não tem botão de resolução; o corte honesto é o TEXTO.
+    p = dict(params)
+    t = p.get("text") or ""
+    if len(t) > 600:
+        p["text"] = t[:600]
+        return p
+    return None
+
+
+def _wav_de(onda, taxa: int) -> bytes:
+    """Tensor/array → WAV 16-bit. Sem soundfile: struct resolve e é uma
+    dependência a menos na imagem."""
+    import struct
+    try:
+        dados = onda.detach().float().cpu().numpy()
+    except AttributeError:
+        dados = onda
+    dados = dados.reshape(-1)
+    inteiros = (dados.clip(-1, 1) * 32767).astype("<i2").tobytes()
+    return (b"RIFF" + struct.pack("<I", 36 + len(inteiros)) + b"WAVEfmt "
+            + struct.pack("<IHHIIHH", 16, 1, 1, int(taxa), int(taxa) * 2, 2, 16)
+            + b"data" + struct.pack("<I", len(inteiros)) + inteiros)

modelos/wan22.py

@@ -0,0 +1,142 @@
+# -*- coding: utf-8 -*-
+"""
+VÍDEO — Wan 2.2 (TI2V 5B), texto-para-vídeo e imagem-para-vídeo.
+
+A variante 5B é a escolhida de propósito: é a que o próprio projeto publica
+como "cabe em uma GPU de consumidor" (24 GB com offload). As variantes A14B
+são melhores e NÃO cabem no worker que este projeto consegue pagar — quem
+tiver um A100 sobrando troca o VIDEO_MODEL e nada mais.
+
+As duas rotas do backend caem AQUI: `image_url` presente = image-to-video
+(o primeiro quadro é a imagem da pessoa); ausente = text-to-video. Um módulo
+só, porque é o mesmo pipeline com um argumento a mais — dois módulos seriam
+duas cópias do mesmo offload para divergir.
+"""
+from __future__ import annotations
+
+import base64 as b64
+import io
+import logging
+import os
+import tempfile
+from typing import Dict, Optional
+
+from . import base
+
+logger = logging.getLogger("worker.wan22")
+
+VRAM_MINIMA_GB = 16
+
+_pipe = None
+_modelo_carregado = ""
+
+
+def _modelo() -> str:
+    return os.getenv("VIDEO_MODEL", "Wan-AI/Wan2.2-TI2V-5B-Diffusers").strip()
+
+
+def carregar(progresso: base.Progresso) -> None:
+    global _pipe, _modelo_carregado
+    if base.modo_mock():
+        _pipe = "mock"
+        return
+    if _pipe is not None and _modelo_carregado == _modelo():
+        return
+    progresso(None, "Carregando o modelo de vídeo…")
+    import torch
+    from diffusers import WanPipeline
+    _pipe = WanPipeline.from_pretrained(_modelo(), torch_dtype=torch.bfloat16,
+                                        token=os.getenv("HF_TOKEN") or None)
+    # Vídeo é o maior dos quatro: offload SEMPRE, mesmo com VRAM folgada —
+    # o pico do VAE de vídeo no decode é traiçoeiro e é onde o OOM mora.
+    _pipe.enable_model_cpu_offload()
+    _modelo_carregado = _modelo()
+
+
+def gerar(params: Dict, progresso: base.Progresso) -> base.Saida:
+    if base.modo_mock():
+        return _mp4_mock(), "video/mp4"
+
+    prompt = (params.get("prompt") or "").strip()
+    estilo = (params.get("style") or "").strip()
+    if estilo:
+        prompt = f"{prompt}, {estilo} style"
+    largura = int(params.get("width") or 1280)
+    altura = int(params.get("height") or 704)
+    segundos = max(2, min(int(params.get("duration") or 5),
+                          int(os.getenv("VIDEO_MAX_SEGUNDOS", "8"))))
+    fps = 24
+    quadros = segundos * fps + 1
+    passos = int(params.get("steps") or 30)
+
+    imagem = None
+    if params.get("image_url"):
+        imagem = _abrir_imagem(params["image_url"], largura, altura)
+
+    def a_cada_passo(pipe, passo, t, kw):
+        progresso(int(95 * (passo + 1) / max(1, passos)), "Gerando o vídeo…")
+        return kw
+
+    extras = {"image": imagem} if imagem is not None else {}
+    saida = _pipe(prompt=prompt,
+                  negative_prompt=params.get("negative_prompt") or None,
+                  width=largura, height=altura, num_frames=quadros,
+                  num_inference_steps=passos,
+                  generator=base.semente(params),
+                  callback_on_step_end=a_cada_passo, **extras)
+
+    progresso(97, "Codificando o MP4…")
+    from diffusers.utils import export_to_video
+    with tempfile.TemporaryDirectory() as pasta:
+        caminho = os.path.join(pasta, "video.mp4")
+        export_to_video(saida.frames[0], caminho, fps=fps)
+        with open(caminho, "rb") as f:
+            return f.read(), "video/mp4"
+
+
+def descarregar() -> None:
+    global _pipe
+    _pipe = None
+    base.limpar_vram()
+
+
+def config_menor(params: Dict) -> Optional[Dict]:
+    """OOM no vídeo: primeiro menos pixels, depois menos segundos. É a ordem
+    que preserva o que a pessoa pediu — um vídeo menor da cena inteira vale
+    mais que meio vídeo em alta."""
+    p = dict(params)
+    w = int(p.get("width") or 1280)
+    if w > 832:
+        p["width"], p["height"] = 832, 480
+        return p
+    dur = int(p.get("duration") or 5)
+    if dur > 3:
+        p["duration"] = 3
+        return p
+    return None
+
+
+def _abrir_imagem(ref: str, largura: int, altura: int):
+    """A referência chega como data URL (do app) ou como endereço http. O
+    endereço http só é aceito vindo do BACKEND — e o backend já o passou pelo
+    `endereco_seguro` dele; ainda assim o download daqui tem teto de tamanho,
+    porque worker também não baixa gigabyte de ninguém."""
+    from PIL import Image
+    if ref.startswith("data:"):
+        dados = b64.b64decode(ref.split(",", 1)[1])
+    else:
+        import requests
+        r = requests.get(ref, timeout=30, stream=True)
+        r.raise_for_status()
+        dados = r.raw.read(20 * 1024 * 1024 + 1)
+        if len(dados) > 20 * 1024 * 1024:
+            raise ValueError("imagem de referência grande demais")
+    img = Image.open(io.BytesIO(dados)).convert("RGB")
+    return img.resize((largura, altura))
+
+
+def _mp4_mock() -> bytes:
+    # Um MP4 mínimo (só o ftyp) — suficiente para os testes conferirem mime e
+    # transporte. O modo mock nunca finge ser vídeo de verdade: o metadado do
+    # job diz "mock".
+    return bytes.fromhex("000000186674797069736f6d0000020069736f6d69736f32")

modelos/z_image.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+"""
+IMAGEM — Z-Image / Z-Image-Turbo (Tongyi-MAI), via diffusers.
+
+Por que ele: é open-weight, entende prompt em duas línguas e a variante Turbo
+resolve em ~8 passos — numa GPU de 24 GB isso é imagem em poucos segundos, que
+é o que o Estúdio precisa. O id exato vem do ambiente (IMAGE_MODEL); este
+arquivo não prende ninguém a uma versão.
+
+O pipeline fica em bfloat16 e com `enable_model_cpu_offload` quando a VRAM é
+curta: offload troca velocidade por caber, e caber ganha — imagem lenta ainda
+é imagem; OOM é nada.
+"""
+from __future__ import annotations
+
+import io
+import logging
+import os
+from typing import Dict, Optional
+
+from . import base
+
+logger = logging.getLogger("worker.z_image")
+
+VRAM_MINIMA_GB = 8          # com offload; folgado ele usa mais e voa
+
+_pipe = None
+_modelo_carregado = ""
+
+
+def _modelo() -> str:
+    return os.getenv("IMAGE_MODEL", "Tongyi-MAI/Z-Image-Turbo").strip()
+
+
+def carregar(progresso: base.Progresso) -> None:
+    global _pipe, _modelo_carregado
+    if base.modo_mock():
+        _pipe = "mock"
+        return
+    if _pipe is not None and _modelo_carregado == _modelo():
+        return
+    progresso(None, "Carregando o modelo de imagem…")
+    import torch
+    from diffusers import DiffusionPipeline
+    _pipe = DiffusionPipeline.from_pretrained(
+        _modelo(), torch_dtype=torch.bfloat16,
+        token=os.getenv("HF_TOKEN") or None)
+    livre = base.vram_livre_gb()
+    if livre is not None and livre < 20:
+        # Pouca VRAM: o offload deixa os blocos na RAM e sobe um por vez.
+        _pipe.enable_model_cpu_offload()
+    else:
+        _pipe.to(base.dispositivo())
+    _modelo_carregado = _modelo()
+
+
+def gerar(params: Dict, progresso: base.Progresso) -> base.Saida:
+    if base.modo_mock():
+        return base.PNG_1X1, "image/png"
+
+    prompt = (params.get("prompt") or "").strip()
+    estilo = (params.get("style") or "").strip()
+    if estilo:
+        prompt = f"{prompt}, {estilo} style"
+    largura = int(params.get("width") or 1024)
+    altura = int(params.get("height") or 1024)
+    # A tela manda aspect_ratio; quem manda width/height explícito ganha.
+    if not params.get("width") and params.get("aspect_ratio"):
+        largura, altura = _do_aspecto(params["aspect_ratio"])
+    passos = int(params.get("steps") or 8)   # Turbo: 8 é o ponto doce
+
+    def a_cada_passo(pipe, passo, t, kw):
+        progresso(int(100 * (passo + 1) / max(1, passos)), "Gerando…")
+        return kw
+
+    saida = _pipe(prompt,
+                  negative_prompt=params.get("negative_prompt") or None,
+                  width=largura, height=altura,
+                  num_inference_steps=passos,
+                  generator=base.semente(params),
+                  callback_on_step_end=a_cada_passo)
+    img = saida.images[0]
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return buf.getvalue(), "image/png"
+
+
+def descarregar() -> None:
+    global _pipe
+    _pipe = None
+    base.limpar_vram()
+
+
+def config_menor(params: Dict) -> Optional[Dict]:
+    """Depois de um OOM: menos pixels primeiro, depois menos passos. Abaixo
+    de 512px e 4 passos não há mais gordura — devolve None e o job falha
+    limpo dizendo o porquê."""
+    p = dict(params)
+    w = int(p.get("width") or 1024)
+    if w > 512:
+        p["width"] = max(512, w // 2)
+        p["height"] = max(512, int(p.get("height") or 1024) // 2)
+        return p
+    passos = int(p.get("steps") or 8)
+    if passos > 4:
+        p["steps"] = 4
+        return p
+    return None
+
+
+def _do_aspecto(ratio: str):
+    tabela = {"1:1": (1024, 1024), "16:9": (1280, 720), "9:16": (720, 1280),
+              "4:3": (1152, 864), "3:4": (864, 1152)}
+    return tabela.get(str(ratio).strip(), (1024, 1024))

nucleo.py

@@ -0,0 +1,225 @@
+# -*- coding: utf-8 -*-
+"""
+O NÚCLEO DO SPACE — tudo do adapter ZeroGPU que NÃO é Gradio.
+
+Por que a separação: o Gradio e o `spaces` só existem DENTRO do Space, e a
+lógica que importa (autenticação, duração de GPU por tipo, despacho para os
+modelos, tradução dos erros de quota) precisa ser testável nesta casa, onde
+nenhum dos dois está instalado. O `app.py` é só a casca que liga isto ao
+Gradio; este arquivo é o que se mede no `t_zerogpu.py`.
+
+OS MODELOS NÃO SÃO REESCRITOS. Este arquivo importa os MESMOS módulos de
+`services/gpu-worker/modelos/` (e o mesmo `armazenamento.py`): no repositório
+ele os acha pelo caminho relativo; no Space publicado eles são enviados JUNTO
+(o `publicar.sh` faz isso — uma cópia de DEPLOY, nunca uma segunda
+implementação no git). Dois fontes dos mesmos modelos seria o defeito de
+sempre: um conserto entra num e o outro fica para trás.
+
+POR QUE ISTO NÃO É O WORKER FASTAPI NUM SPACE: o ZeroGPU não é uma VM CUDA.
+A GPU só existe DENTRO de uma chamada decorada com `@spaces.GPU`, com prazo
+declarado, e o Space precisa ser Gradio. Então a fila daqui é a do PRÓPRIO
+Gradio (cada chamada é um job do backend, síncrona do lado de cá), e quem
+continua dono do estado do job é o backend — este processo não guarda nada
+que não possa evaporar junto com a GPU.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import secrets
+import sys
+from typing import Callable, Dict, Iterator, Optional
+
+logger = logging.getLogger("zerogpu.nucleo")
+
+# ---------------------------------------------------------------------------
+# Onde moram os modelos: no repo, na pasta irmã gpu-worker; no Space, ao lado
+# (o publicar.sh os põe lá). A ordem tenta o Space primeiro — é onde roda de
+# verdade.
+# ---------------------------------------------------------------------------
+_AQUI = os.path.dirname(os.path.abspath(__file__))
+for _cand in (_AQUI, os.path.join(_AQUI, "..", "gpu-worker")):
+    if os.path.isdir(os.path.join(_cand, "modelos")):
+        if _cand not in sys.path:
+            sys.path.insert(0, _cand)
+        break
+
+from modelos import base as mbase        # noqa: E402
+from modelos import ace_step, qwen3_tts, wan22, z_image  # noqa: E402
+import armazenamento                      # noqa: E402
+
+_MODULOS = {"image": z_image, "speech": qwen3_tts, "voice": qwen3_tts,
+            "music": ace_step, "video": wan22}
+_carregado: Optional[str] = None
+
+# ---------------------------------------------------------------------------
+# DURAÇÃO DE GPU POR TIPO — o prazo que o decorator @spaces.GPU declara.
+# Configurável porque é a variável mais sensível do ZeroGPU: curto demais, a
+# geração é abortada no meio (e a quota foi gasta mesmo assim); longo demais,
+# cada chamada reserva mais quota do que usa. Os padrões saem dos tempos de
+# catálogo dos modelos escolhidos, com folga para a carga do modelo frio.
+# Este prazo é DA GPU, separado de propósito do timeout HTTP do backend
+# (_ESPERA_MAX do adapter): o backend espera mais do que a GPU promete, para
+# a falha vir sempre daqui, com o motivo certo, e nunca das duas pontas ao
+# mesmo tempo.
+# ---------------------------------------------------------------------------
+_DURACAO_PADRAO = {"image": 60, "speech": 60, "voice": 60,
+                   "music": 180, "video": 300}
+_VAR_DURACAO = {"image": "IMAGE_GPU_SECONDS", "speech": "TTS_GPU_SECONDS",
+                "voice": "TTS_GPU_SECONDS", "music": "MUSIC_GPU_SECONDS",
+                "video": "VIDEO_GPU_SECONDS"}
+
+
+def duracao_gpu(tipo: str) -> int:
+    try:
+        valor = int(os.getenv(_VAR_DURACAO.get(tipo, ""), "") or 0)
+    except ValueError:
+        valor = 0
+    return valor if valor > 0 else _DURACAO_PADRAO.get(tipo, 120)
+
+
+# ---------------------------------------------------------------------------
+# A PORTA. O endpoint de um Space é público por natureza — qualquer pessoa
+# que achar a URL pode chamar a API do Gradio. Quem protege a quota é ISTO:
+# o segredo é o primeiro argumento de toda chamada, conferido ANTES de a
+# função de GPU ser invocada — chamada sem segredo morre aqui, sem alocar um
+# segundo de ZeroGPU. Fail closed, como no worker CUDA: sem WORKER_SECRET
+# configurado no Space, ninguém gera nada.
+# ---------------------------------------------------------------------------
+def autenticar(segredo: str) -> Optional[str]:
+    """None = pode passar; string = o motivo da recusa (sem eco do que veio)."""
+    esperado = os.getenv("WORKER_SECRET", "").strip()
+    if not esperado:
+        return ("WORKER_SECRET não configurado no Space — configure o secret "
+                "com o MESMO valor usado no backend.")
+    if not segredo or not secrets.compare_digest(str(segredo), esperado):
+        return "segredo inválido"
+    return None
+
+
+# ---------------------------------------------------------------------------
+# QUOTA É ESTADO. O `spaces` sinaliza quota esgotada/GPU indisponível com
+# exceções próprias cuja MENSAGEM é estável ("GPU quota exceeded", "ZeroGPU");
+# a classe muda entre versões do pacote, então o reconhecimento é pelo texto
+# — e o resultado leva `erro_gpu`, que o backend traduz para
+# GeracaoIndisponivel (degrada ou espera), nunca para falha do pedido.
+# ---------------------------------------------------------------------------
+_SINAIS_DE_QUOTA = ("quota", "zerogpu", "gpu task aborted", "no gpu",
+                    "gpu unavailable", "queue is full")
+
+
+def e_erro_de_gpu(e: BaseException) -> bool:
+    texto = f"{type(e).__name__}: {e}".lower()
+    return any(s in texto for s in _SINAIS_DE_QUOTA)
+
+
+# ---------------------------------------------------------------------------
+# A GERAÇÃO — o corpo que o app.py decora com @spaces.GPU.
+#
+# É um GERADOR: cada yield intermediário vira um evento `generating` no SSE
+# do Gradio (o progresso que a tela do app mostra), e o último yield é o
+# resultado. O contrato do dict é o que o adapter do backend lê:
+#   {"etapa","progress"}  no meio
+#   {"resultado": {...}}  no fim
+#   {"erro": ...}         falha do pedido (não adianta tentar em outro lugar)
+#   {"erro_gpu": ...}     GPU/quota indisponível (degradar ou esperar)
+# ---------------------------------------------------------------------------
+def gerar(tipo: str, params_json: str) -> Iterator[Dict]:
+    global _carregado
+    try:
+        params = json.loads(params_json or "{}")
+        if not isinstance(params, dict):
+            raise ValueError("params não é um objeto")
+    except ValueError as e:
+        yield {"erro": f"parâmetros ilegíveis: {str(e)[:80]}"}
+        return
+
+    modulo = _MODULOS.get(tipo)
+    if not modulo:
+        yield {"erro": f"tipo desconhecido: {tipo}"}
+        return
+
+    progresso_atual: Dict = {}
+
+    def progresso(pct, etapa):
+        # O gerador não pode "yield" de dentro do callback; o valor fica
+        # anotado e sai no próximo passo do laço de fases abaixo.
+        if pct is not None:
+            progresso_atual["progress"] = max(0, min(100, int(pct)))
+        if etapa:
+            progresso_atual["etapa"] = etapa
+
+    yield {"etapa": "Carregando o modelo…", "progress": None}
+    tentativa_oom = 0
+    while True:
+        try:
+            # A troca de residente vale aqui também — na mesma chamada podem
+            # sobrar pesos da chamada anterior NA RAM (o processo do Space
+            # sobrevive entre alocações de GPU; a GPU é que evapora). Nunca
+            # dependa de estado NA GPU entre chamadas: os módulos usam
+            # cpu_offload, que sobe os blocos por passada — é exatamente o
+            # desenho que o ZeroGPU pede.
+            if _carregado and _carregado != tipo:
+                antigo = _MODULOS.get(_carregado)
+                if antigo:
+                    try:
+                        antigo.descarregar()
+                    except Exception:
+                        pass
+                mbase.limpar_vram()
+                _carregado = None
+            modulo.carregar(progresso)
+            _carregado = tipo
+
+            yield {"etapa": "Gerando…", "progress": progresso_atual.get("progress")}
+            saida, mime = modulo.gerar(params, progresso)
+
+            yield {"etapa": "Finalizando…", "progress": 97}
+            resultado = armazenamento.como_url_ou_base64(saida, mime)
+            resultado["mock"] = mbase.modo_mock()
+            _log(tipo, "completed")
+            yield {"resultado": resultado}
+            return
+        except BaseException as e:            # BaseException: o abort do
+            if e_erro_de_gpu(e):               # spaces nem sempre é Exception
+                _log(tipo, "gpu_indisponivel", e)
+                yield {"erro_gpu": f"ZeroGPU indisponível agora: {str(e)[:120]}"}
+                return
+            if "out of memory" in str(e).lower():
+                tentativa_oom += 1
+                mbase.limpar_vram()
+                menor = modulo.config_menor(params)
+                if menor is not None and tentativa_oom <= 2:
+                    params = menor
+                    yield {"etapa": "Memória curta: tentando uma versão menor…",
+                           "progress": None}
+                    continue
+                _log(tipo, "failed_oom", e)
+                yield {"erro": "a GPU não teve memória para este pedido"}
+                return
+            if isinstance(e, (KeyboardInterrupt, SystemExit)):
+                raise
+            _log(tipo, "failed", e)
+            yield {"erro": str(e)[:300]}
+            return
+
+
+def saude() -> Dict:
+    """O retrato para o /api/health/gpu do backend. No ZeroGPU não há GPU
+    residente para medir — CUDA só existe dentro de uma chamada decorada — e
+    o retrato DIZ isso em vez de fingir um número."""
+    return {"worker_status": "ready", "runtime": "zerogpu",
+            "mock": mbase.modo_mock(),
+            "cuda": None,   # None de propósito: "só se sabe dentro da chamada"
+            "duracoes": {t: duracao_gpu(t)
+                         for t in ("image", "speech", "music", "video")},
+            "modelo_residente": _carregado}
+
+
+def _log(tipo: str, status: str, erro: BaseException = None) -> None:
+    # O mesmo log estruturado do worker CUDA — e igualmente SEM o prompt:
+    # prompt é conteúdo da pessoa, e log de Space é ainda mais público que o
+    # nosso (aparece no painel do Hugging Face).
+    logger.info("geracao runtime=zerogpu tipo=%s status=%s%s", tipo, status,
+                f" erro={type(erro).__name__}" if erro else "")

requirements.txt

@@ -0,0 +1,18 @@
+# O Space ZeroGPU. `gradio` vem do SDK do Space (o front-matter do README o
+# declara); `spaces` é injetado pelo próprio Hugging Face em hardware ZeroGPU.
+# O torch NÃO se fixa aqui: no ZeroGPU a versão de torch/CUDA compatível é a
+# do ambiente deles, e fixar a nossa por cima é como se quebra a alocação.
+#
+# O resto é a MESMA camada de inferência do worker CUDA
+# (services/gpu-worker/requirements.txt) — mesmos modelos, mesmas versões,
+# de propósito: dois pares de versões seriam dois comportamentos.
+diffusers==0.32.2
+transformers==4.48.0
+accelerate==1.2.1
+safetensors==0.5.2
+Pillow==11.1.0
+imageio==2.36.1
+imageio-ffmpeg==0.6.0
+acestep==1.5.0
+boto3==1.35.90
+requests==2.31.0