Tutorial vLLM D3: Rulează local modele de decizie AI cu Python

D3 este o familie de modele de decizie cu greutăți deschise care returnează o probabilitate pentru fiecare răspuns în loc să genereze text. Poți clasifica un tichet de suport, nota un articol sau verifica un clip video cu o singură cerere către un model care rulează pe propria ta mașină, în doar 87 de milisecunde în testele noastre.

Familia cuprinde 6 modele, de la 600 de milioane la 27 de miliarde de parametri. Poți experimenta cu modelele mai mici pe hardware modest și folosi pe cele mai mari pentru sarcini mai solicitante. D3 Edge este atât de ușor încât poate rula chiar și pe smartphone-uri compatibile.

vLLM suportă D3 prin cadrul său Structured Decisions, astfel încât poți servi un model local și îl poți apela printr-o interfață de programare a aplicațiilor (API) simplă. Proiectul mai amplu vLLM Semantic Router adaugă funcții de rutare și luare a deciziilor pentru aplicațiile AI.

În acest tutorial, voi acoperi configurarea locală a D3, cele 3 tipuri de decizii și primele tale predicții. Apoi, vom construi 3 proiecte practice:

1. Analizor AI al calității articolelor de blog: Folosește SDK-ul TypeSafe pentru Python și Olostep pentru a clasifica și evalua articole reale.
2. Înțelegerea imaginilor: Analizează imagini de produs, identifică categoriile și evaluează calitatea imaginilor.
3. Înțelegerea videoclipurilor: Analizează videoclipuri scurte pentru a detecta mișcarea și schimbările vizuale.

La final, vei ști cum să rulezi D3 local și cum să-l folosești pentru a construi aplicații care iau decizii pe text, imagini și video. Poți vedea și ghidurile noastre despre rularea locală a modelelor lingvistice mari și accelerarea inferenței locale pe un GPU RTX 3090.

Pe scurt

• D3 este o familie de modele de decizie cu greutăți deschise care returnează probabilități pentru întrebări de tip alegere, da/nu (Noul) și scor, în loc să genereze text.
• D3 Mini (4B) gestionează text, imagini și video și rulează pe un singur GPU NVIDIA RTX 3090 cu vLLM.
• Servești modelul cu vllm serve și îl apelezi prin SDK-ul TypeSafe pentru Python sau endpointul /v1/systemone.
• Construim 3 proiecte: un analizor al calității articolelor, un filtru pentru imagini de produs și un analizor de mișcare în video.
• Răspunsurile în testele noastre au durat între 87 de milisecunde și 1,11 secunde.

Ce sunt modelele de decizie D3?

D3 este o familie de modele AI cu greutăți deschise construite pentru a lua decizii, nu pentru a genera text. În loc să ceri unui model lingvistic mare (LLM) să explice dacă o tranzacție este suspectă, D3 poate returna direct probabilitatea că are nevoie de verificare.

Sursă: vllm-sr/d3-mini · Hugging Face

Suportă 3 tipuri de decizii:

D3 vine în 6 dimensiuni, de la 600 de milioane la 27 de miliarde de parametri, potrivite pentru tot, de la dispozitive edge la GPU-uri de top. Poți răsfoi familia în colecția Decision 3.0 pe Hugging Face.

Modelele sunt evaluate pe benchmark-uri axate pe decizii, precum Typed Decisions, care măsoară acuratețea clasificării și calitatea probabilităților.

Pentru acest tutorial, vom folosi D3 Mini (4B) deoarece suportă înțelegerea textului, imaginilor și videoclipurilor, rămânând suficient de mic pentru a rula pe un GPU NVIDIA RTX 3090 local.

Cum să rulezi D3 local cu vLLM

vLLM Semantic Router (vLLM SR) este un proiect open-source din ecosistemul vLLM care ajută aplicațiile AI să ia decizii inteligente. Suportă rutarea modelelor, verificări de siguranță, caching semantic și modele de decizie specializate precum D3. În timp ce vLLM se ocupă de inferența modelului, vLLM SR se concentrează pe modul în care sunt evaluate și rutate cererile.

În acest tutorial, vom folosi noul suport Structured Decisions al vLLM pentru a rula D3 Mini local, fără a instala Semantic Router-ul propriu-zis. vLLM servește D3 prin API-ul System One, un endpoint numit după gândirea rapidă și intuitivă „System 1”. Răspunde la întrebări tipizate dintr-o singură trecere și returnează probabilități în loc de text generat.

Ne vom conecta la model folosind SDK-ul TypeSafe pentru Python și vom explora cum gestionează clasificarea, estimarea probabilităților și acordarea de scoruri.

1. Instalează vLLM și rulează D3 local

Vom folosi Ubuntu Linux, Python 3.12 și un GPU NVIDIA RTX 3090. Utilizatorii Windows pot urma pașii folosind Ubuntu prin Windows Subsystem for Linux 2 (WSL2).

Mai întâi, instalează uv. După finalizarea instalării, repornește terminalul astfel încât comanda uv să fie disponibilă.

curl -LsSf https://astral.sh/uv/install.sh | shFuncționează cu

Acum, creează un mediu Python 3.12 și activează-l:

uv venv --python 3.12 --seed
source .venv/bin/activateFuncționează cu

Apoi, instalează versiunea nightly a vLLM, care include noul suport Structured Decisions:

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightlyFuncționează cu

Acum pornește modelul D3 Mini cu setări de memorie GPU potrivite pentru testare locală:

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eagerFuncționează cu

Prima lansare descarcă modelul de pe Hugging Face. Odată încărcat, vLLM expune local API-ul System One la http://localhost:8000/v1/systemone.

Păstrează acest terminal deschis. Vom accesa modelul dintr-un notebook Jupyter.

2. Conectează-te la D3 folosind SDK-ul TypeSafe pentru Python

În loc să construim manual cereri HTTP, vom folosi SDK-ul TypeSafe pentru Python ca să comunicăm cu modelul nostru care rulează local.

Instalează bibliotecile necesare:

%pip install typesafe-sdk olostepFuncționează cu

Importă cele 3 tipuri de decizii și configurează clientul să se conecteze la serverul nostru 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"
)Funcționează cu

Folosim o cheie API placeholder deoarece serverul local nu necesită o acreditare TypeSafe găzduită.

3. Fă prima ta decizie AI

Să începem cu un exemplu simplu de detectare a fraudei. Vom da lui D3 o tranzacție neobișnuită și vom întreba dacă ar trebui marcată pentru verificare.

%%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)Funcționează cu

Ieșire:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msFuncționează cu

D3 returnează o probabilitate de aproximativ 99,9%, indicând că tranzacția ar trebui marcată pentru verificare. Inferența a durat aproximativ 87 de milisecunde.

Putem combina și toate cele 3 tipuri de decizii într-o singură cerere. De data aceasta, vom evalua un candidat și îi vom cere lui D3 să identifice cel mai potrivit rol, să verifice calificările și să aprecieze potrivirea.

%%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)Funcționează cu

Ieșire:

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 msFuncționează cu

Modelul identifică corect Data Scientist ca cea mai bună potrivire, atribuie o probabilitate de calificare de 94,5% și oferă un scor de potrivire de 1,64 pe o scară de la 0 la 2. Toate cele 3 decizii au fost returnate în doar 165 de milisecunde.

Acum că avem D3 rulând local, hai să-l folosim pentru a construi 3 aplicații AI practice.

Proiectul 1: Construiește un Analizor AI al Calității Blogurilor cu D3 Mini

Imaginează-ți că gestionezi o publicație tehnică unde zeci de articole trebuie revizuite înainte de publicare. În loc să citești manual fiecare articol, putem construi un analizor AI al calității care folosește Olostep pentru a extrage conținutul site-ului și modelul nostru D3 Mini care rulează local pentru a-l clasifica și puncta.

Îl vom testa pe un articol real, tutorialul nostru KTransformers, pe care l-am scris eu.

1. Extrage conținutul tutorialului nostru KTransformers

Mai întâi, vom folosi SDK-ul Olostep pentru Python pentru a extrage conținutul articolului ca 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])Funcționează cu

Olostep preia articolul ca Markdown, păstrând titlurile, textul și exemplele de cod pentru analiză.

2. Categorizează și evaluează articolul folosind D3

În continuare, vom folosi Alegere pentru a identifica categoria articolului și Scor pentru a-i evalua calitatea educațională pe o scară de 5 puncte.

%%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")Funcționează cu

Ieșire:

Category: ai
Quality: 4.6/5
CPU times: user 3.29 ms, sys: 2.96 ms, total: 6.25 ms
Wall time: 1.11 sFuncționează cu

D3 categorizează corect articolul ca AI și îi acordă un scor de calitate de 4,6/5, finalizând analiza în aproximativ 1,11 secunde.

Proiectul 2: Analizează o Imagine de Produs cu D3 Mini

În acest proiect, vom construi un flux simplu de verificare a imaginilor de produs pentru un magazin online. Scopul este să folosim D3 Mini pentru a identifica categoria produsului, a verifica dacă produsul este clar vizibil și a evalua calitatea imaginii înainte de a fi adăugată în catalog.

Codul următor folosește direct API-ul vLLM System One și citește rezultatele din câmpul corect answers.

1. Încarcă o imagine de produs

Mai întâi, vom descărca o imagine de produs exemplu, o vom afișa în notebook și o vom converti în base64 pentru a putea fi trimisă modelului.

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))Funcționează cu

image_base64 = base64.b64encode(image_data).decode()
image_input = f"data:image/jpeg;base64,{image_base64}"Funcționează cu

Astfel obținem un input de imagine gata de trimis, pe care D3 Mini îl poate analiza direct.

2. Analizează imaginea folosind D3 Mini

În continuare, îi vom cere lui D3 Mini 3 lucruri deodată: ce categorie are produsul, dacă produsul este clar vizibil și cât de potrivită este imaginea pentru un magazin 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)Funcționează cu

Ieșire:

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 msFuncționează cu

Modelul identifică articolul ca footwear, confirmă că produsul este clar vizibil și oferă imaginii un scor solid de calitate în doar 282 de milisecunde.

Proiectul 3: Construiește un Analizor de Mișcare în Video cu D3 Mini

În ultimul nostru proiect, vom construi un analizor simplu de mișcare în video folosind D3 Mini. În loc să generăm descrieri video lungi, vom folosi modelul pentru a înțelege ce se întâmplă într-un clip scurt, a identifica direcția mișcării și a detecta schimbările vizuale. Această abordare poate fi utilă pentru monitorizare video, detectarea evenimentelor și analiza automată a conținutului.

1. Descarcă un videoclip exemplu

Vom folosi videoclipul oficial de probă pentru D3 Mini de pe Hugging Face. Mai întâi, instalează biblioteca necesară:

%pip install huggingface_hubFuncționează cu

Apoi, descarcă videoclipul exemplu pentru a-l analiza 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"
)Funcționează cu

Videoclipul arată o cutie care se mișcă de la stânga la dreapta, schimbându-și culoarea din albastru în verde.

2. Analizează videoclipul

Mai întâi, vom converti videoclipul în format base64 pentru a putea fi trimis serverului nostru 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}"Funcționează cu

Acum, vom folosi API-ul System One pentru a adresa lui D3 Mini 2 întrebări: în ce direcție se mișcă pătratul și dacă își schimbă culoarea.

%%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%}")Funcționează cu

Ieșire:

Movement: right
Color Change: 93.7%
CPU times: user 3.01 ms, sys: 5.04 ms, total: 8.05 ms
Wall time: 723 msFuncționează cu

D3 Mini identifică corect mișcarea ca spre dreapta și atribuie o probabilitate de 93,7% schimbării de culoare, finalizând analiza în doar 723 de milisecunde.

Concluzii

D3 Mini gestionează clasificarea, verificările da/nu și acordarea de scoruri pe text, imagini și video pe un singur GPU NVIDIA RTX 3090. Configurarea locală a D3 a fost surprinzător de simplă. Singura problemă întâlnită a fost o eroare CUDA de memorie insuficientă, pe care am rezolvat-o reducând consumul de memorie GPU.

În rest, totul a mers lin. Dacă ești deja familiarizat cu vLLM, probabil poți optimiza setarea și mai mult.

Ce m-a impresionat cel mai mult a fost viteza. Timpurile de execuție au variat de la 87 de milisecunde pentru o decizie scurtă pe text la 1,11 secunde pentru un articol întreg, iar exemplul video s-a încheiat în 723 de milisecunde. Totul a rulat pe propriul meu GPU.

Cred că ajungem într-un punct în care rularea modelelor de decizie pe un server local pentru o întreagă echipă devine practică. Nu fiecare cerere are nevoie de un model mare de raționare.

Pentru multe sarcini de zi cu zi, precum clasificare, rutare, notare și filtrare de conținut, un model de decizie mai mic își face treaba. Apoi poți rezerva modelele scumpe de raționare pentru sarcinile care chiar necesită analiză mai profundă sau explicații detaliate.

Desigur, tot ai vrea să evaluezi acuratețea și performanța pe propriile tale fluxuri de lucru înainte de a folosi aceste modele în producție. După testarea D3 pe text, imagini și video, regula mea de bază e simplă: dacă sarcina este o clasificare, o verificare da/nu sau o notare, încearcă mai întâi un model D3 și treci la un model de raționare doar atunci când ai nevoie de o explicație.

Dacă ești dornic să afli mai multe despre lucrul cu modele deschise, îți recomand cursul nostru Working with Hugging Face.