Tutorial vLLM D3: rode modelos de decisão de IA localmente com Python

D3 é uma família de modelos de decisão open-weight que retornam uma probabilidade para cada resposta em vez de gerar texto. Você pode classificar um ticket de suporte, pontuar um artigo ou avaliar um clipe de vídeo com uma única chamada para um modelo rodando na sua própria máquina — em apenas 87 milissegundos nos nossos testes.

A família inclui 6 modelos, de 600 milhões a 27 bilhões de parâmetros. Você pode experimentar os menores em hardware modesto e usar os maiores para tarefas mais exigentes. O D3 Edge é tão leve que chega a rodar em smartphones compatíveis.

O vLLM oferece suporte ao D3 por meio do framework Structured Decisions, permitindo servir um modelo localmente e chamá-lo via uma interface de programação de aplicações (API) simples. O projeto mais amplo vLLM Semantic Router adiciona recursos de roteamento e tomada de decisão para aplicações de IA.

Neste tutorial, vou mostrar como configurar o D3 localmente, os 3 tipos de decisão e suas primeiras previsões. Depois, vamos construir 3 projetos práticos:

1. Analisador de qualidade de blog com IA: use o SDK TypeSafe para Python e o Olostep para classificar e avaliar artigos reais.
2. Entendimento de imagens: analise fotos de produtos, identifique categorias e avalie a qualidade das imagens.
3. Entendimento de vídeos: analise vídeos curtos para detectar movimento e mudanças visuais.

Ao final, você vai saber como rodar o D3 localmente e usá-lo para criar aplicações que tomam decisões em texto, imagens e vídeo. Você também pode ver nossos guias sobre como rodar LLMs localmente e como acelerar a inferência local em uma GPU RTX 3090.

Em resumo

• D3 é uma família de modelos de decisão open-weight que retornam probabilidades para perguntas de escolha, sim/não (Noul) e pontuação, em vez de gerar texto.
• O D3 Mini (4B) lida com texto, imagens e vídeo e roda em uma única GPU NVIDIA RTX 3090 com vLLM.
• Você serve o modelo com vllm serve e o chama pelo SDK TypeSafe para Python ou pelo endpoint /v1/systemone.
• Vamos construir 3 projetos: um analisador de qualidade de artigos, um validador de imagens de produto e um analisador de movimento em vídeo.
• As respostas nos nossos testes variaram entre 87 milissegundos e 1,11 segundo.

O que são os modelos de decisão D3?

D3 é uma família de modelos de IA open-weight voltados para tomar decisões, não para gerar texto. Em vez de pedir a um LLM para explicar se uma transação é suspeita, o D3 retorna diretamente a probabilidade de que ela precise de revisão.

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

Ele oferece 3 tipos de decisão:

O D3 tem 6 tamanhos, de 600 milhões a 27 bilhões de parâmetros, atendendo desde dispositivos de borda até GPUs de alto desempenho. Você pode explorar a família na coleção Decision 3.0 no Hugging Face.

Os modelos são avaliados em benchmarks focados em decisão, como o Typed Decisions, que medem acurácia de classificação e qualidade das probabilidades.

Para este tutorial, vamos usar o D3 Mini (4B) porque ele oferece entendimento de texto, imagem e vídeo, e ainda é pequeno o suficiente para rodar em uma GPU NVIDIA RTX 3090 local.

Como rodar o D3 localmente com vLLM

O vLLM Semantic Router (vLLM SR) é um projeto open-source do ecossistema vLLM que ajuda aplicações de IA a tomarem decisões inteligentes. Ele oferece roteamento de modelos, checagens de segurança, cache semântico e modelos especializados de decisão como o D3. Enquanto o vLLM cuida da inferência, o vLLM SR foca em como as requisições são avaliadas e roteadas.

Neste tutorial, vamos usar o novo suporte a Structured Decisions do vLLM para rodar o D3 Mini localmente sem instalar o Semantic Router em si. O vLLM serve o D3 por meio da System One API, um endpoint batizado em referência ao pensamento rápido e intuitivo do "Sistema 1". Ele responde perguntas tipadas em uma única passada e retorna probabilidades em vez de texto gerado.

Vamos nos conectar ao modelo usando o SDK TypeSafe para Python e explorar como ele lida com classificação, estimativa de probabilidade e pontuação.

1. Instale o vLLM e rode o D3 localmente

Vamos usar Ubuntu Linux, Python 3.12 e uma GPU NVIDIA RTX 3090. Usuários de Windows podem acompanhar usando Ubuntu via Windows Subsystem for Linux 2 (WSL2).

Primeiro, instale o uv. Quando concluir, reinicie seu terminal para que o comando uv fique disponível.

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

Agora, crie um ambiente Python 3.12 e ative-o:

uv venv --python 3.12 --seed
source .venv/bin/activateTecnologia

Em seguida, instale o nightly build do vLLM, que inclui o novo suporte a Structured Decisions:

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

Agora inicie o modelo D3 Mini com configurações de memória de GPU adequadas para testes locais:

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

No primeiro lançamento, o modelo é baixado do Hugging Face. Assim que carregar, o vLLM expõe a System One API local em http://localhost:8000/v1/systemone.

Mantenha esse terminal aberto. Vamos acessar o modelo a partir de um notebook Jupyter.

2. Conecte-se ao D3 usando o SDK TypeSafe para Python

Em vez de montar requisições HTTP manualmente, vamos usar o SDK TypeSafe para Python para se comunicar com o modelo rodando localmente.

Instale as bibliotecas necessárias:

%pip install typesafe-sdk olostepTecnologia

Importe os 3 tipos de decisão e configure o cliente para se conectar ao nosso servidor vLLM local:

from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

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

Usamos uma chave de API fictícia porque o servidor local não exige uma credencial TypeSafe hospedada.

3. Faça sua primeira decisão com IA

Comecemos com um exemplo simples de detecção de fraude. Vamos fornecer ao D3 uma transação incomum e perguntar se ela deve ser sinalizada para revisão.

%%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)Tecnologia

Saída:

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

O D3 retorna uma probabilidade de aproximadamente 99,9%, indicando que a transação deve ser sinalizada para revisão. A inferência levou cerca de 87 milissegundos.

Também podemos combinar os 3 tipos de decisão em uma única requisição. Desta vez, vamos avaliar um candidato e pedir ao D3 para identificar o melhor cargo, checar suas qualificações e pontuar sua adequação.

%%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)Tecnologia

Saída:

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 msTecnologia

O modelo identifica corretamente Data Scientist como a melhor opção, atribui 94,5% de probabilidade de qualificação e dá uma pontuação de adequação de 1,64 em uma escala de 0 a 2. As 3 decisões foram retornadas em apenas 165 milissegundos.

Agora que temos o D3 rodando localmente, vamos usá-lo para construir 3 aplicações práticas de IA.

Projeto 1: construa um analisador de qualidade de blogs com o D3 Mini

Imagine gerenciar uma publicação técnica em que dezenas de artigos precisam ser revisados antes de publicar. Em vez de ler tudo manualmente, podemos criar um analisador de qualidade com IA que usa o Olostep para extrair o conteúdo do site e o nosso D3 Mini local para classificar e pontuar.

Vamos testar em um artigo real, o nosso tutorial de KTransformers, que eu escrevi.

1. Faça o scrape do nosso tutorial de KTransformers

Primeiro, vamos usar o SDK do Olostep para Python para extrair o conteúdo do artigo em 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])Tecnologia

O Olostep recupera o artigo em Markdown, preservando títulos, texto e exemplos de código para análise.

2. Categorize e avalie o artigo usando o D3

Em seguida, vamos usar Choice para identificar a categoria do artigo e Score para avaliar sua qualidade educacional em uma escala de 5 pontos.

%%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")Tecnologia

Saída:

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

O D3 categoriza corretamente o artigo como IA e atribui uma nota de qualidade 4,6/5, concluindo a análise em aproximadamente 1,11 segundo.

Projeto 2: analise uma imagem de produto com o D3 Mini

Neste projeto, vamos montar um fluxo simples de triagem de imagens de produto para um e-commerce. A ideia é usar o D3 Mini para identificar a categoria do produto, verificar se ele está claramente visível e avaliar a qualidade da imagem antes de entrar no catálogo.

O código a seguir usa diretamente a System One API do vLLM e lê os resultados no campo correto answers.

1. Carregue uma imagem de produto

Primeiro, vamos baixar uma imagem de produto de exemplo, exibi-la no notebook e convertê-la para base64 para enviá-la ao modelo.

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))Tecnologia

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

Isso nos dá uma entrada de imagem pronta para envio que o D3 Mini pode analisar diretamente.

2. Analise a imagem com o D3 Mini

Agora, vamos pedir 3 coisas ao D3 Mini de uma vez: a categoria do produto, se o produto está claramente visível e quão adequada é a imagem para uma loja 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)Tecnologia

Saída:

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 msTecnologia

O modelo identifica o item como footwear, confirma que o produto está claramente visível e atribui uma boa nota de qualidade à imagem em apenas 282 milissegundos.

Projeto 3: construa um analisador de movimento em vídeo com o D3 Mini

No projeto final, vamos criar um analisador simples de movimento em vídeo usando o D3 Mini. Em vez de gerar descrições longas, vamos usar o modelo para entender o que acontece em um clipe curto, identificar a direção do movimento e detectar mudanças visuais. Essa abordagem é útil para monitoramento de vídeo, detecção de eventos e análise automática de conteúdo.

1. Baixe um vídeo de exemplo

Vamos usar o vídeo de exemplo oficial do D3 Mini no Hugging Face. Primeiro, instale a biblioteca necessária:

%pip install huggingface_hubTecnologia

Depois, baixe o vídeo de exemplo para analisarmos localmente.

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"
)Tecnologia

O vídeo mostra um quadrado se movendo da esquerda para a direita enquanto muda de cor de azul para verde.

2. Analise o vídeo

Primeiro, vamos converter o vídeo para base64 para enviá-lo ao nosso servidor vLLM local.

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}"Tecnologia

Agora, vamos usar a System One API para fazer 2 perguntas ao D3 Mini: em que direção o quadrado se move e se ele muda de cor.

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

Saída:

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

O D3 Mini identifica corretamente o movimento como right e atribui 93,7% de probabilidade para a mudança de cor, concluindo a análise em apenas 723 milissegundos.

Considerações finais

O D3 Mini lida com classificação, checagens de sim/não e pontuação em texto, imagens e vídeo em uma única GPU NVIDIA RTX 3090. Configurar o D3 localmente foi surpreendentemente simples. A única questão que tive foi um erro de falta de memória CUDA, que resolvi reduzindo o consumo de memória da GPU.

Fora isso, tudo funcionou muito bem. Se você já está familiarizado com o vLLM, provavelmente consegue otimizar a configuração ainda mais.

O que mais me impressionou foi a velocidade. Os tempos de execução variaram de 87 milissegundos para uma decisão de texto curta a 1,11 segundo para um artigo completo, e o exemplo de vídeo terminou em 723 milissegundos. Tudo rodando na minha própria GPU.

Acho que estamos chegando a um ponto em que rodar modelos de decisão em um servidor local para todo o time está se tornando viável. Nem toda requisição precisa de um modelo de raciocínio grande.

Para muitas tarefas do dia a dia — como classificação, roteamento, pontuação e filtragem de conteúdo — um modelo de decisão menor dá conta do recado. Aí você reserva os modelos de raciocínio mais caros para o que realmente exige análise profunda ou explicações detalhadas.

Claro, ainda é importante avaliar acurácia e desempenho nos seus próprios workloads antes de usar esses modelos em produção. Depois de testar o D3 em texto, imagens e vídeo, minha regra prática é simples: se a tarefa é classificação, checagem de sim/não ou atribuição de nota, comece com um modelo D3 e só parta para um modelo de raciocínio quando precisar de explicação.

Se você quer se aprofundar no trabalho com modelos abertos, recomendo o nosso curso Working with Hugging Face.