vLLM D3-tutorial: AI-beslismodellen lokaal draaien met Python

D3 is een familie van open-weight beslismodellen die een waarschijnlijkheid voor elk antwoord teruggeven in plaats van tekst te genereren. Je kunt een supportticket classificeren, een artikel beoordelen of een videofragment controleren met één verzoek aan een model dat op je eigen machine draait, in slechts 87 milliseconden in onze tests.

De familie omvat 6 modellen, van 600 miljoen tot 27 miljard parameters. Je kunt met de kleinere modellen op bescheidener hardware experimenteren en de grotere inzetten voor veeleisendere taken. D3 Edge is zo lichtgewicht dat het zelfs op compatibele smartphones kan draaien.

vLLM ondersteunt D3 via het Structured Decisions-framework, zodat je een model lokaal kunt aanbieden en aanroepen via een eenvoudige application programming interface (API). Het bredere vLLM Semantic Router-project voegt routering en besluitvormingsfuncties toe voor AI-toepassingen.

In deze tutorial behandel ik het lokaal opzetten van D3, de 3 besluittypen en je eerste voorspellingen. Daarna bouwen we 3 praktische projecten:

1. AI Blog Kwaliteitsanalyzer: Gebruik de TypeSafe Python software development kit (SDK) en Olostep om echte artikelen te classificeren en te evalueren.
2. Begrip van Afbeeldingen: Analyseer productafbeeldingen, identificeer categorieën en beoordeel de beeldkwaliteit.
3. Begrip van Video: Analyseer korte video’s om beweging en visuele veranderingen te detecteren.

Aan het eind weet je hoe je D3 lokaal draait en hoe je het gebruikt om toepassingen te bouwen die beslissingen nemen over tekst, afbeeldingen en video. Bekijk ook onze gidsen voor het lokaal draaien van large language models en het versnellen van lokale inferentie op een RTX 3090 GPU.

In het kort

• D3 is een familie van open-weight beslismodellen die waarschijnlijkheden teruggeven voor keuze-, ja/nee- (Noul) en scorevragen in plaats van tekst te genereren.
• D3 Mini (4B) ondersteunt tekst, afbeeldingen en video, en draait op een enkele NVIDIA RTX 3090 graphics processing unit (GPU) met vLLM.
• Je biedt het model aan met vllm serve en roept het aan via de TypeSafe Python SDK of het /v1/systemone-endpoint.
• We bouwen 3 projecten: een kwaliteitsanalyzer voor artikelen, een productafbeelding-checker en een videobewegingsanalyzer.
• Reactietijden in onze tests lagen tussen 87 milliseconden en 1,11 seconden.

Wat zijn D3-beslismodellen?

D3 is een familie van open-weight AI-modellen die zijn gebouwd om beslissingen te nemen in plaats van tekst te genereren. In plaats van een large language model (LLM) te vragen uit te leggen of een transactie verdacht is, kan D3 direct een waarschijnlijkheid teruggeven dat beoordeling nodig is.

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

Het ondersteunt 3 besluittypen:

D3 is er in 6 groottes, van 600 miljoen tot 27 miljard parameters, geschikt voor alles van edge-apparaten tot high-end GPU’s. Je kunt de familie bekijken in de Decision 3.0-collectie op Hugging Face.

De modellen worden geëvalueerd op besluitgerichte benchmarks zoals Typed Decisions, die classificatienauwkeurigheid en de kwaliteit van waarschijnlijkheden meten.

Voor deze tutorial gebruiken we D3 Mini (4B) omdat het tekst-, beeld- en videobegrip ondersteunt en toch klein genoeg is om op een lokale NVIDIA RTX 3090 GPU te draaien.

Hoe D3 lokaal draaien met vLLM

vLLM Semantic Router (vLLM SR) is een open source-project in het vLLM-ecosysteem dat AI-toepassingen helpt slimme beslissingen te nemen. Het ondersteunt modelroutering, veiligheidscontroles, semantische caching en gespecialiseerde beslismodellen zoals D3. Terwijl vLLM modelinference afhandelt, richt vLLM SR zich op hoe verzoeken worden geëvalueerd en gerouteerd.

In deze tutorial gebruiken we vLLM’s nieuwe Structured Decisions-ondersteuning om D3 Mini lokaal te draaien zonder de Semantic Router zelf te installeren. vLLM biedt D3 aan via de System One API, een endpoint vernoemd naar het snelle, intuïtieve "Systeem 1"-denken. Het beantwoordt getypeerde vragen in één keer en geeft waarschijnlijkheden terug in plaats van gegenereerde tekst.

We verbinden met het model via de TypeSafe Python SDK en verkennen hoe het classificatie, waarschijnlijkheidsinschatting en scoring afhandelt.

1. Installeer vLLM en draai D3 lokaal

We gebruiken Ubuntu Linux, Python 3.12 en een NVIDIA RTX 3090 GPU. Windows-gebruikers kunnen meekijken via Ubuntu met Windows Subsystem for Linux 2 (WSL2).

Installeer eerst uv. Zodra de installatie is voltooid, start je terminal opnieuw zodat het uv-commando beschikbaar is.

curl -LsSf https://astral.sh/uv/install.sh | shMogelijk gemaakt door

Maak nu een Python 3.12-omgeving en activeer die:

uv venv --python 3.12 --seed
source .venv/bin/activateMogelijk gemaakt door

Installeer vervolgens de vLLM nightly build, die de nieuwe Structured Decisions-ondersteuning bevat:

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightlyMogelijk gemaakt door

Start nu het D3 Mini-model met GPU-geheugeninstellingen die geschikt zijn voor lokaal testen:

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eagerMogelijk gemaakt door

Bij de eerste start wordt het model gedownload van Hugging Face. Zodra het geladen is, stelt vLLM de lokale System One API bloot op http://localhost:8000/v1/systemone.

Laat deze terminal actief. We benaderen het model vanuit een Jupyter-notebook.

2. Verbind met D3 via de TypeSafe Python SDK

In plaats van handmatig HTTP-verzoeken te bouwen, gebruiken we de TypeSafe Python SDK om met ons lokaal draaiende model te communiceren.

Installeer de benodigde bibliotheken:

%pip install typesafe-sdk olostepMogelijk gemaakt door

Importeer de 3 besluittypen en configureer de client om te verbinden met onze lokale vLLM-server:

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

client = TypeSafeClient(
    base_url="http://localhost:8000",
    api_key="local",
    model="vllm-sr/d3-mini"
)Mogelijk gemaakt door

We gebruiken een placeholder-API-sleutel omdat de lokale server geen gehoste TypeSafe-credential vereist.

3. Maak je eerste AI-besluit

We beginnen met een simpel voorbeeld voor fraudedetectie. We geven D3 een ongewone transactie en vragen of deze moet worden gemarkeerd voor beoordeling.

%%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)Mogelijk gemaakt door

Uitvoer:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msMogelijk gemaakt door

D3 geeft een waarschijnlijkheid van ongeveer 99,9% terug, wat aangeeft dat de transactie moet worden gemarkeerd voor beoordeling. De inferentie duurde ongeveer 87 milliseconden.

We kunnen ook alle 3 besluittypen combineren in één verzoek. Dit keer evalueren we een sollicitant en vragen we D3 om de beste rol te bepalen, de kwalificaties te controleren en de geschiktheid te scoren.

%%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)Mogelijk gemaakt door

Uitvoer:

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 msMogelijk gemaakt door

Het model identificeert Data Scientist correct als beste match, kent een waarschijnlijkheid van 94,5% toe voor kwalificatie en geeft een fit-score van 1,64 op een schaal van 0 tot 2. Alle 3 beslissingen werden in slechts 165 milliseconden teruggegeven.

Nu D3 lokaal draait, gebruiken we het om 3 praktische AI-toepassingen te bouwen.

Project 1: Bouw een AI Blog Kwaliteitsanalyzer met D3 Mini

Stel je beheert een technische publicatie waar tientallen artikelen moeten worden gereviewd voordat ze gepubliceerd worden. In plaats van elk artikel handmatig te lezen, kunnen we een AI-kwaliteitsanalyzer bouwen die Olostep gebruikt om website-inhoud te extraheren en ons lokaal draaiende D3 Mini-model om die te classificeren en te scoren.

We testen dit op een echt artikel, onze KTransformers-tutorial, die ik schreef.

1. Scrape onze KTransformers-tutorial

Eerst gebruiken we de Olostep Python SDK om de artikelinhoud als Markdown te extraheren.

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])Mogelijk gemaakt door

Olostep haalt het artikel op als Markdown en behoudt de koppen, tekst en codevoorbeelden voor analyse.

2. Categoriseer en beoordeel het artikel met D3

Vervolgens gebruiken we Choice om de categorie van het artikel te bepalen en Score om de educatieve kwaliteit op een 5-puntsschaal te evalueren.

%%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")Mogelijk gemaakt door

Uitvoer:

Category: ai
Quality: 4.6/5
CPU times: user 3.29 ms, sys: 2.96 ms, total: 6.25 ms
Wall time: 1.11 sMogelijk gemaakt door

D3 categoriseert het artikel correct als AI en geeft het een kwaliteitscore van 4,6/5, en rondt de analyse af in ongeveer 1,11 seconden.

Project 2: Analyseer een productafbeelding met D3 Mini

In dit project bouwen we een eenvoudige screeningworkflow voor productafbeeldingen voor een e-commercestore. Het doel is om D3 Mini te gebruiken om de productcategorie te identificeren, te controleren of het product duidelijk zichtbaar is en de beeldkwaliteit te beoordelen voordat het aan een catalogus wordt toegevoegd.

De volgende code gebruikt de vLLM System One API direct en leest resultaten uit het juiste answers-veld.

1. Laad een productafbeelding

Eerst downloaden we een voorbeeldproductafbeelding, tonen die in de notebook en converteren we hem naar base64 zodat hij naar het model kan worden gestuurd.

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))Mogelijk gemaakt door

image_base64 = base64.b64encode(image_data).decode()
image_input = f"data:image/jpeg;base64,{image_base64}"Mogelijk gemaakt door

Dit levert een kant-en-klare afbeeldingsinput op die D3 Mini direct kan analyseren.

2. Analyseer de afbeelding met D3 Mini

Vervolgens stellen we D3 Mini 3 vragen tegelijk: tot welke categorie het product behoort, of het product duidelijk zichtbaar is en hoe geschikt de afbeelding is voor een online winkel.

%%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)Mogelijk gemaakt door

Uitvoer:

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 msMogelijk gemaakt door

Het model identificeert het item als footwear, bevestigt dat het product duidelijk zichtbaar is en geeft de afbeelding een solide kwaliteitsscore in slechts 282 milliseconden.

Project 3: Bouw een videobewegingsanalyzer met D3 Mini

In ons laatste project bouwen we een eenvoudige videobewegingsanalyzer met D3 Mini. In plaats van lange videobeschrijvingen te genereren, gebruiken we het model om te begrijpen wat er gebeurt in een kort fragment, de bewegingsrichting te identificeren en visuele veranderingen te detecteren. Deze aanpak is handig voor videobewaking, gebeurtenisdetectie en geautomatiseerde contentanalyse.

1. Download een voorbeeldvideo

We gebruiken de officiële D3 Mini-voorbeeldvideo van Hugging Face. Installeer eerst de vereiste bibliotheek:

%pip install huggingface_hubMogelijk gemaakt door

Download vervolgens de voorbeeldvideo zodat we die lokaal kunnen analyseren.

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"
)Mogelijk gemaakt door

De video toont een blokje dat van links naar rechts beweegt terwijl de kleur van blauw naar groen verandert.

2. Analyseer de video

Eerst converteren we de video naar base64-formaat zodat die naar onze lokale vLLM-server kan worden gestuurd.

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}"Mogelijk gemaakt door

Nu gebruiken we de System One API om D3 Mini 2 vragen te stellen: in welke richting het vierkant beweegt en of het van kleur verandert.

%%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%}")Mogelijk gemaakt door

Uitvoer:

Movement: right
Color Change: 93.7%
CPU times: user 3.01 ms, sys: 5.04 ms, total: 8.05 ms
Wall time: 723 msMogelijk gemaakt door

D3 Mini identificeert de beweging correct als right en kent een waarschijnlijkheid van 93,7% toe aan de kleurverandering, en rondt de analyse af in slechts 723 milliseconden.

Tot slot

D3 Mini kan classificatie, ja/nee-checks en scoring aan voor tekst, afbeeldingen en video op een enkele NVIDIA RTX 3090 GPU. D3 lokaal opzetten was verrassend eenvoudig. Het enige probleem dat ik tegenkwam was een CUDA out-of-memory-fout, die ik oploste door het GPU-geheugenverbruik te verminderen.

Verder werkte alles soepel. Als je al bekend bent met vLLM, kun je de setup waarschijnlijk nog verder optimaliseren.

Waar ik het meest van onder de indruk was, is de snelheid. Wall times varieerden van 87 milliseconden voor een korte tekstbeslissing tot 1,11 seconden voor een volledig artikel, en het video-voorbeeld was klaar in 723 milliseconden. En dat alles draaide op mijn eigen GPU.

Ik denk dat we een punt bereiken waarop het draaien van beslismodellen op een lokale server voor een heel team praktisch wordt. Niet elk verzoek heeft een groot redeneermodel nodig.

Voor veel alledaagse taken, zoals classificatie, routering, scoring en contentfiltering, kan een kleiner beslismodel het werk doen. Duurdere redeneermodellen kun je dan reserveren voor taken die echt diepere analyse of gedetailleerde uitleg vereisen.

Natuurlijk wil je nog steeds nauwkeurigheid en prestaties evalueren op je eigen workloads voordat je deze modellen in productie gebruikt. Na het testen van D3 op tekst, afbeeldingen en video is mijn vuistregel simpel: als de taak een classificatie, een ja/nee-check of een beoordeling is, probeer eerst een D3-model en stap pas over op een redeneermodel als je een uitleg nodig hebt.

Als je graag meer wilt leren over werken met open modellen, raad ik onze cursus Working with Hugging Face aan.