Inicio rápido de SGLang: instalar, configurar y servir modelos LLM a través de la API de OpenAI.

Sirva modelos abiertos rápidamente con SGLang.

Índice

SGLang es un marco de servicio de alto rendimiento para grandes modelos de lenguaje y modelos multimodales, diseñado para ofrecer inferencia de baja latencia y alto rendimiento en todo, desde una sola GPU hasta clústeres distribuidos.

Para una comparación más amplia de las opciones de alojamiento de LLM autoadministrados y en la nube —incluyendo Ollama, vLLM, llama-swap, LocalAI y proveedores de nube gestionados— consulte la guía de alojamiento de LLM para 2026.

Si ya tiene aplicaciones conectadas a la forma de la API de OpenAI, SGLang es especialmente atractivo porque puede exponer endpoints compatibles con OpenAI para completos de chat y de texto, lo que facilita la migración de APIs alojados a modelos autoadministrados con cambios mínimos en el lado del cliente. Cuando necesite enrutar solicitudes a través de múltiples backends (llama.cpp, vLLM, SGLang, etc.) con intercambio en caliente y descarga basada en TTL, llama-swap proporciona una capa de proxy transparente que mantiene estable una única URL /v1 mientras intercambia los servidores upstream según sea necesario.

infografía de sglang

Esta guía de inicio rápido recorre la instalación (varios métodos), patrones de configuración prácticos y un flujo de trabajo limpio de “instalar → servir → verificar → integrar → ajustar”, con ejemplos funcionales tanto para servicio HTTP como para inferencia por lotes fuera de línea.

Si necesita soporte multimodal (texto, incrustaciones, imágenes, audio) con una interfaz web integrada y compatibilidad máxima de inserción directa con la API de OpenAI, LocalAI ofrece un conjunto de características más amplio con soporte para más formatos de modelos.

¿Qué es SGLang para el servicio de alto rendimiento de LLM y modelos multimodales

En su núcleo, SGLang está diseñado para una inferencia eficiente y un servicio escalable. El stack de “tiempo de ejecución rápido” incluye RadixAttention para caché de prefijos, un programador de CPU sin sobrecarga, decodificación especulativa, agrupación continua, atención paginada, múltiples estrategias de paralelismo (tensor, pipeline, experto, paralelismo de datos), salidas estructuradas, prellenado por fragmentos y múltiples opciones de cuantización (por ejemplo FP4, FP8, INT4, AWQ, GPTQ).

Está diseñado para despliegue en múltiples plataformas: GPUs de NVIDIA, GPUs de AMD, CPUs Intel Xeon, TPUs de Google, NPUs Ascend y más.

PyPI requiere Python >= 3.10. A partir del 23 de marzo de 2026, la línea publicada incluía la versión 0.5.9 (lanzada el 23 de febrero de 2026); fije o verifique las versiones actuales al instalar.

Cómo instalar SGLang en hosts Linux con GPU con uv pip, compilación desde fuentes o Docker

Las opciones de instalación incluyen uv o pip, compilación desde fuentes, imágenes Docker, manifiestos de Kubernetes, Docker Compose, SkyPilot y AWS SageMaker. La mayoría de los tutoriales asumen configuraciones comunes de GPU NVIDIA; otros aceleradores tienen sus notas de configuración en otros lugares.

Instale SGLang rápidamente con uv o pip en Python 3.10+

Para una instalación local directa, uv suele ser el camino más rápido:

pip install --upgrade pip
pip install uv
uv pip install sglang

Notas sobre CUDA 13

Para CUDA 13, Docker evita incompatibilidades de PyTorch/CUDA en el host. Sin Docker: instale una compilación de PyTorch con CUDA 13, luego sglang y, finalmente, la rueda sglang-kernel correspondiente de las publicaciones de ruedas (la versión debe coincidir con el stack).

# 1) Instale PyTorch con soporte CUDA 13 (reemplace X.Y.Z según sea necesario)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) Instale SGLang
uv pip install sglang

# 3) Instale la rueda sglang-kernel correspondiente para CUDA 13 (reemplace X.Y.Z)
uv pip install "https://github.com/sgl-project/whl/releases/download/vX.Y.Z/sglang_kernel-X.Y.Z+cu130-cp310-abi3-manylinux2014_x86_64.whl"

Instale y ejecute SGLang con imágenes de Docker Hub

Para despliegues contenerizados, o para evitar problemas de emparejamiento CUDA/PyTorch en el host, utilice las imágenes publicadas en Docker Hub. Un docker run típico monta la caché de Hugging Face y pasa HF_TOKEN al descargar modelos restringidos.

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=<secret>" \
  --ipc=host \
  lmsysorg/sglang:latest \
  python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000

Para imágenes de estilo de producción, latest-runtime elimina las herramientas de compilación y las dependencias de desarrollo, por lo que la imagen es mucho más pequeña que la variante latest predeterminada.

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=<secret>" \
  --ipc=host \
  lmsysorg/sglang:latest-runtime \
  python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000

Instale desde fuentes y otros métodos de despliegue

Para desarrollar con SGLang o aplicar parches locales, clone una rama de liberación e instale el paquete Python en modo editable:

git clone -b v0.5.9 https://github.com/sgl-project/sglang.git
cd sglang

pip install --upgrade pip
pip install -e "python"

Para la orquestación, el repositorio incluye manifiestos de Kubernetes (de nodo único y multinodo) y una disposición mínima de Docker Compose, que son puntos de partida razonables antes de realizar cableado personalizado.

Cómo configurar los argumentos del servidor SGLang con archivos de configuración YAML y variables de entorno

La configuración de SGLang se controla mediante argumentos del servidor y variables de entorno. Las banderas cubren la selección del modelo, paralelismo, memoria y controles de optimización; el conjunto completo se lista con python3 -m sglang.launch_server --help.

Las variables de entorno utilizan dos prefijos: SGL_ y SGLANG_ (muchas banderas aceptan la forma de CLI o de entorno—launch_server --help muestra el mapeo).

Algunas variables de entorno comúnmente relevantes incluyen controles de host y puerto como SGLANG_HOST_IP y SGLANG_PORT.

Utilice un archivo de configuración YAML para lanzamientos reproducibles del servidor SGLang

Para despliegues repetibles y líneas de comando más cortas, pase un archivo YAML con --config. Los argumentos de CLI sobrescriben los valores del archivo cuando ambos establecen la misma opción.

# Cree config.yaml
cat > config.yaml << 'EOF'
model-path: meta-llama/Meta-Llama-3-8B-Instruct
host: 0.0.0.0
port: 30000
tensor-parallel-size: 2
enable-metrics: true
log-requests: true
EOF

# Lance el servidor con el archivo de configuración
python -m sglang.launch_server --config config.yaml

Algunos elementos esenciales de configuración y ajuste a tener en cuenta:

--model-path de SGLang puede apuntar a una carpeta local o a un ID de repositorio de Hugging Face, lo que facilita cambiar entre pesos locales y modelos alojados en el Hub sin cambiar su código de servicio.

Para múltiples GPUs, habilite el paralelismo de tensor con --tp. Si el inicio falla con “peer access is not supported between these two devices”, añada --enable-p2p-check.

Si el servicio alcanza OOM (Out Of Memory), reduzca la presión de la caché KV con un --mem-fraction-static más pequeño (el predeterminado es 0.9).

Si los prompts largos OOM durante el prellenado, reduzca --chunked-prefill-size.

Cómo ejecutar un servidor SGLang compatible con OpenAI y llamarlo desde el cliente Python de OpenAI

Un flujo de trabajo práctico de “camino feliz” se ve así:

  1. Instale SGLang (uv/pip o Docker).
  2. Inicie el servidor con su modelo y puerto elegidos.
  3. Verifique el servicio básico mediante endpoints compatibles con OpenAI.
  4. Integre su aplicación apuntando el SDK de OpenAI base_url al servidor local.
  5. Ajuste el rendimiento y la memoria con argumentos del servidor una vez que tenga tráfico real.

Envíe una solicitud de completado de chat local a SGLang utilizando el SDK de OpenAI

Para el uso compatible con OpenAI, dos detalles importan:

El servidor implementa la superficie HTTP de OpenAI y, cuando el tokenizador lo proporciona, aplica la plantilla de chat de Hugging Face automáticamente. Sobrescríballo con --chat-template al inicio si es necesario.

Apunte un cliente de OpenAI al prefijo /v1 del servidor (base_url → http://<host>:<port>/v1), luego llame a client.chat.completions.create(...) como de costumbre.

Inicie el servidor con cualquiera de los dos puntos de entrada: python -m sglang.launch_server sigue funcionando, pero sglang serve es la CLI preferida.

# Punto de entrada de CLI recomendado
sglang serve --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

# Todavía soportado
python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

Luego llámelo con el cliente Python de OpenAI:

import openai

client = openai.Client(base_url="http://127.0.0.1:30000/v1", api_key="None")

response = client.chat.completions.create(
    model="qwen/qwen2.5-0.5b-instruct",
    messages=[{"role": "user", "content": "Liste 3 países y sus capitales."}],
    temperature=0,
    max_tokens=64,
)

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

Cómo ejecutar inferencia por lotes con la API del Motor fuera de línea de SGLang y endpoints nativos

SGLang soporta múltiples “superficies de API” dependiendo de lo que esté construyendo:

El endpoint /generate es la API de tiempo de ejecución de bajo nivel. Prefiera las rutas compatibles con OpenAI /v1/... cuando desee plantillas de chat y el ecosistema de clientes habitual gestionado para usted.

Sin ningún servidor HTTP, el Motor fuera de línea ejecuta la inferencia en el proceso: adecuado para trabajos por lotes y servicios personalizados. Soporta combinaciones síncrono/asíncrono y streaming/no streaming; elija el modo que coincida con el patrón de llamada.

Ejemplo utilizando el endpoint nativo /generate

Patrón minimalista: ejecute un servidor, luego haga POST a /generate con temperature y max_new_tokens (y cualquier otro campo de muestreo que necesite).

import requests

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "La capital de Francia es",
        "sampling_params": {
            "temperature": 0,
            "max_new_tokens": 32,
        },
    },
)

print(response.json())

temperature = 0 es muestreo voraz; valores más altos aumentan la diversidad.

Ejemplo utilizando la API del Motor fuera de línea para inferencia por lotes en el proceso

Flujo típico: construya sgl.Engine(model_path=...), ejecute llm.generate(...) sobre un lote de prompts y luego llm.shutdown() para liberar GPU y otros recursos.

import sglang as sgl

llm = sgl.Engine(model_path="qwen/qwen2.5-0.5b-instruct")

prompts = [
    "Escriba una breve autointroducción.",
    "Explique qué es la caché de prefijos en un párrafo.",
]

sampling_params = {"temperature": 0.2, "top_p": 0.9}

outputs = llm.generate(prompts, sampling_params)
for prompt, output in zip(prompts, outputs):
    print("PROMPT:", prompt)
    print("OUTPUT:", output["text"])
    print()

llm.shutdown()