Construye un servidor de inferencia compatible con OpenAI en tus propias GPUs: guía de la API compatible con OpenAI del servidor de inferencia vLLM

Si ya dispones de capacidad GPU, un servidor de inferencia compatible con OpenAI permite que tu aplicación conserve la misma forma de cliente mientras cambias el backend de una API de modelo alojada a tu propia infraestructura. El camino habitual es sencillo en concepto: ejecuta vLLM o LocalAI en un nodo con GPU, expón una API /v1, apunta el base_url de tu SDK a ese endpoint y luego refuerza el servicio con autenticación, enrutamiento, monitorización y capacidad.

Esta guía se centra en la construcción práctica: cómo poner en marcha un vllm inference server openai compatible api, qué probar antes de ponerlo detrás de tráfico de producción y cuándo es más inteligente mantener el autoalojamiento como referencia mientras enrutas la mayor parte de las cargas de trabajo a través de una API de modelo gestionada como Flatkey.

La respuesta rápida

Para la mayoría de las cargas de trabajo de texto de LLM, empieza con vLLM. Proporciona un servidor HTTP compatible con OpenAI, admite puntos finales comunes al estilo de OpenAI como chat completions, completions, embeddings y el listado de modelos, según el tipo de modelo cargado, y ofrece imágenes oficiales de Docker para su despliegue.

Una pila autoalojada mínima se ve así:

Usa un vllm inference server openai compatible api cuando necesites control directo del hardware, localización de datos, pesos de modelo personalizados o una economía de servicio predecible y de alto volumen. Usa una base de referencia con gateway/API de modelo cuando principalmente necesites resultados fiables y no quieras encargarte del uso de GPU, la deriva de drivers, la carga de modelos y el failover.

Antes de construir: decide si el autoalojamiento merece la pena

Ejecutar tu propio servidor de inferencia compatible con OpenAI no es automáticamente más barato. Puede ser excelente cuando tus GPUs están ocupadas y tu carga de trabajo encaja con el modelo que alojas. Puede ser caro cuando la utilización es irregular, los prompts varían mucho, la calidad del modelo cambia con frecuencia o el equipo pasa más tiempo depurando la infraestructura que entregando producto.

Usa esta tabla de decisión antes de alquilar o comprar hardware:

Flatkey encaja en la última columna como base de referencia: un endpoint compatible con OpenAI, un único saldo y acceso a muchos modelos oficiales. Incluso si construyes un vllm inference server openai compatible api, mantén una base de referencia de API de modelo en tu benchmark para poder comparar latencia, calidad y coste por salida aceptada en lugar de solo el coste por hora de GPU.

Arquitectura de referencia

Un servidor de inferencia compatible con OpenAI para producción no debería exponer directamente el motor del modelo a Internet público. Coloca delante una capa delgada de control.

flowchart LR
  A[OpenAI SDK / app workers] --> B[API edge: TLS, auth, rate limits]
  B --> C[OpenAI-compatible /v1 route]
  C --> D[vLLM inference server]
  D --> E[GPU node or GPU pool]
  D --> F[Metrics and logs]
  B --> G[Fallback route: Flatkey or another model API]

La decisión de diseño importante es separar la compatibilidad de las operaciones. vLLM puede hablar la API al estilo de OpenAI. Tu edge debe encargarse de la autenticación, las cuotas, los límites de tamaño de solicitud, TLS, los registros de auditoría y el comportamiento de fallback.

Paso 1: prepara el anfitrión GPU

Empieza con una máquina Linux limpia con GPU. Confirma que el host tiene:

• Un driver de NVIDIA compatible con la GPU y la pila CUDA que planeas ejecutar.
• Docker u otro tiempo de ejecución de contenedores compatible.
• NVIDIA Container Toolkit configurado para que los contenedores puedan acceder a las GPUs.
• Suficiente almacenamiento local o en red para los pesos del modelo.
• Una ruta de red que no exponga el puerto de inferencia hasta que la autenticación y TLS estén en su sitio.

El flujo de instalación del kit de herramientas de contenedores de NVIDIA configura Docker con nvidia-ctk runtime configure --runtime=docker y luego reinicia Docker. Después de eso, se puede ejecutar un contenedor con acceso a GPU usando las banderas de GPU de Docker.

Ejecuta estas comprobaciones antes de instalar el servidor de modelos:

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

Si cualquiera de los comandos falla, corrige primero la capa de controlador/runtime. Una vllm inference server openai compatible api no puede ser estable cuando el runtime base de GPU es inestable.

Paso 2: Inicia una API compatible con OpenAI del servidor de inferencia vLLM

La documentación oficial de despliegue con Docker de vLLM identifica vllm/vllm-openai como la imagen para ejecutar un servidor compatible con OpenAI. Una primera ejecución práctica se ve así:

docker run --rm --gpus all \
  --ipc=host \
  -p 8000:8000 \
  -e HUGGING_FACE_HUB_TOKEN="$HUGGING_FACE_HUB_TOKEN" \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name llama-3.1-8b-instruct

Para un modelo privado, reemplaza el id del modelo con tu propio repositorio o ruta local. Para producción, fija las etiquetas de imagen y las revisiones del modelo en lugar de desplegar latest.

Luego prueba el listado de modelos:

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

Y prueba las completaciones de chat:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b-instruct",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Reply with one sentence about self-hosted inference."}
    ],
    "temperature": 0.2
  }'

Ese es el primer hito funcional: una vllm inference server openai compatible api local a la que tu aplicación puede llamar con la misma forma de petición que ya usa para el chat estilo OpenAI.

Paso 3: Apunta tu SDK existente al endpoint local

La mayor parte del trabajo de migración compatible con OpenAI debería ocurrir en la configuración, no en la lógica de la aplicación. Con el patrón del SDK de Python, establece un base_url y una clave de API personalizados:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="local-dev-key",
)

response = client.chat.completions.create(
    model="llama-3.1-8b-instruct",
    messages=[
        {"role": "user", "content": "Give me a deployment checklist."}
    ],
)

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

En producción, no apuntes los workers de la aplicación directamente a un proceso vLLM en bruto. Apúntalos a tu propio gateway interno o balanceador de carga:

OPENAI_BASE_URL=https://inference.example.com/v1
OPENAI_API_KEY=<your-internal-service-token>

Ese gateway puede enrutar a vLLM, bloquear campos de solicitud no admitidos, normalizar alias de modelos y hacer failover a Flatkey u otra API de modelo cuando el pool autohospedado esté saturado.

Paso 4: Entiende lo que "OpenAI-Compatible" no significa

Compatible con OpenAI no significa que cada endpoint, comportamiento del modelo, llamada a herramientas, evento de streaming u opción específica del proveedor funcione exactamente como OpenAI. Significa que el servidor acepta una forma familiar para endpoints seleccionados.

Antes de dar por hecha la migración, prueba:

El patrón más seguro es mantener una suite de pruebas de compatibilidad. Envía un conjunto fijo de prompts reales de la aplicación a OpenAI, Flatkey y a tu vllm inference server openai compatible api. Compara latencia, validez del esquema, comportamiento de rechazo, calidad de la salida y tasa de salida aceptada.

Paso 5: Dimensiona la memoria de GPU para el modelo y el tráfico

El principal modo de fallo del servicio no es "el servidor arranca lentamente". Es "el servidor arranca y luego se cae bajo una longitud de contexto y concurrencia reales".

Planifica la memoria en torno a:

• Pesos del modelo.
• Caché KV para contexto y secuencias concurrentes.
• Overhead del runtime.
• Fragmentación y margen de seguridad.
• Paralelismo tensorial cuando un modelo no cabe en una sola GPU.
• Compromisos de cuantización si usas menor precisión.

Para una hoja de trabajo más profunda, usa la guía de Flatkey sobre requisitos de memoria GPU para LLM. Para la planificación a nivel de clúster, combínala con el análisis de estilo arquitectura de clúster GPU y TCO de clúster GPU.

Una regla aproximada de aceptación:

usable_capacity = model_fit + target_context + target_concurrency + 20-30% headroom

Si no puedes mantener el margen, reduce la longitud del contexto, reduce la concurrencia, usa un modelo más pequeño, reparte entre varias GPUs o redirige el tráfico excedente fuera del grupo autogestionado.

Paso 6: Añade un borde de API antes de producción

El servidor vLLM en bruto no es tu plano de control completo para producción. Coloca un borde delante y haz que ese borde se responsabilice de:

• Terminación TLS.
• Autenticación servicio a servicio.
• Límites del cuerpo de la solicitud.
• Límites de tasa por equipo o por aplicación.
• Asignación de alias de modelo.
• Registros estructurados de solicitudes.
• Presupuestos de tiempo de espera y reintentos.
• Enrutamiento canario.
• Enrutamiento de respaldo.

Ejemplo de estructura de Nginx:

server {
  listen 443 ssl;
  server_name inference.example.com;

  client_max_body_size 4m;

  location /v1/ {
    proxy_pass http://vllm_backend:8000/v1/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Request-Id $request_id;
    proxy_read_timeout 120s;
  }
}

Eso es solo un punto de partida. Los equipos de producción deben añadir autenticación, mTLS o red privada, políticas de registro de solicitudes y límites explícitos en torno al tamaño del prompt y la longitud de la salida.

Paso 7: Mide la salida aceptada, no solo los tokens por segundo

Los paneles de servicio GPU a menudo se centran demasiado en el rendimiento. Los tokens por segundo importan, pero los equipos de producto suelen preocuparse por las salidas aceptadas: respuestas lo bastante rápidas, válidas y buenas para enviarlas al usuario o al flujo de trabajo posterior.

Haz seguimiento de:

Luego calcula el coste por salida aceptada:

cost_per_accepted_output =
  (gpu_cost + storage + network + ops_time + fallback_api_cost)
  / accepted_outputs

Aquí es donde una vllm inference server openai compatible api obtiene una comparación honesta frente a las APIs gestionadas. Si la GPU local es más barata por token bruto pero peor en reintentos, fallos o tiempo del operador, el coste por salida aceptada puede ser mayor de lo esperado.

Paso 8: Añade un respaldo en lugar de tratar la caja GPU como un único punto de fallo

Tu aplicación no debería importar si la respuesta viene de vLLM autogestionado, Flatkey u otra ruta de modelo. Debería solicitar un alias de modelo y recibir una respuesta o un fallo controlado.

Usa reglas de enrutamiento como:

Este diseño permite al equipo conservar la economía y el control del autohospedaje sin ligar la disponibilidad del producto a un único servidor de inferencia.

vLLM frente a LocalAI para inferencia local compatible con OpenAI

vLLM y LocalAI aparecen en búsquedas de un servidor de inferencia compatible con OpenAI, pero encajan en tareas diferentes.

Para la carga de trabajo objetivo de este artículo, empieza con una vllm inference server openai compatible api. Evalúa LocalAI cuando tu objetivo sea una experimentación local más amplia o una sola API local sobre múltiples backends, en lugar del máximo rendimiento de servicio GPU para una sola familia de LLM.

Lista de verificación para producción

Úsala antes de enrutar usuarios reales:

• [ ] Controlador de GPU y runtime de contenedores verificados con nvidia-smi dentro de un contenedor.
• [ ] Imagen de vLLM y revisión del modelo fijadas.
• [ ] Alias del modelo estable y documentado.
• [ ] /v1/models y /v1/chat/completions probados a través de la URL edge final.
• [ ] Streaming probado con desconexiones del cliente.
• [ ] Pruebas de contexto largo y concurrencia ejecutadas con la forma esperada de producción.
• [ ] Autenticación añadida en el edge; el puerto bruto de vLLM no es público.
• [ ] Tamaño del cuerpo de la solicitud, tokens máximos de salida y timeouts aplicados.
• [ ] Los registros excluyen datos sensibles del prompt salvo aprobación explícita.
• [ ] Las métricas capturan latencia, colas, memoria de GPU, tasas de error y tasa de salida aceptada.
• [ ] Ruta de fallback configurada para saturación e incidentes.
• [ ] Línea base de API gestionada medida con los mismos prompts.
• [ ] Plan de reversión probado.

Errores comunes

El mayor error es tratar el primer curl exitoso como el final del trabajo. Solo es el comienzo.

Otros fallos comunes:

• Ejecutar imágenes latest en producción sin fijar versiones.
• Exponer el puerto de inferencia bruto a Internet.
• Suponer que se admite cada parámetro de solicitud de OpenAI.
• Comparar el rendimiento de un único prompt corto y llamar al resultado "listo para producción".
• Ignorar el crecimiento de la caché KV por la longitud real del contexto.
• Olvidar que el tiempo de carga del modelo afecta a los despliegues y la recuperación.
• Medir el coste por hora de GPU sin el tiempo del operador, los reintentos y los fallos de calidad.
• Omitir el fallback porque el endpoint local es "compatible con OpenAI".

Un vllm inference server openai compatible api de producción es una infraestructura útil. No es compatibilidad mágica ni un sustituto de la disciplina operativa.

Cuándo usar Flatkey junto con tus propias GPUs

Flatkey es más útil en esta arquitectura como la línea base de modelo/API gestionada y la ruta de fallback. Mantén tu aplicación con una forma de cliente compatible con OpenAI y luego dirige parte del tráfico a tu grupo local de GPU y parte a Flatkey.

Eso te da:

• Una forma de comparar la calidad de salida autohospedada frente a modelos alojados.
• Capacidad de desbordamiento cuando las GPUs locales están saturadas.
• Una ruta de fallback durante incidentes de controlador, modelo o despliegue.
• Acceso a otras familias de modelos sin añadir más claves de proveedor.
• Un camino más limpio de vuelta a las APIs gestionadas si un modelo autohospedado no rinde bien.

La decisión no es "tus propias GPUs o usar APIs". Para muchos equipos, la configuración duradera es ambas: usar las GPUs propias donde aportan control o ventaja de coste, y mantener una ruta gestionada para resiliencia y elección de modelo.

Preguntas frecuentes

¿Qué es un servidor de inferencia compatible con OpenAI?

Un servidor de inferencia compatible con OpenAI expone endpoints HTTP con formatos de solicitud y respuesta al estilo de OpenAI, normalmente bajo /v1. Eso permite que las aplicaciones usen configuraciones SDK familiares, como una base_url personalizada, mientras envían tráfico a un backend diferente.

¿Es vLLM un servidor de inferencia compatible con OpenAI?

Sí. vLLM proporciona un servidor compatible con OpenAI y documenta soporte para endpoints comunes al estilo de OpenAI, como chat completions, completions, embeddings y listado de modelos, según el tipo de modelo y la funcionalidad.

¿Puedo ejecutar localmente un servidor compatible con OpenAI de vLLM?

Sí. Puedes ejecutar vLLM localmente en una estación de trabajo o servidor con GPU, y luego exponer el endpoint /v1 a tu aplicación. Para producción, coloca delante un edge autenticado o una gateway interna.

¿Qué hardware necesito?

Depende del tamaño del modelo, la precisión, la longitud del contexto y el objetivo de concurrencia. Empieza dimensionando los pesos del modelo más la caché KV y el margen, y luego prueba con prompts reales. Un pequeño modelo instruct puede caber en una GPU; un modelo de 70B o una carga de alta concurrencia puede requerir GPUs con más memoria o paralelismo tensorial.

¿Debería usar vLLM o LocalAI?

Usa primero vLLM cuando el trabajo sea inferencia LLM de alto rendimiento en GPUs. Evalúa LocalAI cuando quieras un servidor local más amplio y compatible con OpenAI a través de múltiples backends o modalidades locales.

¿Compatible con OpenAI significa idéntico para usar directamente?

No. La forma del endpoint puede coincidir, pero el comportamiento del modelo, los parámetros admitidos, las herramientas, el streaming, los embeddings, los errores y la contabilidad de tokens pueden diferir. Ejecuta pruebas de compatibilidad antes de cambiar el tráfico de producción.

Conclusión

Construir una vllm inference server openai compatible api es la forma práctica más rápida de convertir tus propias GPUs en un endpoint al estilo OpenAI. La construcción principal es sencilla: prepara el runtime de GPU, ejecuta vLLM, apunta el SDK a /v1 y luego añade el edge, la monitorización, las pruebas de compatibilidad y las rutas de fallback que lo hacen apto para producción.

Los mejores equipos no se detienen en "funciona". Comparan la inferencia autohospedada con una línea base de API de modelo gestionado, miden las salidas aceptadas y mantienen lista una ruta de fallback. Así consigues el control de tus propias GPUs sin hacer que cada solicitud del producto dependa de un único servidor de inferencia frágil.

Referencias oficiales

• Documentación del servidor compatible con OpenAI de vLLM: https://docs.vllm.ai/en/latest/serving/online_serving/
• Documentación de implementación con Docker de vLLM: https://docs.vllm.ai/en/latest/deployment/docker/
• Guía de instalación de NVIDIA Container Toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• README del SDK de Python de OpenAI: https://github.com/openai/openai-python
• Documentación del proyecto LocalAI: https://localai.io/