Nano-vLLM: Uma implementação mínima do vLLM para inferência local

Nano-vLLM é uma reimplementação open-source, feita do zero, do vLLM servidor de inferência, escrita em aproximadamente 1.200 linhas de Python. Foi lançada em meados de 2025 por Xingkai Yu, engenheiro da DeepSeek, sob licença MIT, em github.com/GeeeekExplorer/nano-vllm. Trata-se de uma base de código voltada para ensino e uma ferramenta eficiente para inferência em lote — não é um substituto imediato para o servidor completo vLLM.

O que realmente é o Nano-vLLM

O repositório upstream vllm-project/vllm é um servidor de inferência robusto, voltado para produção, com centenas de colaboradores, uma API HTTP compatível com OpenAI, workers distribuídos e suporte a dezenas de arquiteturas de modelos e esquemas de quantização. O Nano-vLLM reduz isso ao núcleo essencial: carregamento do modelo, gerenciador de cache KV, agendador de lote e amostrador.

Segundo o README do projeto, o nano-vllm mantém as principais otimizações que tornam o vLLM rápido:

• Cache de prefixos — reutiliza blocos de cache KV entre requisições que compartilham um prefixo de prompt.
• Paralelismo de tensores — divide um modelo entre múltiplas GPUs em um único nó.
• Compilação com Torch — usa torch.compile para fusão de kernels.
• Grafos CUDA — reduz a sobrecarga de inicialização por etapa durante a decodificação.

O que ele deliberadamente omite: o servidor HTTP compatível com OpenAI, APIs contínuas de streaming, a maioria dos back-ends de quantização (AWQ, GPTQ, FP8), decodificação especulativa, troca dinâmica de LoRA, clustering multi-nó e o amplo ecossistema de modelos. Ele é testado principalmente com modelos densos da classe Qwen3.

Instalando o Nano-vLLM

Nano-vLLM é um pacote Python. Não há suporte nativo para CUDA no Windows no repositório upstream; no Windows, use WSL2 com um driver NVIDIA. Linux e WSL2 são as plataformas principais. macOS não é suportado porque os caminhos de código pressupõem CUDA.

Linux e WSL2

python -m venv .venv
source .venv/bin/activate
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install git+https://github.com/GeeeekExplorer/nano-vllm.git

Ajuste a versão do wheel CUDA (cu121, cu124, etc.) ao driver NVIDIA instalado. Verifique com nvidia-smi antes de instalar.

Windows (via WSL2)

Instale o driver NVIDIA para Windows, habilite o WSL2 com uma distribuição Ubuntu (wsl --install -d Ubuntu), depois siga os passos para Linux dentro do WSL. Não instale o toolkit CUDA dentro do WSL — o driver do Windows expõe a GPU.

macOS

Não suportado. O Nano-vLLM depende de kernels CUDA e primitivas de atenção paginada que não possuem backend Metal. Em Apple Silicon, use Ollama ou LM Studio em vez disso, ambos executando llama.cpp sob a capa.

Baixando um modelo

Nano-vLLM carrega diretórios de modelos padrão do Hugging Face — o mesmo config.json, tokenizer.json e safetensors layout usado por transformers e vLLM. Baixe um modelo com a CLI oficial do huggingface_hub Linha de comando:

pip install -U "huggingface_hub[cli]"
hf download Qwen/Qwen3-8B --local-dir ~/models/Qwen3-8B

Veja o documentação da CLI do Hugging Face Hub para autenticação e modelos com acesso restrito. Observe que o ponto de entrada mais antigo huggingface-cli ainda é distribuído com o pacote, mas agora o Hugging Face recomenda o comando hf .

Executando inferência

A API espelha de perto a interface offline em lote do vLLM. Um script mínimo:

from nanovllm import LLM, SamplingParams

llm = LLM("/home/user/models/Qwen3-8B", enforce_eager=False, tensor_parallel_size=1)
sp = SamplingParams(temperature=0.7, max_tokens=256)

prompts = ["Explique atenção paginada em um único parágrafo."]
outputs = llm.generate(prompts, sp)
print(outputs[0]["text"])

Os nomes exatos das classes e a forma de retorno podem variar entre commits — verifique o arquivo example.py na raiz do repositório, que é a referência canônica de uso.

Requisitos de hardware por modelo

Como o nano-vllm atualmente executa modelos em bf16/fp16 (sem quantização nativa de 4 bits no momento da redação), os requisitos de VRAM são aproximadamente o dobro dos valores listados abaixo para 4 bits. Use a Calculadora de VRAM tabela de requisitos de VRAM banco de dados de modelos da Convly — para o nano-vllm em bf16, preveja cerca de duas vezes esses valores, além de uma margem adicional para o cache KV.

Modelo	Contexto	VRAM (referência em 4 bits)	GPU NVIDIA realista para nano-vllm
Qwen3 8B	128K	~5 GB	Única RTX 4090 (24 GB) em bf16
Qwen3 14B	128K	~9 GB	Única RTX 4090 em bf16 com contexto moderado
Qwen3 32B	128K	~20 GB	2× RTX 4090 com tensor_parallel_size=2
Llama 3.1 8B	128K	~5 GB	Única RTX 4090
Llama 3.3 70B	128K	~40 GB	2× A100 80 GB ou 4× RTX 4090

Para uma visão mais ampla do que cabe em cada placa, consulte a melhores GPUs para LLMs locais e o tabela de requisitos de VRAM.

Nano-vLLM vs vLLM vs Ollama

Recurso	Nano-vLLM	vLLM	Ollama
Número de linhas	~1.200 linhas em Python	~100 mil+ linhas em Python/C++/CUDA	Wrapper em Go sobre llama.cpp
Servidor compatível com OpenAI	Não	Sim	Sim (por meio de /v1)
Backend	PyTorch + CUDA	PyTorch + kernels personalizados	llama.cpp (GGUF)
Quantização	Mínima	AWQ, GPTQ, FP8, INT4	Q2–Q8 GGUF
Multi-GPU	Paralelismo de tensores	Paralelismo de tensores + pipeline + especialistas	Limitado
Uso principal	Aprendizado, incorporações	Serving em produção	Desktop / desenvolvimento

Se seu objetivo for disponibilizar um endpoint voltado ao cliente, use o vLLM completo. Se desejar incorporar um loop de inferência em lote dentro de um programa maior em Python com dependências mínimas, o nano-vllm é uma opção razoável. Se quiser um chatbot local com um único comando, use Ollama.

Quando faz sentido usar o Nano-vLLM

• Aprender os detalhes internos. O agendador e o gerenciador de blocos cabem em uma única tela. Ler o código do nano-vllm é a maneira mais rápida de compreender a atenção paginada em código real.
• Forks para pesquisa. Modificar uma base de código de 1.200 linhas para testar um novo amostrador ou política de cache é viável; fazer fork do vLLM upstream não é.
• Inferência em lote offline. Correção de provas, geração de dados sintéticos, loops de avaliação sobre um conjunto fixo de prompts.

Quando não faz sentido: APIs em produção, serving multi-inquilino, orçamentos rigorosos de quantização ou qualquer hardware não-NVIDIA.

Auto-hospedagem vs API

Executar o nano-vllm localmente tem custos reais — investimento em GPU, eletricidade e tempo de engenharia. Modelos hospedados em plataformas de ponta costumam ser mais baratos por token do que a inferência local amortizada em baixo volume. Compare com a calculadora de autohospedagem versus API e o Calculadora de custos de APItabela de custos por token Qwen3 8B executado em um endpoint hospedado custa $0,04 por entrada / $0,14 por saída a cada 1 milhão de tokens, segundo a Convly banco de dados de modelos, enquanto uma GPU de 24 GB capaz de executá-lo localmente custa bem mais de $1.500.

Perguntas frequentes

Quem escreveu o nano-vllm?

O repositório é mantido por Xingkai Yu (identificador no GitHub GeeeekExplorer), engenheiro da DeepSeek. Trata-se de um projeto pessoal, não de um lançamento oficial da DeepSeek. O código é licenciado sob MIT e está disponível em github.com/GeeeekExplorer/nano-vllm.

O nano-vllm é mais rápido que o vLLM?

O README relata uma taxa de transferência próxima à do vLLM em modelos densos pequenos, como o Qwen3-0,6B, em uma GPU de classe RTX 4070, e, em algumas configurações de benchmark curtas, ligeiramente mais rápida devido à menor sobrecarga do agendador. Em modelos maiores, contextos mais longos ou serving com múltiplas requisições, as otimizações do vLLM upstream se destacam. Considere a equivalência como 'na mesma faixa para inferência em lote offline', não como 'substituição estrita'.

O nano-vllm pode expor uma API compatível com OpenAI?

Não nativamente. O projeto expõe uma Python LLM.generate() método para uso offline em lote. Se você precisar de um servidor HTTP com /v1/chat/completions, envolva-o manualmente com FastAPI ou use o servidor compatível com OpenAI do vLLM ou o Ollama.

O nano-vllm suporta modelos quantizados, como GGUF ou AWQ?

Não. A base de código carrega pesos padrão do Hugging Face no formato safetensors, em bf16/fp16. Para GGUF (Q4_K_M etc.), use ferramentas baseadas em llama.cpp; para AWQ ou GPTQ, use o vLLM oficial. Essa é uma das razões pelas quais a pegada de VRAM do nano-vllm é maior por parâmetro do que a do Ollama para o mesmo modelo.

Quais modelos são conhecidos por funcionar?

Os modelos densos Qwen3 são o alvo principal da implementação de referência. Outros modelos com arquitetura Llama frequentemente funcionam com pequenos ajustes no carregador de modelos, mas arquiteturas exóticas (mistura de especialistas, híbridas baseadas em espaço de estado) geralmente não funcionam. Consulte o diretório nanovllm/models/ do repositório para obter a lista atual de modelos suportados.

Posso executar o nano-vllm em hardware AMD ou Apple Silicon?

Não atualmente. Os kernels pressupõem CUDA. O ROCm pode funcionar com uma compilação personalizada do PyTorch, mas não foi testado oficialmente. Em chips Apple Silicon, não há suporte — use ferramentas baseadas em MLX ou llama.cpp. Para uma visão geral de alternativas, consulte o Ranking de LLMs e escolha um modelo compatível com o seu perfil de hardware.