vLLM D3-handledning: Kör AI-beslutsmodeller lokalt med Python

D3 är en familj av öppenvikts-beslutsmodeller som returnerar en sannolikhet för varje svar i stället för att generera text. Du kan klassificera ett supportärende, poängsätta en artikel eller granska ett videoklipp med en enda förfrågan till en modell som körs på din egen dator, på så lite som 87 millisekunder i våra tester.

Familjen omfattar 6 modeller, från 600 miljoner till 27 miljarder parametrar. Du kan experimentera med de mindre modellerna på modest hårdvara och använda de större för mer krävande uppgifter. D3 Edge är så lätt att den till och med kan köras på kompatibla smartphones.

vLLM stöder D3 genom sitt Structured Decisions-ramverk, så att du kan serva en modell lokalt och anropa den via ett enkelt applikationsprogrammeringsgränssnitt (API). Det bredare vLLM Semantic Router-projektet lägger till routing- och beslutsfunktioner för AI-applikationer.

I den här handledningen går jag igenom hur du sätter upp D3 lokalt, de 3 beslutstyperna och dina första förutsägelser. Sedan bygger vi 3 praktiska projekt:

1. AI-analys av bloggars kvalitet: Använd TypeSafe Python SDK och Olostep för att klassificera och utvärdera riktiga artiklar.
2. Bildförståelse: Analysera produktbilder, identifiera kategorier och utvärdera bildkvalitet.
3. Videoförståelse: Analysera korta videor för att upptäcka rörelse och visuella förändringar.

I slutet kommer du att veta hur du kör D3 lokalt och använder den för att bygga applikationer som fattar beslut över text, bilder och video. Du kan också se våra guider till att köra stora språkmodeller lokalt och att snabba upp lokal inferens på ett RTX 3090-GPU.

Kortfattat

• D3 är en familj av öppenvikts-beslutsmodeller som returnerar sannolikheter för val-, ja/nej- (Noul) och poängfrågor i stället för att generera text.
• D3 Mini (4B) hanterar text, bilder och video och körs på en enda NVIDIA RTX 3090-grafikprocessor (GPU) med vLLM.
• Du servar modellen med vllm serve och anropar den via TypeSafe Python SDK eller slutpunkten /v1/systemone.
• Vi bygger 3 projekt: en kvalitetsanalys av artiklar, en granskning av produktbilder och en videorörelseanalys.
• Svarstiderna i våra tester låg mellan 87 millisekunder och 1,11 sekunder.

Vad är D3-beslutsmodeller?

D3 är en familj av öppenvikts-AI-modeller byggda för att fatta beslut i stället för att generera text. I stället för att be en stor språkmodell (LLM) förklara om en transaktion är misstänkt kan D3 direkt returnera en sannolikhet för att den behöver granskas.

Källa: vllm-sr/d3-mini · Hugging Face

Den stöder 3 beslutstyper:

D3 finns i 6 storlekar, från 600 miljoner till 27 miljarder parametrar, vilket passar allt från edge-enheter till högpresterande GPU:er. Du kan bläddra i familjen i Decision 3.0-samlingen på Hugging Face.

Modellerna utvärderas på beslutsfokuserade riktmärken som Typed Decisions, som mäter klassificeringsnoggrannhet och sannolikhetskvalitet.

För den här handledningen använder vi D3 Mini (4B) eftersom den stöder förståelse av text, bild och video samtidigt som den är tillräckligt liten för att köras på en lokal NVIDIA RTX 3090-GPU.

Så här kör du D3 lokalt med vLLM

vLLM Semantic Router (vLLM SR) är ett öppet källkodsprojekt i vLLM-ekosystemet som hjälper AI-applikationer att fatta intelligenta beslut. Det stöder modellrouting, säkerhetskontroller, semantisk cache och specialiserade beslutsmodeller som D3. Medan vLLM hanterar modellinferens fokuserar vLLM SR på hur förfrågningar utvärderas och dirigeras.

I den här handledningen använder vi vLLM:s nya stöd för Structured Decisions för att köra D3 Mini lokalt utan att installera själva Semantic Router. vLLM servar D3 via System One API, en slutpunkt uppkallad efter det snabba, intuitiva "System 1"-tänkandet. Den besvarar typade frågor i ett enda steg och returnerar sannolikheter i stället för genererad text.

Vi kommer att ansluta till modellen med TypeSafe Python SDK och utforska hur den hanterar klassificering, sannolikhetsestimering och poängsättning.

1. Installera vLLM och kör D3 lokalt

Vi använder Ubuntu Linux, Python 3.12 och en NVIDIA RTX 3090-GPU. Windows-användare kan hänga med genom att använda Ubuntu via Windows Subsystem for Linux 2 (WSL2).

Installera först uv. När installationen är klar, starta om din terminal så att kommandot uv är tillgängligt.

curl -LsSf https://astral.sh/uv/install.sh | shDrivs av

Skapa nu en Python 3.12-miljö och aktivera den:

uv venv --python 3.12 --seed
source .venv/bin/activateDrivs av

Installera sedan vLLM nightly-builden, som inkluderar det nya stödet för Structured Decisions:

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

Starta nu D3 Mini-modellen med GPU-minnesinställningar som passar lokal testning:

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

Vid första starten hämtas modellen från Hugging Face. När den är inläst exponerar vLLM det lokala System One API på http://localhost:8000/v1/systemone.

Håll denna terminal igång. Vi kommer att komma åt modellen från en Jupyter-notebook.

2. Anslut till D3 med TypeSafe Python SDK

I stället för att manuellt skapa HTTP-förfrågningar använder vi TypeSafe Python SDK för att kommunicera med vår lokalt körande modell.

Installera de nödvändiga biblioteken:

%pip install typesafe-sdk olostepDrivs av

Importera de 3 beslutstyperna och konfigurera klienten för att ansluta till vår lokala 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"
)Drivs av

Vi använder en platshållare för API-nyckeln eftersom den lokala servern inte kräver en hostad TypeSafe-referens.

3. Gör ditt första AI-beslut

Låt oss börja med ett enkelt exempel på bedrägeridetektion. Vi ger D3 en ovanlig transaktion och frågar om den bör flaggas för granskning.

%%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)Drivs av

Utdata:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msDrivs av

D3 returnerar en sannolikhet på cirka 99,9 %, vilket indikerar att transaktionen bör flaggas för granskning. Inferensen tog runt 87 millisekunder.

Vi kan också kombinera alla 3 beslutstyper i en enda förfrågan. Den här gången utvärderar vi en arbetssökande och ber D3 att identifiera bästa rollen, kontrollera kvalifikationer och poängsätta lämpligheten.

%%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)Drivs av

Utdata:

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 msDrivs av

Modellen identifierar korrekt Data Scientist som bästa matchning, tilldelar 94,5 % sannolikhet för kvalifikation och ger en fit-poäng på 1,64 på en skala 0 till 2. Alla 3 besluten returnerades på bara 165 millisekunder.

Nu när vi har D3 körande lokalt, låt oss använda den för att bygga 3 praktiska AI-applikationer.

Projekt 1: Bygg en AI-analys av bloggars kvalitet med D3 Mini

Föreställ dig att du driver en teknisk publikation där dussintals artiklar behöver granskas innan publicering. I stället för att läsa varje artikel manuellt kan vi bygga en AI-baserad kvalitetsanalys som använder Olostep för att extrahera webbplatsinnehåll och vår lokalt körande D3 Mini-modell för att klassificera och poängsätta det.

Vi testar den på en riktig artikel, vår KTransformers-handledning, som jag skrev.

1. Skrapa vår KTransformers-handledning

Först använder vi Olostep Python SDK för att extrahera artikelinnehållet som 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])Drivs av

Olostep hämtar artikeln som Markdown och bevarar dess rubriker, text och kodexempel för analys.

2. Kategorisera och betygsätt artikeln med D3

Därefter använder vi Choice för att identifiera artikelns kategori och Score för att utvärdera dess pedagogiska kvalitet på en femgradig skala.

%%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")Drivs av

Utdata:

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

D3 kategoriserar artikeln korrekt som AI och ger den ett kvalitetsbetyg på 4,6/5, och slutför analysen på cirka 1,11 sekunder.

Projekt 2: Analysera en produktbild med D3 Mini

I det här projektet bygger vi ett enkelt arbetsflöde för granskning av produktbilder för en e-handelsbutik. Målet är att använda D3 Mini för att identifiera produktkategori, kontrollera om produkten är tydligt synlig och bedöma bildkvaliteten innan den läggs till i en katalog.

Koden nedan använder vLLM System One API direkt och läser resultat från det korrekta fältet answers.

1. Läs in en produktbild

Först laddar vi ner en exempelbild på en produkt, visar den i notebooken och konverterar den till base64 så att den kan skickas till modellen.

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))Drivs av

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

Detta ger oss en färdig bildingång som D3 Mini kan analysera direkt.

2. Analysera bilden med D3 Mini

Nästa steg är att fråga D3 Mini 3 saker på en gång: vilken kategori produkten tillhör, om produkten är tydligt synlig och hur lämplig bilden är för en onlinebutik.

%%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)Drivs av

Utdata:

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 msDrivs av

Modellen identifierar objektet som footwear, bekräftar att produkten är tydligt synlig och ger bilden en god kvalitetsbedömning på bara 282 millisekunder.

Projekt 3: Bygg en videorörelseanalys med D3 Mini

I vårt sista projekt bygger vi en enkel videorörelseanalys med D3 Mini. I stället för att generera långa videobeskrivningar använder vi modellen för att förstå vad som händer i ett kort klipp, identifiera rörelseriktningen och upptäcka visuella förändringar. Det här tillvägagångssättet kan vara användbart för videoövervakning, händelsedetektering och automatiserad innehållsanalys.

1. Ladda ner en exempelvideo

Vi använder den officiella exempelvideon för D3 Mini från Hugging Face. Installera först det nödvändiga biblioteket:

%pip install huggingface_hubDrivs av

Ladda sedan ner exempelvideon så att vi kan analysera den lokalt.

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"
)Drivs av

Videon visar en ruta som rör sig från vänster till höger samtidigt som den byter färg från blå till grön.

2. Analysera videon

Först konverterar vi videon till base64-format så att den kan skickas till vår lokala vLLM-server.

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}"Drivs av

Nu använder vi System One API för att ställa 2 frågor till D3 Mini: i vilken riktning rutan rör sig och om den byter färg.

%%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%}")Drivs av

Utdata:

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

D3 Mini identifierar korrekt rörelsen som höger och tilldelar 93,7 % sannolikhet för färgändring, och slutför analysen på bara 723 millisekunder.

Avslutande tankar

D3 Mini hanterar klassificering, ja/nej-kontroller och poängsättning över text, bilder och video på en enda NVIDIA RTX 3090-GPU. Att sätta upp D3 lokalt var förvånansvärt enkelt. Det enda problem jag stötte på var ett CUDA out-of-memory-fel, vilket jag åtgärdade genom att minska GPU-minnesförbrukningen.

I övrigt fungerade allt smidigt. Om du redan är bekant med vLLM kan du troligen optimera uppsättningen ännu mer.

Det som imponerade mest var hastigheten. Väggtidsspannen låg från 87 millisekunder för ett kort textbeslut till 1,11 sekunder för en hel artikel, och videoexemplet blev klart på 723 millisekunder. Allt kördes på mitt eget GPU-kort.

Jag tror att vi närmar oss en punkt där det blir praktiskt att köra beslutsmodeller på en lokal server för ett helt team. Inte varje förfrågan behöver en stor resonemangsmodell.

För många vardagliga uppgifter, som klassificering, routing, poängsättning och innehållsfiltrering, kan en mindre beslutsmodell göra jobbet. Du kan sedan reservera dyra resonemangsmodeller för de uppgifter som faktiskt kräver djupare analys eller detaljerade förklaringar.

Naturligtvis vill du fortfarande utvärdera noggrannhet och prestanda på dina egna arbetsbelastningar innan du använder dessa modeller i produktion. Efter att ha testat D3 över text, bilder och video är min tumregel enkel: om uppgiften är en klassificering, en ja/nej-kontroll eller en betygsättning, prova en D3-modell först och gå över till en resonemangsmodell först när du behöver en förklaring.

Om du vill lära dig mer om att arbeta med öppna modeller rekommenderar jag vår kurs Working with Hugging Face.