Implantação de Stack Completa de IA com Docker Compose: Orquestração em Um Clique do LLM ao Banco de Dados Vetorial

DevOps

Configurar um Ambiente de Desenvolvimento de IA Ainda Leva Três Dias?

Em 2026, a configuração do ambiente de desenvolvimento de IA continua sendo um pesadelo para desenvolvedores. Você precisa instalar o Ollama para o serviço LLM, configurar o Qdrant para armazenamento vetorial, configurar serviços de embedding, construir um gateway de API para autenticação e lidar com drivers de GPU, versões de CUDA e downloads de modelos... Três dias se foram, e você não escreveu uma única linha de código.

A implantação de stack completa de IA com Docker Compose orquestra tudo em um único arquivo. docker compose up -d lança toda a stack de IA em minutos. Este artigo é um guia prático completo cobrindo 7 padrões principais, 5 armadilhas comuns, 10 etapas de solução de problemas e estratégias de endurecimento para produção.

Pontos-chave

  • Implantação de stack completa de IA com Docker Compose = LLM + Banco de Dados Vetorial + Embedding + Gateway de API + Monitoramento, um arquivo para governar todos
  • Ollama + OpenWebUI é a solução de serviço LLM local mais madura
  • Qdrant/Milvus são os bancos de dados vetoriais de referência com implantação Docker ultrassimples
  • Passthrough de GPU é crítico para implantação de IA — configure via deploy.resources.reservations.devices
  • Produção requer autenticação, limitação de taxa, monitoramento e endurecimento de backups

Sumário

  • Visão Geral da Arquitetura de Stack Completa de IA
  • Padrão 1: Serviço LLM com Ollama + OpenWebUI
  • Padrão 2: Bancos de Dados Vetoriais Qdrant/Milvus
  • Padrão 3: Serviços de Embedding e Gerenciamento de Modelos
  • Padrão 4: Gateway de API e Autenticação
  • Padrão 5: Passthrough de GPU e Limites de Recursos
  • Padrão 6: Monitoramento e Observabilidade
  • Padrão 7: Endurecimento para Produção e Segurança
  • 5 Armadilhas Comuns e Soluções
  • 10 Soluções de Erros Comuns
  • Dicas Avançadas de Otimização
  • Comparação: Docker Compose vs K8s vs Docker Swarm
  • Ferramentas Online Recomendadas
  • Resumo

Visão Geral da Arquitetura de Stack Completa de IA

A implantação de stack completa de IA com Docker Compose é construída sobre uma arquitetura de 7 camadas, da GPU na base ao gateway de API no topo:

┌─────────────────────────────────────────────────────┐
│                   API Gateway                        │
│              (Traefik / Nginx)                       │
│         Auth · Rate Limit · Routing · TLS            │
├──────────┬──────────┬──────────┬────────────────────┤
│ OpenWebUI│  RAG App │  Agent   │  Admin Panel       │
│  (Chat)  │ (Search) │  (Proxy) │  (Management)      │
├──────────┴──────────┴──────────┴────────────────────┤
│              Embedding Service                       │
│       (TEI / Infinity / FastEmbed)                  │
├──────────────────┬──────────────────────────────────┤
│   Ollama LLM     │    vLLM / TGI                    │
│  (Model Serving) │  (High-Perf Inference)           │
├──────────────────┴──────────────────────────────────┤
│           Vector Database                            │
│     (Qdrant / Milvus / Weaviate)                    │
├─────────────────────────────────────────────────────┤
│              Infrastructure                          │
│   Redis · PostgreSQL · MinIO · Prometheus            │
├─────────────────────────────────────────────────────┤
│              GPU / CPU Runtime                       │
│     NVIDIA CUDA · ROCm · CPU Fallback               │
└─────────────────────────────────────────────────────┘

Estrutura de diretórios do projeto para implantação de stack completa de IA com Docker Compose:

ai-stack/
├── docker-compose.yml
├── docker-compose.gpu.yml
├── docker-compose.prod.yml
├── .env
├── ollama/
│   └── Modelfile
├── qdrant/
│   └── config.yaml
├── traefik/
│   ├── traefik.yml
│   └── acme.json
├── monitoring/
│   ├── prometheus.yml
│   └── grafana/
│       └── dashboards/
└── scripts/
    ├── init-models.sh
    └── backup-vectors.sh

Padrão 1: Serviço LLM com Ollama + OpenWebUI

Ollama é a solução de serviço LLM local mais madura em 2026, suportando Llama 4, Qwen 3, DeepSeek V3 e outros modelos mainstream. OpenWebUI fornece uma interface web estilo ChatGPT.

Configuração Básica

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      OLLAMA_KEEP_ALIVE: "24h"
      OLLAMA_NUM_PARALLEL: "4"
      OLLAMA_MAX_LOADED_MODELS: "3"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    volumes:
      - open_webui_data:/app/backend/data
    environment:
      OLLAMA_BASE_URL: "http://ollama:11434"
      WEBUI_SECRET_KEY: "${WEBUI_SECRET_KEY}"
      ENABLE_SIGNUP: "false"
      DEFAULT_USER_ROLE: "user"
    depends_on:
      ollama:
        condition: service_healthy
    restart: unless-stopped

volumes:
  ollama_data:
  open_webui_data:

Download Automático de Modelos

Após iniciar o Ollama, você precisa baixar modelos manualmente. Automatize isso com um script de inicialização:

#!/bin/bash
# scripts/init-models.sh

MODELS=(
  "qwen3:8b"
  "llama4:8b"
  "deepseek-v3:8b"
  "nomic-embed-text"
)

for model in "${MODELS[@]}"; do
  echo "Pulling model: $model"
  until curl -s http://localhost:11434/api/pull -d "{\"name\":\"$model\"}" | grep -q "success"; do
    echo "  Retrying $model..."
    sleep 5
  done
  echo "  ✓ $model ready"
done

echo "All models pulled successfully!"

Adicione o serviço de inicialização ao Docker Compose:

  model-init:
    image: curlimages/curl:latest
    container_name: model-init
    depends_on:
      ollama:
        condition: service_healthy
    volumes:
      - ./scripts/init-models.sh:/init-models.sh:ro
    entrypoint: ["/bin/sh", "/init-models.sh"]
    restart: "no"

Modelfile Personalizado

# ollama/Modelfile
FROM qwen3:8b

PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER stop "<|im_end|>"

SYSTEM """
You are a professional AI assistant. When answering questions:
1. Give a concise conclusion first
2. Then provide detailed explanation
3. If uncertain, say so explicitly
"""

Construa um modelo personalizado:

docker exec ollama ollama create my-assistant -f /root/.ollama/Modelfile

Padrão 2: Bancos de Dados Vetoriais Qdrant/Milvus

Bancos de dados vetoriais são o núcleo da arquitetura RAG. A implantação de stack completa de IA com Docker Compose geralmente usa Qdrant (leve) ou Milvus (larga escala).

Configuração do Qdrant (Recomendado para Projetos de Pequeno-Médio Porte)

  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_data:/qdrant/storage
      - ./qdrant/config.yaml:/qdrant/config/production.yaml:ro
    environment:
      QDRANT__SERVICE__GRPC_PORT: "6334"
      QDRANT__LOG_LEVEL: "INFO"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6333/healthz"]
      interval: 10s
      timeout: 5s
      retries: 3
    restart: unless-stopped

Arquivo de configuração do Qdrant:

# qdrant/config.yaml
storage:
  performance:
    max_search_threads: 4
  wal:
    wal_capacity_mb: 32
    wal_segments_ahead: 0
  optimizers:
    indexing_threshold: 20000
    memmap_threshold: 50000
service:
  max_request_size_mb: 64
  enable_cors: true
telemetry_disabled: true

Configuração do Milvus (Recomendado para Projetos de Larga Escala)

  etcd:
    image: quay.io/coreos/etcd:v3.5.16
    container_name: milvus-etcd
    environment:
      ETCD_AUTO_COMPACTION_MODE: "revision"
      ETCD_AUTO_COMPACTION_RETENTION: "1000"
      ETCD_QUOTA_BACKEND_BYTES: "4294967296"
    volumes:
      - etcd_data:/etcd
    command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379
    restart: unless-stopped

  minio:
    image: minio/minio:latest
    container_name: milvus-minio
    environment:
      MINIO_ACCESS_KEY: "${MINIO_ACCESS_KEY}"
      MINIO_SECRET_KEY: "${MINIO_SECRET_KEY}"
    ports:
      - "9001:9001"
      - "9000:9000"
    volumes:
      - minio_data:/minio_data
    command: minio server /minio_data --console-address ":9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3
    restart: unless-stopped

  milvus:
    image: milvusdb/milvus:v2.5-latest
    container_name: milvus
    ports:
      - "19530:19530"
      - "9091:9091"
    volumes:
      - milvus_data:/var/lib/milvus
    environment:
      ETCD_ENDPOINTS: "etcd:2379"
      MINIO_ADDRESS: "minio:9000"
    depends_on:
      - etcd
      - minio
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      timeout: 20s
      retries: 3
      start_period: 90s
    restart: unless-stopped

Comparação de Bancos de Dados Vetoriais

Característica Qdrant Milvus Weaviate ChromaDB
Complexidade de Implantação Muito Baixa (1 contêiner) Alta (3+ contêineres) Baixa (1 contêiner) Muito Baixa (1 contêiner)
Desempenho (Milhões) Excelente Excelente Bom Regular
Desempenho (Bilhões) Bom Excelente Regular N/A
Busca Filtrada ✅ Poderosa ✅ Poderosa ✅ Boa ⚠️ Básica
Persistência ✅ ✅ ✅ ⚠️ Em memória por padrão
Multi-réplica ✅ ✅ ✅ ❌
Suporte gRPC ✅ ✅ ❌ ❌
Compatibilidade com Docker Compose ✅ Melhor ⚠️ Pesado ✅ Bom ✅ Apenas desenvolvimento
Pronto para Produção ✅ ✅ ✅ ❌ Apenas desenvolvimento

Recomendação: Para implantação de stack completa de IA com Docker Compose, Qdrant é a primeira escolha — implantação simples, desempenho excelente. Considere Milvus quando a contagem de vetores exceder 100 milhões. ChromaDB é adequado apenas para prototipagem.

Padrão 3: Serviços de Embedding e Gerenciamento de Modelos

Serviços de embedding convertem texto em vetores, uma etapa crítica no pipeline RAG. A orquestração de contêineres Docker Compose AI oferece três soluções principais.

Hugging Face TEI (Recomendado)

  tei:
    image: ghcr.io/huggingface/text-embeddings-inference:latest
    container_name: tei
    ports:
      - "8080:80"
    volumes:
      - tei_cache:/data
    environment:
      MODEL_ID: "BAAI/bge-m3"
      REVISION: "main"
      MAX_BATCH_TOKENS: "16384"
      MAX_CLIENT_BATCH_SIZE: "32"
      HF_TOKEN: "${HF_TOKEN}"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 120s
    restart: unless-stopped

Serviço de Embedding Infinity

  infinity:
    image: michaelf34/infinity:latest
    container_name: infinity
    ports:
      - "7997:7997"
    volumes:
      - infinity_cache:/app/.cache
    environment:
      MODEL_ID: "BAAI/bge-m3"
      ENGINE: "optimum"
      BATCH_SIZE: "32"
    command: >
      --model-id BAAI/bge-m3
      --engine optimum
      --port 7997
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7997/health"]
      interval: 10s
      timeout: 5s
      retries: 3
    restart: unless-stopped

Exemplo de Uso do Serviço de Embedding

import httpx
import numpy as np

async def get_embeddings(texts: list[str]) -> list[list[float]]:
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.post(
            "http://tei:80/embed",
            json={"inputs": texts}
        )
        response.raise_for_status()
        return response.json()

async def search_similar(query: str, top_k: int = 5) -> list[dict]:
    query_embedding = await get_embeddings([query])
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.post(
            "http://qdrant:6333/collections/documents/points/search",
            json={
                "vector": query_embedding[0],
                "limit": top_k,
                "with_payload": True
            }
        )
        response.raise_for_status()
        return response.json()["result"]

Comparação de Serviços de Embedding

Característica TEI Infinity FastEmbed
Aceleração GPU ✅ Nativa ✅ Nativa ❌ Apenas CPU
Inferência em Lote ✅ Eficiente ✅ Eficiente ⚠️ Regular
Multi-modelo ✅ ✅ ✅
Tamanho da Imagem Docker ~2GB ~4GB ~500MB
Pronto para Produção ✅ ✅ ⚠️ Apenas desenvolvimento
API Compatível com OpenAI ✅ ✅ ❌

Padrão 4: Gateway de API e Autenticação

A implantação de stack completa de IA com Docker Compose em produção requer um gateway de API para autenticação unificada, limitação de taxa e roteamento.

Configuração do Traefik

  traefik:
    image: traefik:v3.2
    container_name: traefik
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik/traefik.yml:/etc/traefik/traefik.yml:ro
      - traefik_certs:/etc/traefik/certs
      - ./traefik/dynamic:/etc/traefik/dynamic:ro
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.file.directory=/etc/traefik/dynamic"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
    labels:
      traefik.enable: "true"
      traefik.http.routers.traefik.rule: "Host(`traefik.ai-stack.local`)"
      traefik.http.routers.traefik.entrypoints: "websecure"
      traefik.http.routers.traefik.tls: "true"
      traefik.http.services.traefik.loadbalancer.server.port: "8080"
    restart: unless-stopped

OpenWebUI com Traefik

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    volumes:
      - open_webui_data:/app/backend/data
    environment:
      OLLAMA_BASE_URL: "http://ollama:11434"
    labels:
      traefik.enable: "true"
      traefik.http.routers.webui.rule: "Host(`chat.ai-stack.local`)"
      traefik.http.routers.webui.entrypoints: "websecure"
      traefik.http.routers.webui.tls: "true"
      traefik.http.services.webui.loadbalancer.server.port: "8080"
    depends_on:
      ollama:
        condition: service_healthy
    restart: unless-stopped

Middleware de Autenticação

# traefik/dynamic/auth.yml
http:
  middlewares:
    auth-middleware:
      forwardAuth:
        address: "http://auth-service:8000/verify"
        trustForwardHeader: true
        authResponseHeaders:
          - "X-User-Id"
          - "X-User-Role"

    rate-limit:
      rateLimit:
        average: 30
        burst: 60
        period: 1m

  routers:
    api-router:
      rule: "Host(`api.ai-stack.local`)"
      entrypoints:
        - "websecure"
      tls: true
      middlewares:
        - "auth-middleware"
        - "rate-limit"
      service: "ollama-api"

Padrão 5: Passthrough de GPU e Limites de Recursos

A GPU é o núcleo da implantação de IA. A implantação de stack completa de IA com Docker Compose habilita o passthrough de GPU via deploy.resources.reservations.devices.

Passthrough de GPU NVIDIA

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
        limits:
          memory: 16G
          cpus: "8.0"
    environment:
      NVIDIA_VISIBLE_DEVICES: "all"
      NVIDIA_DRIVER_CAPABILITIES: "compute,utility"
      OLLAMA_KEEP_ALIVE: "24h"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

Alocação Multi-GPU

  ollama:
    image: ollama/ollama:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]
              capabilities: [gpu]
    environment:
      CUDA_VISIBLE_DEVICES: "0"

  tei:
    image: ghcr.io/huggingface/text-embeddings-inference:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["1"]
              capabilities: [gpu]
    environment:
      CUDA_VISIBLE_DEVICES: "1"

Configuração de Fallback para CPU

  ollama-cpu:
    image: ollama/ollama:latest
    profiles: ["cpu-only"]
    container_name: ollama
    volumes:
      - ollama_data:/root/.ollama
    environment:
      OLLAMA_NUM_PARALLEL: "2"
      OLLAMA_MAX_LOADED_MODELS: "1"
    deploy:
      resources:
        limits:
          memory: 8G
          cpus: "4.0"

  ollama-gpu:
    image: ollama/ollama:latest
    profiles: ["gpu"]
    container_name: ollama
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
        limits:
          memory: 16G

Comandos de inicialização:

# Modo GPU
docker compose --profile gpu up -d

# Modo CPU
docker compose --profile cpu-only up -d

Script de Monitoramento de Recursos GPU

import subprocess
import json
import time

def monitor_gpu_usage(interval: int = 60):
    while True:
        result = subprocess.run(
            ["nvidia-smi", "--query-gpu=index,name,memory.used,memory.total,utilization.gpu",
             "--format=csv,noheader,nounits"],
            capture_output=True, text=True
        )
        for line in result.stdout.strip().split("\n"):
            idx, name, mem_used, mem_total, util = line.split(", ")
            print(f"GPU {idx} ({name}): {mem_used}/{mem_total}MB, Util: {util}%")
        time.sleep(interval)

if __name__ == "__main__":
    monitor_gpu_usage()

Padrão 6: Monitoramento e Observabilidade

O monitoramento da implantação de stack completa de IA com Docker Compose precisa cobrir utilização de GPU, latência de inferência, desempenho do banco de dados vetorial e outras métricas específicas de IA.

Prometheus + Grafana

  prometheus:
    image: prom/prometheus:v3.2.0
    container_name: prometheus
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.retention.time=30d"
      - "--storage.tsdb.retention.size=10GB"
    ports:
      - "9090:9090"
    restart: unless-stopped

  grafana:
    image: grafana/grafana:11.5.0
    container_name: grafana
    volumes:
      - grafana_data:/var/lib/grafana
      - ./monitoring/grafana/dashboards:/etc/grafana/provisioning/dashboards:ro
      - ./monitoring/grafana/datasources:/etc/grafana/provisioning/datasources:ro
    environment:
      GF_SECURITY_ADMIN_USER: "${GRAFANA_USER}"
      GF_SECURITY_ADMIN_PASSWORD: "${GRAFANA_PASSWORD}"
      GF_USERS_ALLOW_SIGN_UP: "false"
    ports:
      - "3001:3000"
    depends_on:
      - prometheus
    restart: unless-stopped

  dcgm-exporter:
    image: nvidia/dcgm-exporter:latest
    container_name: dcgm-exporter
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "9400:9400"
    restart: unless-stopped

Configuração do Prometheus

# monitoring/prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "ollama"
    static_configs:
      - targets: ["ollama:11434"]
    metrics_path: "/metrics"
    scrape_interval: 30s

  - job_name: "qdrant"
    static_configs:
      - targets: ["qdrant:6333"]
    metrics_path: "/metrics"
    scrape_interval: 30s

  - job_name: "dcgm"
    static_configs:
      - targets: ["dcgm-exporter:9400"]
    scrape_interval: 10s

  - job_name: "node-exporter"
    static_configs:
      - targets: ["node-exporter:9100"]

  - job_name: "traefik"
    static_configs:
      - targets: ["traefik:8080"]

Regras de Alerta Principais

# monitoring/alerts.yml
groups:
  - name: ai-stack
    rules:
      - alert: OllamaHighLatency
        expr: histogram_quantile(0.95, rate(ollama_request_duration_seconds_bucket[5m])) > 30
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Latência de inferência do Ollama muito alta"

      - alert: GPUMemoryHigh
        expr: DCGM_FI_DEV_FB_USED / DCGM_FI_DEV_FB_TOTAL > 0.9
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Uso de memória GPU excede 90%"

      - alert: QdrantHighLatency
        expr: histogram_quantile(0.95, rate(qdrant_request_duration_seconds_bucket[5m])) > 5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Latência de consulta do Qdrant muito alta"

      - alert: OllamaContainerDown
        expr: up{job="ollama"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Serviço Ollama indisponível"

Padrão 7: Endurecimento para Produção e Segurança

Segurança é a linha de base para a implantação de stack completa de IA com Docker Compose em produção.

Gerenciamento de Secrets

services:
  ollama:
    image: ollama/ollama:latest
    secrets:
      - hf_token
    environment:
      HF_TOKEN_FILE: /run/secrets/hf_token

  qdrant:
    image: qdrant/qdrant:latest
    secrets:
      - qdrant_api_key
    environment:
      QDRANT__SERVICE__API_KEY_FILE: /run/secrets/qdrant_api_key

secrets:
  hf_token:
    file: ./secrets/hf_token.txt
  qdrant_api_key:
    file: ./secrets/qdrant_api_key.txt
  db_password:
    file: ./secrets/db_password.txt

Isolamento de Rede

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true
  monitoring:
    driver: bridge
    internal: true

services:
  traefik:
    networks:
      - frontend
      - backend

  open-webui:
    networks:
      - frontend
      - backend

  ollama:
    networks:
      - backend

  qdrant:
    networks:
      - backend

  tei:
    networks:
      - backend

  prometheus:
    networks:
      - monitoring
      - backend

  grafana:
    networks:
      - frontend
      - monitoring

Estratégia de Backup

#!/bin/bash
# scripts/backup-vectors.sh

BACKUP_DIR="/backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

echo "Backing up Qdrant..."
curl -s -X POST "http://localhost:6333/snapshots" | jq .

echo "Backing up Ollama models list..."
curl -s "http://localhost:11434/api/tags" | jq . > "$BACKUP_DIR/ollama_models.json"

echo "Backing up environment config..."
cp .env "$BACKUP_DIR/.env.backup"
cp docker-compose.yml "$BACKUP_DIR/docker-compose.yml.backup"

echo "Backup completed: $BACKUP_DIR"

Configuração Completa de Produção

# docker-compose.prod.yml
services:
  ollama:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
        limits:
          memory: 16G
          cpus: "8.0"
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 5
        window: 120s
    logging:
      driver: json-file
      options:
        max-size: "100m"
        max-file: "5"
    read_only: true
    tmpfs:
      - /tmp

  qdrant:
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"

5 Armadilhas Comuns e Soluções

Armadilha 1: Timeout no Download de Modelos do Ollama

Sintoma: Após docker compose up, o Ollama fica travado baixando modelos. Modelos grandes (ex., Llama 4 70B) podem levar mais de uma hora para baixar.

Solução: Use o serviço model-init para download assíncrono. O serviço Ollama em si não precisa esperar pelos modelos.

  model-init:
    image: curlimages/curl:latest
    depends_on:
      ollama:
        condition: service_healthy
    volumes:
      - ./scripts/init-models.sh:/init-models.sh:ro
    entrypoint: ["/bin/sh", "/init-models.sh"]
    restart: "no"
    deploy:
      resources:
        limits:
          memory: 256M

Armadilha 2: OOM do Contêiner Qdrant

Sintoma: À medida que os dados vetoriais crescem, o contêiner Qdrant sofre OOM Killed.

Solução: Defina limites de memória e habilite mapeamento de memória.

  qdrant:
    image: qdrant/qdrant:latest
    deploy:
      resources:
        limits:
          memory: 8G
    environment:
      QDRANT__STORAGE__PERFORMANCE__MAX_SEARCH_THREADS: "4"
      QDRANT__STORAGE__WAL__WAL_CAPACITY_MB: "64"

Armadilha 3: Incompatibilidade de Versão do Driver de GPU

Sintoma: docker compose up exibe o erro CUDA driver version is insufficient.

Solução: Certifique-se de que o driver NVIDIA do host seja ≥ 535, instale nvidia-container-toolkit.

# Verificar versão do driver
nvidia-smi | head -3

# Instalar nvidia-container-toolkit (Ubuntu)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Armadilha 4: Serviço de Embedding e LLM Competindo pela GPU

Sintoma: Memória GPU insuficiente quando TEI e Ollama são executados simultaneamente; carregamento do modelo falha.

Solução: Use device_ids para alocação precisa de GPU, ou execute o serviço de embedding na CPU.

  ollama:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]
              capabilities: [gpu]

  tei:
    # Executar serviço de embedding no modo CPU
    environment:
      MODEL_ID: "BAAI/bge-m3"
      # Sem alocação de GPU, usa CPU

Armadilha 5: Falha de Resolução DNS entre Contêineres

Sintoma: OpenWebUI relata ollama: Name or service not known.

Solução: Certifique-se de que todos os serviços estejam na mesma rede, use container_name ou o nome do serviço como hostname.

networks:
  ai-network:
    driver: bridge

services:
  ollama:
    container_name: ollama
    networks:
      - ai-network

  open-webui:
    container_name: open-webui
    networks:
      - ai-network
    environment:
      OLLAMA_BASE_URL: "http://ollama:11434"

10 Soluções de Erros Comuns

1. could not select device driver — Runtime NVIDIA não instalado

# Instalar nvidia-container-toolkit e reiniciar Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker info | grep -i runtime
# Deve ver o runtime nvidia

2. OOM Killed — Memória GPU insuficiente

# Verificar memória GPU
nvidia-smi
# Usar modelos menores ou quantizados
docker exec ollama ollama run qwen3:4b

3. Connection refused ao Ollama — Serviço não pronto

# Verificar estado de saúde do Ollama
docker compose ps
docker compose logs ollama
# Aguardar o healthcheck passar antes de conectar

4. permission denied no socket Docker

sudo usermod -aG docker $USER
newgrp docker

5. Qdrant collection not found — Coleção não criada

curl -X PUT "http://localhost:6333/collections/documents" \
  -H "Content-Type: application/json" \
  -d '{"vectors": {"size": 1024, "distance": "Cosine"}}'

6. model not found — Modelo do Ollama não baixado

docker exec ollama ollama pull qwen3:8b

7. CUDA out of memory — Estouro de memória GPU durante inferência

# Reduzir requisições paralelas
# Configurar em docker-compose.yml
environment:
  OLLAMA_NUM_PARALLEL: "1"
  OLLAMA_MAX_LOADED_MODELS: "1"

8. TLS handshake error — Problema de certificado Traefik

# Verificar permissões do arquivo de certificado
chmod 600 traefik/acme.json
# Verificar logs do Traefik
docker compose logs traefik

9. too many open files — Limite de descritores de arquivo

# Aumentar limite temporariamente
ulimit -n 65536
# Configuração permanente (/etc/security/limits.conf)
# * soft nofile 65536
# * hard nofile 65536

10. vector dimension mismatch — Inconsistência de dimensões de embedding

# Garantir que a dimensão da coleção Qdrant corresponda à saída do modelo de embedding
# bge-m3: 1024 dimensões
# nomic-embed-text: 768 dimensões
curl -X PUT "http://localhost:6333/collections/documents" \
  -d '{"vectors": {"size": 1024, "distance": "Cosine"}}'

Dicas Avançadas de Otimização

Aquecimento de Modelos em Múltiplas Etapas

  model-warmer:
    image: curlimages/curl:latest
    container_name: model-warmer
    depends_on:
      ollama:
        condition: service_healthy
    entrypoint: >
      /bin/sh -c "
        echo 'Warming up models...' &&
        curl -s http://ollama:11434/api/generate -d '{\"model\":\"qwen3:8b\",\"prompt\":\"hi\",\"stream\":false}' > /dev/null &&
        curl -s http://ollama:11434/api/generate -d '{\"model\":\"nomic-embed-text\",\"prompt\":\"test\",\"stream\":false}' > /dev/null &&
        echo 'Models warmed up!'
      "
    restart: "no"

Descarregamento Inteligente de Modelos

  ollama:
    environment:
      OLLAMA_KEEP_ALIVE: "5m"
      OLLAMA_NUM_PARALLEL: "4"
      OLLAMA_MAX_LOADED_MODELS: "2"

OLLAMA_KEEP_ALIVE: "5m" descarrega automaticamente modelos inativos por 5 minutos, liberando memória GPU.

Dependências Encadeadas de Verificações de Saúde

  tei:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 120s

  qdrant:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6333/healthz"]
      interval: 10s
      timeout: 5s
      retries: 3

  rag-app:
    depends_on:
      ollama:
        condition: service_healthy
      tei:
        condition: service_healthy
      qdrant:
        condition: service_healthy

Docker Compose Watch para Desenvolvimento

# docker-compose.yml
services:
  rag-app:
    build: .
    develop:
      watch:
        - action: rebuild
          path: ./app
          target: /app
        - action: sync
          path: ./app/static
          target: /app/static

Comparação: Docker Compose vs K8s vs Docker Swarm

Dimensão Docker Compose Kubernetes Docker Swarm
Complexidade de Implantação de Stack IA ⭐ Muito Baixa ⭐⭐⭐⭐⭐ Muito Alta ⭐⭐ Baixa
Agendamento de GPU ✅ Nativo ✅ Device Plugin ⚠️ Precisa de configuração
Auto-escalação ❌ ✅ HPA ⚠️ Manual
Descoberta de Serviços ✅ DNS ✅ CoreDNS ✅ DNS
Atualizações Contínuas ⚠️ Precisa de scripts ✅ Nativo ✅ Nativo
Gerenciamento de Configuração ✅ .env ✅ ConfigMap ⚠️ Config
Gerenciamento de Secrets ✅ Docker Secret ✅ K8s Secret ⚠️ Básico
Ecossistema de Monitoramento ✅ Prometheus ✅ Completo ⚠️ Limitado
Orquestração Multi-nó ❌ Nó único ✅ Capacidade central ✅ Nativo
Curva de Aprendizado Baixa Alta Baixa
Atividade da Comunidade ✅ Ativa ✅ Muito Ativa ❌ Em Declínio
Escala de Projeto IA Adequada 1-5 GPUs 10+ GPUs 2-5 GPUs

Recomendação: A implantação de stack completa de IA com Docker Compose é ideal para cenários de máquina única com 1-5 GPUs — a melhor escolha para desenvolvimento de IA e produção em pequena escala. Para 5+ GPUs ou necessidades multi-nó, considere Kubernetes + KServe/vLLM. Docker Swarm não é recomendado para implantação de IA.

Ferramentas Online Recomendadas

Resumo

A implantação de stack completa de IA com Docker Compose transforma ambientes de desenvolvimento de IA de "três dias para configurar" para "um comando para lançar". Ollama + OpenWebUI gerencia o serviço LLM, Qdrant gerencia o armazenamento vetorial, TEI gerencia os embeddings, Traefik gerencia o gateway, Prometheus + Grafana gerencia o monitoramento, e o passthrough de GPU faz a inferência voar. 7 padrões cobrem toda a cadeia do desenvolvimento à produção, 5 armadilhas comuns e 10 etapas de solução de problemas ajudam você a evitar desvios. Para projetos de IA com 1-5 GPUs, Docker Compose é a solução de orquestração de contêineres de IA mais prática em 2026.

Posts Relacionados

Referências Externas

Experimente estas ferramentas executadas localmente no navegador — nenhum cadastro necessário →

#Docker#Docker Compose#AI部署#LLM#向量数据库#Ollama#2026#DevOps