Tutorial vLLM D3: esegui modelli decisionali AI in locale con Python

D3 è una famiglia di modelli decisionali open-weight che restituiscono una probabilità per ogni risposta invece di generare testo. Puoi classificare un ticket di supporto, valutare un articolo o controllare una clip video con una singola richiesta a un modello in esecuzione sulla tua macchina, in appena 87 millisecondi nei nostri test.

La famiglia comprende 6 modelli, da 600 milioni a 27 miliardi di parametri. Puoi sperimentare con i modelli più piccoli su hardware modesto e usare quelli più grandi per compiti più impegnativi. D3 Edge è così leggero da poter girare perfino su smartphone compatibili.

vLLM supporta D3 tramite il framework Structured Decisions, così puoi servire un modello in locale e chiamarlo tramite una semplice API (application programming interface). Il più ampio progetto vLLM Semantic Router aggiunge funzionalità di routing e decision-making per applicazioni di AI.

In questo tutorial vedremo come configurare D3 in locale, i 3 tipi di decisione e le prime predizioni. Poi costruiremo 3 progetti pratici:

1. AI Blog Quality Analyzer: Usa il software development kit (SDK) TypeSafe per Python e Olostep per classificare e valutare articoli reali.
2. Comprensione delle immagini: Analizza immagini di prodotto, identifica le categorie e valuta la qualità dell’immagine.
3. Comprensione dei video: Analizza brevi video per rilevare movimento e cambiamenti visivi.

Alla fine saprai come eseguire D3 in locale e usarlo per creare applicazioni che prendono decisioni su testo, immagini e video. Puoi anche consultare le nostre guide su come eseguire i large language model in locale e su come accelerare l’inferenza locale su una GPU RTX 3090.

In breve

• D3 è una famiglia di modelli decisionali open-weight che restituiscono probabilità per domande di tipo scelta, sì/no (Noul) e punteggio invece di generare testo.
• D3 Mini (4B) gestisce testo, immagini e video e gira su una singola GPU NVIDIA RTX 3090 con vLLM.
• Servi il modello con vllm serve e lo chiami tramite l’SDK Python di TypeSafe o l’endpoint /v1/systemone.
• Costruiamo 3 progetti: un analizzatore della qualità degli articoli, uno screening per immagini di prodotto e un analizzatore del movimento nei video.
• Nei nostri test le risposte hanno impiegato tra 87 millisecondi e 1,11 secondi.

Cosa sono i modelli decisionali D3?

D3 è una famiglia di modelli AI open-weight pensati per prendere decisioni piuttosto che generare testo. Invece di chiedere a un large language model (LLM) di spiegare se una transazione è sospetta, D3 può restituire direttamente la probabilità che necessiti di revisione.

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

Supporta 3 tipi di decisione:

D3 è disponibile in 6 dimensioni, da 600 milioni a 27 miliardi di parametri, adatte dai dispositivi edge alle GPU di fascia alta. Puoi esplorare la famiglia nella collezione Decision 3.0 su Hugging Face.

I modelli sono valutati su benchmark focalizzati sulle decisioni come Typed Decisions, che misurano l’accuratezza della classificazione e la qualità delle probabilità.

Per questo tutorial useremo D3 Mini (4B) perché supporta la comprensione di testo, immagini e video rimanendo abbastanza piccolo da poter girare in locale su una GPU NVIDIA RTX 3090.

Come eseguire D3 in locale con vLLM

vLLM Semantic Router (vLLM SR) è un progetto open source dell’ecosistema vLLM che aiuta le applicazioni AI a prendere decisioni intelligenti. Supporta il model routing, i controlli di sicurezza, la cache semantica e modelli decisionali specializzati come D3. Mentre vLLM gestisce l’inferenza del modello, vLLM SR si concentra su come le richieste vengono valutate e instradate.

In questo tutorial useremo il nuovo supporto Structured Decisions di vLLM per eseguire D3 Mini in locale senza installare il Semantic Router. vLLM serve D3 tramite la System One API, un endpoint chiamato in onore del pensiero rapido e intuitivo “System 1”. Risponde a domande tipizzate in un singolo passaggio e restituisce probabilità invece di testo generato.

Ci connetteremo al modello usando l’SDK TypeSafe per Python ed esploreremo come gestisce classificazione, stima di probabilità e scoring.

1. Installa vLLM ed esegui D3 in locale

Useremo Ubuntu Linux, Python 3.12 e una GPU NVIDIA RTX 3090. Chi usa Windows può seguire con Ubuntu tramite Windows Subsystem for Linux 2 (WSL2).

Per prima cosa, installa uv. Al termine dell’installazione, riavvia il terminale in modo che il comando uv sia disponibile.

curl -LsSf https://astral.sh/uv/install.sh | shOfferto da

Ora crea un ambiente Python 3.12 e attivalo:

uv venv --python 3.12 --seed
source .venv/bin/activateOfferto da

Quindi installa la nightly build di vLLM, che include il nuovo supporto Structured Decisions:

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

Ora avvia il modello D3 Mini con impostazioni di memoria GPU adatte ai test locali:

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

Al primo avvio il modello viene scaricato da Hugging Face. Una volta caricato, vLLM espone la System One API locale su http://localhost:8000/v1/systemone.

Lascia questo terminale aperto. Accederemo al modello da un notebook Jupyter.

2. Connettiti a D3 usando l’SDK TypeSafe per Python

Invece di costruire manualmente richieste HTTP, useremo l’SDK TypeSafe per Python per comunicare con il nostro modello in esecuzione locale.

Installa le librerie necessarie:

%pip install typesafe-sdk olostepOfferto da

Importa i 3 tipi di decisione e configura il client per connettersi al nostro server vLLM locale:

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

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

Usiamo una chiave API fittizia perché il server locale non richiede una credenziale TypeSafe ospitata.

3. Fai la tua prima decisione AI

Partiamo con un semplice esempio di rilevamento frodi. Forniremo a D3 una transazione insolita e chiederemo se dovrebbe essere contrassegnata per revisione.

%%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)Offerto da

Output:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msOfferto da

D3 restituisce una probabilità di circa 99,9%, indicando che la transazione dovrebbe essere contrassegnata per revisione. L’inferenza ha impiegato circa 87 millisecondi.

Possiamo anche combinare tutti e 3 i tipi di decisione in una singola richiesta. Questa volta valuteremo un candidato e chiederemo a D3 di identificare il ruolo migliore, verificare le qualifiche e dare un punteggio di idoneità.

%%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)Offerto da

Output:

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 msOfferto da

Il modello identifica correttamente Data Scientist come miglior corrispondenza, assegna una probabilità del 94,5% di qualificazione e dà un punteggio di idoneità di 1,64 su una scala da 0 a 2. Tutte e 3 le decisioni sono state restituite in soli 165 millisecondi.

Ora che abbiamo D3 in esecuzione in locale, usiamolo per costruire 3 applicazioni AI pratiche.

Progetto 1: crea un AI Blog Quality Analyzer con D3 Mini

Immagina di gestire una pubblicazione tecnica in cui decine di articoli devono essere revisionati prima della pubblicazione. Invece di leggere ogni articolo manualmente, possiamo creare un analizzatore di qualità AI che utilizza Olostep per estrarre i contenuti del sito web e il nostro modello D3 Mini in locale per classificarli e valutarli.

Lo testeremo su un articolo reale, il nostro tutorial su KTransformers, che ho scritto io.

1. Fai lo scraping del nostro tutorial su KTransformers

Per prima cosa useremo l’SDK Python di Olostep per estrarre il contenuto dell’articolo in 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])Offerto da

Olostep recupera l’articolo in Markdown, preservando titoli, testo ed esempi di codice per l’analisi.

2. Categorizza e valuta l’articolo con D3

Successivamente useremo Choice per identificare la categoria dell’articolo e Score per valutarne la qualità didattica su una scala a 5 punti.

%%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")Offerto da

Output:

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

D3 classifica correttamente l’articolo come AI e gli assegna un punteggio di qualità di 4,6/5, completando l’analisi in circa 1,11 secondi.

Progetto 2: analizza un’immagine di prodotto con D3 Mini

In questo progetto costruiremo un semplice flusso di screening delle immagini di prodotto per un negozio e-commerce. L’obiettivo è usare D3 Mini per identificare la categoria del prodotto, verificare se il prodotto è chiaramente visibile e valutare la qualità dell’immagine prima che venga aggiunta a un catalogo.

Il codice seguente usa direttamente la System One API di vLLM e legge i risultati dal campo corretto answers.

1. Carica un’immagine di prodotto

Per prima cosa scaricheremo un’immagine di prodotto di esempio, la mostreremo nel notebook e la convertiremo in base64 così da poterla inviare al modello.

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))Offerto da

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

Questo ci fornisce un input immagine pronto all’invio che D3 Mini può analizzare direttamente.

2. Analizza l’immagine con D3 Mini

Ora chiederemo a D3 Mini 3 cose in una volta: a quale categoria appartiene il prodotto, se il prodotto è chiaramente visibile e quanto è adatta l’immagine per un negozio online.

%%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)Offerto da

Output:

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 msOfferto da

Il modello identifica l’articolo come footwear, conferma che il prodotto è chiaramente visibile e assegna all’immagine un buon punteggio di qualità in appena 282 millisecondi.

Progetto 3: crea un analizzatore del movimento nei video con D3 Mini

Nell’ultimo progetto costruiremo un semplice analizzatore del movimento nei video usando D3 Mini. Invece di generare lunghe descrizioni, useremo il modello per capire cosa succede in una clip breve, identificare la direzione del movimento e rilevare i cambiamenti visivi. Questo approccio può essere utile per monitoraggio video, rilevamento di eventi e analisi automatizzata dei contenuti.

1. Scarica un video di esempio

Useremo il video di esempio ufficiale di D3 Mini da Hugging Face. Per prima cosa installa la libreria necessaria:

%pip install huggingface_hubOfferto da

Quindi scarica il video di esempio per analizzarlo in locale.

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"
)Offerto da

Il video mostra un riquadro che si muove da sinistra a destra cambiando colore da blu a verde.

2. Analizza il video

Per prima cosa convertiremo il video in formato base64 così da poterlo inviare al nostro server vLLM locale.

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}"Offerto da

Ora useremo la System One API per porre a D3 Mini 2 domande: in che direzione si muove il quadrato e se cambia colore.

%%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%}")Offerto da

Output:

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

D3 Mini identifica correttamente il movimento verso destra e assegna una probabilità del 93,7% al cambiamento di colore, completando l’analisi in soli 723 millisecondi.

Considerazioni finali

D3 Mini gestisce classificazione, verifiche sì/no e scoring su testo, immagini e video su una singola GPU NVIDIA RTX 3090. Configurare D3 in locale è stato sorprendentemente semplice. L’unico problema che ho riscontrato è stato un errore di memoria insufficiente CUDA, che ho risolto riducendo il consumo di memoria della GPU.

A parte questo, tutto ha funzionato senza intoppi. Se conosci già vLLM, probabilmente puoi ottimizzare ulteriormente la configurazione.

Quello che mi ha colpito di più è stata la velocità. I tempi wall sono andati da 87 millisecondi per una decisione su testo breve a 1,11 secondi per un articolo completo, e l’esempio video si è concluso in 723 millisecondi. Tutto è girato sulla mia GPU.

Penso che stiamo arrivando al punto in cui eseguire modelli decisionali su un server locale per un intero team sta diventando praticabile. Non ogni richiesta ha bisogno di un grande modello di ragionamento.

Per molte attività quotidiane, come classificazione, routing, scoring e filtraggio dei contenuti, un modello decisionale più piccolo può fare il suo lavoro. Puoi poi riservare i modelli di ragionamento più costosi ai compiti che richiedono davvero analisi più profonde o spiegazioni dettagliate.

Ovviamente, vorrai comunque valutare accuratezza e prestazioni sui tuoi carichi di lavoro prima di usare questi modelli in produzione. Dopo aver testato D3 su testo, immagini e video, la mia regola empirica è semplice: se il compito è una classificazione, un controllo sì/no o una valutazione, prova prima un modello D3, e passa a un modello di ragionamento solo quando ti serve una spiegazione.

Se vuoi approfondire il lavoro con modelli open, ti consiglio di dare un’occhiata al nostro corso Working with Hugging Face.