vLLM D3 Tutorial: KI-Entscheidungsmodelle lokal mit Python ausführen

D3 ist eine Familie offener Entscheidungsmodelle, die statt Text eine Wahrscheinlichkeit für jede Antwort zurückgeben. Du kannst ein Support-Ticket klassifizieren, einen Artikel bewerten oder einen Videoclip prüfen – mit nur einer Anfrage an ein Modell, das auf deinem eigenen Rechner läuft. In unseren Tests dauerte das nur 87 Millisekunden.

Die Familie umfasst 6 Modelle mit 600 Millionen bis 27 Milliarden Parametern. Mit kleineren Modellen kannst du auf moderater Hardware experimentieren, die größeren sind für anspruchsvollere Aufgaben gedacht. D3 Edge ist so leichtgewichtig, dass es sogar auf kompatiblen Smartphones läuft.

vLLM unterstützt D3 über das Structured Decisions Framework. So kannst du ein Modell lokal bereitstellen und über eine einfache Programmierschnittstelle (API) ansprechen. Das größere Projekt vLLM Semantic Router ergänzt Routing- und Entscheidungsfunktionen für KI-Anwendungen.

In diesem Tutorial zeige ich die lokale Einrichtung von D3, die 3 Entscheidungstypen und deine ersten Vorhersagen. Anschließend bauen wir 3 praxisnahe Projekte:

1. AI Blog Quality Analyzer: Nutze das TypeSafe Python Software Development Kit (SDK) und Olostep, um echte Artikel zu klassifizieren und zu bewerten.
2. Image Understanding: Analysiere Produktbilder, erkenne Kategorien und bewerte die Bildqualität.
3. Video Understanding: Analysiere Kurzvideos, um Bewegung und visuelle Veränderungen zu erkennen.

Am Ende weißt du, wie du D3 lokal ausführst und damit Anwendungen baust, die auf Basis von Text, Bildern und Video Entscheidungen treffen. Sieh dir auch unsere Anleitungen zum lokalen Ausführen großer Sprachmodelle und zum Beschleunigen lokaler Inferenz auf einer RTX 3090 GPU an.

Auf einen Blick

• D3 ist eine Familie offener Entscheidungsmodelle, die statt Text Wahrscheinlichkeiten für Choice-, Yes/No- (Noul) und Score-Fragen zurückgeben.
• D3 Mini (4B) verarbeitet Text, Bilder und Videos und läuft mit vLLM auf einer einzelnen NVIDIA RTX 3090 Grafikkarte (GPU).
• Du stellst das Modell mit vllm serve bereit und rufst es über das TypeSafe Python SDK oder den /v1/systemone-Endpoint auf.
• Wir bauen 3 Projekte: einen Artikel-Qualitätsanalysator, einen Produktbild-Checker und einen Video-Bewegungsanalysator.
• In unseren Tests lagen die Antwortzeiten zwischen 87 Millisekunden und 1,11 Sekunden.

Was sind D3-Entscheidungsmodelle?

D3 ist eine Familie offener KI-Modelle, die für Entscheidungen statt Texte generieren entwickelt wurden. Anstatt ein Large Language Model (LLM) zu bitten zu erklären, ob eine Transaktion verdächtig ist, kann D3 direkt die Wahrscheinlichkeit zurückgeben, dass eine Prüfung nötig ist.

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

Es unterstützt 3 Entscheidungstypen:

D3 gibt es in 6 Größen, von 600 Millionen bis 27 Milliarden Parametern – passend von Edge-Geräten bis zu High-End-GPUs. Die Familie findest du in der Decision 3.0 Kollektion auf Hugging Face.

Die Modelle werden auf entscheidungsorientierten Benchmarks wie Typed Decisions evaluiert, die Klassifikationsgenauigkeit und die Qualität der Wahrscheinlichkeiten messen.

Für dieses Tutorial nutzen wir D3 Mini (4B), weil es Text-, Bild- und Videounterstützung bietet und gleichzeitig klein genug ist, um auf einer lokalen NVIDIA RTX 3090 GPU zu laufen.

So führst du D3 lokal mit vLLM aus

vLLM Semantic Router (vLLM SR) ist ein Open-Source-Projekt im vLLM-Ökosystem, das KI-Anwendungen bei intelligenten Entscheidungen unterstützt. Es bietet Modell-Routing, Sicherheitsprüfungen, semantisches Caching und spezialisierte Entscheidungsmodelle wie D3. Während vLLM die Modellausführung übernimmt, konzentriert sich vLLM SR darauf, wie Anfragen bewertet und geroutet werden.

In diesem Tutorial nutzen wir die neue Structured Decisions Unterstützung von vLLM, um D3 Mini lokal auszuführen – ohne den Semantic Router selbst zu installieren. vLLM stellt D3 über die System One API bereit, einen Endpoint, benannt nach schnellem, intuitivem „System 1“-Denken. Er beantwortet typisierte Fragen in einem Durchgang und liefert Wahrscheinlichkeiten statt generierten Texts.

Wir verbinden uns über das TypeSafe Python SDK mit dem Modell und sehen uns an, wie es Klassifikation, Wahrscheinlichkeiten und Scoring handhabt.

1. vLLM installieren und D3 lokal starten

Wir verwenden Ubuntu Linux, Python 3.12 und eine NVIDIA RTX 3090 GPU. Windows-Nutzer können mit Ubuntu über Windows Subsystem for Linux 2 (WSL2) mitmachen.

Installiere zuerst uv. Starte anschließend dein Terminal neu, damit der Befehl uv verfügbar ist.

curl -LsSf https://astral.sh/uv/install.sh | shBereitgestellt von

Erstelle jetzt eine Python-3.12-Umgebung und aktiviere sie:

uv venv --python 3.12 --seed
source .venv/bin/activateBereitgestellt von

Als Nächstes installierst du das vLLM Nightly Build mit der neuen Structured Decisions Unterstützung:

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

Starte nun das D3 Mini Modell mit GPU-Speichereinstellungen für lokale Tests:

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

Beim ersten Start lädt vLLM das Modell von Hugging Face. Nach dem Laden stellt vLLM die lokale System One API unter http://localhost:8000/v1/systemone bereit.

Lass dieses Terminal geöffnet. Wir greifen gleich aus einem Jupyter-Notebook darauf zu.

2. Mit dem TypeSafe Python SDK verbinden

Statt HTTP-Anfragen manuell zu bauen, nutzen wir das TypeSafe Python SDK, um mit unserem lokal laufenden Modell zu kommunizieren.

Installiere die benötigten Bibliotheken:

%pip install typesafe-sdk olostepBereitgestellt von

Importiere die 3 Entscheidungstypen und konfiguriere den Client für unseren lokalen 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"
)Bereitgestellt von

Wir verwenden einen Platzhalter-API-Schlüssel, da der lokale Server keine gehosteten TypeSafe-Anmeldedaten benötigt.

3. Triff deine erste KI-Entscheidung

Starten wir mit einem einfachen Beispiel zur Betrugserkennung. Wir geben D3 eine ungewöhnliche Transaktion und fragen, ob sie zur Prüfung markiert werden sollte.

%%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)Bereitgestellt von

Ausgabe:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msBereitgestellt von

D3 liefert eine Wahrscheinlichkeit von etwa 99,9% – die Transaktion sollte geprüft werden. Die Inferenz dauerte rund 87 Millisekunden.

Wir können auch alle 3 Entscheidungstypen in einer Anfrage kombinieren. Dieses Mal bewerten wir eine Bewerberin bzw. einen Bewerber und bitten D3, die beste Rolle zu bestimmen, die Qualifikation zu prüfen und die Eignung zu bewerten.

%%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)Bereitgestellt von

Ausgabe:

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 msBereitgestellt von

Das Modell erkennt Data Scientist als beste Rolle, gibt eine Qualifikationswahrscheinlichkeit von 94,5% und eine Eignungsbewertung von 1,64 auf einer 0–2 Skala zurück. Alle 3 Entscheidungen kamen in nur 165 Millisekunden.

Jetzt, da D3 lokal läuft, bauen wir 3 praktische KI-Anwendungen.

Projekt 1: Baue einen AI Blog Quality Analyzer mit D3 Mini

Stell dir vor, du betreibst eine technische Publikation, in der Dutzende Artikel vor der Veröffentlichung geprüft werden müssen. Statt jeden Artikel komplett zu lesen, bauen wir einen KI-Qualitätsanalysator, der Olostep zum Extrahieren von Website-Inhalten und unser lokal laufendes D3 Mini Modell zum Klassifizieren und Bewerten nutzt.

Wir testen das an einem echten Artikel, unserem KTransformers Tutorial, das ich geschrieben habe.

1. Unser KTransformers Tutorial scrapen

Als Erstes nutzen wir das Olostep Python SDK, um den Artikelinhalt als Markdown zu extrahieren.

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])Bereitgestellt von

Olostep ruft den Artikel als Markdown ab und erhält Überschriften, Text und Codebeispiele für die Analyse.

2. Artikel kategorisieren und bewerten mit D3

Als Nächstes nutzen wir Choice, um die Kategorie des Artikels zu bestimmen, und Score, um seine didaktische Qualität auf einer 5-Punkte-Skala zu bewerten.

%%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")Bereitgestellt von

Ausgabe:

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

D3 ordnet den Artikel korrekt der Kategorie KI zu und vergibt eine Qualitätsbewertung von 4,6/5 – die Analyse war in etwa 1,11 Sekunden fertig.

Projekt 2: Analysiere ein Produktbild mit D3 Mini

In diesem Projekt bauen wir einen einfachen Screening-Workflow für Produktbilder in einem Onlineshop. Ziel ist es, mit D3 Mini die Produktkategorie zu erkennen, zu prüfen, ob das Produkt klar sichtbar ist, und die Bildqualität zu bewerten, bevor es in den Katalog kommt.

Der folgende Code nutzt die vLLM System One API direkt und liest die Ergebnisse aus dem Feld answers aus.

1. Ein Produktbild laden

Zuerst laden wir ein Beispielbild, zeigen es im Notebook an und konvertieren es in Base64, um es an das Modell zu senden.

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))Bereitgestellt von

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

Damit haben wir ein versandfertiges Bild-Input, das D3 Mini direkt analysieren kann.

2. Das Bild mit D3 Mini analysieren

Als Nächstes fragen wir D3 Mini gleichzeitig nach der Produktkategorie, ob das Produkt klar sichtbar ist, und wie gut sich das Bild für einen Onlineshop eignet.

%%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)Bereitgestellt von

Ausgabe:

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 msBereitgestellt von

Das Modell erkennt das Produkt als footwear, bestätigt die klare Sichtbarkeit und vergibt in nur 282 Millisekunden eine solide Qualitätsbewertung.

Projekt 3: Baue einen Video-Bewegungsanalysator mit D3 Mini

Im letzten Projekt bauen wir einen einfachen Video-Bewegungsanalysator mit D3 Mini. Statt lange Videobeschreibungen zu generieren, nutzen wir das Modell, um zu verstehen, was in einem kurzen Clip passiert, die Bewegungsrichtung zu erkennen und visuelle Veränderungen zu detektieren. Das ist nützlich für Videomonitoring, Ereigniserkennung und automatisierte Inhaltsanalyse.

1. Ein Beispielvideo herunterladen

Wir verwenden das offizielle D3 Mini Beispielvideo von Hugging Face. Installiere zuerst die benötigte Bibliothek:

%pip install huggingface_hubBereitgestellt von

Lade anschließend das Beispielvideo herunter, um es lokal zu analysieren.

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"
)Bereitgestellt von

Das Video zeigt ein Quadrat, das sich von links nach rechts bewegt und seine Farbe von Blau zu Grün wechselt.

2. Das Video analysieren

Zuerst konvertieren wir das Video in Base64, um es an unseren lokalen vLLM-Server zu senden.

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}"Bereitgestellt von

Nun nutzen wir die System One API und stellen D3 Mini 2 Fragen: In welche Richtung bewegt sich das Quadrat und ändert es seine Farbe?

%%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%}")Bereitgestellt von

Ausgabe:

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

D3 Mini erkennt die Bewegung korrekt als right und gibt eine 93,7% Wahrscheinlichkeit für die Farbänderung an – die Analyse war in nur 723 Millisekunden abgeschlossen.

Fazit

D3 Mini meistert Klassifikation, Ja/Nein-Prüfungen und Scoring über Text, Bilder und Video – auf einer einzelnen NVIDIA RTX 3090 GPU. Die lokale Einrichtung war überraschend einfach. Einzig ein CUDA Out-of-Memory-Fehler ist aufgetreten, den ich durch geringere GPU-Speichernutzung behoben habe.

Abgesehen davon lief alles reibungslos. Wenn du vLLM bereits kennst, kannst du das Setup wahrscheinlich noch weiter optimieren.

Am meisten beeindruckt hat mich die Geschwindigkeit. Die Laufzeiten reichten von 87 Millisekunden für eine kurze Textentscheidung bis 1,11 Sekunden für einen ganzen Artikel, und das Video-Beispiel war in 723 Millisekunden fertig. Alles lief auf meiner eigenen GPU.

Ich denke, wir nähern uns dem Punkt, an dem es praktikabel wird, Entscheidungsmodelle auf einem lokalen Server für ein ganzes Team zu betreiben. Nicht jede Anfrage braucht ein großes Reasoning-Modell.

Für viele Alltagsaufgaben wie Klassifikation, Routing, Scoring und Inhaltsfilterung reicht ein kleineres Entscheidungsmodell aus. Teure Reasoning-Modelle kannst du dann für Aufgaben reservieren, die wirklich tiefere Analysen oder ausführliche Erklärungen erfordern.

Natürlich solltest du vor dem Produktionseinsatz Genauigkeit und Performance auf deinen eigenen Workloads evaluieren. Nach Tests von D3 über Text, Bilder und Video ist meine Faustregel simpel: Wenn die Aufgabe eine Klassifikation, ein Ja/Nein-Check oder eine Bewertung ist, probiere zuerst ein D3-Modell – und wechsle nur zu einem Reasoning-Modell, wenn du eine Erklärung brauchst.

Wenn du mehr über die Arbeit mit offenen Modellen lernen willst, empfehle ich unseren Kurs Working with Hugging Face.