# SGLang

SGLang (Structured Generation Language) es un framework de servicio de LLM de alto rendimiento desarrollado por el equipo LMSYS, conocido por su trabajo en Vicuna y Chatbot Arena. Cuenta con RadixAttention para el uso compartido de la caché KV, soporte eficiente para MoE (Mixture of Experts) y una API compatible con OpenAI, lo que lo convierte en uno de los motores de inferencia de código abierto más rápidos disponibles en los servidores GPU de CLORE.AI.

{% hint style="success" %}
Todos los ejemplos se pueden ejecutar en servidores GPU alquilados a través de [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Requisitos del servidor

| Parámetro | Mínimo                     | Recomendado          |
| --------- | -------------------------- | -------------------- |
| RAM       | 16 GB                      | 32 GB+               |
| VRAM      | 8 GB                       | 24 GB+               |
| Disco     | 50 GB                      | 200 GB+              |
| GPU       | NVIDIA Turing+ (RTX 2000+) | A100, H100, RTX 4090 |

{% hint style="info" %}
SGLang alcanza su mejor rendimiento en GPUs Ampere+ con FlashInfer habilitado. Para modelos MoE como Mixtral o DeepSeek, se recomiendan configuraciones multi-GPU.
{% endhint %}

## Despliegue rápido en CLORE.AI

**Imagen Docker:** `lmsysorg/sglang:latest`

**Puertos:** `22/tcp`, `30000/http`

**Variables de entorno:**

| Variable               | Ejemplo     | Descripción                                    |
| ---------------------- | ----------- | ---------------------------------------------- |
| `HF_TOKEN`             | `hf_xxx...` | Token de HuggingFace para modelos restringidos |
| `CUDA_VISIBLE_DEVICES` | `0,1`       | GPUs a usar                                    |

## Configuración paso a paso

### 1. Alquila un servidor GPU en CLORE.AI

Visita [CLORE.AI Marketplace](https://clore.ai/marketplace) y selecciona un servidor:

* **Modelos 7B**: mínimo 16 GB VRAM (RTX 4080, A10)
* **Modelos 13B**: 24 GB VRAM (RTX 3090, RTX 4090, A5000)
* **Modelos 70B**: 80 GB+ VRAM (A100 80GB) o multi-GPU
* **Modelos MoE (Mixtral 8x7B)**: 48 GB VRAM o 2× 24 GB

### 2. Conéctate por SSH a tu servidor

```bash
ssh -p <PORT> root@<SERVER_IP>
```

### 3. Obtener la imagen Docker de SGLang

```bash
docker pull lmsysorg/sglang:latest
```

### 4. Iniciar el servidor SGLang

**Lanzamiento básico (Llama 3.1 8B):**

```bash
docker run -d \
  --name sglang \
  --gpus all \
  --shm-size 16g \
  --ipc host \
  -p 30000:30000 \
  -v /root/models:/root/.cache/huggingface \
  lmsysorg/sglang:latest \
  python3 -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000
```

**Con token de HuggingFace:**

```bash
docker run -d \
  --name sglang \
  --gpus all \
  --shm-size 16g \
  --ipc host \
  -p 30000:30000 \
  -v /root/models:/root/.cache/huggingface \
  -e HF_TOKEN=hf_your_token_here \
  lmsysorg/sglang:latest \
  python3 -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000 \
    --dtype bfloat16
```

**Qwen2.5 72B en multi-GPU:**

```bash
docker run -d \
  --name sglang \
  --gpus all \
  --shm-size 32g \
  --ipc host \
  -p 30000:30000 \
  -v /root/models:/root/.cache/huggingface \
  lmsysorg/sglang:latest \
  python3 -m sglang.launch_server \
    --model-path Qwen/Qwen2.5-72B-Instruct \
    --host 0.0.0.0 \
    --port 30000 \
    --tp 2 \
    --dtype bfloat16
```

**DeepSeek-V2 (modelo MoE):**

```bash
docker run -d \
  --name sglang \
  --gpus all \
  --shm-size 32g \
  --ipc host \
  -p 30000:30000 \
  -v /root/models:/root/.cache/huggingface \
  lmsysorg/sglang:latest \
  python3 -m sglang.launch_server \
    --model-path deepseek-ai/DeepSeek-V2-Lite-Chat \
    --host 0.0.0.0 \
    --port 30000 \
    --trust-remote-code \
    --tp 1
```

### 5. Verificar la salud del servidor

```bash
# Ver registros
docker logs -f sglang

# Comprobación de salud (espera ~2-3 minutos para que cargue el modelo)
curl http://localhost:30000/health

# Obtener información del modelo
curl http://localhost:30000/get_model_info
```

### 6. Acceso desde el exterior a través del proxy de CLORE.AI

Tu panel de CLORE.AI proporciona un `http_pub` URL para el puerto 30000:

```
https://<order-id>-30000.clore.ai/
```

Usa esta URL como tu URL base en cualquier cliente compatible con OpenAI.

***

## Ejemplos de uso

### Ejemplo 1: Completaciones de chat compatibles con OpenAI

```bash
curl http://localhost:30000/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
    "messages": [
      {"role": "system", "content": "Eres un asistente útil de programación."},
      {"role": "user", "content": "Escribe una implementación de quicksort en Python."}
    ],
    "max_tokens": 512,
    "temperature": 0.2
  }'
```

### Ejemplo 2: Respuesta por streaming

```bash
curl http://localhost:30000/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
    "messages": [
      {"role": "user", "content": "Explica cómo funciona la atención en transformadores."}
    ],
    "max_tokens": 800,
    "stream": true
  }' \
  --no-buffer
```

### Ejemplo 3: Cliente OpenAI en Python

```python
from openai import OpenAI

# Apunta a tu servidor SGLang en CLORE.AI
client = OpenAI(
    base_url="http://localhost:30000/v1",
    api_key="none",  # SGLang no requiere autenticación por defecto
)

response = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    messages=[
        {"role": "system", "content": "Eres un experto en ciencia de datos."},
        {"role": "user", "content": "¿Qué es el gradient boosting?"},
    ],
    max_tokens=400,
    temperature=0.7,
)

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

### Ejemplo 4: Inferencia por lotes con la API nativa de SGLang

La API nativa de SGLang ofrece control adicional:

```python
import requests

# Generar completaciones
response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "El futuro de la IA es",
        "sampling_params": {
            "max_new_tokens": 200,
            "temperature": 0.8,
            "top_p": 0.95,
        },
    },
)
print(response.json()["text"])
```

### Ejemplo 5: Salida JSON con restricciones

SGLang soporta generación de salidas estructuradas:

```python
import requests

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "city": {"type": "string"},
    },
    "required": ["name", "age", "city"],
}

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "Extrae la información: John Smith, 35 años, vive en Nueva York.",
        "sampling_params": {
            "max_new_tokens": 100,
            "temperature": 0.0,
        },
        "json_schema": schema,
    },
)
print(response.json()["text"])
# Salida: {"name": "John Smith", "age": 35, "city": "New York"}
```

***

## Configuración

### Parámetros clave de lanzamiento

| Parámetro               | Por defecto         | Descripción                                     |
| ----------------------- | ------------------- | ----------------------------------------------- |
| `--model-path`          | requerido           | ID de modelo de HuggingFace o ruta local        |
| `--host`                | `127.0.0.1`         | Host de enlace (usar `0.0.0.0` para externo)    |
| `--port`                | `30000`             | Puerto del servidor                             |
| `--tp`                  | `1`                 | Grado de paralelismo tensorial (número de GPUs) |
| `--dp`                  | `1`                 | Grado de paralelismo de datos                   |
| `--dtype`               | `auto`              | `float16`, `bfloat16`, `float32`                |
| `--mem-fraction-static` | `0.88`              | Fracción de VRAM para la caché KV               |
| `--max-prefill-tokens`  | auto                | Máx. tokens en un paso de prefill               |
| `--context-length`      | máx. del modelo     | Anular la longitud máxima del contexto          |
| `--trust-remote-code`   | false               | Permitir código de modelo personalizado         |
| `--quantization`        | ninguna             | `awq`, `gptq`, `fp8`                            |
| `--load-format`         | `auto`              | `auto`, `pt`, `safetensors`                     |
| `--tokenizer-path`      | igual que el modelo | Ruta personalizada del tokenizador              |

### Opciones de cuantización

**AWQ (recomendado para velocidad):**

```bash
python3 -m sglang.launch_server \
  --model-path casperhansen/mistral-7b-instruct-v0.2-awq \
  --quantization awq \
  --host 0.0.0.0 \
  --port 30000
```

**FP8 (para H100/A100):**

```bash
python3 -m sglang.launch_server \
  --model-path meta-llama/Meta-Llama-3.1-8B-Instruct \
  --quantization fp8 \
  --host 0.0.0.0 \
  --port 30000
```

***

## Consejos de rendimiento

### 1. RadixAttention — La ventaja clave

RadixAttention de SGLang reutiliza automáticamente la caché KV para prefijos de prompt compartidos. Esto es especialmente potente para:

* Chatbots con prompts del sistema largos
* Aplicaciones RAG con contexto repetido
* Llamadas API por lotes que comparten el mismo prefijo

No se necesita configuración adicional: está siempre habilitado.

### 2. Aumentar el tamaño de la caché KV

```bash
--mem-fraction-static 0.90  # Usar 90% de la VRAM para la caché KV
```

Ten cuidado de no subirlo demasiado: deja espacio para los pesos del modelo.

### 3. Prefill por fragmentos para contextos largos

```bash
--chunked-prefill-size 4096  # Procesar prompts largos en fragmentos
```

### 4. Habilitar el backend FlashInfer

SGLang usa automáticamente FlashInfer cuando está disponible (GPUs Ampere+):

```bash
--attention-backend flashinfer
```

### 5. Paralelismo tensorial multi-GPU

Para modelos que no caben en una sola GPU:

```bash
--tp 4  # Usar 4 GPUs
```

Cada GPU debe tener suficiente VRAM para una porción del modelo.

### 6. Ajustar para rendimiento vs latencia

**Baja latencia (usuario único):**

```bash
--max-running-requests 4
```

**Alto rendimiento (muchos usuarios):**

```bash
--max-running-requests 64 \
--schedule-policy lpm  # Planificación Longest Prefix Match
```

***

## Solución de problemas

### Problema: "torch.cuda.OutOfMemoryError"

```
torch.cuda.OutOfMemoryError: CUDA out of memory
```

**Solución:** Reduce la fracción de memoria o usa cuantización:

```bash
--mem-fraction-static 0.80
# o
--quantization awq
```

### Problema: El servidor no arranca (se queda cargando)

```bash
# Comprobar disponibilidad de CUDA
docker exec -it sglang nvidia-smi

# Comprobar progreso de descarga del modelo
docker logs -f sglang 2>&1 | tail -50
```

### Problema: "trust\_remote\_code required"

Añade `--trust-remote-code` al comando de lanzamiento para modelos con arquitecturas personalizadas (DeepSeek, Falcon, etc.).

### Problema: Generación lenta en modelos MoE

Los modelos MoE (Mixtral, DeepSeek) están limitados por el ancho de banda de memoria. Asegúrate de usar:

```bash
--dtype bfloat16  # Mejor que float16 para MoE
--tp 2            # Repartir entre GPUs si están disponibles
```

### Problema: Errores de longitud de contexto

```bash
# Anular la longitud de contexto
--context-length 32768
```

### Problema: Puerto 30000 no accesible

Verifica que el puerto esté expuesto en la configuración de tu pedido de CLORE.AI. Revisa la URL http\_pub en el panel de tu pedido, no localhost.

***

## Enlaces

* [GitHub](https://github.com/sgl-project/sglang)
* [Documentación](https://sgl-project.github.io/start/install.html)
* [Docker Hub](https://hub.docker.com/r/lmsysorg/sglang)
* [Modelos compatibles](https://github.com/sgl-project/sglang?tab=readme-ov-file#supported-models)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)

***

## Recomendaciones de GPU de Clore.ai

| Caso de uso            | GPU recomendada  | Coste estimado en Clore.ai |
| ---------------------- | ---------------- | -------------------------- |
| Desarrollo/Pruebas     | RTX 3090 (24GB)  | \~$0.12/gpu/hr             |
| Producción (7B–13B)    | RTX 4090 (24GB)  | \~$0.70/gpu/hr             |
| Modelos grandes (70B+) | A100 80GB / H100 | \~$1.20/gpu/hr             |

> 💡 Todos los ejemplos en esta guía se pueden desplegar en [Clore.ai](https://clore.ai/marketplace) servidores GPU. Navega por las GPUs disponibles y alquila por hora: sin compromisos, acceso root completo.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/sglang.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.