Construisez un serveur d’inférence compatible OpenAI sur vos propres GPU : guide de l’API compatible OpenAI du serveur d’inférence vLLM

Si vous disposez déjà de capacité GPU, un serveur d’inférence compatible OpenAI permet à votre application de conserver la même forme client tout en remplaçant le backend d’une API de modèle hébergée par votre propre infrastructure. Le parcours habituel est simple dans son principe : exécuter vLLM ou LocalAI sur un nœud GPU, exposer une API /v1, pointer le base_url de votre SDK vers ce point de terminaison, puis durcir le service pour l’authentification, le routage, la supervision et la capacité.

Ce guide se concentre sur la mise en place pratique : comment déployer un vllm inference server openai compatible api, quoi tester avant de le placer derrière du trafic de production, et quand il est plus judicieux de conserver l’auto-hébergement comme référence tout en orientant la plupart des charges de travail vers une API de modèle managée comme Flatkey.

Réponse rapide

Pour la plupart des charges de travail textuelles LLM, commencez avec vLLM. Il fournit un serveur HTTP compatible OpenAI, prend en charge les points de terminaison courants de type OpenAI tels que les chat completions, completions, embeddings et la liste des modèles selon le type de modèle chargé, et fournit des images Docker officielles pour le déploiement.

Une pile auto-hébergée minimale ressemble à ceci :

Utilisez un vllm inference server openai compatible api lorsque vous avez besoin d’un contrôle direct du matériel, d’une localisation des données, de poids de modèle personnalisés ou d’une économie de service à haut volume prévisible. Utilisez une base de référence via passerelle/API de modèle lorsque vous avez surtout besoin de sorties fiables et que vous ne voulez pas gérer l’utilisation des GPU, la dérive des pilotes, le chargement des modèles et le basculement.

Avant de construire : décidez si l’auto-hébergement en vaut la peine

Faire fonctionner votre propre serveur d’inférence compatible OpenAI n’est pas automatiquement moins cher. Cela peut être excellent lorsque vos GPU sont très utilisés et que votre charge de travail correspond au modèle que vous hébergez. Cela peut devenir coûteux lorsque l’utilisation est irrégulière, que les prompts varient énormément, que la qualité des modèles change souvent, ou que l’équipe passe plus de temps à déboguer l’infrastructure qu’à livrer le produit.

Utilisez ce tableau de décision avant de louer ou d’acheter du matériel :

Flatkey convient à la dernière colonne comme base de référence : un point de terminaison compatible OpenAI, une seule facturation et l’accès à de nombreux modèles officiels. Même si vous construisez un vllm inference server openai compatible api, conservez une base de référence d’API de modèle dans votre benchmark afin de pouvoir comparer la latence, la qualité et le coût par sortie acceptée plutôt que seulement le coût par heure GPU.

Architecture de référence

Un serveur d’inférence de production compatible OpenAI ne doit pas exposer directement le moteur de modèle à l’Internet public. Placez devant lui une fine couche de contrôle.

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]

Le choix de conception important consiste à séparer la compatibilité des opérations. vLLM peut parler l’API de style OpenAI. Votre front d’accès doit gérer l’authentification, les quotas, les limites de taille des requêtes, TLS, les journaux d’audit et le comportement de repli.

Étape 1 : préparez l’hôte GPU

Commencez avec une machine GPU Linux propre. Vérifiez que l’hôte dispose de :

• Un pilote NVIDIA compatible avec le GPU et la pile CUDA que vous prévoyez d’exécuter.
• Docker ou un autre runtime de conteneur pris en charge.
• NVIDIA Container Toolkit configuré afin que les conteneurs puissent accéder aux GPU.
• Assez de stockage local ou réseau pour les poids du modèle.
• Un chemin réseau qui n’expose pas le port d’inférence avant que l’authentification et TLS soient en place.

L’installation du conteneur toolkit de NVIDIA configure Docker avec nvidia-ctk runtime configure --runtime=docker, puis redémarre Docker. Après cela, un conteneur peut être exécuté avec un accès GPU à l’aide des indicateurs GPU de Docker.

Exécutez ces vérifications avant d’installer le serveur de modèle :

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

Si l’une ou l’autre commande échoue, corrigez d’abord la couche pilote/runtime. Un vllm inference server openai compatible api ne peut pas être stable lorsque le runtime GPU de base est instable.

Étape 2 : démarrez une API compatible OpenAI du serveur d’inférence vLLM

La documentation officielle de déploiement Docker de vLLM identifie vllm/vllm-openai comme l’image pour exécuter un serveur compatible OpenAI. Un premier lancement pratique ressemble à ceci :

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

Pour un modèle privé, remplacez l’identifiant du modèle par votre propre dépôt ou chemin local. En production, figez les tags d’image et les révisions de modèle plutôt que de déployer latest.

Testez ensuite la liste des modèles :

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

Et testez les complétions 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
  }'

C’est le premier jalon fonctionnel : une vllm inference server openai compatible api locale que votre application peut appeler avec la même forme de requête qu’elle utilise déjà pour le chat au style OpenAI.

Étape 3 : pointez votre SDK existant vers le point de terminaison local

La plupart des travaux de migration compatibles OpenAI devraient se faire dans la configuration, et non dans la logique applicative. Avec le modèle du SDK Python, définissez un base_url et une clé API personnalisés :

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)

En production, ne pointez pas les workers de l’application directement vers un processus vLLM brut. Pointez-les vers votre propre passerelle interne ou équilibreur de charge :

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

Cette passerelle peut acheminer vers vLLM, bloquer les champs de requête non pris en charge, normaliser les alias de modèles et basculer vers Flatkey ou une autre API de modèle lorsque le pool auto-hébergé est saturé.

Étape 4 : sachez ce que « compatible OpenAI » ne signifie pas

Compatible OpenAI ne signifie pas que chaque point de terminaison, comportement de modèle, appel d’outil, événement de streaming ou option propre au fournisseur se comporte exactement comme OpenAI. Cela signifie que le serveur accepte une forme familière pour certains points de terminaison.

Avant de considérer la migration comme terminée, testez :

L’approche la plus sûre consiste à maintenir une suite de tests de compatibilité. Envoyez un ensemble fixe de requêtes réelles d’application à OpenAI, Flatkey et à votre vllm inference server openai compatible api. Comparez la latence, la validité du schéma, le comportement de refus, la qualité de sortie et le taux de sortie acceptée.

Étape 5 : dimensionnez la mémoire GPU pour le modèle et le trafic

Le principal mode d’échec d’un service n’est pas « le serveur démarre lentement ». C’est « le serveur démarre, puis s’écroule sous la vraie longueur de contexte et la concurrence ».

Planifiez la mémoire en fonction de :

• Les poids du modèle.
• Le cache KV pour le contexte et les séquences concurrentes.
• Les surcharges d’exécution.
• La fragmentation et la marge de sécurité.
• Le parallélisme tensoriel lorsqu’un modèle ne tient pas sur un seul GPU.
• Les compromis de quantification si vous utilisez une précision inférieure.

Pour une feuille de calcul plus approfondie, utilisez le guide Flatkey sur les exigences de mémoire GPU pour les LLM. Pour la planification au niveau du cluster, associez cela à une analyse de type architecture de cluster GPU et TCO de cluster GPU.

Une règle d’acceptation approximative :

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

Si vous ne pouvez pas conserver cette marge, réduisez la longueur du contexte, réduisez la concurrence, utilisez un modèle plus petit, répartissez sur plusieurs GPU, ou redirigez le trafic excédentaire hors du pool auto-hébergé.

Étape 6 : ajoutez une couche API avant la production

Le serveur vLLM brut n’est pas votre plan de contrôle de production complet. Placez une couche d’entrée devant lui et faites en sorte que cette couche soit responsable de :

• Terminaison TLS.
• Authentification de service à service.
• Limites de taille du corps des requêtes.
• Limites de débit par équipe ou par application.
• Mappage des alias de modèle.
• Journaux de requêtes structurés.
• Budgets de timeout et de retry.
• Routage canari.
• Routage de repli.

Exemple de structure 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;
  }
}

Cela n’est qu’un point de départ. Les équipes de production devraient ajouter l’authentification, le mTLS ou un réseau privé, des politiques de journalisation des requêtes, ainsi que des limites explicites sur la taille du prompt et la longueur de sortie.

Étape 7 : mesurez la sortie acceptée, pas seulement les tokens par seconde

Les tableaux de bord de service GPU mettent souvent trop l’accent sur le débit. Les tokens par seconde comptent, mais les équipes produit se soucient généralement de la sortie acceptée : des réponses assez rapides, suffisamment valides et assez bonnes pour être livrées à l’utilisateur ou à un workflow en aval.

Suivez :

Calculez ensuite le coût par sortie acceptée :

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

C’est là qu’un vllm inference server openai compatible api se compare honnêtement aux API gérées. Si le GPU local est moins cher par token brut mais moins performant sur les retries, les échecs ou le temps opérateur, le coût par sortie acceptée peut être plus élevé que prévu.

Étape 8 : ajoutez un repli au lieu de traiter la machine GPU comme un point de défaillance unique

Votre application ne devrait pas se soucier de savoir si la réponse provient de vLLM auto-hébergé, de Flatkey, ou d’un autre chemin de modèle. Elle devrait demander un alias de modèle et recevoir une réponse ou un échec contrôlé.

Utilisez des règles de routage comme :

Cette conception permet à l’équipe de conserver l’économie et le contrôle de l’auto-hébergement sans lier la disponibilité du produit à un seul serveur d’inférence.

vLLM vs LocalAI pour une inférence locale compatible OpenAI

vLLM et LocalAI apparaissent tous deux dans les recherches d’un serveur d’inférence compatible OpenAI, mais ils répondent à des besoins différents.

Pour la charge de travail cible de cet article, commencez par un vllm inference server openai compatible api. Évaluez LocalAI lorsque votre objectif est une expérimentation locale plus large ou une API locale unique sur plusieurs backends plutôt qu’un débit maximal de service GPU pour une seule famille de LLM.

Liste de contrôle de production

Utilisez cette liste avant de rediriger de vrais utilisateurs :

• [ ] Le pilote GPU et le runtime de conteneur ont été vérifiés avec nvidia-smi à l’intérieur d’un conteneur.
• [ ] Le tag de l’image vLLM et la révision du modèle sont épinglés.
• [ ] L’alias du modèle est stable et documenté.
• [ ] /v1/models et /v1/chat/completions ont été testés via l’URL d’edge finale.
• [ ] Le streaming a été testé avec des déconnexions client.
• [ ] Les tests de long contexte et de concurrence ont été exécutés à la forme de production attendue.
• [ ] L’authentification a été ajoutée à l’edge ; le port brut de vLLM n’est pas सार्वजनिक.
• [ ] La taille du corps de requête, le nombre maximal de jetons de sortie et les délais d’attente sont imposés.
• [ ] Les journaux excluent les données sensibles des prompts, sauf approbation explicite.
• [ ] Les métriques capturent la latence, la mise en file d’attente, la mémoire GPU, les taux d’erreur et le taux de sortie acceptée.
• [ ] Une route de repli est configurée en cas de saturation et d’incident.
• [ ] La base de référence de l’API managée est mesurée avec les mêmes prompts.
• [ ] Le plan de retour arrière a été testé.

Erreurs courantes

La plus grande erreur consiste à considérer le premier curl réussi comme la fin du travail. Ce n’est que le début.

Autres échecs courants :

• Faire tourner des images latest en production sans épingler les versions.
• Exposer le port d’inférence brut à Internet.
• Supposer que chaque paramètre de requête OpenAI est pris en charge.
• Évaluer un seul prompt court et qualifier le résultat de « prêt pour la production ».
• Ignorer la croissance du cache KV liée à la vraie longueur du contexte.
• Oublier que le temps de chargement du modèle affecte les déploiements et la reprise.
• Mesurer le coût en GPU-heures sans tenir compte du temps opérateur, des tentatives et des échecs de qualité.
• Ignorer le fallback parce que le point de terminaison local est « compatible OpenAI ».

Un vllm inference server openai compatible api en production est une infrastructure utile. Ce n’est pas une compatibilité magique, et ce n’est pas un substitut à la discipline opérationnelle.

Quand utiliser Flatkey avec vos propres GPU

Flatkey est surtout utile dans cette architecture comme base de référence de modèle/API managée et comme chemin de secours. Gardez votre application sur une forme de client compatible OpenAI, puis acheminez une partie du trafic vers votre pool GPU local et une autre vers Flatkey.

Cela vous donne :

• Un moyen de comparer la qualité des sorties auto-hébergées à celle des modèles hébergés.
• Une capacité de débordement lorsque les GPU locaux sont saturés.
• Une route de repli pendant des incidents liés au pilote, au modèle ou au déploiement.
• L’accès à d’autres familles de modèles sans ajouter davantage de clés fournisseur.
• Un chemin plus propre vers des API managées si un modèle auto-hébergé est moins performant.

La décision n’est pas « posséder des GPU ou utiliser des API ». Pour beaucoup d’équipes, la configuration durable combine les deux : garder la voie GPU là où elle apporte contrôle ou avantage de coût, et conserver une route managée pour la résilience et le choix des modèles.

FAQ

Qu’est-ce qu’un serveur d’inférence compatible OpenAI ?

Un serveur d’inférence compatible OpenAI expose des points de terminaison HTTP avec des formes de requête et de réponse de style OpenAI, généralement sous /v1. Cela permet aux applications d’utiliser une configuration SDK familière, comme un base_url personnalisé, tout en envoyant le trafic vers un backend différent.

vLLM est-il un serveur d’inférence compatible OpenAI ?

Oui. vLLM fournit un serveur compatible OpenAI et documente la prise en charge de points de terminaison courants de style OpenAI tels que les chat completions, les completions, les embeddings et le listage des modèles, selon le type de modèle et la fonctionnalité.

Puis-je exécuter localement un serveur vLLM compatible OpenAI ?

Oui. Vous pouvez exécuter vLLM localement sur une station de travail ou un serveur GPU, puis exposer le point de terminaison /v1 à votre application. En production, placez devant lui un edge ou une passerelle interne avec authentification.

De quel matériel ai-je besoin ?

Cela dépend de la taille du modèle, de la précision, de la longueur du contexte et de la cible de concurrence. Commencez par dimensionner les poids du modèle plus le cache KV et une marge, puis testez avec de vrais prompts. Un petit modèle instruct peut tenir sur un seul GPU ; un modèle 70B ou une charge à forte concurrence peut nécessiter des GPU à plus grande mémoire ou du parallélisme tensoriel.

Dois-je utiliser vLLM ou LocalAI ?

Utilisez d’abord vLLM lorsque la charge de travail consiste en une inférence LLM à haut débit sur GPU. Évaluez LocalAI si vous souhaitez un serveur local plus large compatible OpenAI sur plusieurs backends ou modalités locaux.

« Compatible OpenAI » signifie-t-il identique au remplacement direct ?

Non. La forme du point de terminaison peut correspondre, mais le comportement du modèle, les paramètres pris en charge, les outils, le streaming, les embeddings, les erreurs et la comptabilisation des jetons peuvent différer. Exécutez des tests de compatibilité avant de basculer le trafic de production.

Conclusion

Construire un vllm inference server openai compatible api est le moyen pratique le plus rapide de transformer vos propres GPU en point de terminaison de style OpenAI. La construction de base est simple : préparez le runtime GPU, lancez vLLM, pointez le SDK vers /v1, puis ajoutez l’edge, la surveillance, les tests de compatibilité et les routes de repli qui le rendent prêt pour la production.

Les meilleures équipes ne s’arrêtent pas à « ça fonctionne ». Elles comparent l’inférence auto-hébergée à une base de référence d’API de modèle managée, mesurent les sorties acceptées et gardent une route de repli prête. C’est ainsi que vous obtenez le contrôle de vos propres GPU sans faire dépendre chaque demande produit d’un seul serveur d’inférence fragile.

Références officielles

• Documentation du serveur compatible OpenAI de vLLM : https://docs.vllm.ai/en/latest/serving/online_serving/
• Documentation de déploiement Docker de vLLM : https://docs.vllm.ai/en/latest/deployment/docker/
• Guide d’installation du NVIDIA Container Toolkit : https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• README du SDK Python OpenAI : https://github.com/openai/openai-python
• Documentation du projet LocalAI : https://localai.io/