Despliegue local de DiffusionGemma: ejecutar el modelo de difusión de texto de Google con vLLM

El artículo anterior explicó por qué DiffusionGemma merece atención: no usa generación autoregresiva tradicional token por token, sino difusión de texto y denoising paralelo sobre un canvas de 256 tokens, lo que lo hace más adecuado para interacción local de baja latencia, edición en línea y autocompletado de código.

Este artículo se centra en algo más concreto: cómo desplegarlo y cómo ejecutarlo desde la línea de comandos.

La ruta oficial principal por ahora es vLLM. DiffusionGemma puede arrancarse como un servidor local OpenAI-compatible de vLLM, y luego consultarse con una interfaz parecida a OpenAI Chat Completions.

Antes de empezar

Primero confirma si tiene sentido probar DiffusionGemma en tu configuración.

DiffusionGemma es un MoE de 26B total, con 3.8B parámetros activos durante inferencia. No es un modelo pequeño. MoE, cuantización y generación paralela solo bajan el umbral de despliegue local hasta un rango explorable con GPU de consumo de gama alta.

Si solo quieres escritura larga estable, preguntas y respuestas de conocimiento o una API de producción, Gemma 4 estándar sigue siendo más seguro. DiffusionGemma encaja mejor para probar editores de baja latencia, infilling de código y reparación instantánea de texto estructurado.

Opción 1: iniciar directamente con vLLM

El comando central de la guía oficial para desarrolladores es:

1
2
3
4
5
6
7
8
9

vllm serve google/diffusiongemma-26B-A4B-it \
  --max-model-len 262144 \
  --max-num-seqs 4 \
  --gpu-memory-utilization 0.85 \
  --attention-backend TRITON_ATTN \
  --generation-config vllm \
  --hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}' \
  --diffusion-config '{"canvas_length": 256}' \
  --enable-chunked-prefill

Este comando descarga google/diffusiongemma-26B-A4B-it desde Hugging Face e inicia un servidor local OpenAI-compatible. Por defecto, el servicio suele escuchar en http://localhost:8000.

Si tu entorno de Hugging Face requiere autenticación, ejecuta:

1

huggingface-cli login

Si todavía no tienes vLLM instalado, puedes preparar un entorno virtual de Python:

1
2
3
4

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -U vllm

Que pip install -U vllm baste o no depende de si la versión actual de vLLM ya incluye soporte para DiffusionGemma. DiffusionGemma es una arquitectura nueva. Si aparecen errores de estructura de modelo desconocida, parámetros no reconocidos o attention backend, consulta primero el release más reciente de vLLM, la guía de Google y la model card.

Opción 2: ejecutar vLLM con Docker

Si no quieres modificar el entorno Python local, puedes usar una imagen Docker de vLLM. Las recetas de vLLM han usado comandos parecidos a este:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

docker run -itd --name diffusiongemma \
  --ipc=host \
  --network host \
  --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:gemma \
    --model google/diffusiongemma-26B-A4B-it \
    --max-model-len 262144 \
    --max-num-seqs 4 \
    --gpu-memory-utilization 0.85 \
    --generation-config vllm \
    --enable-chunked-prefill \
    --host 0.0.0.0 \
    --port 8000

La ventaja es un entorno más limpio, útil en servidores, workstations o máquinas de prueba temporales. Ten en cuenta dos puntos:

• El host debe tener instalados NVIDIA driver y NVIDIA Container Toolkit.
• Si la versión de vLLM dentro de la imagen no incluye soporte para DiffusionGemma, el arranque fallará igual. Usa una imagen más reciente o la rama adecuada.

El montaje -v ~/.cache/huggingface:/root/.cache/huggingface es útil si quieres reutilizar la caché de Hugging Face del host y evitar descargar el modelo cada vez.

Probar el servicio con curl

Después de iniciar el servicio, consulta la lista de modelos:

1

curl http://localhost:8000/v1/models

Si la respuesta incluye google/diffusiongemma-26B-A4B-it, el servicio está básicamente funcionando.

Luego prueba Chat Completions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/diffusiongemma-26B-A4B-it",
    "messages": [
      {
        "role": "user",
        "content": "Explica en tres frases la diferencia entre DiffusionGemma y un LLM autoregresivo normal."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.7
  }'

Si prefieres el SDK de OpenAI, apunta base_url al servicio local:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",
)

response = client.chat.completions.create(
    model="google/diffusiongemma-26B-A4B-it",
    messages=[
        {
            "role": "user",
            "content": "Escribe una función en Python que convierta una tabla Markdown a CSV.",
        }
    ],
    max_tokens=512,
)

print(response.choices[0].message.content)

Cómo entender los parámetros

Hay varios parámetros del comando oficial que conviene mirar por separado.

--max-model-len 262144

Define la longitud máxima de contexto. DiffusionGemma / Gemma 4 soporta contextos muy largos, pero eso no significa que debas abrir siempre el límite. Cuanto más largo sea el contexto, mayor será la presión sobre VRAM y planificación.

Para una prueba local puedes conservar el valor oficial. Si la VRAM va justa, bájalo y comprueba si afecta a tu tarea real.

--max-num-seqs 4

Limita cuántas secuencias se procesan a la vez. DiffusionGemma encaja mejor en interacción local de baja concurrencia. Subir demasiado la concurrencia no siempre acelera y puede aumentar la presión de VRAM.

Para una herramienta local de un solo usuario, prueba entre 1 y 4. Para servicio multiusuario, hace falta benchmarking serio.

--gpu-memory-utilization 0.85

Indica a vLLM qué proporción de la memoria GPU puede usar. 0.85 es un valor conservador común.

Si el arranque da OOM, prueba:

1

--gpu-memory-utilization 0.75

Si tienes VRAM de sobra, puedes subirlo un poco, pero no lo pongas al máximo desde el principio. Deja margen para el sistema y otros procesos.

--attention-backend TRITON_ATTN

Selecciona el attention backend. El comando oficial usa TRITON_ATTN, relacionado con la ruta especial de attention / denoising de DiffusionGemma.

Si el backend no está soportado, suele ser un problema de versiones entre vLLM, CUDA, Triton y arquitectura de GPU. No cambies parámetros del modelo al azar; revisa primero el stack de software.

--hf-overrides

Esta parte del comando oficial es clave:

1

--hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}'

Sobrescribe ajustes del diffusion sampler en la configuración de Hugging Face. entropy_bound puede entenderse como una estrategia para controlar la parada del denoising o el comportamiento de sampling, en combinación con la generación iterativa de DiffusionGemma.

No es un parámetro normal de LLM. Primero usa el valor oficial y confirma que funciona; luego experimenta.

--diffusion-config

El comando oficial usa:

1

--diffusion-config '{"canvas_length": 256}'

canvas_length corresponde al canvas de 256 tokens de DiffusionGemma. El modelo no genera un token tras otro de forma lineal; denoising ocurre en paralelo dentro de un bloque. Este valor afecta directamente a la generación por bloques.

No conviene cambiarlo al principio. Usa el valor oficial para confirmar velocidad, calidad y VRAM; después prueba según la documentación futura de vLLM.

--enable-chunked-prefill

Activa chunked prefill. El procesamiento de secuencias largas en DiffusionGemma coordina prefill y denoising, y chunked prefill puede ayudar a planificar mejor en contextos largos.

Si solo pruebas prompts cortos, quizá no notes mucho. En contexto largo tiene más sentido.

Un comando local más conservador

Si solo quieres confirmar si puede arrancar, reduce concurrencia y presión de VRAM:

1
2
3
4
5
6
7
8
9

vllm serve google/diffusiongemma-26B-A4B-it \
  --max-model-len 65536 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.75 \
  --attention-backend TRITON_ATTN \
  --generation-config vllm \
  --hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}' \
  --diffusion-config '{"canvas_length": 256}' \
  --enable-chunked-prefill

Este comando no es necesariamente óptimo en rendimiento, pero es mejor para la primera depuración. Primero haz que el modelo arranque; luego sube contexto y concurrencia poco a poco.

Qué demos conviene probar

No conviene probar DiffusionGemma solo con preguntas de chat normal. Lo que merece la pena medir es la generación no lineal y la reparación local en tiempo real.

Puedes probar prompts como estos:

1
2
3
4

Completa la lógica que falta en esta función Python. Devuelve solo la función completa:

def markdown_table_to_csv(markdown: str) -> str:
    ...

1
2
3

Corrige el siguiente JSON para que sea JSON válido y conserva el significado original de los campos:

{"name":"demo","items":[{"id":1,"tags":["a","b",],},]}

1
2
3
4

Completa la siguiente tabla Markdown hasta 5 filas y asegúrate de que todas tengan el mismo número de columnas:

| Parámetro | Función | Recomendación |
| --- | --- | --- |

1
2
3

Eres un modelo de autocompletado en línea dentro de un editor. Reescribe solo la parte entre corchetes y mantiene coherente el contexto:

DiffusionGemma es adecuado para [escribe aquí una frase corta sobre interacción de baja latencia], pero no para escritura larga donde la calidad sea prioritaria.

Estas tareas muestran mejor su atención bidireccional, autocorrección dentro del bloque y capacidad de salida estructurada que “cuéntame una historia”.

Problemas comunes

El modelo no está soportado al arrancar

Primero revisa la versión de vLLM. DiffusionGemma es nuevo y versiones antiguas de vLLM pueden no tener la implementación.

Consulta:

1

vllm --version

Luego compáralo con la guía oficial, release notes de vLLM o la model card de DiffusionGemma.

Falla la descarga desde Hugging Face

Comprueba red y estado de login:

1

huggingface-cli whoami

Si hace falta, inicia sesión de nuevo:

1

huggingface-cli login

En servidor, conviene descargar el modelo antes o montar la caché de Hugging Face dentro del contenedor.

OOM

Reduce presión en este orden:

1

--max-num-seqs 1

1

--gpu-memory-utilization 0.75

1

--max-model-len 65536

Si aún da OOM, revisa si estás usando pesos cuantizados, si vLLM carga bien el formato de cuantización y si la GPU cumple los requisitos del modelo.

La velocidad no es tan alta como esperabas

Primero confirma que tu escenario cae en la zona de ventaja de DiffusionGemma. Su aceleración apunta sobre todo a ejecución local, baja concurrencia, GPU dedicada y batch bajo o medio.

En servicios cloud de alta concurrencia, los modelos autoregresivos pueden saturar hardware con batching, reduciendo la ventaja de DiffusionGemma. Apple Silicon y otras arquitecturas de memoria unificada tampoco garantizan la misma mejora.

La calidad de salida es peor que Gemma 4

Es esperado. Google dice explícitamente que, como DiffusionGemma prioriza velocidad y generación paralela de layout, su calidad general es inferior a Gemma 4 estándar. Las aplicaciones de producción donde la calidad es prioritaria deberían seguir usando Gemma 4 estándar.

Flujo mínimo de validación

Puedes seguir este orden:

1. Inicia sesión en Hugging Face.

1

huggingface-cli login

2. Arranca el servicio vLLM.

1
2
3
4
5
6
7
8
9

vllm serve google/diffusiongemma-26B-A4B-it \
  --max-model-len 65536 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.75 \
  --attention-backend TRITON_ATTN \
  --generation-config vllm \
  --hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}' \
  --diffusion-config '{"canvas_length": 256}' \
  --enable-chunked-prefill

3. Comprueba la lista de modelos.

1

curl http://localhost:8000/v1/models

4. Envía una petición.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/diffusiongemma-26B-A4B-it",
    "messages": [
      {
        "role": "user",
        "content": "Completa una función Python: recibe una cadena con una tabla Markdown y devuelve una cadena CSV."
      }
    ],
    "max_tokens": 512,
    "temperature": 0.4
  }'

5. Luego prueba reparación estructurada o code infilling.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/diffusiongemma-26B-A4B-it",
    "messages": [
      {
        "role": "user",
        "content": "Corrige este JSON y devuelve solo JSON válido: {\"name\":\"demo\",\"items\":[{\"id\":1,\"tags\":[\"a\",\"b\",],},]}"
      }
    ],
    "max_tokens": 256,
    "temperature": 0.2
  }'

Si estos cinco pasos funcionan, ajusta después longitud de contexto, concurrencia y uso de memoria GPU.

Resumen

Desplegar DiffusionGemma no va de encontrar un sustituto genérico para un modelo de chat. Va de validar una nueva ruta de interacción local: iniciar un servicio OpenAI-compatible con vLLM y experimentar con edición en línea, code infilling, reparación de texto estructurado y salida de baja latencia.

Para un primer despliegue, usa parámetros conservadores: --max-num-seqs 1, --max-model-len 65536, --gpu-memory-utilization 0.75. Cuando funcione, vuelve a la configuración oficial y prueba gradualmente velocidad, VRAM y calidad de salida.

Referencias:

• DiffusionGemma - Google DeepMind
• DiffusionGemma: 4x faster text generation
• DiffusionGemma: The Developer Guide
• Gemma 4 Usage Guide - vLLM Recipes