Deployment público de referência para serving de modelos em GPU NVIDIA
Quick Start · Instalação · Serving · Monitoramento · Segurança
Important
Este é um deployment de referência para laboratório. A produção atual documentada do debuga.ai não depende deste repositório como topologia obrigatória. Modelos, imagens, performance e capacidade devem ser homologados no hardware-alvo.
O projeto reúne exemplos de configuração, scripts operacionais, Compose e monitoramento para expor um modelo por uma API compatível com clientes OpenAI. O foco é facilitar um laboratório reproduzível, não oferecer uma imagem enterprise pronta.
flowchart LR
CLIENT[Cliente OpenAI-compatible] --> API[vLLM API Server]
API --> SCHED[Scheduler / batching]
SCHED --> GPU[NVIDIA GPU]
API --> METRICS[/metrics]
METRICS --> PROM[Prometheus]
PROM --> GRAF[Grafana]
| Componente | Estado | Observação |
|---|---|---|
| Compose vLLM | Referência executável | usa imagem de exemplo |
| Configurações 7B/14B/32B | Ponto de partida | não homologadas universalmente |
| Download de modelo | Script utilitário | depende do Hugging Face |
| Start direto | Script utilitário | requer vLLM instalado |
| Health check | Script funcional | valida conectividade e inferência curta |
| Benchmark sintético | Ferramenta inicial | mede transporte/latência, não qualidade |
| Prometheus | Exemplo | métricas dependem da versão do vLLM |
| Grafana | Dashboard de referência | revisar queries com a versão instalada |
| SLA/capacidade | Não definido | requer teste de carga |
- host Linux compatível;
- driver NVIDIA;
- Docker e Docker Compose;
- NVIDIA Container Toolkit;
- modelo cuja licença permita o uso pretendido.
Siga a documentação oficial atual do NVIDIA Container Toolkit para instalação do runtime.
git clone https://github.com/SperryTecnologia/debuga-vllm-engine.git
cd debuga-vllm-engine
cp .env.example .envRevise .env, especialmente MODEL_ID, quantização, contexto e uso de GPU.
docker compose -f docker/docker-compose.yml config
docker compose -f docker/docker-compose.yml up -d vllm
docker compose -f docker/docker-compose.yml logs -f vllmValidação:
./scripts/health-check.sh http://localhost:8000
curl -fsS http://localhost:8000/v1/modelsMonitoramento opcional:
docker compose -f docker/docker-compose.yml --profile monitoring up -dCaution
O exemplo pode operar sem API key e expõe portas. Restrinja rede, configure autenticação, use TLS em proxy reverso e remova senhas padrão antes de qualquer ambiente compartilhado.
A API e os parâmetros suportados dependem da versão do vLLM e do modelo. Este repositório usa como referência:
- health check;
- listagem de modelos;
- chat completions;
- streaming;
- métricas em
/metricsquando disponíveis.
Consulte Model Serving.
Não há uma comparação universal entre vLLM, Ollama, TGI ou llama.cpp. Resultados válidos precisam registrar:
engine e versão
imagem/container digest
modelo e revisão
quantização
GPU, driver e CUDA
contexto e tamanho de saída
concorrência
warm-up
número de execuções
dados brutos
Use o script sintético como ponto de partida:
./scripts/benchmark.sh http://localhost:8000 10Ele mede latência e tokens reportados pelo endpoint; não avalia correção técnica da resposta.
debuga-vllm-engine/
├── configs/
├── docker/
├── docs/
├── monitoring/
├── scripts/
├── .env.example
└── README.md
| Documento | Conteúdo |
|---|---|
| Instalação | Preparação e início do laboratório |
| Hardware | Critérios de dimensionamento |
| Serving | API e parâmetros |
| Quantização | Trade-offs e validação |
| Monitoramento | Métricas e dashboard |
| Troubleshooting | Diagnóstico inicial |
| Projeto | Papel |
|---|---|
| debuga-ai | Produto e documentação oficial |
| debuga-llm-stack | Arquitetura de referência |
| debuga-llm-gateway | Roteamento local/cloud |
| debuga-vllm-engine | Este deployment de referência |
| debuga-qwen-coder-lab | Avaliação de modelos |
Código, scripts e documentação sob Apache License 2.0. Modelos, imagens e ferramentas de terceiros mantêm suas próprias licenças.
- Plataforma: debuga.ai
- Contato: contato@sperrytecnologia.com.br