Samouczek vLLM D3: uruchamiaj lokalnie modele decyzyjne AI w Pythonie

D3 to rodzina otwarto‑wagowych modeli decyzyjnych, które zamiast generować tekst zwracają prawdopodobieństwo dla każdej odpowiedzi. Jednym zapytaniem do modelu uruchomionego na twojej maszynie możesz sklasyfikować zgłoszenie do supportu, ocenić artykuł albo sprawdzić klip wideo — w naszych testach już w 87 milisekund.

Rodzina obejmuje 6 modeli, od 600 milionów do 27 miliardów parametrów. Z mniejszymi modelami poeksperymentujesz na skromnym sprzęcie, a większych użyjesz do bardziej wymagających zadań. D3 Edge jest tak lekki, że może działać nawet na zgodnych smartfonach.

vLLM obsługuje D3 przez framework Structured Decisions, więc możesz serwować model lokalnie i wywoływać go przez prosty interfejs API (application programming interface). Szerszy projekt vLLM Semantic Router dodaje do aplikacji AI funkcje routingu i podejmowania decyzji.

W tym samouczku omówię lokalną konfigurację D3, 3 typy decyzji i twoje pierwsze predykcje. Następnie zbudujemy 3 praktyczne projekty:

1. AI Blog Quality Analyzer: Użyj zestawu SDK Python TypeSafe i Olostep do klasyfikacji i oceny prawdziwych artykułów.
2. Zrozumienie obrazu: Analizuj zdjęcia produktów, identyfikuj kategorie i oceniaj jakość obrazów.
3. Zrozumienie wideo: Analizuj krótkie filmy, aby wykrywać ruch i zmiany wizualne.

Na końcu będziesz wiedzieć, jak uruchomić D3 lokalnie i użyć go do budowy aplikacji podejmujących decyzje dla tekstu, obrazów i wideo. Zobacz też nasze poradniki o lokalnym uruchamianiu dużych modeli językowych oraz przyspieszaniu wnioskowania lokalnego na GPU RTX 3090.

W skrócie

• D3 to rodzina otwarto‑wagowych modeli decyzyjnych, które zamiast generować tekst zwracają prawdopodobieństwa dla pytań typu wybór, tak/nie (Noul) i ocena.
• D3 Mini (4B) obsługuje tekst, obrazy i wideo i działa na pojedynczym GPU NVIDIA RTX 3090 z vLLM.
• Serwujesz model poleceniem vllm serve i wywołujesz go przez SDK TypeSafe dla Pythona albo endpoint /v1/systemone.
• Budujemy 3 projekty: analizator jakości artykułów, selektor zdjęć produktów i analizator ruchu na wideo.
• W naszych testach odpowiedzi trwały od 87 milisekund do 1,11 sekundy.

Czym są modele decyzyjne D3?

D3 to rodzina modeli AI o otwartych wagach zbudowanych do podejmowania decyzji zamiast generowania tekstu. Zamiast prosić duży model językowy (LLM) o wyjaśnienie, czy transakcja jest podejrzana, D3 może bezpośrednio zwrócić prawdopodobieństwo, że wymaga ona przeglądu.

Źródło: vllm-sr/d3-mini · Hugging Face

Obsługuje 3 typy decyzji:

D3 występuje w 6 rozmiarach, od 600 milionów do 27 miliardów parametrów, co pasuje zarówno do urządzeń brzegowych, jak i wydajnych GPU. Przeglądaj rodzinę w kolekcji Decision 3.0 na Hugging Face.

Modele są oceniane na benchmarkach skupionych na decyzjach, takich jak Typed Decisions, które mierzą dokładność klasyfikacji i jakość prawdopodobieństw.

W tym samouczku użyjemy D3 Mini (4B), ponieważ obsługuje zrozumienie tekstu, obrazu i wideo, a jednocześnie jest wystarczająco mały, by działać lokalnie na GPU NVIDIA RTX 3090.

Jak uruchomić D3 lokalnie z vLLM

vLLM Semantic Router (vLLM SR) to open‑source’owy projekt w ekosystemie vLLM, który pomaga aplikacjom AI podejmować inteligentne decyzje. Obsługuje routing modeli, kontrolę bezpieczeństwa, cache semantyczny i wyspecjalizowane modele decyzyjne jak D3. Podczas gdy vLLM zajmuje się wnioskowaniem modelu, vLLM SR skupia się na tym, jak są oceniane i kierowane żądania.

W tym samouczku użyjemy nowej obsługi Structured Decisions w vLLM, aby uruchomić D3 Mini lokalnie bez instalowania samego Semantic Routera. vLLM serwuje D3 przez System One API, endpoint nazwany od szybkiego, intuicyjnego myślenia „System 1”. Odpowiada na typowane pytania w pojedynczym przebiegu i zwraca prawdopodobieństwa zamiast generowanego tekstu.

Połączymy się z modelem za pomocą SDK TypeSafe dla Pythona i sprawdzimy, jak radzi sobie z klasyfikacją, estymacją prawdopodobieństwa i ocenianiem.

1. Zainstaluj vLLM i uruchom D3 lokalnie

Użyjemy Ubuntu Linux, Pythona 3.12 i GPU NVIDIA RTX 3090. Użytkownicy Windows mogą podążać, korzystając z Ubuntu w Windows Subsystem for Linux 2 (WSL2).

Najpierw zainstaluj uv. Gdy instalacja się zakończy, zrestartuj terminal, aby polecenie uv było dostępne.

curl -LsSf https://astral.sh/uv/install.sh | shObsługiwane przez

Teraz utwórz środowisko Python 3.12 i je aktywuj:

uv venv --python 3.12 --seed
source .venv/bin/activateObsługiwane przez

Następnie zainstaluj nocne wydanie vLLM, które zawiera nową obsługę Structured Decisions:

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightlyObsługiwane przez

Teraz uruchom model D3 Mini z ustawieniami pamięci GPU odpowiednimi do lokalnych testów:

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eagerObsługiwane przez

Przy pierwszym uruchomieniu model pobierze się z Hugging Face. Po załadowaniu vLLM udostępnia lokalne System One API pod adresem http://localhost:8000/v1/systemone.

Pozostaw ten terminal uruchomiony. Uzyskamy dostęp do modelu z notatnika Jupyter.

2. Połącz się z D3 za pomocą SDK TypeSafe dla Pythona

Zamiast ręcznie konstruować zapytania HTTP, użyjemy SDK TypeSafe dla Pythona do komunikacji z naszym lokalnie działającym modelem.

Zainstaluj wymagane biblioteki:

%pip install typesafe-sdk olostepObsługiwane przez

Zaimportuj 3 typy decyzji i skonfiguruj klienta do połączenia z lokalnym serwerem vLLM:

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

client = TypeSafeClient(
    base_url="http://localhost:8000",
    api_key="local",
    model="vllm-sr/d3-mini"
)Obsługiwane przez

Używamy zastępczego klucza API, ponieważ lokalny serwer nie wymaga hostowanego poświadczenia TypeSafe.

3. Podejmij swoją pierwszą decyzję AI

Zacznijmy od prostego przykładu wykrywania oszustw. Podamy D3 nietypową transakcję i zapytamy, czy powinna zostać oflagowana do przeglądu.

%%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)Obsługiwane przez

Wynik:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msObsługiwane przez

D3 zwraca prawdopodobieństwo około 99,9%, wskazując, że transakcja powinna zostać oflagowana do przeglądu. Wnioskowanie trwało około 87 milisekund.

Możemy też połączyć wszystkie 3 typy decyzji w jednym żądaniu. Tym razem ocenimy kandydata do pracy i poprosimy D3 o wskazanie najlepszego stanowiska, sprawdzenie kwalifikacji i ocenę dopasowania.

%%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)Obsługiwane przez

Wynik:

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 msObsługiwane przez

Model poprawnie wskazuje Data Scientist jako najlepsze dopasowanie, nadaje 94,5% prawdopodobieństwa spełnienia wymagań i przyznaje ocenę dopasowania 1,64 w skali 0–2. Wszystkie 3 decyzje zwrócił w zaledwie 165 milisekund.

Skoro mamy D3 uruchomione lokalnie, użyjmy go do zbudowania 3 praktycznych aplikacji AI.

Projekt 1: Zbuduj AI Blog Quality Analyzer z D3 Mini

Wyobraź sobie zarządzanie publikacją techniczną, w której dziesiątki artykułów trzeba zrecenzować przed publikacją. Zamiast czytać każdy tekst ręcznie, możemy zbudować analizator jakości AI, który używa Olostep do ekstrakcji treści z witryny oraz naszego lokalnie działającego modelu D3 Mini do klasyfikacji i oceny.

Przetestujemy go na prawdziwym artykule, naszym samouczku KTransformers, który napisałem.

1. Zeskrob nasz samouczek KTransformers

Najpierw użyjemy SDK Python Olostep, aby wyodrębnić treść artykułu jako 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])Obsługiwane przez

Olostep pobiera artykuł jako Markdown, zachowując nagłówki, tekst i przykłady kodu do analizy.

2. Sklasyfikuj i oceń artykuł za pomocą D3

Następnie użyjemy Choice, aby zidentyfikować kategorię artykułu, oraz Score, aby ocenić jego wartość edukacyjną w 5‑stopniowej skali.

%%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")Obsługiwane przez

Wynik:

Category: ai
Quality: 4.6/5
CPU times: user 3.29 ms, sys: 2.96 ms, total: 6.25 ms
Wall time: 1.11 sObsługiwane przez

D3 poprawnie kategoryzuje artykuł jako AI i przyznaje mu ocenę jakości 4,6/5, kończąc analizę w około 1,11 sekundy.

Projekt 2: Przeanalizuj zdjęcie produktu z D3 Mini

W tym projekcie zbudujemy prosty workflow selekcji zdjęć produktów dla sklepu e‑commerce. Celem jest użycie D3 Mini do identyfikacji kategorii produktu, sprawdzenia, czy produkt jest wyraźnie widoczny, oraz oceny jakości obrazu, zanim trafi do katalogu.

Poniższy kod używa bezpośrednio System One API vLLM i odczytuje wyniki z właściwego pola answers.

1. Załaduj zdjęcie produktu

Najpierw pobierzemy przykładowe zdjęcie produktu, wyświetlimy je w notatniku i skonwertujemy do base64, aby można je było wysłać do modelu.

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))Obsługiwane przez

image_base64 = base64.b64encode(image_data).decode()
image_input = f"data:image/jpeg;base64,{image_base64}"Obsługiwane przez

To daje nam gotowe wejście obrazkowe, które D3 Mini może analizować bezpośrednio.

2. Przeanalizuj obraz za pomocą D3 Mini

Następnie zadamy D3 Mini 3 rzeczy na raz: do jakiej kategorii należy produkt, czy produkt jest wyraźnie widoczny i na ile zdjęcie nadaje się do sklepu internetowego.

%%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)Obsługiwane przez

Wynik:

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 msObsługiwane przez

Model identyfikuje przedmiot jako footwear, potwierdza, że produkt jest wyraźnie widoczny, i przyznaje obrazowi solidną ocenę jakości — w zaledwie 282 milisekundy.

Projekt 3: Zbuduj analizator ruchu na wideo z D3 Mini

W ostatnim projekcie zbudujemy prosty analizator ruchu na wideo z wykorzystaniem D3 Mini. Zamiast generować długie opisy, użyjemy modelu do zrozumienia, co dzieje się w krótkim klipie, zidentyfikowania kierunku ruchu i wykrycia zmian wizualnych. To podejście może być użyteczne w monitoringu wideo, wykrywaniu zdarzeń i automatycznej analizie treści.

1. Pobierz przykładowe wideo

Użyjemy oficjalnego przykładowego wideo D3 Mini z Hugging Face. Najpierw zainstaluj wymaganą bibliotekę:

%pip install huggingface_hubObsługiwane przez

Następnie pobierz przykładowe wideo, abyśmy mogli je analizować lokalnie.

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"
)Obsługiwane przez

Wideo przedstawia kwadrat poruszający się z lewej na prawą, zmieniający kolor z niebieskiego na zielony.

2. Przeanalizuj wideo

Najpierw skonwertujemy wideo do formatu base64, aby można je było wysłać do naszego lokalnego serwera vLLM.

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}"Obsługiwane przez

Teraz użyjemy System One API, żeby zadać D3 Mini 2 pytania: w jakim kierunku porusza się kwadrat i czy zmienia kolor.

%%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%}")Obsługiwane przez

Wynik:

Movement: right
Color Change: 93.7%
CPU times: user 3.01 ms, sys: 5.04 ms, total: 8.05 ms
Wall time: 723 msObsługiwane przez

D3 Mini poprawnie rozpoznaje ruch jako right i przypisuje 93,7% prawdopodobieństwa zmianie koloru, kończąc analizę w zaledwie 723 milisekundy.

Na koniec

D3 Mini obsługuje klasyfikację, sprawdzenia tak/nie i ocenianie dla tekstu, obrazów i wideo na pojedynczym GPU NVIDIA RTX 3090. Konfiguracja D3 lokalnie była zaskakująco prosta. Jedyny problem, na jaki trafiłem, to błąd braku pamięci CUDA, który naprawiłem, zmniejszając zużycie pamięci GPU.

Poza tym wszystko działało gładko. Jeśli znasz już vLLM, prawdopodobnie możesz jeszcze lepiej zoptymalizować konfigurację.

Najbardziej zaimponowała mi szybkość. Czas ścienny wahał się od 87 milisekund dla krótkiej decyzji tekstowej do 1,11 sekundy dla pełnego artykułu, a przykład wideo zakończył się w 723 milisekundy. Wszystko działało na moim własnym GPU.

Myślę, że dochodzimy do punktu, w którym uruchamianie modeli decyzyjnych na lokalnym serwerze dla całego zespołu staje się praktyczne. Nie każde żądanie potrzebuje dużego modelu rozumującego.

W wielu codziennych zadaniach — takich jak klasyfikacja, routing, ocenianie i filtrowanie treści — mniejszy model decyzyjny w zupełności wystarczy. Droższe modele rozumujące możesz zarezerwować do zadań, które rzeczywiście wymagają głębszej analizy lub szczegółowych wyjaśnień.

Oczywiście przed produkcją nadal warto ocenić dokładność i wydajność na własnych obciążeniach. Po przetestowaniu D3 na tekście, obrazach i wideo moja zasada jest prosta: jeśli zadanie to klasyfikacja, sprawdzenie tak/nie albo ocena, zacznij od modelu D3, a po model rozumujący sięgnij dopiero wtedy, gdy potrzebujesz wyjaśnienia.

Jeśli chcesz dowiedzieć się więcej o pracy z otwartymi modelami, polecam nasz kurs Working with Hugging Face.