JoyCaption, TagGUI, e AICaptionHelper

TL;DR

• JoyCaption Alpha 2 processa 21 imagens em 45 segundos numa 3090
• TagGUI roda em GPU ou CPU com interface gráfica
• AICaptionHelper oferece integração interativa com API OpenAI

Por Que Isso Importa

Treinar modelos Stable Diffusion exige datasets de imagens pareadas com descrições de texto precisas. Durante o treinamento, a descrição de texto é codificada no modelo anexada aos dados vetoriais, para que o Stable Diffusion possa usar esse texto (ou variações) para gerar imagens depois. Escrever legendas manualmente para centenas ou milhares de imagens é tedioso, e a qualidade dessas legendas afeta diretamente o comportamento do modelo.

VLMs de código aberto recentes mudaram a equação. Modelos como CogVLM e LLaVA agora produzem legendas com profundidade descritiva suficiente para aproveitar as capacidades de codificação de texto do SDXL — capturando emoções, iluminação, composição e humor, em vez de apenas nomear objetos. Duas abordagens de processamento em lote surgiram: scripts CLI que rodam sem supervisão sobre um diretório de imagens, e aplicações desktop que permitem revisar e editar resultados interativamente.

Três Principais Soluções

Ferramenta | VRAM | Suporte a Modelos | Processamento em Lote | Fonte | Melhor Para

|------|------|---------------|------------------|--------|----------

JoyCaption Alpha 2 | 19–22 GB (padrão); ~10 GB (baixo VRAM) | Llama-3.1 8B + SigLIP-So400M | Lote 8 na 3090; lote 16 em baixo VRAM | GitHub | Setups com GPU TagGUI | GPU ou CPU | BLIP-2, LLaVA, CogVLM, outros via Hugging Face | Legendagem baseada em GUI | GitHub | Hardware misto AICaptionHelper | Não documentado | API OpenAI (opcional) | Por imagem, interativo | Civitai | Integração OpenAI As três ferramentas diferem em custo, fluxo de trabalho e requisitos de hardware. JoyCaption e TagGUI são gratuitas e de código aberto, enquanto AICaptionHelper roda no navegador com custos opcionais de API OpenAI. Para fluxos de trabalho relacionados, veja construção automatizada de dataset e setup ComfyUI para benchmark.

JoyCaption Alpha 2

Arquitetura e Configuração

JoyCaption Alpha 2 roda no modelo fancyfeast/llama-joycaption-alpha-two-hf-llava hospedado no Hugging Face. O modelo combina meta-llama/Llama-3.1-8B-Instruct como backbone de linguagem com google/siglip-so400m-patch14-384 como codificador de visão. O script de lote usa LlavaForConditionalGeneration do Hugging Face Transformers.

A configuração requer clonar o repositório joy-caption-batch e rodar o script de lote (batch-alpha2.py). O script processa imagens de um subdiretório /input por padrão, configurável com --input-dir.

Para fluxos de trabalho relacionados, veja fluxo de trabalho de consistência de personagem.

Desempenho

Numa 3090 com 24GB VRAM, contagem de lote 8 processa 21 imagens em cerca de 45 segundos, versus 3 minutos com tamanho de lote 1 — aproximadamente 4× de melhoria (fonte). Parâmetros de amostragem padrão são temperatura 0.5 e top-k 10 com top-p 0.9.

Modo padrão precisa 19–22GB VRAM. A versão Pre-Alpha oferece modo de baixo VRAM que carrega uma variante quantizada llama3-8b-bnb-4bit da Unsloth, baixando o requisito para cerca de 10GB. Modo de baixo VRAM não está disponível no Alpha 2. Com Pre-Alpha em modo de baixo VRAM numa 3090, a contagem de lote pode chegar a 16.

Seleção de Prompt

O script vem com vários templates de prompt integrados. O padrão — "Please provide a detailed description of the image" — produz legendas em prosa longa. Outras opções incluem descrições curtas, prompts para Stable Diffusion, prompts para MidJourney, listas de tags estilo Booru, e legendas para redes sociais. Também pode carregar um arquivo JSON de prompt personalizado com entradas ponderadas.

Entrada/Saída de Arquivos

O script escreve arquivos .txt de legenda ao lado de cada imagem por padrão. Formato de saída pode ser txt ou json. Flags adicionais incluem --recursive (processa subpastas), --prepend-string e --append-string (envolve toda legenda), e --overwrite (substitui arquivos existentes). Veja fpgaminer/joycaption para o script de lote original.

TagGUI

Suporte a Modelos

TagGUI é uma aplicação desktop multiplataforma para tagging e legendagem de datasets de imagens. Conecta-se aos model hubs do Hugging Face e suporta múltiplos backends de legendagem incluindo BLIP-2, LLaVA, e CogVLM — este último detalhado no model card THUDM/cogvlm2-llama3-chat-19B. A avaliação de usuário no Civitai destaca a qualidade detalhada das legendas do CogVLM para datasets de 90 imagens.

CogVLM2 lida com até 8K tokens e imagens até 1344×1344 pixels, marcando 84.2 no TextVQA. Usuários podem apontar TagGUI para um diretório de modelo local nas Configurações para evitar downloads repetidos. Carregamentos de modelo na primeira vez levam vários minutos; carregamentos subsequentes são muito mais rápidos.

Legendagem em Lote

Selecione imagens na lista de imagens, escolha um modelo no painel Auto-Captioner, e clique Iniciar Auto-Legendagem. A aplicação baixa modelos no primeiro uso e os armazena em cache localmente. O campo de prompt aceita variáveis de template: {tags} insere tags existentes, {name} insere o nome do arquivo, e {directory} insere o nome da pasta. Também pode definir palavras a desencorajar ou exigir na saída.

Gestão de Tags

TagGUI lê arquivos .txt com nomes correspondentes aos das imagens e auto-salva toda edição. A caixa de filtragem suporta prefixos: tag: para correspondência de tag, caption: para busca no texto da legenda, name: para padrões de nome de arquivo, e path: para caminhos completos de diretório. Filtros numéricos também funcionam — tags:>10 encontra imagens com mais de 10 tags; tokens:<75 encontra legendas com menos de 75 tokens.

Combinado com operadores AND, OR, e NOT mais parênteses para precedência, isso permite criar consultas como tag:gato AND tokens:<=75 para encontrar imagens de gatos com poucas tags. Atalhos de teclado aceleram trabalho em massa: Ctrl+J salta para a primeira imagem sem tag, Ctrl+R abre Localizar e Substituir, e Ctrl+B abre Reordenar Tags em Lote. Para consistência de personagem durante treinamento, veja fluxo de trabalho de consistência de personagem.

AICaptionHelper

AICaptionHelper é hospedado no Civitai. Combina palavras-chave fornecidas pelo usuário com refinamento opcional via API OpenAI para produzir legendas. Usuários descrevem suas imagens em campos estruturados — sujeito, penteado, atividade, local, expressões — e a ferramenta monta uma legenda a partir dessas entradas. Uma chave de API OpenAI é opcional; sem uma, a ferramenta salva exatamente o que você digita. Com uma, a API OpenAI refina ortografia, gramática, e fluidez da linguagem natural.

Nenhum repositório GitHub independente ou documentação autônoma foi encontrado além do artigo do Civitai, então detalhes sobre seus internos são limitados a essa fonte.

Erros Comuns e Correções

Sintoma | Causa | Correção | Fonte

|---------|-------|-----|--------

JoyCaption Alpha 2 não inicia na GPU | Alpha 2 requer 19–22GB VRAM | Use Pre-Alpha com LOW_VRAM_MODE=true (~10GB necessário) | GitHub README Saída de tags Booru entra em loop no Alpha 2 | Modelo sem penalidade de repetição | Ainda não corrigido; penalidade de repetição necessária | Civitai TagGUI não encontra minhas imagens | Tags carregam de arquivos .txt com nomes correspondentes | Verifique convenções de nomeação e carregue diretório via Arquivo > Carregar Diretório | GitHub README Script JoyCaption não localiza CUDA | CUDA não no PATH ou GPU errada | Defina CUDA_VISIBLE_DEVICES="0" próximo ao topo do script | GitHub README

Perguntas Frequentes (FAQ)

Quanto VRAM o JoyCaption precisa? Alpha 2 precisa 19–22GB. Pre-Alpha com modo de baixo VRAM precisa cerca de 10GB (fonte).

Posso processar imagens em lote com JoyCaption? Sim. Coloque imagens em /input e rode o script de lote. Configure contagem de lote com --batch-processing-count. Numa 3090, lote 8 dá aproximadamente 4× o throughput de lote 1.

Quais modelos o TagGUI suporta? BLIP-2, LLaVA, CogVLM, e outros disponíveis via Hugging Face. Geração em GPU e CPU são suportadas (fonte).

TagGUI funciona offline? Sim, após o primeiro download do modelo. Modelos ficam em cache localmente.

Quais formatos de imagem funcionam com essas ferramentas? JoyCaption suporta JPG, JPEG, PNG, BMP, GIF, TIFF, e WebP. TagGUI tem suporte de formato similar via PIL/Pillow.