vLLM D3 教程：使用 Python 在本地运行 AI 决策模型

D3 是一组开源权重的决策模型家族，它不会生成文本，而是为每个答案返回一个概率。您可以用一条请求对运行在自己机器上的模型进行操作，来分类工单、为文章打分，或检查一段视频片段。在我们的测试中，最快仅需 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（40 亿参数）可处理文本、图像和视频，并可在单块 NVIDIA RTX 3090 图形处理器（GPU）上配合 vLLM 运行。
• 您使用 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）上进行评测，衡量分类准确率与概率质量。

在本教程中，我们将使用D3 Mini（40 亿），因为它支持文本、图像和视频理解，同时足够小，可在本地的 NVIDIA RTX 3090 GPU 上运行。

如何使用 vLLM 在本地运行 D3

vLLM Semantic Router（vLLM SR）是 vLLM 生态中的一个开源项目，帮助 AI 应用做出智能决策。它支持模型路由、安全检查、语义缓存以及像 D3 这样的专业决策模型。vLLM 负责模型推理，而 vLLM SR 关注如何评估与路由请求。

在本教程中，我们将使用vLLM 新增的 Structured Decisions 支持在本地运行 D3 Mini，而无需安装 Semantic Router 本身。vLLM 通过 System One API 来提供 D3 服务，该端点以快速、直觉的“系统 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技术支持

接着，安装 vLLM 的 nightly 版本，其中包含新的 Structured Decisions 支持：

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 会在 http://localhost:8000/v1/systemone 暴露本地 System One API。

让该终端保持运行。我们将通过 Jupyter 笔记本访问该模型。

2. 使用 TypeSafe Python SDK 连接 D3

我们将使用 TypeSafe Python SDK 与本地运行的模型通信，而不是手动构造 HTTP 请求。

安装所需库：

%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"
)技术支持

我们使用占位的 API 密钥，因为本地服务器不需要托管的 TypeSafe 凭据。

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 种决策类型。这一次，我们将评估一名候选人，让 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技术支持

模型正确识别出最匹配岗位为数据科学家，给出 94.5% 的胜任概率，并在 0 到 2 的刻度上给出 1.64 的匹配分。3 个决策总计仅用时 165 毫秒。

既然我们已经在本地成功运行 D3，接下来用它来构建 3 个实用的 AI 应用。

项目一：使用 D3 Mini 构建 AI 博客质量分析器

设想您要管理一个技术出版物，在发布前需要审阅数十篇文章。我们可以构建一个 AI 质量分析器，使用 Olostep 抽取网页内容，并用本地运行的 D3 Mini 模型进行分类和打分，而无需逐篇通读。

我们将在一篇真实文章上测试：我们的 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 秒完成。

项目二：使用 D3 Mini 分析产品图片

在本项目中，我们将为一家电商构建一个简单的产品图片筛查流程。目标是使用 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 三个问题：产品属于哪个类别、是否清晰可见，以及该图片是否适合用于网店。

%%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 毫秒内给出不错的质量评分。

项目三：使用 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. 分析视频

首先，我们将把视频转换为 base64 格式，以便发送到本地 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}"技术支持

现在，我们将使用 System One API 向 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 正确识别出运动方向为右，并为颜色变化给出93.7% 的概率，整个分析仅用时 723 毫秒。

总结

D3 Mini 能在单块 NVIDIA RTX 3090 GPU 上跨文本、图像和视频完成分类、是/否检查与评分。将 D3 本地化部署出乎意料地简单。我遇到的唯一问题是 CUDA 内存不足，通过降低 GPU 内存占用便解决了。

除此之外，一切运行顺畅。如果您已经熟悉 vLLM，可能还能进一步优化设置。

最令我印象深刻的是速度。壁钟时间从短文本决策的 87 毫秒到整篇文章的 1.11 秒不等，视频示例在 723 毫秒内完成。全部都运行在我的自有 GPU 上。

我认为我们正逐步迈向这样一个阶段：在本地服务器上为整个团队运行决策模型变得切实可行。并非每个请求都需要大型推理模型。

对于许多日常任务，如分类、路由、评分和内容过滤，小型决策模型就能胜任。然后您可以将昂贵的推理模型保留给那些确实需要更深入分析或详细解释的任务。

当然，在用于生产之前，您仍应在自身工作负载上评估准确性和性能。在对 D3 横跨文本、图像与视频进行测试后，我的经验法则很简单：如果任务是分类、是/否检查或评级，先试试 D3 模型；只有当您需要解释时，再转向推理模型。

如果您希望进一步了解如何使用开源模型，推荐查看我们的课程：Working with Hugging Face。