uv<\/a>, que resolve o \u00edndice correto do PyTorch para a sua vers\u00e3o de CUDA automaticamente:<\/p>\n# instala o uv, se ainda n\u00e3o tiver\ncurl -LsSf https:\/\/astral.sh\/uv\/install.sh | sh\n\n# ambiente isolado + vLLM\nuv venv --python 3.12 --seed\nsource .venv\/bin\/activate\nuv pip install vllm --torch-backend=auto<\/code><\/pre>\nO --torch-backend=auto<\/code> inspeciona o driver CUDA instalado e escolhe a build certa. Para fixar uma vers\u00e3o espec\u00edfica, troque por --torch-backend=cu129<\/code> (ou a build que voc\u00ea usa \u2014 os bin\u00e1rios do vLLM hoje saem para CUDA 12.8, 12.9 e 13.0).<\/p>\nQuer s\u00f3 experimentar, sem criar ambiente nenhum?<\/p>\n
uv run --with vllm vllm --help<\/code><\/pre>\nEm GPUs AMD, o \u00edndice \u00e9 outro:<\/p>\n
uv venv --python 3.12 --seed\nsource .venv\/bin\/activate\nuv pip install vllm --extra-index-url https:\/\/wheels.vllm.ai\/rocm\/<\/code><\/pre>\nO --python 3.12<\/code> n\u00e3o \u00e9 detalhe: as wheels ROCm s\u00f3 existem para essa vers\u00e3o. Com 3.11 ou 3.13 o instalador cai silenciosamente na wheel CUDA do PyPI, e o erro s\u00f3 aparece na hora de rodar, como libcudart.so: cannot open shared object file<\/code>.<\/p>\nE, se voc\u00ea prefere n\u00e3o instalar nada no host, a imagem oficial resolve:<\/p>\n
docker run --runtime nvidia --gpus all \n -v ~\/.cache\/huggingface:\/root\/.cache\/huggingface \n -p 8000:8000 --ipc=host \n vllm\/vllm-openai:latest \n --model Qwen\/Qwen2.5-1.5B-Instruct<\/code><\/pre>\nO --ipc=host<\/code> d\u00e1 ao container acesso \u00e0 mem\u00f3ria compartilhada do host. Sem ele, \/dev\/shm<\/code> fica min\u00fasculo e o vLLM quebra ao inicializar os workers \u2014 sobretudo com tensor parallel. A alternativa, se voc\u00ea n\u00e3o quiser compartilhar o namespace de IPC, \u00e9 --shm-size=8g<\/code>.<\/p>\nPrimeiro teste: infer\u00eancia em lote<\/h2>\n
Antes de subir o servidor, vale um teste offline para confirmar que a GPU est\u00e1 sendo usada. Crie teste.py<\/code>:<\/p>\nfrom vllm import LLM, SamplingParams\n\nprompts = [\n \"O kernel Linux foi criado por\",\n \"A capital do Brasil \u00e9\",\n \"Em uma frase, explique o que \u00e9 pagina\u00e7\u00e3o de mem\u00f3ria:\",\n]\n\nsampling_params = SamplingParams(temperature=0.8, top_p=0.95, max_tokens=64)\n\nllm = LLM(model=\"Qwen\/Qwen2.5-1.5B-Instruct\")\noutputs = llm.generate(prompts, sampling_params)\n\nfor output in outputs:\n print(f\">> {output.prompt!r}\")\n print(f\" {output.outputs[0].text!r}n\")<\/code><\/pre>\npython3 teste.py<\/code><\/pre>\nRepare que os tr\u00eas prompts s\u00e3o processados juntos<\/strong>, n\u00e3o em fila \u2014 \u00e9 o batching em a\u00e7\u00e3o. Um detalhe que pega muita gente: llm.generate()<\/code> n\u00e3o aplica o chat template<\/strong> do modelo. Para modelos instruct<\/em>, use llm.chat()<\/code> com a mesma estrutura de mensagens da API da OpenAI:<\/p>\nmensagens = [[{\"role\": \"user\", \"content\": p}] for p in prompts]\noutputs = llm.chat(mensagens, sampling_params)<\/code><\/pre>\nSubindo o servidor compat\u00edvel com a API da OpenAI<\/h2>\n
Esta \u00e9 a principal raz\u00e3o de ser do vLLM em produ\u00e7\u00e3o: ele fala o protocolo da OpenAI, ent\u00e3o qualquer aplica\u00e7\u00e3o, SDK ou agente que j\u00e1 usa a OpenAI aponta para ele trocando apenas a base_url<\/code>.<\/p>\nvllm serve Qwen\/Qwen2.5-1.5B-Instruct<\/code><\/pre>\nO servidor sobe em http:\/\/localhost:8000<\/code>. Teste:<\/p>\ncurl http:\/\/localhost:8000\/v1\/models\n\ncurl http:\/\/localhost:8000\/v1\/chat\/completions \n -H \"Content-Type: application\/json\" \n -d '{\n \"model\": \"Qwen\/Qwen2.5-1.5B-Instruct\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Explique inodes em duas frases.\"}],\n \"temperature\": 0.7\n }'<\/code><\/pre>\nDo lado do cliente Python, \u00e9 o SDK oficial da OpenAI sem gambiarra:<\/p>\n
from openai import OpenAI\n\nclient = OpenAI(api_key=\"EMPTY\", base_url=\"http:\/\/localhost:8000\/v1\")\n\nresposta = client.chat.completions.create(\n model=\"Qwen\/Qwen2.5-1.5B-Instruct\",\n messages=[{\"role\": \"user\", \"content\": \"Escreva um one-liner que conta arquivos por extens\u00e3o.\"}],\n)\nprint(resposta.choices[0].message.content)<\/code><\/pre>\nPara exigir autentica\u00e7\u00e3o, suba com --api-key SEGREDO<\/code> \u2014 ou, melhor, com a vari\u00e1vel VLLM_API_KEY<\/code>, porque chave em linha de comando aparece no ps aux<\/code>. O servidor aceita m\u00faltiplas chaves, o que facilita rota\u00e7\u00e3o sem downtime.<\/p>\nAten\u00e7\u00e3o:<\/strong> o --api-key<\/code> autentica apenas os prefixos \/v1<\/code>, \/v2<\/code> e \/inference<\/code>. Endpoints como \/invocations<\/code> (que exp\u00f5e a mesma capacidade de infer\u00eancia), \/pooling<\/code>, \/classify<\/code> e os de controle \/pause<\/code>, \/resume<\/code> e \/abort_requests<\/code> continuam abertos. Se voc\u00ea usa --host 0.0.0.0<\/code>, ponha o vLLM atr\u00e1s de um proxy reverso que libere s\u00f3 as rotas que voc\u00ea quer expor \u2014 nunca deixe a porta 8000 acess\u00edvel direto da rede.<\/p>\nOs par\u00e2metros que realmente importam<\/h2>\n
O padr\u00e3o funciona, mas quase nunca \u00e9 o que voc\u00ea quer em produ\u00e7\u00e3o:<\/p>\n
vllm serve Qwen\/Qwen2.5-7B-Instruct \n --host 0.0.0.0 --port 8000 \n --gpu-memory-utilization 0.90 \n --max-model-len 8192 \n --tensor-parallel-size 1 \n --api-key MINHA_CHAVE<\/code><\/pre>\n\n--gpu-memory-utilization<\/code> \u2014 fra\u00e7\u00e3o da VRAM que o vLLM pode ocupar (padr\u00e3o 0.92<\/strong> nas vers\u00f5es atuais; era 0.9 at\u00e9 a v0.11). Baixe<\/strong> se a GPU tamb\u00e9m roda seu monitor ou outro processo; suba<\/strong> se a placa \u00e9 dedicada. Quanto maior, mais KV cache, mais requisi\u00e7\u00f5es simult\u00e2neas.<\/li>\n--max-model-len<\/code> \u2014 janela de contexto m\u00e1xima. \u00c9 o par\u00e2metro n\u00ba 1 para resolver erro de mem\u00f3ria na inicializa\u00e7\u00e3o: modelos anunciam contextos gigantes (128k) que exigem KV cache que voc\u00ea n\u00e3o tem. Corte para o que a sua aplica\u00e7\u00e3o de fato usa.<\/li>\n--tensor-parallel-size<\/code> \u2014 n\u00famero de GPUs para dividir o modelo. Use quando o modelo n\u00e3o cabe em uma placa s\u00f3.<\/li>\n--dtype<\/code> \u2014 auto<\/code> resolve bem; bfloat16<\/code> em placas Ampere ou mais novas, float16<\/code> em placas antigas.<\/li>\n--quantization<\/code> \u2014 para pesos AWQ, GPTQ ou FP8, que cortam a VRAM pela metade ou mais.<\/li>\n--served-model-name<\/code> \u2014 o nome que a API exp\u00f5e, \u00fatil para n\u00e3o vazar o caminho do Hugging Face para os clientes.<\/li>\n--cpu-offload-gb<\/code> \u2014 quantos GiB dos pesos empurrar para a RAM, por GPU. Salva o dia quando o modelo n\u00e3o cabe, mas cada forward pass<\/em> passa pelo barramento: s\u00f3 use se a alternativa for n\u00e3o rodar.<\/li>\n<\/ul>\nModelos com licen\u00e7a restrita (Llama, Gemma) exigem token do Hugging Face:<\/p>\n
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx\nvllm serve meta-llama\/Llama-3.1-8B-Instruct<\/code><\/pre>\nRodando como servi\u00e7o no systemd<\/h2>\n
Em um servidor de verdade, o vLLM tem que subir sozinho no boot. Crie \/etc\/systemd\/system\/vllm.service<\/code>:<\/p>\n[Unit]\nDescription=vLLM OpenAI-compatible server\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=exec\nUser=vllm\nGroup=vllm\nWorkingDirectory=\/opt\/vllm\nEnvironment=\"HF_HOME=\/opt\/vllm\/hf\"\nEnvironment=\"VLLM_API_KEY=MINHA_CHAVE\"\nExecStart=\/opt\/vllm\/.venv\/bin\/vllm serve Qwen\/Qwen2.5-7B-Instruct \n --host 0.0.0.0 --port 8000 \n --gpu-memory-utilization 0.90 \n --max-model-len 8192\nRestart=always\nRestartSec=10\nTimeoutStartSec=600\n\n[Install]\nWantedBy=multi-user.target<\/code><\/pre>\nO TimeoutStartSec<\/code> alto \u00e9 proposital: na primeira execu\u00e7\u00e3o o modelo \u00e9 baixado do Hugging Face e os kernels s\u00e3o compilados, e com o padr\u00e3o de 90 segundos o systemd desistiria no meio do caminho. Repare que ele s\u00f3 tem efeito porque a unit usa Type=exec<\/code> \u2014 com Type=simple<\/code>, o systemd considera o servi\u00e7o iniciado j\u00e1 no fork()<\/code> e o timeout de partida nunca chega a valer.<\/p>\nO servi\u00e7o roda com usu\u00e1rio e ambiente pr\u00f3prios \u2014 o .venv<\/code> que voc\u00ea criou no seu diret\u00f3rio pessoal n\u00e3o serve aqui:<\/p>\nsudo useradd -r -s \/usr\/sbin\/nologin -d \/opt\/vllm vllm\nsudo mkdir -p \/opt\/vllm\/hf\nsudo chown -R vllm:vllm \/opt\/vllm\n\n# instala o vLLM dentro de \/opt\/vllm, como o usu\u00e1rio do servi\u00e7o\nsudo -u vllm uv venv --python 3.12 --seed \/opt\/vllm\/.venv\nsudo -u vllm env VIRTUAL_ENV=\/opt\/vllm\/.venv uv pip install vllm --torch-backend=auto\n\nsudo systemctl daemon-reload\nsudo systemctl enable --now vllm\njournalctl -u vllm -f<\/code><\/pre>\n
![\"Mascote](\"\/wp-content\/uploads\/2026\/09\/vllm-v5.webp\")
<\/p>\n