Tutorial vLLM D3: Jalankan Model Keputusan AI Secara Lokal dengan Python

D3 adalah keluarga model keputusan open-weight yang mengembalikan probabilitas untuk setiap jawaban alih-alih menghasilkan teks. Anda dapat mengklasifikasikan tiket dukungan, memberi skor pada artikel, atau memeriksa klip video dengan satu permintaan ke model yang berjalan di mesin Anda sendiri, hanya dalam 87 milidetik pada pengujian kami.

Keluarga ini mencakup 6 model, dari 600 juta hingga 27 miliar parameter. Anda dapat bereksperimen dengan model yang lebih kecil pada perangkat keras sederhana dan menggunakan model yang lebih besar untuk tugas yang lebih berat. D3 Edge sangat ringan sehingga bahkan dapat berjalan di ponsel pintar yang kompatibel.

vLLM mendukung D3 melalui kerangka Structured Decisions, sehingga Anda dapat menyajikan model secara lokal dan memanggilnya melalui application programming interface (API) yang sederhana. Proyek vLLM Semantic Router yang lebih luas menambahkan fitur perutean dan pengambilan keputusan untuk aplikasi AI.

Dalam tutorial ini, saya akan membahas penyiapan D3 secara lokal, 3 jenis keputusan, dan prediksi pertama Anda. Lalu, kita akan membangun 3 proyek praktis:

1. AI Blog Quality Analyzer: Gunakan software development kit (SDK) TypeSafe Python dan Olostep untuk mengklasifikasikan dan mengevaluasi artikel nyata.
2. Pemahaman Gambar: Analisis gambar produk, identifikasi kategori, dan evaluasi kualitas gambar.
3. Pemahaman Video: Analisis video pendek untuk mendeteksi pergerakan dan perubahan visual.

Pada akhirnya, Anda akan tahu cara menjalankan D3 secara lokal dan menggunakannya untuk membangun aplikasi yang mengambil keputusan pada teks, gambar, dan video. Anda juga dapat melihat panduan kami tentang menjalankan large language model secara lokal dan mempercepat inferensi lokal pada GPU RTX 3090.

Intinya

• D3 adalah keluarga model keputusan open-weight yang mengembalikan probabilitas untuk pertanyaan pilihan, ya/tidak (Noul), dan skor alih-alih menghasilkan teks.
• D3 Mini (4B) menangani teks, gambar, dan video, serta berjalan pada satu unit pemrosesan grafis (GPU) NVIDIA RTX 3090 dengan vLLM.
• Anda menyajikan model dengan vllm serve dan memanggilnya melalui TypeSafe Python SDK atau endpoint /v1/systemone.
• Kami membangun 3 proyek: penganalisis kualitas artikel, penyaring gambar produk, dan penganalisis pergerakan video.
• Respons pada pengujian kami berkisar antara 87 milidetik hingga 1,11 detik.

Apa Itu Model Keputusan D3?

D3 adalah keluarga model AI open-weight yang dibuat untuk mengambil keputusan alih-alih menghasilkan teks. Alih-alih meminta large language model (LLM) menjelaskan apakah suatu transaksi mencurigakan, D3 dapat langsung mengembalikan probabilitas bahwa transaksi tersebut perlu ditinjau.

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

Model ini mendukung 3 jenis keputusan:

D3 hadir dalam 6 ukuran, dari 600 juta hingga 27 miliar parameter, cocok untuk semuanya mulai dari perangkat edge hingga GPU kelas atas. Anda dapat menelusuri keluarga ini di koleksi Decision 3.0 di Hugging Face.

Model-model ini dievaluasi pada tolok ukur berfokus keputusan seperti Typed Decisions, yang mengukur akurasi klasifikasi dan kualitas probabilitas.

Untuk tutorial ini, kita akan menggunakan D3 Mini (4B) karena mendukung pemahaman teks, gambar, dan video, sekaligus cukup kecil untuk dijalankan pada GPU NVIDIA RTX 3090 lokal.

Cara Menjalankan D3 Secara Lokal Dengan vLLM

vLLM Semantic Router (vLLM SR) adalah proyek open-source dalam ekosistem vLLM yang membantu aplikasi AI membuat keputusan cerdas. Ia mendukung perutean model, pemeriksaan keamanan, cache semantik, dan model keputusan khusus seperti D3. Sementara vLLM menangani inferensi model, vLLM SR berfokus pada bagaimana permintaan dievaluasi dan dirutekan.

Dalam tutorial ini, kita akan menggunakan dukungan Structured Decisions baru dari vLLM untuk menjalankan D3 Mini secara lokal tanpa menginstal Semantic Router itu sendiri. vLLM menyajikan D3 melalui System One API, sebuah endpoint yang dinamai dari pemikiran "System 1" yang cepat dan intuitif. Ia menjawab pertanyaan bertipe dalam satu kali proses dan mengembalikan probabilitas alih-alih teks yang dihasilkan.

Kita akan terhubung ke model menggunakan TypeSafe Python SDK dan mengeksplorasi bagaimana ia menangani klasifikasi, estimasi probabilitas, dan pemberian skor.

1. Instal vLLM dan jalankan D3 secara lokal

Kita akan menggunakan Ubuntu Linux, Python 3.12, dan GPU NVIDIA RTX 3090. Pengguna Windows dapat mengikuti menggunakan Ubuntu melalui Windows Subsystem for Linux 2 (WSL2).

Pertama, instal uv. Setelah instalasi selesai, mulai ulang terminal Anda agar perintah uv tersedia.

curl -LsSf https://astral.sh/uv/install.sh | shDidukung oleh

Sekarang, buat lingkungan Python 3.12 dan aktifkan:

uv venv --python 3.12 --seed
source .venv/bin/activateDidukung oleh

Berikutnya, instal rilis nightly vLLM, yang menyertakan dukungan Structured Decisions baru:

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

Sekarang mulai model D3 Mini dengan pengaturan memori GPU yang cocok untuk pengujian lokal:

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

Peluncuran pertama mengunduh model dari Hugging Face. Setelah dimuat, vLLM mengekspose System One API lokal di http://localhost:8000/v1/systemone.

Biarkan terminal ini tetap berjalan. Kita akan mengakses model dari notebook Jupyter.

2. Sambungkan ke D3 menggunakan TypeSafe Python SDK

Alih-alih membangun permintaan HTTP secara manual, kita akan menggunakan TypeSafe Python SDK untuk berkomunikasi dengan model yang berjalan secara lokal.

Instal pustaka yang diperlukan:

%pip install typesafe-sdk olostepDidukung oleh

Impor 3 jenis keputusan dan konfigurasikan klien untuk terhubung ke server vLLM lokal kita:

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

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

Kita menggunakan API key placeholder karena server lokal tidak memerlukan kredensial TypeSafe yang dihosting.

3. Buat keputusan AI pertama Anda

Mari mulai dengan contoh deteksi penipuan sederhana. Kita akan memberikan D3 sebuah transaksi yang tidak biasa dan menanyakan apakah transaksi tersebut harus ditandai untuk ditinjau.

%%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)Didukung oleh

Keluaran:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msDidukung oleh

D3 mengembalikan probabilitas sekitar 99,9%, mengindikasikan bahwa transaksi harus ditandai untuk ditinjau. Inferensi memakan waktu sekitar 87 milidetik.

Kita juga dapat menggabungkan ketiga jenis keputusan dalam satu permintaan. Kali ini, kita akan mengevaluasi kandidat pekerjaan dan meminta D3 untuk mengidentifikasi peran terbaik, memeriksa kualifikasi, dan memberi skor kecocokan.

%%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)Didukung oleh

Keluaran:

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 msDidukung oleh

Model dengan benar mengidentifikasi Data Scientist sebagai kecocokan terbaik, memberikan probabilitas kualifikasi 94,5%, dan skor kecocokan 1,64 pada skala 0 hingga 2. Ketiga keputusan dikembalikan hanya dalam 165 milidetik.

Sekarang kita telah menjalankan D3 secara lokal, mari gunakan untuk membangun 3 aplikasi AI yang praktis.

Proyek 1: Bangun AI Blog Quality Analyzer Dengan D3 Mini

Bayangkan Anda mengelola publikasi teknis di mana puluhan artikel harus ditinjau sebelum diterbitkan. Alih-alih membaca setiap artikel secara manual, kita dapat membangun penganalisis kualitas AI yang menggunakan Olostep untuk mengekstrak konten situs web dan model D3 Mini yang berjalan lokal untuk mengklasifikasikan dan memberi skor.

Kita akan mengujinya pada artikel nyata, tutorial KTransformers kami, yang saya tulis.

1. Scrape tutorial KTransformers kami

Pertama, kita akan menggunakan Olostep Python SDK untuk mengekstrak konten artikel sebagai 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])Didukung oleh

Olostep mengambil artikel sebagai Markdown, mempertahankan judul, teks, dan contoh kode untuk dianalisis.

2. Kategorikan dan nilai artikel menggunakan D3

Berikutnya, kita akan menggunakan Choice untuk mengidentifikasi kategori artikel dan Score untuk mengevaluasi kualitas edukatifnya pada skala 5 poin.

%%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")Didukung oleh

Keluaran:

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

D3 dengan benar mengategorikan artikel sebagai AI dan memberinya skor kualitas 4,6/5, menyelesaikan analisis dalam sekitar 1,11 detik.

Proyek 2: Analisis Gambar Produk Dengan D3 Mini

Pada proyek ini, kita akan membangun alur penyaringan gambar produk sederhana untuk toko e-commerce. Tujuannya adalah menggunakan D3 Mini untuk mengidentifikasi kategori produk, memeriksa apakah produk terlihat jelas, dan menilai kualitas gambar sebelum ditambahkan ke katalog.

Kode berikut menggunakan langsung System One API vLLM dan membaca hasil dari bidang answers yang benar.

1. Muat gambar produk

Pertama, kita akan mengunduh sampel gambar produk, menampilkannya di notebook, dan mengonversinya ke base64 sehingga dapat dikirim ke model.

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))Didukung oleh

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

Ini memberi kita input gambar siap kirim yang dapat langsung dianalisis oleh D3 Mini.

2. Analisis gambar menggunakan D3 Mini

Berikutnya, kita akan menanyakan 3 hal sekaligus kepada D3 Mini: kategori produk, apakah produk terlihat jelas, dan seberapa cocok gambar tersebut untuk toko 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)Didukung oleh

Keluaran:

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 msDidukung oleh

Model mengidentifikasi item sebagai footwear, mengonfirmasi bahwa produk terlihat jelas, dan memberikan skor kualitas gambar yang solid hanya dalam 282 milidetik.

Proyek 3: Bangun Video Motion Analyzer Dengan D3 Mini

Pada proyek terakhir, kita akan membangun penganalisis pergerakan video sederhana menggunakan D3 Mini. Alih-alih menghasilkan deskripsi video yang panjang, kita akan menggunakan model untuk memahami apa yang terjadi dalam klip pendek, mengidentifikasi arah pergerakan, dan mendeteksi perubahan visual. Pendekatan ini berguna untuk pemantauan video, deteksi kejadian, dan analisis konten otomatis.

1. Unduh video sampel

Kita akan menggunakan video sampel resmi D3 Mini dari Hugging Face. Pertama, instal pustaka yang diperlukan:

%pip install huggingface_hubDidukung oleh

Berikutnya, unduh video sampel sehingga kita dapat menganalisisnya secara lokal.

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"
)Didukung oleh

Video tersebut menampilkan sebuah kotak bergerak dari kiri ke kanan sambil berubah warna dari biru menjadi hijau.

2. Analisis video

Pertama, kita akan mengonversi video ke format base64 sehingga dapat dikirim ke server vLLM lokal kita.

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}"Didukung oleh

Sekarang, kita akan menggunakan System One API untuk menanyakan 2 hal kepada D3 Mini: arah gerak kotak dan apakah warnanya berubah.

%%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%}")Didukung oleh

Keluaran:

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

D3 Mini dengan benar mengidentifikasi pergerakan sebagai right dan memberikan probabilitas 93,7% untuk perubahan warna, menyelesaikan analisis hanya dalam 723 milidetik.

Pemikiran Akhir

D3 Mini menangani klasifikasi, pemeriksaan ya/tidak, dan pemberian skor pada teks, gambar, dan video hanya dengan satu GPU NVIDIA RTX 3090. Menyiapkan D3 secara lokal ternyata cukup mudah. Satu-satunya masalah yang saya temui adalah kesalahan kehabisan memori CUDA, yang saya perbaiki dengan mengurangi konsumsi memori GPU.

Selain itu, semuanya berjalan mulus. Jika Anda sudah terbiasa dengan vLLM, Anda mungkin bisa mengoptimalkan penyiapan lebih jauh lagi.

Yang paling mengesankan bagi saya adalah kecepatannya. Wall time berkisar dari 87 milidetik untuk keputusan teks pendek hingga 1,11 detik untuk artikel lengkap, dan contoh video selesai dalam 723 milidetik. Semuanya berjalan di GPU saya sendiri.

Menurut saya, kita sedang mencapai titik di mana menjalankan model keputusan pada server lokal untuk seluruh tim menjadi praktis. Tidak setiap permintaan membutuhkan model penalaran besar.

Untuk banyak tugas sehari-hari, seperti klasifikasi, perutean, pemberian skor, dan penyaringan konten, model keputusan yang lebih kecil sudah dapat mengerjakan tugasnya. Anda kemudian dapat menyisihkan model penalaran yang mahal untuk tugas yang benar-benar memerlukan analisis lebih dalam atau penjelasan terperinci.

Tentu saja, Anda tetap perlu mengevaluasi akurasi dan kinerja pada beban kerja Anda sendiri sebelum menggunakan model ini di produksi. Setelah menguji D3 pada teks, gambar, dan video, aturan praktis saya sederhana: jika tugasnya klasifikasi, pemeriksaan ya/tidak, atau penilaian, coba model D3 terlebih dahulu, dan beralih ke model penalaran hanya ketika Anda memerlukan penjelasan.

Jika Anda tertarik mempelajari lebih lanjut tentang bekerja dengan model open-source, saya sarankan melihat kursus Working with Hugging Face kami.