vLLM D3チュートリアル：PythonでAI意思決定モデルをローカル実行

D3は、テキストを生成するのではなく、各回答に対する確率を返すオープンウェイトの意思決定モデル群です。サポートチケットの分類、記事の採点、動画クリップの確認などを、自分のマシン上で動くモデルに1回のリクエストで実行できます。私たちのテストでは最短87ミリ秒でした。

このファミリーは6つのモデルからなり、パラメータ数は6億から270億まで幅広く用意されています。小型モデルは手頃なハードウェアで試すことができ、大型モデルは高負荷なタスクに使えます。D3 Edgeは非常に軽量で、対応するスマートフォンでも動作します。

vLLMはStructured Decisionsフレームワークを通じてD3をサポートしており、ローカルでモデルを提供し、シンプルなアプリケーション・プログラミング・インターフェイス（API）経由で呼び出せます。より広範なvLLM Semantic Routerプロジェクトは、AIアプリケーション向けのルーティングや意思決定機能を追加します。

このチュートリアルでは、ローカルでのD3セットアップ、3つの意思決定タイプ、最初の予測までを解説します。その後、次の3つの実用プロジェクトを作ります。

1. AIブログ品質アナライザー： TypeSafe Pythonソフトウェア開発キット（SDK）とOlostepを使い、実際の記事を分類・評価します。
2. 画像理解： 商品画像を分析し、カテゴリの特定と画質の評価を行います。
3. 動画理解： 短い動画を分析して動きと視覚的な変化を検出します。

最後まで読むと、D3をローカルで動かし、テキスト・画像・動画にまたがる意思決定を行うアプリケーションを作る方法が分かります。あわせて、大規模言語モデルをローカルで実行する方法や、RTX 3090 GPUでローカル推論を高速化する方法のガイドも参照してください。

要点まとめ

• D3は、テキスト生成の代わりに、選択・はい/いいえ（Noul）・スコアの各質問に対する確率を返すオープンウェイトの意思決定モデル群です。
• D3 Mini（4B）はテキスト・画像・動画に対応し、vLLMで単一のNVIDIA RTX 3090グラフィックス・プロセッシング・ユニット（GPU）上で動作します。
• vllm serveでモデルを提供し、TypeSafe Python SDKまたは/v1/systemoneエンドポイントから呼び出します。
• 3つのプロジェクトを作成します：記事品質アナライザー、商品画像スクリーナー、動画モーションアナライザー。
• テストにおける応答時間は87ミリ秒から1.11秒の範囲でした。

D3意思決定モデルとは？

D3は、テキスト生成ではなく意思決定のために構築されたオープンウェイトのAIモデル群です。例えば、不審な取引かどうかを大規模言語モデル（LLM）に説明させる代わりに、D3はレビューが必要かどうかの確率を直接返せます。

出典：vllm-sr/d3-mini · Hugging Face

対応する意思決定タイプは3つです。

D3は6つのサイズがあり、パラメータ数は6億から270億まで。エッジデバイスからハイエンドGPUまで幅広い用途に対応します。ファミリーはHugging FaceのDecision 3.0コレクションで確認できます。

モデルはTyped Decisionsのような意思決定に特化したベンチマークで評価され、分類精度や確率の品質を測定します。

本チュートリアルでは、テキスト・画像・動画を扱え、ローカルのNVIDIA RTX 3090 GPUで動かせる十分な小ささを保つD3 Mini（4B）を使用します。

vLLMでD3をローカル実行する方法

vLLM Semantic Router（vLLM SR）は、vLLMエコシステムのオープンソースプロジェクトで、AIアプリケーションが賢く意思決定できるよう支援します。モデルのルーティング、安全性チェック、セマンティックキャッシング、D3のような意思決定に特化したモデルをサポートします。vLLMがモデル推論を担当し、vLLM SRはリクエストの評価とルーティングに焦点を当てます。

このチュートリアルでは、vLLMの新しいStructured Decisionsサポートを使い、Semantic Router自体をインストールせずにD3 Miniをローカル実行します。vLLMはD3をSystem One API経由で提供します。これは直感的な「システム1」思考にちなんで名付けられたエンドポイントで、型付きの質問に1パスで答え、生成テキストの代わりに確率を返します。

TypeSafe Python SDKを使ってモデルに接続し、分類、確率推定、スコアリングの扱い方を見ていきます。

1. vLLMをインストールしてD3をローカル実行

Ubuntu Linux、Python 3.12、NVIDIA RTX 3090 GPUを使います。Windowsの方はWindows Subsystem for Linux 2（WSL2）でUbuntuを使って進められます。

まずuvをインストールします。インストール完了後、ターミナルを再起動してuvコマンドを使えるようにしてください。

curl -LsSf https://astral.sh/uv/install.sh | sh提供：

次に、Python 3.12環境を作成して有効化します。

uv venv --python 3.12 --seed
source .venv/bin/activate提供：

続いて、Structured Decisionsの新機能を含むvLLMのナイトリービルドをインストールします。

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightly提供：

ローカルテストに適したGPUメモリ設定でD3 Miniモデルを起動します。

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eager提供：

初回起動時はHugging Faceからモデルをダウンロードします。読み込みが完了すると、vLLMはローカルのSystem One APIをhttp://localhost:8000/v1/systemoneで公開します。

このターミナルは開いたままにしてください。Jupyterノートブックからモデルにアクセスします。

2. TypeSafe Python SDKでD3に接続

HTTPリクエストを手作業で作らずに、TypeSafe Python SDKを使ってローカルで稼働中のモデルと通信します。

必要なライブラリをインストールします。

%pip install typesafe-sdk olostep提供：

3つの意思決定タイプをインポートし、ローカルのvLLMサーバーに接続するようクライアントを設定します。

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

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

ローカルサーバーはホストされたTypeSafeの認証情報を必要としないため、APIキーはプレースホルダーを使っています。

3. 最初のAI意思決定を実行

まずは単純な不正検知の例から始めます。D3に不審な取引を与え、レビュー対象にすべきかどうかを尋ねます。

%%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)提供：

出力：

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 ms提供：

D3は約99.9%の確率を返し、この取引をレビュー対象にすべきだと示しています。推論は約87ミリ秒でした。

3つの意思決定タイプを1回のリクエストで組み合わせることもできます。今回は候補者を評価し、最適な職種の特定、要件の充足可否、適合度のスコアをD3に求めます。

%%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)提供：

出力：

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提供：

モデルは最適な職種としてData Scientistを正しく特定し、適格性を94.5%とし、適合度は0〜2のスケールで1.64を付与しました。3つの判断がわずか165ミリ秒で返ってきます。

ローカルでD3が動いたので、ここから3つの実用AIアプリを作っていきます。

プロジェクト1：D3 MiniでAIブログ品質アナライザーを構築

多数の記事を公開前にレビューする技術メディアを運営しているとします。すべてを手読みする代わりに、Olostepでサイトコンテンツを抽出し、ローカルで動くD3 Miniで分類・採点するAI品質アナライザーを作成します。

テストには、筆者が執筆したKTransformersチュートリアルという実在の記事を使います。

1. KTransformersチュートリアルをスクレイピング

まず、Olostep Python SDKを使って記事内容を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])提供：

Olostepは記事をMarkdownとして取得し、見出し・本文・コード例を分析しやすい形で保持します。

2. D3で記事を分類・評価

続いて、Choiceで記事カテゴリを判定し、Scoreで教育的な質を5段階で評価します。

%%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")提供：

出力：

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提供：

D3は記事をAIカテゴリと正しく分類し、品質スコア4.6/5を付けました。分析は約1.11秒で完了しました。

プロジェクト2：D3 Miniで商品画像を分析

このプロジェクトでは、EC店舗向けの簡単な商品画像スクリーニングを構築します。D3 Miniを使って、商品のカテゴリ特定、商品が明確に見えているかの確認、カタログ掲載に適した画質かどうかの評価を行います。

以下のコードはvLLMのSystem One APIを直接使用し、結果を正しいanswersフィールドから読み取ります。

1. 商品画像を読み込む

まず、サンプルの商品画像をダウンロードしてノートブックに表示し、モデルに送信できるようbase64に変換します。

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))提供：

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

これで、D3 Miniが直接解析できる送信用の画像入力が用意できました。

2. D3 Miniで画像を分析

次に、D3 Miniに対して、商品のカテゴリ、商品が明確に見えているか、オンラインストア向けに適切な画像かを、同時に3点尋ねます。

%%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)提供：

出力：

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提供：

モデルは対象をfootwear（履物）と特定し、商品が明確に見えていることを確認、さらにわずか282ミリ秒で良好な画質スコアを付けました。

プロジェクト3：D3 Miniで動画モーションアナライザーを構築

最後のプロジェクトでは、D3 Miniを使ってシンプルな動画モーションアナライザーを作ります。冗長な動画説明を生成する代わりに、短いクリップで何が起きているかを理解し、動きの方向や視覚的な変化を検出します。これは動画監視、イベント検出、自動コンテンツ分析に有用です。

1. サンプル動画をダウンロード

Hugging Faceの公式D3 Miniサンプル動画を使用します。まず必要なライブラリをインストールします。

%pip install huggingface_hub提供：

次に、サンプル動画をダウンロードしてローカルで分析できるようにします。

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"
)提供：

動画では、四角形が左から右へ動き、青から緑へ色が変わります。

2. 動画を分析

まず、ローカルのvLLMサーバーに送れるよう、動画をbase64形式に変換します。

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}"提供：

次に、System One APIを使い、四角形がどの方向に動くか、色が変わるかの2点をD3 Miniに尋ねます。

%%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%}")提供：

出力：

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

D3 Miniは動きをright（右方向）と正しく判定し、色の変化に93.7%の確率を付与しました。分析はわずか723ミリ秒で完了です。

まとめ

D3 Miniは、単一のNVIDIA RTX 3090 GPU上で、テキスト・画像・動画にわたる分類、はい/いいえチェック、スコアリングをこなします。ローカルでのセットアップは驚くほど簡単でした。唯一遭遇したのはCUDAのメモリ不足エラーで、GPUメモリ消費を下げて解決しました。

それ以外はすべてスムーズです。すでにvLLMに慣れていれば、さらに最適化できるでしょう。

特に印象的だったのは速度です。短いテキストの意思決定で87ミリ秒、記事全体でも1.11秒、動画の例は723ミリ秒でした。すべて自分のGPU上で動いています。

チーム全体向けにローカルサーバーで意思決定モデルを動かすことが現実的になりつつあると感じます。すべてのリクエストに大きな推論モデルは必要ありません。

分類、ルーティング、採点、コンテンツフィルタリングのような日常的なタスクには、小型の意思決定モデルで十分です。そして本当に深い分析や詳細な説明が必要なタスクにだけ、高価な推論モデルを割り当てればよいでしょう。

もちろん、本番利用の前に自分たちのワークロードで精度と性能を評価する必要はあります。D3をテキスト・画像・動画で試した結果、私の経験則はシンプルです。タスクが分類・はい/いいえ判断・レーティングのいずれかなら、まずD3モデルを試し、説明が必要になったときだけ推論モデルに切り替える、というものです。

オープンモデルの活用についてさらに学ぶなら、Working with Hugging Faceコースもおすすめです。