Construa um servidor de inferência compatível com OpenAI nas suas próprias GPUs: guia da API compatível com OpenAI do vLLM Inference Server

Se você já tem capacidade de GPU, um servidor de inferência compatível com OpenAI permite que sua aplicação mantenha a mesma estrutura de cliente enquanto você troca o backend de uma API de modelo hospedada para sua própria infraestrutura. O caminho usual é simples em conceito: execute vLLM ou LocalAI em um nó de GPU, exponha uma API /v1, aponte o base_url do seu SDK para esse endpoint e, depois, fortaleça o serviço com autenticação, roteamento, monitoramento e capacidade.

Este guia foca na construção prática: como colocar em pé um vllm inference server openai compatible api, o que testar antes de colocá-lo atrás de tráfego de produção e quando é mais inteligente manter o self-hosting como referência enquanto você direciona a maior parte das cargas de trabalho por meio de uma API de modelo gerenciada, como a Flatkey.

A Resposta Rápida

Para a maioria das cargas de trabalho de texto de LLM, comece com o vLLM. Ele fornece um servidor HTTP compatível com OpenAI, suporta endpoints comuns no estilo OpenAI, como chat completions, completions, embeddings e listagem de modelos, dependendo do tipo de modelo carregado, e oferece imagens oficiais do Docker para implantação.

Uma stack mínima auto-hospedada se parece com isto:

Use uma vllm inference server openai compatible api quando precisar de controle direto do hardware, localidade dos dados, pesos de modelo personalizados ou economia previsível de serving em alto volume. Use uma base de gateway/API de modelo quando você precisar principalmente de resultados confiáveis e não quiser assumir a utilização de GPU, desvio de driver, carregamento de modelo e failover.

Antes de Construir: Decida se o Self-Hosting Vale a Pena

Executar seu próprio servidor de inferência compatível com OpenAI não é automaticamente mais barato. Pode ser excelente quando suas GPUs ficam ocupadas e sua carga de trabalho se encaixa no modelo que você hospeda. Pode ser caro quando a utilização é irregular, os prompts variam muito, a qualidade do modelo muda com frequência ou a equipe passa mais tempo depurando a infraestrutura do que entregando produto.

Use esta tabela de decisão antes de alugar ou comprar hardware:

A Flatkey se encaixa na última coluna como base: um endpoint compatível com OpenAI, uma cobrança e acesso a muitos modelos oficiais. Mesmo que você construa uma vllm inference server openai compatible api, mantenha uma base de API de modelo no seu benchmark para que você possa comparar latência, qualidade e custo por saída aceita, e não apenas custo por hora de GPU.

Arquitetura de Referência

Um servidor de inferência de produção compatível com OpenAI não deve expor o motor de modelo diretamente à internet pública. Coloque uma camada fina de controle na frente dele.

flowchart LR
  A[OpenAI SDK / app workers] --> B[API edge: TLS, auth, rate limits]
  B --> C[OpenAI-compatible /v1 route]
  C --> D[vLLM inference server]
  D --> E[GPU node or GPU pool]
  D --> F[Metrics and logs]
  B --> G[Fallback route: Flatkey or another model API]

A escolha de design importante é separar compatibilidade de operações. O vLLM pode falar a API no estilo OpenAI. Seu edge deve ser responsável por autenticação, quota, limites de tamanho de requisição, TLS, logs de auditoria e comportamento de fallback.

Passo 1: Prepare o Host de GPU

Comece com uma máquina Linux de GPU limpa. Confirme que o host tem:

• Um driver NVIDIA compatível com a GPU e a stack CUDA que você planeja executar.
• Docker ou outro runtime de contêiner compatível.
• NVIDIA Container Toolkit configurado para que os contêineres possam acessar GPUs.
• Armazenamento local ou em rede suficiente para os pesos do modelo.
• Um caminho de rede que não exponha a porta de inferência até que autenticação e TLS estejam em vigor.

O fluxo de instalação do toolkit de contêineres da NVIDIA configura o Docker com nvidia-ctk runtime configure --runtime=docker e depois reinicia o Docker. Depois disso, um contêiner pode ser executado com acesso à GPU usando as flags de GPU do Docker.

Execute estas verificações antes de instalar o servidor do modelo:

nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

Se qualquer um dos comandos falhar, corrija primeiro a camada de driver/runtime. Um vllm inference server openai compatible api não pode ser estável quando o runtime básico da GPU é instável.

Passo 2: Inicie uma API compatível com OpenAI do vLLM Inference Server

A documentação oficial de implantação em Docker do vLLM identifica vllm/vllm-openai como a imagem para executar um servidor compatível com OpenAI. Uma primeira execução prática tem esta aparência:

docker run --rm --gpus all \
  --ipc=host \
  -p 8000:8000 \
  -e HUGGING_FACE_HUB_TOKEN="$HUGGING_FACE_HUB_TOKEN" \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name llama-3.1-8b-instruct

Para um modelo privado, substitua o id do modelo pelo seu próprio repositório ou caminho local. Em produção, fixe as tags da imagem e as revisões do modelo em vez de implantar latest.

Em seguida, teste a listagem de modelos:

curl http://localhost:8000/v1/models

E teste as conclusões de chat:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b-instruct",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Reply with one sentence about self-hosted inference."}
    ],
    "temperature": 0.2
  }'

Esse é o primeiro marco funcional: um vllm inference server openai compatible api local que seu aplicativo pode chamar com a mesma forma de requisição que já usa para chat no estilo OpenAI.

Passo 3: Direcione seu SDK existente para o endpoint local

A maior parte do trabalho de migração compatível com OpenAI deve acontecer na configuração, não na lógica do aplicativo. Com o padrão do SDK em Python, defina um base_url e uma chave de API personalizados:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="local-dev-key",
)

response = client.chat.completions.create(
    model="llama-3.1-8b-instruct",
    messages=[
        {"role": "user", "content": "Give me a deployment checklist."}
    ],
)

print(response.choices[0].message.content)

Em produção, não aponte os workers da aplicação diretamente para um processo vLLM bruto. Aponte-os para o seu próprio gateway interno ou balanceador de carga:

OPENAI_BASE_URL=https://inference.example.com/v1
OPENAI_API_KEY=<your-internal-service-token>

Esse gateway pode rotear para o vLLM, bloquear campos de requisição não suportados, normalizar aliases de modelos e fazer failover para Flatkey ou outra API de modelo quando o pool auto-hospedado estiver saturado.

Passo 4: Saiba o que "OpenAI-Compatible" não significa

Compatível com OpenAI não significa que todo endpoint, comportamento do modelo, chamada de ferramenta, evento de streaming ou opção específica do provedor se comporta exatamente como a OpenAI. Isso significa que o servidor aceita uma estrutura familiar para endpoints selecionados.

Antes de considerar a migração concluída, teste:

O padrão mais seguro é manter um conjunto de testes de compatibilidade. Envie um conjunto fixo de prompts reais do aplicativo para OpenAI, Flatkey e sua vllm inference server openai compatible api. Compare latência, validade do schema, comportamento de recusa, qualidade da saída e taxa de saída aceita.

Passo 5: Dimensione a memória da GPU para o modelo e o tráfego

O principal modo de falha do serving não é "o servidor inicia lentamente". É "o servidor inicia e depois cai sob o comprimento de contexto e a concorrência reais".

Planeje a memória com base em:

• Pesos do modelo.
• Cache KV para contexto e sequências concorrentes.
• Overhead de runtime.
• Fragmentação e margem de segurança.
• Parallelismo de tensor quando um modelo não cabe em uma única GPU.
• Compensações de quantização se você usar menor precisão.

Para uma planilha mais aprofundada, use o guia da Flatkey sobre requisitos de memória de GPU para LLMs. Para planejamento em nível de cluster, combine isso com análises no estilo de arquitetura de cluster de GPU e TCO de cluster de GPU.

Uma regra de aceitação aproximada:

usable_capacity = model_fit + target_context + target_concurrency + 20-30% headroom

Se você não conseguir manter a margem, reduza o comprimento do contexto, reduza a concorrência, use um modelo menor, distribua entre GPUs ou desvie o tráfego excedente para fora do pool auto-hospedado.

Passo 6: Adicione uma camada de API antes da produção

O servidor vLLM bruto não é sua plataforma completa de controle de produção. Coloque uma camada de borda na frente dele e faça com que ela seja responsável por:

• Encerramento TLS.
• Autenticação entre serviços.
• Limites no corpo da requisição.
• Limites de taxa por equipe ou por aplicativo.
• Mapeamento de alias de modelo.
• Logs estruturados de requisições.
• Orçamentos de timeout e retentativas.
• Roteamento canário.
• Roteamento de fallback.

Exemplo de configuração do Nginx:

server {
  listen 443 ssl;
  server_name inference.example.com;

  client_max_body_size 4m;

  location /v1/ {
    proxy_pass http://vllm_backend:8000/v1/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Request-Id $request_id;
    proxy_read_timeout 120s;
  }
}

Isso é apenas um ponto de partida. Equipes de produção devem adicionar autenticação, mTLS ou rede privada, políticas de registro de requisições e limites explícitos para o tamanho do prompt e o comprimento da saída.

Passo 7: Meça a saída aceita, não apenas tokens por segundo

Os painéis de serviço em GPU muitas vezes dão peso excessivo ao throughput. Tokens por segundo importam, mas as equipes de produto geralmente se preocupam com saídas aceitas: respostas rápidas o suficiente, válidas o suficiente e boas o suficiente para enviar ao usuário ou ao fluxo de trabalho downstream.

Acompanhe:

Depois calcule o custo por saída aceita:

cost_per_accepted_output =
  (gpu_cost + storage + network + ops_time + fallback_api_cost)
  / accepted_outputs

É aqui que uma vllm inference server openai compatible api recebe uma comparação honesta com APIs gerenciadas. Se a GPU local for mais barata por token bruto, mas pior em novas tentativas, falhas ou tempo do operador, o custo por saída aceita pode ser maior do que o esperado.

Passo 8: Adicione fallback em vez de tratar a máquina de GPU como um único ponto de falha

Sua aplicação não deve se importar se a resposta vem do vLLM auto-hospedado, da Flatkey ou de outra rota de modelo. Ela deve solicitar um alias de modelo e receber uma resposta ou uma falha controlada.

Use regras de roteamento como:

Esse design permite que a equipe mantenha a economia e o controle da auto-hospedagem sem vincular a disponibilidade do produto a um único servidor de inferência.

vLLM vs LocalAI para inferência local compatível com OpenAI

vLLM e LocalAI aparecem em buscas por um servidor de inferência compatível com OpenAI, mas atendem a necessidades diferentes.

Para a carga de trabalho-alvo deste artigo, comece com uma vllm inference server openai compatible api. Avalie o LocalAI quando seu objetivo for uma experimentação local mais ampla ou uma única API local sobre múltiplos backends, em vez do máximo throughput de serviço em GPU para uma única família de LLM.

Checklist de produção

Use isto antes de encaminhar usuários reais:

• [ ] Driver da GPU e runtime de contêiner verificados com nvidia-smi dentro de um contêiner.
• [ ] Tag da imagem do vLLM e revisão do modelo fixadas.
• [ ] Alias do modelo estável e documentado.
• [ ] /v1/models e /v1/chat/completions testados por meio da URL final na borda.
• [ ] Streaming testado com desconexões de cliente.
• [ ] Testes de contexto longo e concorrência executados na escala esperada de produção.
• [ ] Autenticação adicionada na borda; porta bruta do vLLM não pública.
• [ ] Tamanho do corpo da requisição, número máximo de tokens de saída e timeouts लागूcidos.
• [ ] Logs excluem dados sensíveis do prompt, salvo aprovação explícita.
• [ ] Métricas capturam latência, enfileiramento, memória da GPU, taxas de erro e taxa de saída aceita.
• [ ] Rota de fallback configurada para saturação e incidentes.
• [ ] Linha de base da API gerenciada medida com os mesmos prompts.
• [ ] Plano de rollback testado.

Erros Comuns

O maior erro é tratar o primeiro curl bem-sucedido como o fim do trabalho. Isso é apenas o começo.

Outras falhas comuns:

• Executar imagens latest em produção sem fixar versões.
• Expor a porta bruta de inferência para a internet.
• Assumir que todo parâmetro de requisição da OpenAI é suportado.
• Fazer benchmark com um prompt curto e chamar o resultado de "pronto para produção".
• Ignorar o crescimento do cache KV com o comprimento real do contexto.
• Esquecer que o tempo de carregamento do modelo afeta deploys e recuperação.
• Medir o custo por hora de GPU sem tempo de operador, tentativas e falhas de qualidade.
• Ignorar fallback porque o endpoint local é "compatível com OpenAI".

Um vllm inference server openai compatible api em produção é uma infraestrutura útil. Não é compatibilidade mágica, e não substitui disciplina operacional.

Quando Usar a Flatkey Junto com suas Próprias GPUs

A Flatkey é mais útil nessa arquitetura como a linha de base gerenciada do modelo/API e caminho de fallback. Mantenha sua aplicação com uma forma de cliente compatível com OpenAI e então direcione parte do tráfego para seu pool local de GPUs e parte para a Flatkey.

Isso lhe dá:

• Uma forma de comparar a qualidade da saída auto-hospedada com modelos hospedados.
• Capacidade de overflow quando as GPUs locais estiverem saturadas.
• Uma rota de fallback durante incidentes de driver, modelo ou deploy.
• Acesso a outras famílias de modelos sem adicionar mais chaves de provedor.
• Um caminho mais limpo de volta para APIs gerenciadas se um modelo auto-hospedado apresentar desempenho inferior.

A decisão não é "ter suas próprias GPUs ou usar APIs". Para muitas equipes, a configuração durável é ambas: usar a rota de GPU própria onde ela oferece controle ou vantagem de custo, e manter uma rota gerenciada para resiliência e escolha de modelo.

FAQ

O que é um servidor de inferência compatível com OpenAI?

Um servidor de inferência compatível com OpenAI expõe endpoints HTTP com formatos de requisição e resposta no estilo OpenAI, geralmente sob /v1. Isso permite que aplicações usem uma configuração de SDK familiar, como um base_url personalizado, enquanto enviam o tráfego para um backend diferente.

O vLLM é um servidor de inferência compatível com OpenAI?

Sim. O vLLM fornece um servidor compatível com OpenAI e documenta suporte para endpoints comuns no estilo OpenAI, como chat completions, completions, embeddings e listagem de modelos, dependendo do tipo de modelo e do recurso.

Posso executar localmente um servidor vLLM compatível com OpenAI?

Sim. Você pode executar o vLLM localmente em uma estação de trabalho ou servidor com GPU e então expor o endpoint /v1 para sua aplicação. Em produção, coloque uma borda autenticada ou um gateway interno à frente dele.

De que hardware eu preciso?

Depende do tamanho do modelo, da precisão, do comprimento do contexto e da meta de concorrência. Comece dimensionando os pesos do modelo mais o cache KV e a folga, e depois teste com prompts reais. Um modelo pequeno de instruções pode caber em uma GPU; um modelo de 70B ou uma carga de alta concorrência pode exigir GPUs com mais memória ou paralelismo de tensor.

Devo usar vLLM ou LocalAI?

Use o vLLM primeiro quando a tarefa for inferência de LLM de alto throughput em GPUs. Avalie o LocalAI quando quiser um servidor local mais amplo, compatível com OpenAI, em múltiplos backends locais ou modalidades.

Compatível com OpenAI significa idêntico e plug-and-play?

Não. A forma dos endpoints pode coincidir, mas o comportamento do modelo, os parâmetros suportados, as ferramentas, o streaming, os embeddings, os erros e a contagem de tokens podem diferir. Execute testes de compatibilidade antes de mudar o tráfego de produção.

Conclusão

Construir uma vllm inference server openai compatible api é a maneira prática mais rápida de transformar suas próprias GPUs em um endpoint no estilo OpenAI. A construção central é direta: prepare o runtime da GPU, execute o vLLM, aponte o SDK para /v1 e, em seguida, adicione a borda, o monitoramento, os testes de compatibilidade e as rotas de fallback que o tornam pronto para produção.

As melhores equipes não param em "está funcionando". Elas comparam a inferência auto-hospedada com uma linha de base de API de modelo gerenciada, medem as saídas aceitas e mantêm uma rota de fallback pronta. É assim que você obtém o controle das suas próprias GPUs sem fazer com que cada requisição do produto dependa de um servidor de inferência frágil.

Referências Oficiais

• Documentação do servidor compatível com OpenAI do vLLM: https://docs.vllm.ai/en/latest/serving/online_serving/
• Documentação de implantação com Docker do vLLM: https://docs.vllm.ai/en/latest/deployment/docker/
• Guia de instalação do NVIDIA Container Toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• README do SDK Python da OpenAI: https://github.com/openai/openai-python
• Documentação do projeto LocalAI: https://localai.io/