AI Lab — Guia de utilização

Arranque rápido

cd ~/ai-lab
ai start image     # ComfyUI — geração de imagem
ai stop all        # para tudo e liberta CPU/RAM/VRAM

O comando ai está em ~/ai-lab/bin/ai, com symlink em ~/.local/bin/ai. Alternativa: make image, make stop, …

Serviços e URLs locais

⚠️ Os URLs abaixo só funcionam na própria máquina do lab (tudo está exposto apenas em 127.0.0.1, por segurança). Esta página é só o guia.

Serviço	Para quê	Iniciar	URL local
ComfyUI	Geração de imagem por nós (Flux, SDXL, ControlNet, LoRA…)	`ai start image`	127.0.0.1:8188
SwarmUI	Interface simples “prompt → imagem” sobre o ComfyUI	`ai start swarmui`	127.0.0.1:7801
Open WebUI	Chat com LLMs locais (tipo ChatGPT)	`ai start chat`	127.0.0.1:8180
Ollama	Servidor de LLMs (API)	`ai start chat`	127.0.0.1:11434
llama.cpp	API OpenAI-compatible para modelos GGUF	`ai start llama-cpp`	127.0.0.1:8085/v1
Whisper	Transcrição áudio/vídeo (one-shot, termina sozinho)	`ai transcribe f.mp4`	—
Kokoro TTS	Síntese de voz (one-shot)	`ai tts "texto"`	127.0.0.1:8880

Comandos do shell

ai start <serviço|grupo>…   # inicia (ex.: ai start comfyui)
ai stop <serviço|all>…      # para e remove containers (liberta VRAM)
ai restart <serviço>…       # reinicia
ai status                   # estado e portas de todos os serviços
ai logs <serviço> [-f]      # logs do serviço
ai gpu                      # nvidia-smi (VRAM em uso)
ai models                   # modelos instalados e espaço ocupado
ai transcribe <ficheiro> [--language pt] [--output <pasta>]
ai tts <texto|ficheiro.txt> [--voice <voz>]
ai update                   # atualiza imagens (não inicia nada)
ai clean                    # limpa containers parados (pede confirmação)
ai backup [config|full]     # backup para backups/
ai help

Grupos: image = ComfyUI · chat = Ollama + Open WebUI · all = todos (nunca arranca sozinho).

Fluxos de trabalho

🎨 Gerar imagens

ai start image → abre 127.0.0.1:8188 → carrega um workflow de workflows/comfyui ou constrói um → resultados em output/images.

💬 Conversar com um LLM

ai start chat → abre 127.0.0.1:8180 → primeiro uso: cria conta local de admin → descarrega um modelo (ex. llama3.2) na própria UI.

🎙️ Transcrever

ai transcribe entrevista.mp4 --language pt → TXT, MD, SRT, VTT e JSON em output/transcripts. O container termina sozinho.

🔊 Texto para voz

ai tts "Olá!" ou ai tts guiao.txt → mp3 em output/audio. Arranca, gera, para e liberta a VRAM.

Modelos já instalados

Modelo	Tarefa	Notas
Z-Image Turbo fp8	Imagem (uso diário)	~15 s por imagem 1024px; workflow em `workflows/comfyui`
Qwen-Image-2512 Q4	Imagem com texto perfeito	~80 s; ideal para cartazes/azulejos/tipografia
Wan 2.2 I2V + lightning	Vídeo a partir de imagem	~40 s por clip de 2 s a 480p
`qwen3.5:9b`	Chat geral (Open WebUI)	117 tokens/s
`qwen3-vl:8b`	Visão/OCR	descrever imagens, ler documentos
`qwen3-coder-next`	Código (sem pressa)	51 GB MoE; ~13 tokens/s com offload para RAM
EuroLLM-22B	Português europeu	`ai start llama-cpp`; ~55 tokens/s
Whisper large-v3-turbo	Transcrição	`ai transcribe ficheiro --language pt`

Instalar mais modelos

Nada é descarregado automaticamente. Exemplos:

# Diffusion → models/diffusion/checkpoints (ou unet/vae/loras/…)
wget -O ~/ai-lab/models/diffusion/checkpoints/modelo.safetensors '<url do Hugging Face>'

# Ollama (com o serviço ligado)
docker compose exec ollama ollama pull llama3.2:3b

# GGUF para llama.cpp → models/llm/gguf + LLAMACPP_MODEL no .env

Com 16 GB de VRAM: SDXL e Flux (fp8/GGUF) correm bem; LLMs até ~14B em Q4; evita imagem + LLM grande em simultâneo.

Confirmar que está tudo desligado

ai stop all
ai status          # tudo "parado"
ai gpu             # 0 MiB de VRAM, "No running processes found"
docker ps          # sem containers ai-lab-*

Problemas comuns

Sintoma	Solução
“porta X já está ocupada”	Ajusta a porta no `.env` ou para o processo em conflito (`ss -tlnp \| grep X`)
llama-cpp não arranca	Define `LLAMACPP_MODEL` no `.env` e confirma que o ficheiro existe em `models/llm/gguf/`
1.º arranque lento	Está a fazer bootstrap ou a descarregar um modelo — `ai logs <serviço> -f`
Erro CUDA numa imagem nova	A RTX 5070 Ti (Blackwell) exige tags CUDA ≥ 12.8 — usa as tags fixadas no `.env`
Sem espaço	`ai models` mostra o que ocupa espaço; `ai clean` limpa imagens dangling

Documentação completa: ~/ai-lab/README.md.