O suporte a GGUF no vLLM existe, mas a configuração correta depende da sua versão do vLLM, do checkpoint GGUF e de seu tokenizer. A documentação estável atual direciona os usuários ao vllm-gguf-plugin separado; tutoriais mais antigos descrevem um carregador integrado. Comece identificando a stack instalada e, em seguida, valide um modelo pequeno antes de migrar uma carga de trabalho de produção.
Este guia se concentra em fazer com que um checkpoint GGUF carregue e seja servido corretamente. Para escolher entre GGUF, AWQ, GPTQ e FP8, use nosso guia mais abrangente sobre quantização no vLLM.
O que o suporte a GGUF no vLLM significa hoje
GGUF é um formato de arquivo de modelo. Um nome de arquivo que termina em .gguf não comprova que um runtime oferece suporte a todas as arquiteturas, tipos de quantização ou componentes auxiliares contidos nele. Considere a compatibilidade como uma combinação de runtime + plugin + arquitetura do modelo + quantização + tokenizer + hardware.
A documentação do vLLM GGUF atual descreve um caminho experimental com limitações de desempenho e recursos. Ela documenta um seletor repo_id:quant_type do Hugging Face, bem como arquivos locais, e recomenda usar o tokenizer do modelo original. Isso difere das instruções da v0.8.4, que descrevem o fluxo de trabalho mais antigo com arquivos locais. Faça a documentação corresponder à versão que você realmente executa.
| O que você encontrou | O que verificar em seguida |
|---|---|
| Uma instalação estável recente | Se o plugin GGUF está instalado no mesmo ambiente Python que o vLLM |
| Um contêiner antigo ou uma versão fixada | Sua documentação versionada; evite misturar um carregador antigo com flags atuais |
| Um GGUF que funciona em outro runtime | Arquitetura, mapeamento de tensores, tokenizer e recursos necessários em sua stack do vLLM |
Um exemplo que usa --omni |
Se você está usando vLLM-Omni em vez do caminho de serviço de texto deste guia |
O guia GGUF do vLLM-Omni cobre configurações multimodais separadas e adaptadores específicos de modelo. Seus exemplos de difusão não são um comando pronto para uso em um servidor vLLM somente de texto.
1. Registre o ambiente antes de instalar qualquer coisa
Use um ambiente de teste limpo na máquina GPU pretendida. Primeiro, confirme que a instalação base do vLLM é compatível com essa máquina usando as instruções oficiais de instalação para GPU. Uma instalação bem-sucedida apenas do pacote Python não estabelece a compatibilidade do driver ou do dispositivo.
Registre as versões dos pacotes sem importar um modelo:
from importlib.metadata import version, PackageNotFoundError
for package in ("vllm", "vllm-gguf-plugin", "torch", "transformers"):
try:
print(package, version(package))
except PackageNotFoundError:
print(package, "not installed")
Em um host NVIDIA, registre também nvidia-smi, o modelo da GPU, a memória disponível e a tag da imagem do contêiner ou o arquivo de bloqueio do ambiente. Mantenha esse registro junto à revisão do repositório do modelo e ao nome da quantização. Se uma atualização futura falhar, esses detalhes tornam possível comparar dois ambientes conhecidos em vez de adivinhar qual dependência foi alterada.
2. Instale o plugin GGUF no ambiente de serviço
Com um ambiente vLLM compatível já preparado, a documentação estável atual fornece este comando de instalação do pacote:
uv pip install vllm-gguf-plugin
Verifique se o uv está operando no ambiente que contém o executável vllm. Instalar um plugin em um ambiente virtual e iniciar um servidor a partir de outro não disponibilizará o plugin para esse servidor.
Para uma compilação a partir do código-fonte, siga as instruções de instalação do repositório do plugin. Elas exigem um toolkit CUDA ou ROCm e compilam em relação à instalação do PyTorch usada pelo vLLM; por esse motivo, a instalação editável documentada desativa o isolamento de compilação. Use as instruções do repositório para a revisão escolhida, em vez de adicionar flags de compilador não relacionadas até que uma compilação seja concluída com sucesso.
O repositório do plugin também lista famílias de modelos e quantizações testadas para geração. Use esses testes como ponto de partida para um primeiro canário. Eles não comprovam que toda conversão GGUF de todos os modelos funciona.
3. Carregue um checkpoint pequeno com um tokenizer explícito
O comando a seguir usa o pequeno exemplo Qwen documentado pelo projeto do plugin, adiciona um listener apenas local e fornece à API um nome de modelo previsível:
vllm serve Qwen/Qwen3-0.6B-GGUF:Q8_0 \
--tokenizer Qwen/Qwen3-0.6B \
--served-model-name gguf-canary \
--host 127.0.0.1 \
--port 8000
Este é um teste rápido de compatibilidade, não um benchmark de desempenho. Ele baixa os ativos do modelo e requer um runtime e dispositivo compatíveis. Não interprete a escolha do checkpoint pequeno como uma recomendação de modelo para sua aplicação.
Para um arquivo local, substitua o seletor de modelo pelo caminho GGUF real e mantenha o tokenizador correspondente do modelo base. Confirme que o arquivo está completo e que qualquer tratamento de arquivos divididos é compatível com a versão instalada antes de servi-lo. Renomear um checkpoint arbitrário não converte seu formato.
Se os metadados de configuração não puderem ser resolvidos, a documentação atual oferece --hf-config-path como uma entrada de configuração explícita. Use uma configuração que realmente pertença à arquitetura base do checkpoint. Uma configuração conveniente, mas não relacionada, pode transformar uma falha clara de carregamento em erros de tensores ou de saída mais difíceis de diagnosticar.
4. Separe as verificações de carregamento, API e saída
Quando o servidor informar que está pronto, consulte a lista de modelos dele em um segundo terminal:
curl --fail --silent --show-error http://127.0.0.1:8000/v1/models
Em seguida, envie uma pequena conclusão para o nome servido explicitamente:
curl --fail --silent --show-error \
http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{"model":"gguf-canary","prompt":"The capital of France is","max_tokens":16,"temperature":0}'
A documentação do servidor compatível com OpenAI descreve os endpoints compatíveis e o comportamento das solicitações. Uma conclusão simples mantém a primeira verificação independente da configuração do modelo de chat. Depois que isso passar, teste individualmente seu modelo de chat real, os requisitos de saída estruturada, o streaming e outros recursos da aplicação.
Mantenha três resultados separados no registro da sua implantação:
- Carregamento: os pesos e o tokenizador são inicializados sem erros de camadas ou tensores não compatíveis.
- Servir: o endpoint necessário retorna uma resposta válida para o nome de modelo servido.
- Uso: as saídas atendem a um pequeno conjunto de critérios de correção específicos da aplicação.
Uma resposta com HTTP 200 passa apenas na parte da API. Texto vazio, tokens repetidos, formatação incorreta ou respostas de tarefas que falham ainda exigem investigação. Mantenha o servidor inicial vinculado ao localhost; adicione seus controles normais de autenticação e rede antes de expô-lo a outros clientes.
Solução de problemas pela primeira etapa que falhar
| Sintoma | Verifique primeiro | Próxima alteração controlada |
|---|---|---|
| Plugin ou método de quantização não é reconhecido | Ambiente Python ativo e versões dos pacotes instalados | Reproduza em um ambiente limpo e compatível |
| A importação falha com um erro binário ou de símbolo | Alinhamento entre PyTorch, CUDA/ROCm e a compilação do plugin | Recompile usando o procedimento documentado do plugin |
| O seletor de modelo ou quantização não pode ser encontrado | Grafia do repositório, quantização selecionada, permissões, integridade do download | Tente o pequeno checkpoint documentado pelo projeto |
| Os nomes ou formatos dos tensores não correspondem | Arquitetura do modelo, origem da conversão, configuração | Use uma conversão compatível do mesmo modelo base |
| O carregamento para próximo do tokenizador | Identidade e revisão do tokenizador | Forneça explicitamente o tokenizador correspondente do modelo base |
| A conclusão funciona, mas o chat falha | Modelo de chat e formato de solicitação da aplicação | Teste uma solicitação mínima de chat antes de adicionar recursos extras |
| O modelo carrega, mas fica sem memória sob tráfego | Comprimentos de contexto, solicitações ativas, memória de execução, cache KV | Reduza uma dimensão da carga de trabalho e repita o mesmo teste |
Salve o primeiro erro significativo e o comando exato. Alterar modelo, tokenizador, driver e concorrência ao mesmo tempo pode eliminar um erro enquanto oculta sua causa.
Decida se deve manter o GGUF após a aprovação na compatibilidade
Um arquivo menor é útil quando o armazenamento dos pesos ou a memória é sua restrição. Ele não estabelece uma vantagem de latência. Compare o mesmo modelo base e conjunto de tarefas com um checkpoint alternativo compatível antes de escolher um formato para servir.
Use os comprimentos esperados de entrada e saída, bem como os níveis de solicitações simultâneas. Registre o sucesso das tarefas, o tempo até o primeiro token, a latência de cauda, o throughput e o pico de memória. A CLI oficial de benchmark de serving pode gerar tráfego controlado; suas opções e conjuntos de dados devem corresponder à versão instalada. Uma execução de estresse sintética e um teste de aceitação da aplicação respondem a perguntas diferentes, portanto, mantenha ambos os resultados separadamente.
Se os recursos ou saídas necessários do GGUF falharem, primeiro pergunte se você precisa desse checkpoint exato. Quando outro formato atende à carga de trabalho com menos incerteza operacional, a conversão ou outra distribuição compatível pode ser a escolha mais simples. Mantenha nossa comparação de formatos como o guia de decisão mais amplo, em vez de repetir aqui uma pesquisa completa sobre quantização.
Planeje a capacidade de GPU na nuvem a partir da carga de trabalho aprovada
Quando o modelo passar nas verificações acima, dimensione um ambiente de GPU para o requisito de memória e concorrência testado. O Cloud GPU Compute da Flatkey oferece opções de aluguel de GPUs NVIDIA. Confirme a configuração disponível, a região, a capacidade, os detalhes de acesso e os termos de aluguel para o teste pretendido. Este guia não afirma que o exemplo foi avaliado em benchmark em um aluguel da Flatkey nem que uma placa específica esteja sempre disponível.
Prepare uma breve passagem de informações: revisão do modelo, quantização, versões de software, necessidades estimadas de disco, limite de contexto, concorrência-alvo e limites de aceitação. Isso torna uma discussão de infraestrutura concreta e evita que um problema de compatibilidade de software seja confundido com a necessidade de alugar uma GPU maior.
Perguntas frequentes
O vLLM oferece suporte a todos os modelos GGUF?
Não. Valide juntos a arquitetura, a quantização, o tokenizador, o hardware e os recursos. O suporte a um formato de arquivo não significa suporte universal a todos os modelos armazenados nesse formato.
Por que guias mais antigos dizem para fornecer um arquivo local?
Eles podem descrever uma versão anterior. A documentação versionada do vLLM e as orientações atuais de plugins podem descrever caminhos de carregamento diferentes. Use as instruções que correspondem à sua stack instalada.
Posso reutilizar o tokenizador de outro modelo?
Use o tokenizador pertencente ao modelo base do checkpoint, a menos que o publicador documente explicitamente outra opção compatível. Um servidor que inicia com um tokenizador não relacionado ainda pode produzir resultados incorretos.
O carregamento bem-sucedido é suficiente para produção?
Não. Conclua verificações de endpoint, qualidade da tarefa, recursos e carga realista. A resposta prática para o suporte a GGUF no vLLM é uma configuração reprodutível aprovada, não apenas uma instalação bem-sucedida do pacote.
