Учебник по vLLM D3: запускаем модели принятия решений локально на Python

D3 — это семейство моделей принятия решений с открытыми весами, которые возвращают вероятность для каждого ответа вместо генерации текста. Вы можете классифицировать тикет в поддержку, оценивать статью или проверять видеоклип одним запросом к модели, запущенной на вашем компьютере, — в наших тестах это занимало всего 87 миллисекунд.

В семействе 6 моделей — от 600 миллионов до 27 миллиардов параметров. С небольшими моделями можно экспериментировать на скромном «железе», а более крупные использовать для требовательных задач. D3 Edge настолько легковесна, что может работать даже на совместимых смартфонах.

vLLM поддерживает D3 через фреймворк Structured Decisions, поэтому вы можете обслуживать модель локально и вызывать её через простой программный интерфейс (API). Более широкий проект vLLM Semantic Router добавляет функции маршрутизации и принятия решений для ИИ-приложений.

В этом руководстве мы разберём локальную установку D3, 3 типа решений и первые предсказания. Затем создадим 3 практических проекта:

1. Анализатор качества ИИ‑статей: используем Python SDK TypeSafe и Olostep для классификации и оценки реальных материалов.
2. Понимание изображений: анализируем товарные изображения, определяем категории и оцениваем качество.
3. Понимание видео: анализируем короткие ролики для обнаружения движения и визуальных изменений.

К концу вы узнаете, как запускать D3 локально и использовать её для приложений, принимающих решения по текстам, изображениям и видео. Также смотрите наши руководства по локальному запуску больших языковых моделей и ускорению локального вывода на видеокарте RTX 3090.

Коротко

• D3 — это семейство моделей принятия решений с открытыми весами, которые возвращают вероятности для вопросов типа выбор, да/нет (Noul) и оценка вместо генерации текста.
• D3 Mini (4B) работает с текстом, изображениями и видео и запускается на одной видеокарте NVIDIA RTX 3090 с vLLM.
• Вы обслуживаете модель через vllm serve и обращаетесь к ней через Python SDK TypeSafe или эндпоинт /v1/systemone.
• Мы создадим 3 проекта: анализатор качества статей, проверку товарных изображений и анализатор движения на видео.
• Ответы в наших тестах занимали от 87 мс до 1,11 с.

Что такое модели принятия решений D3?

D3 — семейство ИИ‑моделей с открытыми весами, предназначенных для принятия решений, а не генерации текста. Вместо того чтобы просить большую языковую модель (LLM) объяснить, подозрительна ли транзакция, D3 может напрямую вернуть вероятность того, что её нужно проверить.

Источник: vllm-sr/d3-mini · Hugging Face

Поддерживаются 3 типа решений:

D3 выпускается в 6 размерах — от 600 миллионов до 27 миллиардов параметров — для устройств «на краю» и до топовых видеокарт. Смотрите семейство в коллекции Decision 3.0 на Hugging Face.

Модели оцениваются на бенчмарках, ориентированных на решения, таких как Typed Decisions, где измеряются точность классификации и качество вероятностей.

В этом руководстве мы используем D3 Mini (4B), потому что она поддерживает понимание текста, изображений и видео и при этом достаточно мала, чтобы запускаться локально на NVIDIA RTX 3090.

Как запустить D3 локально с vLLM

vLLM Semantic Router (vLLM SR) — это проект с открытым исходным кодом в экосистеме vLLM, который помогает ИИ‑приложениям принимать осмысленные решения. Он поддерживает маршрутизацию моделей, проверки безопасности, семантический кэш и специализированные модели решений, такие как D3. Пока vLLM занимается выводом модели, vLLM SR фокусируется на том, как запросы оцениваются и маршрутизируются.

В этом руководстве мы воспользуемся новой поддержкой Structured Decisions в vLLM, чтобы запустить D3 Mini локально без установки самого Semantic Router. vLLM обслуживает D3 через API System One — эндпоинт, названный в честь быстрого, интуитивного «Системы 1» мышления. Он отвечает на типизированные вопросы за один проход и возвращает вероятности вместо сгенерированного текста.

Мы подключимся к модели через Python SDK TypeSafe и посмотрим, как она справляется с классификацией, оценкой вероятностей и выставлением баллов.

1. Установите vLLM и запустите D3 локально

Мы будем использовать Ubuntu Linux, Python 3.12 и видеокарту NVIDIA RTX 3090. Пользователи Windows могут повторить шаги в Ubuntu через Windows Subsystem for Linux 2 (WSL2).

Сначала установите 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, в которую входит новая поддержка Structured Decisions:

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightlyРаботает на

Теперь запустите модель D3 Mini с настройками использования памяти GPU, подходящими для локального тестирования:

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eagerРаботает на

При первом запуске модель скачивается с Hugging Face. После загрузки vLLM открывает локальный API System One по адресу http://localhost:8000/v1/systemone.

Оставьте этот терминал открытым. Мы обратимся к модели из ноутбука Jupyter.

2. Подключитесь к D3 через Python SDK TypeSafe

Вместо ручной сборки HTTP‑запросов мы будем использовать Python SDK TypeSafe для общения с локально запущенной моделью.

Установите необходимые библиотеки:

%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. Сделайте своё первое ИИ‑решение

Начнём с простого примера обнаружения мошенничества. Передадим 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Работает на

Модель корректно определяет Data Scientist как наилучшее соответствие, присваивает 94,5% вероятности соответствия требованиям и даёт оценку пригодности 1,64 по шкале от 0 до 2. Все 3 решения вернулись всего за 165 миллисекунд.

Теперь, когда D3 работает локально, используем её для создания 3 практических ИИ‑приложений.

Проект 1: создаём анализатор качества ИИ‑статей на D3 Mini

Представьте, что вы управляете техническим изданием, где десятки статей нужно проверить перед публикацией. Вместо ручного чтения каждой мы можем создать анализатор качества на ИИ: он будет использовать 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 корректно относит статью к ИИ и присваивает ей оценку качества 4,6/5, выполнив анализ примерно за 1,11 секунды.

Проект 2: анализ товарного изображения с D3 Mini

В этом проекте мы построим простой процесс проверки товарных изображений для интернет‑магазина. Цель — с помощью D3 Mini определить категорию товара, убедиться, что товар хорошо виден, и оценить качество изображения перед добавлением в каталог.

Следующий код использует напрямую API vLLM System One и читает результаты из правильного поля 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. Скачайте пример видео

Мы используем официальное примерное видео D3 Mini с Hugging Face. Сначала установим нужную библиотеку:

%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}"Работает на

Теперь используем API System One и зададим D3 Mini 2 вопроса: в каком направлении движется квадрат и меняет ли он цвет.

%%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. Настроить D3 локально оказалось удивительно просто. Единственная проблема — ошибка «CUDA: недостаточно памяти», которую удалось решить снижением потребления памяти GPU.

В остальном всё работало без сбоев. Если вы уже знакомы с vLLM, вероятно, сможете оптимизировать настройку ещё сильнее.

Больше всего впечатлила скорость. «Стенные» времена варьировались от 87 миллисекунд для короткого текстового решения до 1,11 секунды для целой статьи, а пример с видео завершился за 723 миллисекунды. И всё это на собственной видеокарте.

Похоже, мы приближаемся к моменту, когда запуск моделей принятия решений на локальном сервере для всей команды становится практичным. Не каждый запрос требует большой рассуждающей модели.

Для многих повседневных задач — таких как классификация, маршрутизация, оценивание и фильтрация контента — справится меньшая модель решений. Дорогие рассуждающие модели можно резервировать для задач, которым действительно нужна глубокая аналитика или развёрнутые объяснения.

Разумеется, перед продакшном стоит оценить точность и производительность на собственных нагрузках. После тестов D3 на тексте, изображениях и видео у меня простой ориентир: если задача — классификация, проверка «да/нет» или рейтинг, сначала попробуйте модель D3, а к рассуждающей переходите только когда нужно объяснение.

Если хотите глубже разобраться в работе с открытыми моделями, рекомендуем наш курс Working with Hugging Face.