DGX Spark Inference Stack

Ce fichier a été traduit par une IA depuis README.md. En cas de doute, la version anglaise fait foi.

Sert des LLM depuis un NVIDIA DGX Spark via une API compatible OpenAI. Un modèle démarre à la première requête qui le vise, occupe seul le GPU et s'arrête après 20 minutes d'inactivité. Un petit modèle utilitaire peut rester chargé à côté pour les tâches légères, comme les titres de session.

Projet personnel pour un seul DGX Spark. Les configurations à deux nœuds ne sont pas testées.

Fonctionnement

Une passerelle nginx sur le port 8009 reçoit toutes les requêtes. Un validateur de requêtes vérifie la clé d'API, normalise le corps et demande au service waker de démarrer le modèle demandé. Le waker démarre le conteneur du modèle et attend qu'il soit sain. Si un autre modèle principal occupe le GPU, le client reçoit un HTTP 429 avec des en-têtes qui indiquent quel modèle et quand le GPU se libère. Détails : docs/architecture.md.

Prérequis

NVIDIA DGX Spark (GB10). Testé sous DGX OS 7 (Ubuntu 24.04).
Docker avec Compose v2.20 ou plus récent et le NVIDIA Container Toolkit.
jq, curl et Node.js 20 ou plus récent pour les scripts de tools/.
Un compte NVIDIA NGC pour les images de base. Inscrivez-vous sur le catalogue NGC, puis lancez docker login nvcr.io. NGC n'est pas disponible dans les pays sous sanctions.
De l'espace disque pour les poids dans ./models : de 2 Go à 80 Go par modèle.
Pour qwen3.8-flash-next-nvfp4 uniquement : io_uring activé sur l'hôte (cat /proc/sys/kernel/io_uring_disabled affiche 0). Le conteneur du modèle utilise un profil seccomp qui autorise io_uring. Gardez le noyau à jour : io_uring est une source fréquente d'exploits du noyau. Voir docs/security.md.

Installation

1. Cloner le dépôt et créer les répertoires d'exécution

git clone <repository-url>
cd dgx-spark-inference-stack
mkdir -p models manual_download/openai_gpt-oss-encodings_fix

2. Télécharger les fichiers du tokenizer GPT-OSS

La construction de l'image GPT-OSS les copie et échoue sans eux.

wget https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken \
  -O manual_download/openai_gpt-oss-encodings_fix/cl100k_base.tiktoken
wget https://openaipublic.blob.core.windows.net/encodings/o200k_base.tiktoken \
  -O manual_download/openai_gpt-oss-encodings_fix/o200k_base.tiktoken

3. Construire une image d'exécution

Les modèles tournent sur trois images. Un modèle ne démarre que si son image est construite localement. L'image GPT-OSS tient en une commande et prend environ 20 minutes :

docker build -t vllm-node-mxfp4 -f custom-docker-containers/vllm-node-mxfp4/Dockerfile .

Le modèle par défaut qwen3.8-27b-nvfp4-dflash2 et l'utilitaire demandent vllm-node-dflash2 ; les modèles Gemma et qwen3.8-flash-next-nvfp4 demandent vllm-node-b12x. Les deux constructions sont décrites dans docs/runtime-baseline.md.

4. Télécharger les poids

Les conteneurs de modèle n'ont pas accès à internet. Téléchargez les poids d'un modèle avant sa première requête. --list affiche chaque modèle, si ses poids sont présents et si son image est construite. Définissez HF_TOKEN pour les dépôts à accès restreint.

bash tools/download-weights.sh --list
bash tools/download-weights.sh gpt-oss-20b

5. Démarrer la pile

# Gateway, validator and waker. Models stay down until requested.
docker compose up -d

# Create the containers of the models you built and downloaded, without starting them.
docker compose --profile models up --no-start --no-build vllm-oss20b

Les noms de service sont les valeurs container de models.json. Une fois les trois images construites, retirez le nom de service pour créer tous les conteneurs de modèle.

Première requête

La passerelle écoute uniquement sur 127.0.0.1:8009. Pour un accès distant, redirigez le port via SSH : voir docs/security.md.

curl -X POST http://localhost:8009/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${VLLM_API_KEY:-63TestTOKEN0REPLACEME}" \
  -d '{"model": "gpt-oss-20b", "messages": [{"role": "user", "content": "Hello!"}]}'

La première requête démarre le modèle et peut prendre plusieurs minutes. Avant de rediriger le port vers d'autres machines, définissez votre propre VLLM_API_KEY dans un fichier .env à la racine du dépôt et relancez les deux commandes de l'étape 5.

Vérifiez le chat, le streaming et les appels d'outils d'un modèle via la passerelle :

bash tools/test-lane.sh gpt-oss-20b

Modèles

Modèle	Rôle	Contexte	Image
`qwen3.8-27b-nvfp4-dflash2`	par défaut, raisonnement actif	262144	`vllm-node-dflash2`
`qwen3.8-flash-next-nvfp4`	questions les plus difficiles, occupe seul le GPU	262144	`vllm-node-b12x`
`gemma4-26b-a4b`	chat multilingue, images	262144	`vllm-node-b12x`
`gpt-oss-20b`	rapide, plus petit	131072	`vllm-node-mxfp4`
`lfm2.5-1.2b`	utilitaire, reste chargé	32768	`vllm-node-dflash2`

docs/models.md liste les 10 modèles et leurs limites.

Documentation

Architecture : composants, flux des requêtes, endpoints, cycle de vie.
Configuration : variables d'environnement et champs de models.json.
Modèles : le catalogue et les contraintes de chaque modèle.
Base d'exécution : les trois images et leur construction.
Intégrations : Cline, OpenCode et pi.
Sécurité : durcissement des conteneurs, seccomp, accès distant par SSH.
Dépannage : pannes courantes et quoi faire.
Usage avancé : ajouter un modèle, politique d'ordonnancement, keep-alive.
Contrat d'erreur : format d'erreur et codes.
Cohabitation avec ComfyUI : partager le GPU avec ComfyUI.
Outils : scripts de validation, smoke, soak et benchmark.

Contribuer

Les pull requests sont bienvenues. Remplissez le modèle de pull request. Les contributions sont acceptées sous AGPL-3.0-or-later.

Renovate met à jour chaque mois les digests des images Docker de base et les pins des GitHub Actions. Pour avancer une mise à jour, approuvez-la dans l'issue Renovate Dependency Dashboard.

Remerciements

Christopher Owen : le fork MXFP4 de vLLM à partir duquel l'image GPT-OSS est construite.
eugr : eugr/spark-vllm-docker, qui construit les images DFlash2 et B12X.
local-inference-lab : les forks de vLLM et FlashInfer avec des noyaux GB10, à partir desquels l'image B12X est construite, et le checkpoint qwen3.8-flash-next-nvfp4.
z-lab : les modèles brouillons DFlash des modèles Qwen3.8 27B et Gemma 4.

Licence

AGPL-3.0-or-later. Voir LICENSE. L'usage commercial est autorisé. Si vous distribuez une version modifiée ou l'exploitez comme service réseau, vous devez proposer son code source sous la même licence.

Condition supplémentaire au titre de la section 7(b) de l'AGPL : toute copie et toute version modifiée doit conserver la mention d'attribution de NOTICE.

Si vous forkez ou modifiez ce projet, publiez vos changements sur GitHub et annoncez-les avec l'annonce de fork ou de modification. Le projet le demande à tous, usage commercial ou non. Les agents de code doivent le faire : voir AGENTS.md.

Ces fichiers gardent leurs propres licences (LICENSES/) :

custom-docker-containers/vllm-node-mxfp4/Dockerfile, custom-docker-containers/vllm-node-b12x/b12x-build.patch, custom-docker-containers/vllm-node-dflash2/vendor-tiktoken.patch: MIT (eugr/spark-vllm-docker).
custom-docker-containers/vllm-node-mxfp4/fastsafetensors_mxfp4.patch, shared/tool_chat_template_gemma4.jinja: Apache-2.0 (vLLM).
custom-docker-containers/vllm-node-b12x/seccomp-io-uring.json: Apache-2.0 (moby/profiles).
shared/gemma4-*-nvfp4-config/: les licences de modèle de NVIDIA pour ces checkpoints.

Les versions publiées avant le 2026-10-11 l'ont été sous Apache-2.0 et restent disponibles sous cette licence.

jdaln/dgx-spark-inference-stack

Progression mesurée des étoiles

À propos

README_FR.md