Tutoriel vLLM D3 : exécutez des modèles de décision IA en local avec Python

D3 est une famille de modèles de décision open-weight qui renvoient une probabilité pour chaque réponse au lieu de générer du texte. Vous pouvez classer un ticket de support, noter un article ou analyser un extrait vidéo en une seule requête vers un modèle exécuté sur votre propre machine, en seulement 87 millisecondes lors de nos tests.

La famille comprend 6 modèles, de 600 millions à 27 milliards de paramètres. Vous pouvez expérimenter avec les plus petits sur un matériel modeste et réserver les plus grands aux tâches plus exigeantes. D3 Edge est si léger qu’il peut même tourner sur des smartphones compatibles.

vLLM prend en charge D3 via son cadre Structured Decisions, ce qui vous permet de servir un modèle en local et de l’appeler via une simple interface de programmation d’applications (API). Le projet plus large vLLM Semantic Router ajoute des fonctionnalités de routage et de prise de décision pour les applications d’IA.

Dans ce tutoriel, je vous montre l’installation de D3 en local, les 3 types de décisions et vos premières prédictions. Ensuite, nous construirons 3 projets concrets :

1. Analyseur de qualité d’articles de blog par IA : utilisez le SDK Python TypeSafe et Olostep pour classer et évaluer des articles réels.
2. Compréhension d’images : analysez des images produit, identifiez les catégories et évaluez la qualité visuelle.
3. Compréhension de vidéos : analysez de courtes vidéos pour détecter les mouvements et les changements visuels.

À la fin, vous saurez exécuter D3 en local et l’utiliser pour créer des applications qui prennent des décisions sur du texte, des images et de la vidéo. Vous pouvez aussi consulter nos guides sur l’exécution locale de modèles de langage et sur l’accélération de l’inférence locale sur un GPU RTX 3090.

En bref

• D3 est une famille de modèles de décision open-weight qui renvoient des probabilités pour des questions de type choix, oui/non (Noul) et score plutôt que de générer du texte.
• D3 Mini (4B) traite le texte, l’image et la vidéo, et s’exécute avec vLLM sur un seul processeur graphique (GPU) NVIDIA RTX 3090.
• Vous servez le modèle avec vllm serve et l’appelez via le SDK Python TypeSafe ou l’endpoint /v1/systemone.
• Nous réalisons 3 projets : un analyseur de qualité d’articles, un filtre d’images produit et un analyseur de mouvement vidéo.
• Dans nos tests, les réponses allaient de 87 millisecondes à 1,11 seconde.

Qu’est-ce que les modèles de décision D3 ?

D3 est une famille de modèles d’IA open-weight conçus pour prendre des décisions plutôt que pour générer du texte. Au lieu de demander à un large modèle de langage (LLM) d’expliquer si une transaction est suspecte, D3 peut renvoyer directement la probabilité qu’elle nécessite une revue.

Source : vllm-sr/d3-mini · Hugging Face

Il prend en charge 3 types de décisions :

D3 est décliné en 6 tailles, de 600 millions à 27 milliards de paramètres, adaptées aussi bien aux appareils edge qu’aux GPU haut de gamme. Parcourez la famille dans la collection Decision 3.0 sur Hugging Face.

Les modèles sont évalués sur des benchmarks axés décision comme Typed Decisions, qui mesurent la précision de classification et la qualité des probabilités.

Pour ce tutoriel, nous utiliserons D3 Mini (4B) car il comprend le texte, l’image et la vidéo tout en restant assez compact pour tourner sur un GPU NVIDIA RTX 3090 en local.

Comment exécuter D3 en local avec vLLM

vLLM Semantic Router (vLLM SR) est un projet open source de l’écosystème vLLM qui aide les applications d’IA à prendre des décisions intelligentes. Il gère le routage de modèles, les contrôles de sécurité, le cache sémantique et des modèles de décision spécialisés comme D3. vLLM se charge de l’inférence, tandis que vLLM SR se concentre sur l’évaluation et le routage des requêtes.

Dans ce tutoriel, nous utiliserons la nouvelle prise en charge Structured Decisions de vLLM pour exécuter D3 Mini en local sans installer Semantic Router lui-même. vLLM sert D3 via l’API System One, un endpoint nommé d’après la pensée « System 1 », rapide et intuitive. Elle répond à des questions typées en un seul passage et renvoie des probabilités plutôt que du texte généré.

Nous nous connecterons au modèle avec le SDK Python TypeSafe et verrons comment il gère la classification, l’estimation de probabilité et le scoring.

1. Installer vLLM et exécuter D3 en local

Nous utiliserons Ubuntu Linux, Python 3.12 et un GPU NVIDIA RTX 3090. Les utilisateurs Windows peuvent suivre avec Ubuntu via Windows Subsystem for Linux 2 (WSL2).

Commencez par installer uv. Une fois l’installation terminée, redémarrez votre terminal afin que la commande uv soit disponible.

curl -LsSf https://astral.sh/uv/install.sh | shPropulsé par

Créez ensuite un environnement Python 3.12 et activez-le :

uv venv --python 3.12 --seed
source .venv/bin/activatePropulsé par

Installez maintenant la version nightly de vLLM, qui inclut la nouvelle prise en charge Structured Decisions :

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightlyPropulsé par

Démarrez à présent le modèle D3 Mini avec des paramètres mémoire GPU adaptés aux tests locaux :

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eagerPropulsé par

Au premier lancement, le modèle est téléchargé depuis Hugging Face. Une fois chargé, vLLM expose l’API System One locale à l’adresse http://localhost:8000/v1/systemone.

Laissez ce terminal ouvert. Nous accéderons au modèle depuis un notebook Jupyter.

2. Se connecter à D3 avec le SDK Python TypeSafe

Plutôt que de construire des requêtes HTTP à la main, nous utiliserons le SDK Python TypeSafe pour communiquer avec notre modèle local.

Installez les bibliothèques nécessaires :

%pip install typesafe-sdk olostepPropulsé par

Importez les 3 types de décision et configurez le client pour se connecter à notre serveur vLLM local :

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

client = TypeSafeClient(
    base_url="http://localhost:8000",
    api_key="local",
    model="vllm-sr/d3-mini"
)Propulsé par

Nous utilisons une clé API fictive car le serveur local n’exige pas d’identifiants TypeSafe hébergés.

3. Réaliser votre première décision IA

Commençons par un exemple simple de détection de fraude. Nous allons fournir à D3 une transaction inhabituelle et lui demander si elle doit être signalée pour examen.

%%time
result = client.system_one(
    state="""
    A customer usually spends $20-100 in the US.
    A new $2,500 transaction was made from another country.
    """,
    questions={
        "suspicious": Noul(
            instructions="Should this transaction be flagged for fraud review?"
        )
    }
)

print(result.nouls["suspicious"].noul)Propulsé par

Sortie :

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msPropulsé par

D3 renvoie une probabilité d’environ 99,9 %, indiquant que la transaction doit être examinée. L’inférence a pris environ 87 millisecondes.

Nous pouvons aussi combiner les 3 types de décision dans une seule requête. Cette fois, nous allons évaluer une candidate ou un candidat et demander à D3 d’identifier le meilleur poste, de vérifier ses qualifications et de noter son adéquation.

%%time
result = client.system_one(
    state="""
    Candidate: 4 years of Python experience, 2 years working
    with machine learning, and strong SQL skills.
    No experience with frontend development.
    Available roles: Data Scientist, Backend Developer,
    Frontend Developer.
    """,
    questions={
        "role": Choice(
            instructions="Which role best matches the candidate?",
            criteria={
                "data_scientist": "Python, SQL, and machine learning",
                "backend": "Python, APIs, and backend systems",
                "frontend": "JavaScript, React, and UI development"
            }
        ),
        "qualified": Noul(
            instructions="Does the candidate meet the basic requirements for the best-matching role?"
        ),
        "fit": Score(
            instructions="How well does the candidate match the best-fitting role?",
            criteria=["Low", "Medium", "High"]
        )
    }
)

print("Best Role:", result.choices["role"].choice)
print("Qualified:", result.nouls["qualified"].noul)
print("Candidate Fit:", result.scores["fit"].score)Propulsé par

Sortie :

Best Role: data_scientist
Qualified: 0.9446079177060042
Candidate Fit: 1.6421276950866912
CPU times: user 4.18 ms, sys: 3.11 ms, total: 7.29 ms
Wall time: 165 msPropulsé par

Le modèle identifie correctement Data Scientist comme meilleur choix, attribue une probabilité de qualification de 94,5 % et donne une note d’adéquation de 1,64 sur une échelle de 0 à 2. Les 3 décisions sont revenues en seulement 165 millisecondes.

Maintenant que D3 tourne en local, utilisons-le pour créer 3 applications IA pratiques.

Projet 1 : créer un analyseur de qualité de blog avec D3 Mini

Imaginez gérer une publication technique où des dizaines d’articles doivent être relus avant publication. Plutôt que de tout lire manuellement, nous pouvons construire un analyseur de qualité qui utilise Olostep pour extraire le contenu d’un site et notre modèle D3 Mini local pour le classer et le noter.

Nous le testerons sur un article réel, notre tutoriel KTransformers, que j’ai écrit.

1. Récupérer notre tutoriel KTransformers

Nous allons d’abord utiliser le SDK Python Olostep pour extraire le contenu de l’article en Markdown.

from getpass import getpass
from olostep import Olostep

olostep = Olostep(api_key=getpass("Enter your Olostep API key: "))

url = "https://www.datacamp.com/tutorial/ktransformers-tutorial"
page = olostep.scrapes.create(
    url_to_scrape=url,
    formats=["markdown"]
)

content = page.result.markdown_content
print(content[:1000])Propulsé par

Olostep récupère l’article en Markdown, en préservant ses titres, son texte et ses exemples de code pour l’analyse.

2. Classer et noter l’article avec D3

Ensuite, nous utiliserons Choice pour identifier la catégorie de l’article et Score pour évaluer sa qualité pédagogique sur une échelle à 5 niveaux.

%%time
result = client.system_one(
    state=content[:12000],
    questions={
        "category": Choice(
            instructions="What is the main topic of this article?",
            criteria={
                "ai": "Artificial intelligence and LLMs",
                "data_science": "Data science and analytics",
                "programming": "Software development",
                "other": "Other technical topics"
            }
        ),
        "quality": Score(
            instructions=(
                "Rate the article's educational quality based on "
                "clarity, technical depth, practical examples, "
                "and usefulness to readers."
            ),
            criteria=[
                "Very poor: Confusing and lacks useful information",
                "Poor: Limited depth and unclear explanations",
                "Average: Understandable but missing important details",
                "Good: Clear explanations and useful examples",
                "Excellent: Detailed, practical, and easy to follow"
            ]
        )
    }
)

category = result.choices["category"].choice
quality = result.scores["quality"].score + 1

print("Category:", category)
print(f"Quality: {quality:.1f}/5")Propulsé par

Sortie :

Category: ai
Quality: 4.6/5
CPU times: user 3.29 ms, sys: 2.96 ms, total: 6.25 ms
Wall time: 1.11 sPropulsé par

D3 classe correctement l’article en IA et lui attribue une note de qualité de 4,6/5, en environ 1,11 seconde.

Projet 2 : analyser une image produit avec D3 Mini

Dans ce projet, nous allons créer un flux de contrôle d’images produit pour une boutique en ligne. L’objectif est d’utiliser D3 Mini pour identifier la catégorie du produit, vérifier s’il est bien visible et évaluer la qualité de l’image avant l’ajout au catalogue.

Le code suivant utilise directement l’API System One de vLLM et lit les résultats dans le bon champ answers.

1. Charger une image produit

Nous allons d’abord télécharger une image produit d’exemple, l’afficher dans le notebook et la convertir en base64 pour l’envoyer au modèle.

import base64
import requests
from IPython.display import Image, display

image_url = "https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=600"
image_data = requests.get(image_url, timeout=20).content

display(Image(data=image_data))Propulsé par

image_base64 = base64.b64encode(image_data).decode()
image_input = f"data:image/jpeg;base64,{image_base64}"Propulsé par

Nous obtenons ainsi une image prête à être envoyée que D3 Mini peut analyser directement.

2. Analyser l’image avec D3 Mini

Ensuite, nous demanderons 3 choses à D3 Mini en une seule fois : la catégorie du produit, si le produit est clairement visible et l’adéquation de l’image pour une boutique en ligne.

%%time
result = client.system_one(
    state="Review this product image for an online store.",
    images=[image_input],
    questions={
        "category": Choice(
            instructions="What product category is shown?",
            criteria={
                "footwear": "Shoes, sneakers, or boots",
                "clothing": "Shirts, jackets, or trousers",
                "electronics": "Electronic devices",
                "other": "Other products"
            }
        ),
        "product_visible": Noul(
            instructions="Is a physical product clearly visible?"
        ),
        "quality": Score(
            instructions="Rate the image suitability for an online store.",
            criteria=["Poor", "Average", "Good", "Excellent"]
        )
    }
)

print("Category:", result.choices["category"].choice)
print("Product Visible:", result.nouls["product_visible"].noul)
print("Image Quality:", result.scores["quality"].score)Propulsé par

Sortie :

Product Category: footwear
Product Visibility: 97.11%
Image Quality: 2.30/3
CPU times: user 4.91 ms, sys: 952 μs, total: 5.86 ms
Wall time: 282 msPropulsé par

Le modèle identifie l’article comme des chaussures, confirme que le produit est clairement visible et attribue une bonne note de qualité à l’image, en seulement 282 millisecondes.

Projet 3 : créer un analyseur de mouvement vidéo avec D3 Mini

Pour le dernier projet, nous allons créer un analyseur simple de mouvement vidéo avec D3 Mini. Plutôt que de générer de longues descriptions, nous allons utiliser le modèle pour comprendre ce qui se passe dans un court extrait, identifier la direction du mouvement et détecter les changements visuels. Cette approche est utile pour la surveillance vidéo, la détection d’événements et l’analyse de contenu automatisée.

1. Télécharger une vidéo d’exemple

Nous utiliserons la vidéo d’exemple officielle de D3 Mini depuis Hugging Face. Commencez par installer la bibliothèque requise :

%pip install huggingface_hubPropulsé par

Téléchargez ensuite la vidéo d’exemple pour l’analyser en local.

from huggingface_hub import hf_hub_download
from IPython.display import Video, display

video_path = hf_hub_download(
    repo_id="vllm-sr/d3-mini",
    filename="assets/example-video.mp4"
)Propulsé par

La vidéo montre un carré se déplaçant de la gauche vers la droite tout en changeant de couleur, du bleu au vert.

2. Analyser la vidéo

D’abord, nous convertirons la vidéo en base64 afin de l’envoyer à notre serveur vLLM local.

import base64
import requests

with open(video_path, "rb") as f:
    video_base64 = base64.b64encode(f.read()).decode()

video_input = f"data:video/mp4;base64,{video_base64}"Propulsé par

Nous utiliserons ensuite l’API System One pour poser 2 questions à D3 Mini : la direction du mouvement du carré et s’il change de couleur.

%%time
response = requests.post(
    "http://localhost:8000/v1/systemone",
    json={
        "model": "vllm-sr/d3-mini",
        "state": "Analyze the movement of the object in this video.",
        "videos": [video_input],
        "questions": {
            "direction": {
                "type": "choice",
                "instructions": "Which direction does the square move?",
                "criteria": {
                    "left": "From right to left",
                    "right": "From left to right",
                    "still": "The square does not move"
                }
            },
            "color_change": {
                "type": "noul",
                "instructions": "Does the square change color during the video?"
            }
        }
    },
    timeout=120
)
response.raise_for_status()

answers = response.json()["answers"]

print("Movement:", answers["direction"]["choice"])
print(f"Color Change: {answers['color_change']['noul']:.1%}")Propulsé par

Sortie :

Movement: right
Color Change: 93.7%
CPU times: user 3.01 ms, sys: 5.04 ms, total: 8.05 ms
Wall time: 723 msPropulsé par

D3 Mini identifie correctement le mouvement vers la droite et attribue une probabilité de 93,7 % au changement de couleur, le tout en 723 millisecondes.

Conclusion

D3 Mini gère la classification, les vérifications oui/non et le scoring sur le texte, l’image et la vidéo, le tout sur un seul GPU NVIDIA RTX 3090. La mise en place en local s’est révélée étonnamment simple. Le seul problème rencontré fut une erreur CUDA « out-of-memory », résolue en réduisant la consommation mémoire du GPU.

À part cela, tout a fonctionné sans accroc. Si vous connaissez déjà vLLM, vous pourrez sans doute optimiser encore davantage la configuration.

Ce qui m’a le plus impressionné, c’est la vitesse. Les temps muraux allaient de 87 millisecondes pour une décision textuelle courte à 1,11 seconde pour un article complet, et l’exemple vidéo s’est terminé en 723 millisecondes. Tout a tourné sur mon propre GPU.

Nous atteignons, selon moi, un point où exécuter des modèles de décision sur un serveur local pour toute une équipe devient réaliste. Chaque requête n’a pas besoin d’un grand modèle de raisonnement.

Pour de nombreuses tâches du quotidien — classification, routage, scoring et filtrage de contenu — un plus petit modèle de décision suffit largement. Vous pouvez ensuite réserver les modèles de raisonnement coûteux aux cas qui exigent réellement une analyse approfondie ou des explications détaillées.

Bien sûr, vous voudrez toujours évaluer la précision et les performances sur vos propres charges avant une mise en production. Après avoir testé D3 sur le texte, l’image et la vidéo, ma règle empirique est simple : si la tâche consiste à classer, répondre par oui/non ou attribuer une note, essayez d’abord un modèle D3, et ne passez à un modèle de raisonnement que lorsque vous avez besoin d’une explication.

Si vous souhaitez en savoir plus sur le travail avec des modèles ouverts, je vous recommande notre cours Working with Hugging Face.