> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/sglang.md).

# SGLang

Despliega SGLang para servicio de LLM de alto rendimiento con RadixAttention en GPUs de Clore.ai

SGLang (Structured Generation Language) es un marco de servicio de LLM de alto rendimiento desarrollado por el equipo de LMSYS, conocido por su trabajo en Vicuna y Chatbot Arena. Incluye RadixAttention para compartir la caché KV, soporte eficiente para MoE (Mezcla de Expertos) 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 [Marketplace de CLORE.AI](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 el mejor rendimiento en GPUs Ampere+ con FlashInfer habilitado. Para modelos MoE como Mixtral o DeepSeek, se recomiendan configuraciones con varias GPUs.
{% endhint %}

## Despliegue rápido en CLORE.AI

**Imagen de 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 [Marketplace de CLORE.AI](https://clore.ai/marketplace) y selecciona un servidor:

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

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

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

### 3. Descarga la imagen Docker de SGLang

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

### 4. Inicia el servidor SGLang

**Inicio 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 varias GPUs:**

```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. Comprueba el estado del servidor

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

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

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

### 6. Accede desde fuera mediante el 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: finalizaciones 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 de programación útil."},
      {"role": "user", "content": "Escribe una implementación de quicksort en Python."}
    ],
    "max_tokens": 512,
    "temperature": 0.2
  }'
```

### Ejemplo 2: respuesta en 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 de transformers."}
    ],
    "max_tokens": 800,
    "stream": true
  }' \\
  --no-buffer
```

### Ejemplo 3: cliente Python OpenAI

```python
from openai import OpenAI

# Apunta a tu servidor SGLang de 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 finalizaciones
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 restringida

SGLang admite 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": "Nueva York"}
```

***

## Configuración

### Parámetros clave de lanzamiento

| Parámetro               | Predeterminado      | Descripción                                     |
| ----------------------- | ------------------- | ----------------------------------------------- |
| `--model-path`          | obligatorio         | ID del modelo en HuggingFace o ruta local       |
| `--host`                | `127.0.0.1`         | Host de enlace (usa `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áximo de tokens en un paso de prefill          |
| `--context-length`      | máximo del modelo   | Sobrescribe la longitud máxima del contexto     |
| `--trust-remote-code`   | false               | Permite código personalizado del modelo         |
| `--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 por 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 prompts compartidos. Esto es especialmente potente para:

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

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

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

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

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

### 3. Prefill por bloques para contextos largos

```bash
--chunked-prefill-size 4096  # Procesa prompts largos en bloques
```

### 4. Habilita el backend FlashInfer

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

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

### 5. Paralelismo tensorial en varias GPUs

Para modelos que no caben en una sola GPU:

```bash
--tp 4  # Usa 4 GPUs
```

Cada GPU debe tener suficiente VRAM para una parte del modelo.

### 6. Ajusta para rendimiento vs latencia

**Baja latencia (un solo usuario):**

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

**Alto rendimiento (muchos usuarios):**

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

***

## Solución de problemas

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

```
torch.cuda.OutOfMemoryError: memoria CUDA insuficiente
```

**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
# Comprueba la disponibilidad de CUDA
docker exec -it sglang nvidia-smi

# Comprueba el progreso de la 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            # Divide entre GPUs si están disponibles
```

### Problema: errores de longitud de contexto

```bash
# Sobrescribe la longitud del contexto
--context-length 32768
```

### Problema: el puerto 30000 no es accesible

Verifica que el puerto esté expuesto en la configuración de tu pedido de CLORE.AI. Consulta 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)
* [Marketplace de CLORE.AI](https://clore.ai/marketplace)

***

## Recomendaciones de GPU para Clore.ai

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.