Docker Compose para Agentes de IA: O que realmente mudou (e o que você precisa saber agora)

Se você acompanha o ecossistema Docker, 2025 foi o ano em que eles deixaram de ser "só a ferramenta de containerização" e viraram plataforma de IA de verdade. E o que começou como experimento virou padrão com uma velocidade impressionante — tipo aquele colega que vai a uma conferência e volta querendo reescrever tudo em Rust.

O ponto central de tudo isso é simples: modelos de IA agora são componentes de software como qualquer outro — banco de dados, cache, fila de mensagens. E se você pode containerizar um PostgreSQL, por que não containerizar um Llama 3 ou um Stable Diffusion? O Docker Compose deixou de ser exclusividade do backend tradicional e se tornou a ferramenta predileta para orquestrar agentes de IA, pipelines de RAG e APIs de inferência.

Neste artigo, vou mostrar o que realmente mudou na forma como usamos Docker Compose para IA, quais são as melhores práticas emergentes e como você pode começar hoje mesmo a rodar seus próprios agentes de IA open source em um VPS — sem depender de nuvens caras ou APIs fechadas.

1. O que mudou na prática? De infraestrutura a orquestração de agentes

Antes de 2024, Docker Compose era sinônimo de empilhamento web — um docker-compose.yml com Nginx, Node.js e PostgreSQL resolvia 90% dos problemas. Agora, a stack típica mudou:

• Modelo de IA (ex: ollama/llama3.2, vllm/vllm-openai) → equivalente ao antigo banco de dados
• Banco vetorial (ex: chromadb/chroma, qdrant/qdrant) → equivalente ao Redis/cache
• Agente/Orquestrador (ex: langchain/langgraph, crewai/crew) → equivalente ao backend
• Interface (ex: gradio/gradio, open-webui) → equivalente ao frontend

Essa mudança exige uma nova mentalidade: cada serviço agora tem dependências de GPU, memória e rede muito mais críticas do que um contêiner web comum. O Docker Compose precisou evoluir para lidar com:

• Atribuição de GPUs: deploy.resources.reservations.devices se tornou obrigatório
• Volumes massivos: modelos pesam dezenas de GB, exigem volumes dedicados
• Redes personalizadas: agentes precisam se comunicar com bancos vetoriais em baixa latência

2. Estruturando um docker-compose.yml para agentes de IA

Vamos ao código. Esse é o esqueleto moderno para rodar um agente RAG (Retrieval-Augmented Generation) com Docker Compose:

version: '3.9'

services:
  modelo:
    image: ollama/llama3.2:latest
    container_name: ollama-modelo
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - ai-net
    healthcheck:
      test: ["CMD", "ollama", "list"]
      interval: 30s
      timeout: 10s
      retries: 3

  vector-db:
    image: chromadb/chroma:latest
    container_name: chroma-db
    ports:
      - "8000:8000"
    volumes:
      - chroma_data:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE
    networks:
      - ai-net

  agente:
    image: langchain/langgraph-api:latest
    container_name: langgraph-agent
    ports:
      - "8080:8080"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - MODEL_ENDPOINT=http://modelo:11434
      - VECTOR_DB_URL=http://vector-db:8000
    depends_on:
      modelo:
        condition: service_healthy
      vector-db:
        condition: service_started
    networks:
      - ai-net
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          cpus: '2.0'

  interface:
    image: open-webui/open-webui:latest
    container_name: open-webui
    ports:
      - "3000:3000"
    environment:
      - OLLAMA_BASE_URL=http://modelo:11434
    volumes:
      - webui_data:/app/backend/data
    networks:
      - ai-net

volumes:
  ollama_data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/disco-ssd/ollama-data
  chroma_data:
  webui_data:

networks:
  ai-net:
    driver: bridge

Pontos críticos desse YAML:
- GPU reservada via deploy.resources: sem isso, o modelo roda em CPU e fica inviável
- Volumes bind para modelos grandes: evita recarregar gigabytes a cada docker compose down
- Healthcheck no modelo: o agente só sobe depois que o Ollama estiver pronto
- Rede isolada ai-net: os serviços se enxergam por nome, sem expor portas desnecessárias

3. GPU Acceleration no Docker: o gargalo que virou padrão

A documentação oficial do Docker já reconhece que aplicações GenAI frequentemente se beneficiam de aceleração GPU. Mas há nuances:

• Windows com WSL2: suporte completo via Docker Desktop. Basta ter o NVIDIA Container Toolkit instalado no subsistema Linux.
• Linux nativo: suporte direto com Docker Engine + nvidia-container-toolkit. Muito usado em VPS com GPUs (como as RTX 4090 da Hetzner ou as A100 de clouds).
• macOS: não suporta GPU acceleration para contêineres (nem Apple Silicon). Solução: usar serviços remotos ou emuladores.

Para verificar se sua GPU está disponível para o Docker:

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Se funcionar, você pode incluir --gpus all no docker run ou o bloco deploy.resources.reservations.devices no Compose.

4. Rodando em VPS: segurança, escalabilidade e performance

Subir agentes de IA em um VPS barato (tipo $10–$20/mês) virou realidade graças à otimização de modelos e ao uso de quantização (ex: Llama 3 8B Q4_K_M). Veja as práticas recomendadas:

Segurança

• Nunca exponha a API do modelo (porta 11434) publicamente. Use o proxy reverso interno via rede Docker.
• Use Docker Secrets ou variáveis de ambiente criptografadas para chaves de API (OpenAI, Hugging Face).
• Ative o userland proxy do Docker para evitar que contêineres escutem em 0.0.0.0 sem querer.

Escalabilidade

• Horizontais: múltiplas réplicas do agente com replicas: 3 e um balanceador (Traefik/Nginx) em frente.
• Verticais: aumente limites de recursos (memory: 8G, cpus: '4') até o hardware aguentar.
• Cache de embeddings: use um Redis separado para cachear consultas frequentes ao banco vetorial.

Performance

• Montagens bind para modelos: evite o driver local padrão e use device: /caminho/rapido (NVMe SSD)
• Limpeza periódica: modelos antigos (docker exec ollama ollama rm <model>) e logs (docker system prune -af)
• Monitoramento com docker stats ou integração com Prometheus/Grafana

5. Exemplo real: um agente de suporte técnico com RAG

Imagine um agente que busca em manuais técnicos internos (PDFs) e responde dúvidas de suporte. A arquitetura Docker Compose seria:

1. Ingestão: um script Python (container ingestor) que lê PDFs, gera embeddings e insere no Chroma
2. Modelo: Ollama com llama3.2:3b (leve, qualificado)
3. Agente: LangGraph com ferramentas de busca vetorial e geração de respostas
4. Interface: Gradio exposto em subdomínio com autenticação básica (nginx + htpasswd)

O docker-compose.yml ficaria similar ao exemplo anterior, mas com o serviço ingestor rodando uma única vez (profile setup):

services:
  ingestor:
    build: ./ingestor
    profiles: ["setup"]
    volumes:
      - ./manuais:/manuais
    environment:
      - CHROMA_URL=http://vector-db:8000
    depends_on:
      vector-db:
        condition: service_started

Para ingerir: docker compose --profile setup run ingestor. Para rodar o agente: docker compose up -d modelo vector-db agente interface.

Conclusão: por que você deve adotar isso agora?

A containerização de agentes de IA não é mais experimental. Empresas como a NVIDIA, LangChain e a própria Docker Inc. estão investindo pesado em tooling — desde imagens oficiais otimizadas (nvidia/cuda:12.4-runtime-ubuntu22.04 para servir modelos) até extensões do Docker Compose para orquestração de GPU.

Se você ainda está rodando scripts Python soltos no servidor, ou pior, pagando caro por APIs de terceiros para tarefas que poderiam ser feitas localmente, você está perdendo dinheiro e controle. Docker Compose te dá:

• Reprodutibilidade: sua stack de IA vira um arquivo YAML versionado no Git
• Portabilidade: do seu notebook para um VPS bare metal em minutos
• Custo: modelos open source quantizados rodam em hardware de $1000 (ou até $200/mês alugado)

O futuro da IA é auto-hospedado e containerizado. Comece com um docker compose up e veja a mágica acontecer.

Quer se aprofundar? Deixe nos comentários qual stack de IA você mais usa — podemos criar um tutorial passo a passo para ela.