Hướng dẫn vLLM D3: Chạy mô hình ra quyết định AI cục bộ với Python

D3 là một họ mô hình ra quyết định có trọng số mở, trả về xác suất cho mỗi câu trả lời thay vì sinh văn bản. Bạn có thể phân loại thẻ hỗ trợ, chấm điểm một bài viết hoặc kiểm tra một đoạn video chỉ với một yêu cầu gửi đến mô hình chạy trên chính máy của bạn, nhanh chỉ 87 mili-giây trong các thử nghiệm của chúng tôi.

Họ này gồm 6 mô hình, từ 600 triệu đến 27 tỷ tham số. Bạn có thể thử nghiệm các mô hình nhỏ hơn trên phần cứng khiêm tốn và dùng các mô hình lớn hơn cho tác vụ đòi hỏi cao. D3 Edge nhẹ đến mức có thể chạy trên điện thoại thông minh tương thích.

vLLM hỗ trợ D3 thông qua khung Structured Decisions, vì vậy bạn có thể phục vụ mô hình cục bộ và gọi nó qua một giao diện lập trình ứng dụng (API) đơn giản. Dự án vLLM Semantic Router rộng hơn bổ sung các tính năng định tuyến và ra quyết định cho ứng dụng AI.

Trong hướng dẫn này, tôi sẽ trình bày cách thiết lập D3 cục bộ, 3 loại quyết định và dự đoán đầu tiên của bạn. Sau đó, chúng ta sẽ xây dựng 3 dự án thực tiễn:

1. Trình phân tích chất lượng blog AI: Dùng bộ SDK TypeSafe Python và Olostep để phân loại và đánh giá bài viết thực tế.
2. Hiểu hình ảnh: Phân tích ảnh sản phẩm, xác định danh mục và đánh giá chất lượng ảnh.
3. Hiểu video: Phân tích video ngắn để phát hiện chuyển động và thay đổi thị giác.

Kết thúc bài, bạn sẽ biết cách chạy D3 cục bộ và dùng nó để xây dựng ứng dụng đưa ra quyết định trên văn bản, hình ảnh và video. Bạn cũng có thể xem các hướng dẫn về chạy mô hình ngôn ngữ lớn cục bộ và tăng tốc suy luận cục bộ trên GPU RTX 3090.

Tóm tắt nhanh

• D3 là họ mô hình ra quyết định có trọng số mở, trả về xác suất cho câu hỏi lựa chọn, có/không (Noul) và chấm điểm, thay vì sinh văn bản.
• D3 Mini (4B) xử lý văn bản, hình ảnh và video, và chạy trên một GPU NVIDIA RTX 3090 với vLLM.
• Bạn phục vụ mô hình với vllm serve và gọi nó qua SDK TypeSafe Python hoặc endpoint /v1/systemone.
• Chúng ta xây dựng 3 dự án: bộ phân tích chất lượng bài viết, trình sàng lọc ảnh sản phẩm và bộ phân tích chuyển động video.
• Thời gian phản hồi trong thử nghiệm của chúng tôi từ 87 mili-giây đến 1,11 giây.

D3 là mô hình ra quyết định gì?

D3 là họ mô hình AI có trọng số mở, được xây dựng để ra quyết định thay vì sinh văn bản. Thay vì yêu cầu một mô hình ngôn ngữ lớn (LLM) giải thích liệu một giao dịch có đáng ngờ hay không, D3 có thể trả về trực tiếp xác suất rằng nó cần được xem xét.

Nguồn: vllm-sr/d3-mini · Hugging Face

Nó hỗ trợ 3 loại quyết định:

D3 có 6 kích cỡ, từ 600 triệu đến 27 tỷ tham số, phù hợp từ thiết bị biên đến GPU cao cấp. Bạn có thể duyệt cả họ trong bộ sưu tập Decision 3.0 trên Hugging Face.

Các mô hình được đánh giá trên những benchmark tập trung vào quyết định như Typed Decisions, đo độ chính xác phân loại và chất lượng xác suất.

Trong hướng dẫn này, chúng ta sẽ dùng D3 Mini (4B) vì nó hỗ trợ hiểu văn bản, hình ảnh và video, đồng thời đủ nhỏ để chạy trên GPU NVIDIA RTX 3090 cục bộ.

Cách chạy D3 cục bộ với vLLM

vLLM Semantic Router (vLLM SR) là dự án mã nguồn mở trong hệ sinh thái vLLM, giúp ứng dụng AI đưa ra quyết định thông minh. Nó hỗ trợ định tuyến mô hình, kiểm tra an toàn, bộ nhớ đệm ngữ nghĩa và các mô hình quyết định chuyên biệt như D3. Trong khi vLLM xử lý suy luận mô hình, vLLM SR tập trung vào cách đánh giá và định tuyến yêu cầu.

Trong hướng dẫn này, chúng ta sẽ dùng hỗ trợ Structured Decisions mới của vLLM để chạy D3 Mini cục bộ mà không cần cài đặt chính Semantic Router. vLLM phục vụ D3 qua System One API, một endpoint được đặt tên theo lối “tư duy Hệ 1” nhanh, trực giác. Nó trả lời các câu hỏi có kiểu trong một lượt và trả về xác suất thay vì văn bản sinh ra.

Chúng ta sẽ kết nối với mô hình bằng SDK TypeSafe Python và khám phá cách nó xử lý phân loại, ước tính xác suất và chấm điểm.

1. Cài đặt vLLM và chạy D3 cục bộ

Chúng ta sẽ dùng Ubuntu Linux, Python 3.12 và một GPU NVIDIA RTX 3090. Người dùng Windows có thể theo dõi bằng Ubuntu qua Windows Subsystem for Linux 2 (WSL2).

Trước tiên, cài uv. Sau khi cài xong, khởi động lại terminal để lệnh uv khả dụng.

curl -LsSf https://astral.sh/uv/install.sh | shĐược hỗ trợ bởi

Bây giờ, tạo môi trường Python 3.12 và kích hoạt nó:

uv venv --python 3.12 --seed
source .venv/bin/activateĐược hỗ trợ bởi

Tiếp theo, cài bản nightly của vLLM, bao gồm hỗ trợ Structured Decisions mới:

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightlyĐược hỗ trợ bởi

Bây giờ khởi động mô hình D3 Mini với thiết lập bộ nhớ GPU phù hợp cho thử nghiệm cục bộ:

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eagerĐược hỗ trợ bởi

Lần đầu sẽ tải mô hình từ Hugging Face. Khi tải xong, vLLM mở System One API cục bộ tại http://localhost:8000/v1/systemone.

Giữ terminal này chạy. Chúng ta sẽ truy cập mô hình từ Jupyter notebook.

2. Kết nối D3 bằng SDK TypeSafe Python

Thay vì tự xây dựng yêu cầu HTTP, chúng ta sẽ dùng SDK TypeSafe Python để giao tiếp với mô hình chạy cục bộ.

Cài các thư viện cần thiết:

%pip install typesafe-sdk olostepĐược hỗ trợ bởi

Import 3 loại quyết định và cấu hình client để kết nối với máy chủ vLLM cục bộ của chúng ta:

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

client = TypeSafeClient(
    base_url="http://localhost:8000",
    api_key="local",
    model="vllm-sr/d3-mini"
)Được hỗ trợ bởi

Chúng ta dùng khóa API giả vì máy chủ cục bộ không yêu cầu thông tin xác thực TypeSafe được lưu trữ.

3. Thực hiện quyết định AI đầu tiên

Hãy bắt đầu với ví dụ phát hiện gian lận đơn giản. Chúng ta sẽ đưa cho D3 một giao dịch bất thường và hỏi liệu nó có nên được gắn cờ để xem xét hay không.

%%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)Được hỗ trợ bởi

Đầu ra:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msĐược hỗ trợ bởi

D3 trả về xác suất khoảng 99,9%, cho thấy giao dịch nên được gắn cờ để xem xét. Suy luận mất khoảng 87 mili-giây.

Chúng ta cũng có thể kết hợp cả 3 loại quyết định trong một yêu cầu. Lần này, chúng ta sẽ đánh giá một ứng viên và yêu cầu D3 xác định vai trò phù hợp nhất, kiểm tra điều kiện tối thiểu và chấm mức độ phù hợp.

%%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)Được hỗ trợ bởi

Đầu ra:

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 msĐược hỗ trợ bởi

Mô hình xác định đúng Data Scientist là phù hợp nhất, gán xác suất đủ điều kiện 94,5% và điểm phù hợp 1,64 trên thang 0 đến 2. Cả 3 quyết định được trả về chỉ trong 165 mili-giây.

Giờ khi đã chạy D3 cục bộ, hãy dùng nó để xây dựng 3 ứng dụng AI thực tiễn.

Dự án 1: Xây dựng Trình phân tích chất lượng blog AI với D3 Mini

Hãy tưởng tượng bạn quản lý một ấn phẩm kỹ thuật nơi hàng chục bài viết cần duyệt trước khi xuất bản. Thay vì đọc thủ công từng bài, chúng ta có thể xây dựng một bộ phân tích chất lượng AI dùng Olostep để trích xuất nội dung website và mô hình D3 Mini chạy cục bộ để phân loại và chấm điểm.

Chúng ta sẽ thử nghiệm trên một bài viết thực, hướng dẫn KTransformers của chúng tôi, do tôi viết.

1. Thu thập nội dung hướng dẫn KTransformers

Đầu tiên, chúng ta sẽ dùng Olostep Python SDK để trích xuất nội dung bài viết dưới dạng 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])Được hỗ trợ bởi

Olostep truy xuất bài viết ở dạng Markdown, giữ nguyên tiêu đề, văn bản và ví dụ mã để phân tích.

2. Phân loại và chấm điểm bài viết bằng D3

Tiếp theo, chúng ta sẽ dùng Choice để xác định danh mục của bài viết và Score để đánh giá chất lượng giáo dục của nó trên thang 5 điểm.

%%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")Được hỗ trợ bởi

Đầu ra:

Category: ai
Quality: 4.6/5
CPU times: user 3.29 ms, sys: 2.96 ms, total: 6.25 ms
Wall time: 1.11 sĐược hỗ trợ bởi

D3 phân loại đúng bài viết là AI và cho điểm chất lượng 4,6/5, hoàn tất phân tích trong khoảng 1,11 giây.

Dự án 2: Phân tích ảnh sản phẩm với D3 Mini

Trong dự án này, chúng ta sẽ xây dựng quy trình sàng lọc ảnh sản phẩm đơn giản cho cửa hàng thương mại điện tử. Mục tiêu là dùng D3 Mini để xác định danh mục sản phẩm, kiểm tra sản phẩm có hiển thị rõ ràng hay không và chấm chất lượng ảnh trước khi thêm vào danh mục.

Đoạn mã sau dùng trực tiếp vLLM System One API và đọc kết quả từ trường answers đúng.

1. Tải một ảnh sản phẩm

Trước tiên, chúng ta sẽ tải một ảnh sản phẩm mẫu, hiển thị nó trong notebook và chuyển đổi sang base64 để gửi đến mô hình.

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))Được hỗ trợ bởi

image_base64 = base64.b64encode(image_data).decode()
image_input = f"data:image/jpeg;base64,{image_base64}"Được hỗ trợ bởi

Điều này cho chúng ta một đầu vào ảnh sẵn sàng gửi mà D3 Mini có thể phân tích trực tiếp.

2. Phân tích ảnh bằng D3 Mini

Tiếp theo, chúng ta sẽ hỏi D3 Mini 3 điều cùng lúc: sản phẩm thuộc danh mục nào, sản phẩm có hiển thị rõ ràng không và mức độ phù hợp của ảnh cho cửa hàng trực tuyến.

%%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)Được hỗ trợ bởi

Đầu ra:

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 msĐược hỗ trợ bởi

Mô hình xác định mặt hàng là footwear, xác nhận sản phẩm hiển thị rõ ràng và cho điểm chất lượng ảnh khá tốt chỉ trong 282 mili-giây.

Dự án 3: Xây dựng bộ phân tích chuyển động video với D3 Mini

Trong dự án cuối, chúng ta sẽ xây dựng bộ phân tích chuyển động video đơn giản bằng D3 Mini. Thay vì sinh mô tả video dài dòng, chúng ta sẽ dùng mô hình để hiểu điều gì xảy ra trong một đoạn ngắn, xác định hướng di chuyển và phát hiện thay đổi thị giác. Cách tiếp cận này hữu ích cho giám sát video, phát hiện sự kiện và phân tích nội dung tự động.

1. Tải video mẫu

Chúng ta sẽ dùng video mẫu chính thức của D3 Mini từ Hugging Face. Trước tiên, cài thư viện cần thiết:

%pip install huggingface_hubĐược hỗ trợ bởi

Tiếp theo, tải video mẫu để chúng ta có thể phân tích cục bộ.

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"
)Được hỗ trợ bởi

Video cho thấy một ô vuông di chuyển từ trái sang phải đồng thời đổi màu từ xanh dương sang xanh lá.

2. Phân tích video

Đầu tiên, chúng ta sẽ chuyển video sang định dạng base64 để gửi đến máy chủ vLLM cục bộ.

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}"Được hỗ trợ bởi

Bây giờ, chúng ta sẽ dùng System One API để hỏi D3 Mini 2 câu: ô vuông di chuyển theo hướng nào và liệu nó có đổi màu không.

%%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%}")Được hỗ trợ bởi

Đầu ra:

Movement: right
Color Change: 93.7%
CPU times: user 3.01 ms, sys: 5.04 ms, total: 8.05 ms
Wall time: 723 msĐược hỗ trợ bởi

D3 Mini xác định đúng chuyển động là phải và gán 93,7% xác suất cho thay đổi màu, hoàn tất phân tích chỉ trong 723 mili-giây.

Kết luận

D3 Mini xử lý phân loại, kiểm tra có/không và chấm điểm trên văn bản, hình ảnh và video chỉ với một GPU NVIDIA RTX 3090. Thiết lập D3 cục bộ khá dễ dàng. Vấn đề duy nhất tôi gặp là lỗi thiếu bộ nhớ CUDA, tôi đã khắc phục bằng cách giảm mức tiêu thụ bộ nhớ GPU.

Ngoài ra, mọi thứ hoạt động trơn tru. Nếu bạn đã quen với vLLM, có lẽ bạn còn tối ưu thiết lập tốt hơn nữa.

Điều khiến tôi ấn tượng nhất là tốc độ. Thời gian thực dao động từ 87 mili-giây cho quyết định văn bản ngắn đến 1,11 giây cho cả bài viết, và ví dụ video hoàn thành trong 723 mili-giây. Tất cả đều chạy trên GPU của chính tôi.

Tôi nghĩ chúng ta đang đến thời điểm chạy mô hình ra quyết định trên máy chủ cục bộ cho cả một nhóm trở nên khả thi. Không phải yêu cầu nào cũng cần mô hình lập luận lớn.

Với nhiều tác vụ hằng ngày như phân loại, định tuyến, chấm điểm và lọc nội dung, một mô hình ra quyết định nhỏ hơn có thể xử lý tốt. Khi đó, bạn có thể dành các mô hình lập luận đắt đỏ cho tác vụ thực sự cần phân tích sâu hoặc giải thích chi tiết.

Tất nhiên, bạn vẫn nên đánh giá độ chính xác và hiệu năng trên khối lượng công việc của riêng mình trước khi dùng các mô hình này trong sản xuất. Sau khi thử D3 trên văn bản, hình ảnh và video, quy tắc đơn giản của tôi là: nếu tác vụ là phân loại, kiểm tra có/không hoặc chấm điểm, hãy thử mô hình D3 trước, và chỉ chuyển sang mô hình lập luận khi bạn cần lời giải thích.

Nếu bạn muốn tìm hiểu thêm về làm việc với mô hình mở, tôi khuyên bạn xem khóa học Làm việc với Hugging Face của chúng tôi.