Tutorial de vLLM D3: ejecuta modelos de decisión de IA en local con Python

D3 es una familia de modelos de decisión de pesos abiertos que devuelven una probabilidad para cada respuesta en lugar de generar texto. Puedes clasificar un ticket de soporte, puntuar un artículo o revisar un clip de vídeo con una sola petición a un modelo que se ejecuta en tu propio equipo, en tan solo 87 milisegundos en nuestras pruebas.

La familia incluye 6 modelos, desde 600 millones hasta 27.000 millones de parámetros. Puedes experimentar con los modelos más pequeños en hardware modesto y usar los más grandes para tareas exigentes. D3 Edge es tan ligero que incluso puede ejecutarse en smartphones compatibles.

vLLM es compatible con D3 a través de su framework Structured Decisions, así que puedes servir un modelo en local y llamarlo mediante una sencilla interfaz de programación de aplicaciones (API). El proyecto más amplio vLLM Semantic Router añade funciones de enrutamiento y toma de decisiones para aplicaciones de IA.

En este tutorial, veremos cómo configurar D3 en local, los 3 tipos de decisión y tus primeras predicciones. Después, construiremos 3 proyectos prácticos:

1. Analizador de calidad de blogs con IA: usa el SDK de TypeSafe para Python y Olostep para clasificar y evaluar artículos reales.
2. Comprensión de imágenes: analiza imágenes de producto, identifica categorías y evalúa la calidad de la imagen.
3. Comprensión de vídeo: analiza vídeos cortos para detectar movimiento y cambios visuales.

Al final sabrás ejecutar D3 en local y usarlo para crear aplicaciones que tomen decisiones sobre texto, imágenes y vídeo. También puedes consultar nuestras guías sobre cómo ejecutar LLMs en local y acelerar la inferencia local en una GPU RTX 3090.

En pocas palabras

• D3 es una familia de modelos de decisión de pesos abiertos que devuelven probabilidades para preguntas de tipo elección, sí/no (Noul) y puntuación, en lugar de generar texto.
• D3 Mini (4B) maneja texto, imágenes y vídeo, y se ejecuta con vLLM en una única GPU NVIDIA RTX 3090.
• Sirves el modelo con vllm serve y lo llamas mediante el SDK de TypeSafe para Python o el endpoint /v1/systemone.
• Construimos 3 proyectos: un analizador de calidad de artículos, un filtrador de imágenes de producto y un analizador de movimiento en vídeo.
• En nuestras pruebas, las respuestas tardaron entre 87 milisegundos y 1,11 segundos.

¿Qué son los modelos de decisión D3?

D3 es una familia de modelos de IA de pesos abiertos diseñada para tomar decisiones en lugar de generar texto. En vez de pedir a un LLM que explique si una transacción es sospechosa, D3 puede devolver directamente la probabilidad de que necesite revisión.

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

Admite 3 tipos de decisión:

D3 está disponible en 6 tamaños, de 600 millones a 27.000 millones de parámetros, para cubrir desde dispositivos edge hasta GPUs de gama alta. Puedes explorar la familia en la colección Decision 3.0 en Hugging Face.

Los modelos se evalúan en benchmarks centrados en decisiones como Typed Decisions, que miden la precisión de clasificación y la calidad de las probabilidades.

Para este tutorial, usaremos D3 Mini (4B) porque admite comprensión de texto, imagen y vídeo y es lo bastante compacto como para ejecutarlo en una GPU NVIDIA RTX 3090 en local.

Cómo ejecutar D3 en local con vLLM

vLLM Semantic Router (vLLM SR) es un proyecto de código abierto dentro del ecosistema vLLM que ayuda a las aplicaciones de IA a tomar decisiones inteligentes. Admite enrutamiento de modelos, comprobaciones de seguridad, caché semántica y modelos de decisión especializados como D3. Mientras vLLM se encarga de la inferencia, vLLM SR se centra en cómo se evalúan y enrutan las solicitudes.

En este tutorial usaremos la nueva compatibilidad con Structured Decisions de vLLM para ejecutar D3 Mini en local sin instalar el propio Semantic Router. vLLM sirve D3 mediante la API System One, un endpoint bautizado por el pensamiento rápido e intuitivo "Sistema 1". Responde preguntas tipadas en una sola pasada y devuelve probabilidades en lugar de texto generado.

Nos conectaremos al modelo con el SDK de TypeSafe para Python y veremos cómo gestiona la clasificación, la estimación de probabilidades y la puntuación.

1. Instala vLLM y ejecuta D3 en local

Usaremos Ubuntu Linux, Python 3.12 y una GPU NVIDIA RTX 3090. Si usas Windows, puedes seguir los pasos con Ubuntu a través de Windows Subsystem for Linux 2 (WSL2).

Primero, instala uv. Cuando termine la instalación, reinicia tu terminal para que el comando uv esté disponible.

curl -LsSf https://astral.sh/uv/install.sh | shCon la tecnología de

Ahora crea un entorno de Python 3.12 y actívalo:

uv venv --python 3.12 --seed
source .venv/bin/activateCon la tecnología de

Después, instala la versión nightly de vLLM, que incluye la nueva compatibilidad con Structured Decisions:

uv pip install -U vllm --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightlyCon la tecnología de

Ahora inicia el modelo D3 Mini con ajustes de memoria de GPU adecuados para pruebas locales:

vllm serve vllm-sr/d3-mini \
  --gpu-memory-utilization 0.75 \
  --max-model-len 4096 \
  --max-num-seqs 4 \
  --enforce-eagerCon la tecnología de

En el primer arranque se descarga el modelo desde Hugging Face. Una vez cargado, vLLM expone la API System One local en http://localhost:8000/v1/systemone.

Mantén esta terminal en ejecución. Accederemos al modelo desde un cuaderno de Jupyter.

2. Conéctate a D3 con el SDK de TypeSafe para Python

En lugar de construir peticiones HTTP a mano, usaremos el SDK de TypeSafe para Python para comunicarnos con el modelo que tenemos en local.

Instala las librerías necesarias:

%pip install typesafe-sdk olostepCon la tecnología de

Importa los 3 tipos de decisión y configura el cliente para conectar con nuestro 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"
)Con la tecnología de

Usamos una clave de API ficticia porque el servidor local no requiere credenciales alojadas de TypeSafe.

3. Toma tu primera decisión con IA

Empecemos con un ejemplo sencillo de detección de fraude. Le daremos a D3 una transacción inusual y le preguntaremos si debería marcarse para revisión.

%%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)Con la tecnología de

Salida:

0.9990723773071258
CPU times: user 1.89 ms, sys: 2.01 ms, total: 3.91 ms
Wall time: 87.4 msCon la tecnología de

D3 devuelve una probabilidad de aproximadamente 99,9%, lo que indica que la transacción debería marcarse para revisión. La inferencia tardó unos 87 milisegundos.

También podemos combinar los 3 tipos de decisión en una sola petición. Esta vez evaluaremos a una persona candidata y pediremos a D3 que identifique el mejor puesto, compruebe si cumple los requisitos y puntúe su adecuación.

%%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)Con la tecnología de

Salida:

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 msCon la tecnología de

El modelo identifica correctamente Data Scientist como el mejor encaje, asigna un 94,5% de probabilidad de cumplir los requisitos y da una puntuación de adecuación de 1,64 en una escala de 0 a 2. Las 3 decisiones llegaron en solo 165 milisegundos.

Ahora que tenemos D3 en local, vamos a usarlo para crear 3 aplicaciones de IA prácticas.

Proyecto 1: crea un analizador de calidad de blogs con D3 Mini

Imagina que gestionas una publicación técnica donde hay que revisar decenas de artículos antes de publicarlos. En lugar de leerlos todos a mano, podemos crear un analizador de calidad con IA que use Olostep para extraer el contenido del sitio web y nuestro modelo D3 Mini en local para clasificarlo y puntuarlo.

Lo probaremos con un artículo real, nuestro tutorial de KTransformers, que escribí yo.

1. Extrae nuestro tutorial de KTransformers

Primero, usaremos el SDK de Olostep para Python para extraer el contenido del artículo como 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])Con la tecnología de

Olostep recupera el artículo como Markdown, conservando sus encabezados, texto y ejemplos de código para analizarlos.

2. Categoriza y puntúa el artículo con D3

A continuación, usaremos Choice para identificar la categoría del artículo y Score para evaluar su calidad educativa en una escala de 5 puntos.

%%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")Con la tecnología de

Salida:

Category: ai
Quality: 4.6/5
CPU times: user 3.29 ms, sys: 2.96 ms, total: 6.25 ms
Wall time: 1.11 sCon la tecnología de

D3 categoriza correctamente el artículo como IA y le da una puntuación de calidad de 4,6/5, completando el análisis en aproximadamente 1,11 segundos.

Proyecto 2: analiza una imagen de producto con D3 Mini

En este proyecto crearemos un flujo sencillo de revisión de imágenes de producto para una tienda online. El objetivo es usar D3 Mini para identificar la categoría del producto, comprobar si se ve con claridad y valorar la calidad de la imagen antes de añadirla al catálogo.

El siguiente código usa directamente la API System One de vLLM y lee los resultados del campo correcto answers.

1. Carga una imagen de producto

Primero, descargaremos una imagen de ejemplo, la mostraremos en el cuaderno y la convertiremos a base64 para enviarla al 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))Con la tecnología de

image_base64 = base64.b64encode(image_data).decode()
image_input = f"data:image/jpeg;base64,{image_base64}"Con la tecnología de

Esto nos da una imagen lista para enviar que D3 Mini puede analizar directamente.

2. Analiza la imagen con D3 Mini

A continuación, pediremos a D3 Mini tres cosas a la vez: a qué categoría pertenece el producto, si el producto se ve claramente y qué tan adecuada es la imagen para una tienda 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)Con la tecnología de

Salida:

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 msCon la tecnología de

El modelo identifica el artículo como footwear, confirma que el producto se ve claramente y otorga una buena puntuación de calidad en solo 282 milisegundos.

Proyecto 3: crea un analizador de movimiento en vídeo con D3 Mini

En el último proyecto, construiremos un analizador sencillo de movimiento en vídeo con D3 Mini. En lugar de generar descripciones largas, usaremos el modelo para entender qué ocurre en un clip corto, identificar la dirección del movimiento y detectar cambios visuales. Este enfoque puede ser útil para monitorización de vídeo, detección de eventos y análisis automatizado de contenido.

1. Descarga un vídeo de ejemplo

Usaremos el vídeo de muestra oficial de D3 Mini de Hugging Face. Primero, instala la librería necesaria:

%pip install huggingface_hubCon la tecnología de

Después, descarga el vídeo de ejemplo para analizarlo en local.

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"
)Con la tecnología de

El vídeo muestra un cuadrado que se mueve de izquierda a derecha mientras cambia de color de azul a verde.

2. Analiza el vídeo

Primero, convertiremos el vídeo a formato base64 para poder enviarlo a nuestro 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}"Con la tecnología de

Ahora, usaremos la API System One para hacerle a D3 Mini 2 preguntas: en qué dirección se mueve el cuadrado y si cambia de color.

%%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%}")Con la tecnología de

Salida:

Movement: right
Color Change: 93.7%
CPU times: user 3.01 ms, sys: 5.04 ms, total: 8.05 ms
Wall time: 723 msCon la tecnología de

D3 Mini identifica correctamente el movimiento como right y asigna una probabilidad del 93,7% al cambio de color, completando el análisis en solo 723 milisegundos.

Conclusiones

D3 Mini gestiona clasificación, comprobaciones sí/no y puntuación sobre texto, imágenes y vídeo en una única GPU NVIDIA RTX 3090. Configurar D3 en local fue sorprendentemente sencillo. El único problema que tuve fue un error de falta de memoria de CUDA, que solucioné reduciendo el consumo de memoria de la GPU.

Por lo demás, todo funcionó sin sobresaltos. Si ya conoces vLLM, probablemente puedas optimizar aún más la configuración.

Lo que más me impresionó fue la velocidad. Los tiempos de pared fueron desde 87 milisegundos para una decisión de texto corta hasta 1,11 segundos para un artículo completo, y el ejemplo de vídeo terminó en 723 milisegundos. Todo ejecutado en mi propia GPU.

Creo que estamos llegando a un punto en el que ejecutar modelos de decisión en un servidor local para todo un equipo empieza a ser práctico. No todas las solicitudes necesitan un gran modelo de razonamiento.

Para muchas tareas del día a día, como clasificación, enrutamiento, puntuación y filtrado de contenido, un modelo de decisión más pequeño puede hacer el trabajo. Puedes reservar los modelos de razonamiento más costosos para las tareas que realmente requieren un análisis profundo o explicaciones detalladas.

Por supuesto, conviene evaluar la precisión y el rendimiento en tus propias cargas antes de usar estos modelos en producción. Tras probar D3 con texto, imágenes y vídeo, mi regla es simple: si la tarea es una clasificación, una comprobación sí/no o una valoración, prueba primero con un modelo D3 y pasa a un modelo de razonamiento solo cuando necesites una explicación.

Si te apetece aprender más sobre trabajo con modelos abiertos, te recomiendo nuestro curso Working with Hugging Face.