🎨 Geração de Imagens com IA Local

Serviço profissional de geração de imagens com IA usando a biblioteca diffusers e arquitetura event-driven.

🏗️ Arquitetura

Event-Driven + Task Queue

✅ REST API (FastAPI) para submissão
✅ Task Queue para processamento assíncrono
✅ WebSockets para updates em tempo real
✅ Modular - suporte a múltiplos modelos
✅ Escalável - workers configuráveis

Estrutura do Projeto

├── src/
│   ├── api/            # REST API (FastAPI)
│   ├── core/           # Classes base e interfaces
│   ├── models/         # Geradores de modelos específicos
│   ├── services/       # Serviços de negócio
│   └── cli.py          # Interface de linha de comando
├── config/             # Configurações
├── output/             # Imagens geradas
├── logs/               # Logs da aplicação
├── tests/              # Testes automatizados
├── server.py           # Servidor principal
└── ai-image            # CLI client

🚀 Quick Start

1. Instalação Automática

# Script de configuração automática
./setup.sh

# Ou instalação manual
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows
pip install -r requirements.txt

2. Iniciar Servidor

# Método recomendado
source venv/bin/activate
python server.py

# Método alternativo com Uvicorn
source venv/bin/activate
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

# Usando Docker
./docker-run.sh up

3. Usando a Interface CLI

# Gerar uma imagem via linha de comando
./ai-image generate --prompt "Um astronauta cavalgando um cavalo no espaço"

# Verificar status de tarefas
./ai-image status --task-id abc123

# Ver opções disponíveis
./ai-image --help

3. Usar CLI

# Gerar imagem
./ai-image generate -p "A dragon in a mystical forest" -w 768 -h 768 -s 50

# Acompanhar progresso
./ai-image watch <task_id>

# Listar tarefas
./ai-image list

# Ver fila
./ai-image queue

4. Usar API REST

# Submeter geração (versão simples - apenas o prompt é obrigatório)
curl -X POST "http://localhost:8000/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A majestic dragon"
  }'

# Submeter geração (versão completa com parâmetros personalizados)
curl -X POST "http://localhost:8000/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A majestic dragon flying over mountains at sunset",
    "negative_prompt": "blurry, bad quality, distorted, low resolution",
    "width": 768,
    "height": 768,
    "num_inference_steps": 40,
    "guidance_scale": 8.5,
    "model": "stable-diffusion-v1.5",
    "seed": 42,
    "num_images_per_prompt": 2
  }'

# Verificar status
curl "http://localhost:8000/task/{task_id}"

# Baixar imagem
curl "http://localhost:8000/image/{task_id}/1" -o imagem.png

# Listar todas as tarefas (últimas 50)
curl "http://localhost:8000/tasks"

# Listar tarefas por status
curl "http://localhost:8000/tasks?status=completed&limit=10"

📡 WebSocket (Tempo Real)

Monitoramento de Tarefa

// Monitorar uma tarefa específica em tempo real
const ws = new WebSocket(`ws://localhost:8000/ws/task/${taskId}`);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Status: ${data.status}`);
  console.log(`Progresso: ${data.progress}%`);
  console.log(`Mensagem: ${data.message}`);
  
  if (data.status === "completed") {
    console.log(`Imagens geradas: ${data.output_paths.length}`);
    console.log(`Tempo de geração: ${data.generation_time} segundos`);
  }
};

Monitoramento de Performance do Sistema

// Monitorar métricas de sistema em tempo real
const ws = new WebSocket("ws://localhost:8000/ws/performance");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`CPU: ${data.system.cpu_percent}%`);
  console.log(`Memória: ${data.system.memory_percent}%`);
  console.log(`Tarefas ativas: ${data.application.active_tasks}`);
  console.log(`Tamanho da fila: ${data.application.queue_size}`);
};

🤖 Modelos Suportados

Modelo	Resolução	Memória	Tempo (M3 Pro)	Casos de uso
Stable Diffusion v1.5	512x512	~2GB	~20s	Uso geral, rápido e eficiente
Stable Diffusion XL	1024x1024	~6GB	~60s	Alta qualidade, detalhamento superior
Qwen-Image	1024x1024	~20GB	~120s	Fidelidade extrema, compreensão de texto complexa

Exemplos de Imagens Geradas

Prompt: "A beautiful cyberpunk cityscape with neon lights"

⚙️ Configuração Completa

GenerationRequest (Todos os Parâmetros)

Todos os parâmetros exceto prompt são opcionais e têm valores padrão que garantem uma qualidade equilibrada de geração.

{
  # Básico (apenas prompt é obrigatório)
  "prompt": "A beautiful landscape", # Obrigatório - descrição do que você deseja gerar
  "negative_prompt": "blurry, low quality", # Opcional (padrão: "") - o que evitar na imagem
  "model": "stable-diffusion-v1.5", # Opcional (padrão: "stable-diffusion-v1.5") - modelo a ser usado
  "scheduler": "euler_discrete", # Opcional (padrão: "euler_discrete") - algoritmo de difusão
  
  # Dimensões
  "width": 768, # Opcional (padrão: 512) - largura em pixels
  "height": 768, # Opcional (padrão: 512) - altura em pixels
  
  # Qualidade
  "num_inference_steps": 50, # Opcional (padrão: 20) - passos de inferência (mais = melhor qualidade, mais lento)
  "guidance_scale": 12.0, # Opcional (padrão: 7.5) - aderência ao prompt (mais alto = mais fiel ao prompt)
  "num_images_per_prompt": 1, # Opcional (padrão: 1) - número de imagens para gerar (1-4)
  
  # Reproduzibilidade
  "seed": 123456, # Opcional (padrão: aleatório) - semente para resultados reproduzíveis
  "eta": 0.0, # Opcional (padrão: 0.0) - quantidade de ruído para adicionar (0.0-1.0)
  
  # Pós-processamento
  "enhance_sharpness": 1.2, # Opcional (padrão: 1.0) - aumenta nitidez
  "enhance_contrast": 1.1, # Opcional (padrão: 1.0) - aumenta contraste
  "enhance_color": 1.15, # Opcional (padrão: 1.0) - aumenta saturação de cores
  "enhance_brightness": 1.05, # Opcional (padrão: 1.0) - aumenta brilho
  "apply_unsharp_mask": true, # Opcional (padrão: false) - aplica máscara de nitidez
  
  # Performance
  "use_attention_slicing": true, # Opcional (padrão: true) - reduz uso de memória
  "use_cpu_offload": false, # Opcional (padrão: false) - usa CPU para partes do modelo
  "use_vae_slicing": true # Opcional (padrão: true) - processa VAE em partes para economizar memória
}

Configurações de Ambiente (.env)

AI_IMAGE_HOST=0.0.0.0
AI_IMAGE_PORT=8000
AI_IMAGE_MAX_WORKERS=2
AI_IMAGE_OUTPUT_DIR=output
AI_IMAGE_CACHE_DIR=.cache
AI_IMAGE_DEBUG=false
AI_IMAGE_LOG_LEVEL=INFO

🎯 Casos de Uso

1. Desenvolvimento Local

# Iniciar servidor
python server.py

# Gerar imagem básica
./ai-image generate -p "A cyberpunk city" --watch

2. Produção/API

# Servidor robusto
uvicorn src.api.main:app --workers 4 --host 0.0.0.0

# Integração com sistemas
POST /generate + WebSocket /ws/{task_id}

3. Batch Processing

# Múltiplas imagens
for prompt in prompts.txt; do
  ./ai-image generate -p "$prompt" --priority 1
done

# Monitorar fila
./ai-image queue

🔧 Extensibilidade

Adicionar Novo Modelo

Criar classe em src/models/novo_modelo.py
Herdar de BaseImageGenerator
Implementar métodos abstratos
Registrar em generation_service.py

Adicionar Middleware

# src/api/main.py
@app.middleware("http")
async def custom_middleware(request, call_next):
    # Sua lógica aqui
    response = await call_next(request)
    return response

📊 Monitoring

Health Check

curl http://localhost:8000/health

Métricas da Fila

curl http://localhost:8000/queue/info

Performance

CPU/RAM em tempo real
Tempo médio por imagem
Taxa de falhas
Throughput

🧪 Testes

# Testes unitários
pytest tests/

# Teste de carga
python tests/load_test.py

# Teste de integração
python tests/integration_test.py

🐳 Docker

O projeto oferece suporte completo para execução em contêineres Docker, facilitando a implantação e escalabilidade.

Inicialização rápida com Docker

# Iniciar o serviço
./docker-run.sh up

# Verificar logs
./docker-run.sh logs

# Parar o serviço
./docker-run.sh down

docker-compose.yml

version: '3.8'
services:
  image-ai:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - ./output:/app/output
      - ./logs:/app/logs
    environment:
      - AI_IMAGE_DEBUG=true
      - AI_IMAGE_HOST=0.0.0.0
      - AI_IMAGE_PORT=8000
      - AI_IMAGE_MAX_WORKERS=2
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 5

Construção manual

# Construir a imagem
docker build -t image-ai:latest .

# Executar o container
docker run -p 8000:8000 -v $(pwd)/output:/app/output -v $(pwd)/logs:/app/logs image-ai:latest

🤝 Contribuição

Fork o projeto
Criar branch: git checkout -b feature/nova-feature
Commit: git commit -m 'Adiciona nova feature'
Push: git push origin feature/nova-feature
Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja LICENSE para mais detalhes.

🔗 Links Úteis

API Docs: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
Health: http://localhost:8000/health

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
config		config
output/samples		output/samples
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
ai-image		ai-image
docker-compose.yml		docker-compose.yml
docker-run.sh		docker-run.sh
main.py		main.py
requirements.txt		requirements.txt
security_check.py		security_check.py
server.py		server.py
setup.sh		setup.sh
test_websocket.py		test_websocket.py

License

vhrita/image-ai

Folders and files

Latest commit

History

Repository files navigation