Despliegue de Qwen2.5-0.5B-Instruct con Docker y vLLM: guía paso a paso

  1. Ventajas de un modelo pequeño en producción local

Qwen2.5-0.5B-Instruct es el miembro más ligero de la familia Qwen2.5 de Alibaba. Con apenas medio billón de parámetros, su versión fp16 ocupa alrededor de 1 GB y una versión cuantizada puede reducirse a menos de 300 MB. Esto permite ejecutarlo cómodamente en equipos con 4 GB de RAM, Raspberry Pi, portátiles antiguos o incluso dispositivos móviles con capacidades de inferencia local.

A pesar de su tamaño, mantiene caratcerísticas clave: ventana de contexto de 32 000 tokens, soporte multilingüe amplio con fuerte rendimiento en chino e inglés, generación de JSON estructurado, completado de código y razonamiento matemático básico. Además, su licencia Apache 2.0 permite uso comercial sin restricciones.

Esta guía describe cómo ponerlo en marcha mediante un contenedor Docker basado en vLLM, aprovechando la compatibilidad nativa de esta imagen con la API de OpenAI. El resultado será un servicio HTTP local al que podrás enviar peticiones desde curl, Python o cualquier cliente compatible.

  1. Requisitos previos del entorno

Antes de lanzar el contenedor, verifica que tu sistema cumple estos puntos.

2.1 Docker instalado y en ejecución

docker --version

Si no tienes Docker, instálalo según tu sistema. En Ubuntu, por ejemplo:

sudo apt update && sudo apt install -y docker.io
sudo systemctl enable docker --now
sudo usermod -aG docker $USER

Tras ejecutar el último comando, cierra sesión y vuelve a abrir el terminal para que el grupo tenga efecto.

2.2 Soporte de GPU (opcional)

Si vas a usar aceleración NVIDIA, instala el NVIDIA Container Toolkit y comprueba que Docker detecta la tarjeta:

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubuntu22.04 nvidia-smi -L

Si solo dispones de CPU, omite las directivas relacionadas con GPU; vLLM funcionará en modo CPU sin configuración adicional.

2.3 Espacio y conectividad

  • Reserva al menos 2 GB de espacio libre para la imagen, el modelo y los logs.
  • Confirma que puedes acceder a Hugging Face y a Docker Hub:
curl -I https://huggingface.co
  1. Descarga del modelo

Es recomendable descargar primero los pesos para evitar que el contenedor falle al no encontrarlos. Usaremos un pequeño script de Python con huggingface_hub:

pip install huggingface-hub


# descargar_qwen.py
from pathlib import Path
from huggingface_hub import snapshot_download

destino = Path("modelos/Qwen2.5-0.5B-Instruct")
destino.mkdir(parents=True, exist_ok=True)

snapshot_download(
    repo_id="Qwen/Qwen2.5-0.5B-Instruct",
    local_dir=str(destino),
    local_dir_use_symlinks=False,
    allow_patterns=[
        "pytorch_model*.bin",
        "model*.safetensors",
        "config.json",
        "tokenizer*.json",
        "tokenizer.model",
        "special_tokens_map.json",
    ],
)
print(f"Modelo guardado en: {destino}")

Ejecuta el script:

python descargar_qwen.py

El proceso descargará aproximadamente 1 GB y dejará los archivos en modelos/Qwen2.5-0.5B-Instruct/.

  1. Lanzamiento del servicio con Docker

Para facilitar la gestión, crea un archivo de variables de entorno y un pequeño script de arranque. De este modo podrás cambiar entre CPU y GPU sin tocar el comando Docker directamente.

Archivo .env:

NOMBRE_CONTENEDOR=qwen05-servicio
PUERTO_HOST=8080
PUERTO_CONTENEDOR=8000
RUTA_MODELOS=/opt/modelos
RUTA_LOGS=/opt/logs
USAR_GPU=1

Script iniciar.sh:

#!/usr/bin/env bash
set -e

source .env

if [ "$USAR_GPU" -eq 1 ]; then
  GPU_FLAGS='--gpus "device=0"'
else
  GPU_FLAGS=""
fi

docker stop "$NOMBRE_CONTENEDOR" 2>/dev/null || true
docker rm "$NOMBRE_CONTENEDOR" 2>/dev/null || true

mkdir -p modelos logs

eval docker run -d \
  --name "$NOMBRE_CONTENEDOR" \
  -p "${PUERTO_HOST}:${PUERTO_CONTENEDOR}" \
  $GPU_FLAGS \
  -v "$(pwd)/modelos:${RUTA_MODELOS}" \
  -v "$(pwd)/logs:${RUTA_LOGS}" \
  --shm-size=2g \
  --restart unless-stopped \
  vllm/vllm-openai:latest \
  --model "${RUTA_MODELOS}/Qwen2.5-0.5B-Instruct" \
  --served-model-name qwen05 \
  --tensor-parallel-size 1 \
  --max-model-len 32768 \
  --enable-prefix-caching \
  --enforce-eager

Hazlo ejecutable y arranca el servicio:

chmod +x iniciar.sh
./iniciar.sh

Comprueba que el contenedor está activo:

docker ps -f name=qwen05-servicio

Y revisa los logs hasta ver que el servidor ha arrancado:

docker logs -f qwen05-servicio 2>&1 | grep -i "application startup complete"
  1. Pruebas con la API

5.1 Petición básica

Crea el archivo consulta.json con una conversación en formato OpenAI:

cat > consulta.json <<'EOF'
{
  "model": "qwen05",
  "messages": [
    {"role": "system", "content": "Eres un asistente útil, claro y conciso."},
    {"role": "user", "content": "Explica qué es Qwen2.5-0.5B-Instruct en una frase."}
  ],
  "temperature": 0.6,
  "max_tokens": 150
}
EOF

Envía la petición:

curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @consulta.json

Si todo funciona, recibirás una respuesta con finish_reason: "stop" y el texto generado.

5.2 Generación de JSON estructurado

Esta capacidad resulta especailmente útil para construir agentes ligeros o backends de bajo consumo. Envía una petición que fuerza el formato JSON:

curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen05",
    "messages": [
      {"role": "system", "content": "Responde únicamente con JSON. Claves: nombre(texto), categoria(texto), precio(numero), disponible(booleano)."},
      {"role": "user", "content": "Crea un producto llamado EdgePi, categoría IoT, precio 129 euros, disponible en stock."}
    ],
    "response_format": {"type": "json_object"},
    "temperature": 0.1,
    "max_tokens": 128
  }'
  1. Consejos prácticos

6.1 Interfaz web

Puedes conectar el endpoint a cualquier interfaz compatible con la API de OpenAI, como Open WebUI. Basta con indicar la URL base http://localhost:8080/v1 y el nombre del modelo qwen05.

6.2 Optimización en CPU

En dispositivos sin GPU, reduce el consumo de memoria y mejora la latencia usando cuantización. Si descargas el modelo AWQ o GGUF compatible, ajusta el arranque del contenedor:

--quantization awq

O bien, para versiones recientes de vLLM:

--kv-cache-dtype fp8_e4m3

6.3 Actualización y mantenimiento

Para actualizar la imagen base de vLLM, ejecuta:

docker pull vllm/vllm-openai:latest
./iniciar.sh

Si necesitas eliminar completamente el entorno:

docker stop qwen05-servicio
docker rm qwen05-servicio

Etiquetas: Qwen2.5 vLLM Docker OpenAI API Hugging Face

Publicado el 6-27 16:49

Etiquetas populares

©2026 Friki Work