# SGLang

SGLang (Structured Generation Language) — это высокопроизводительная платформа для обслуживания LLM, разработанная командой LMSYS, известной по проектам Vicuna и Chatbot Arena. Она включает RadixAttention для совместного использования KV-кеша, эффективную поддержку MoE (Mixture of Experts) и совместимый с OpenAI API — что делает её одним из самых быстрых открытых движков для инференса, доступных на GPU-серверах CLORE.AI.

{% hint style="success" %}
Все примеры можно запускать на GPU-серверах, арендуемых через [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Требования к серверу

| Параметр           | Минимум                    | Рекомендуется        |
| ------------------ | -------------------------- | -------------------- |
| ОЗУ                | 16 ГБ                      | 32 ГБ+               |
| Видеопамять (VRAM) | 8 ГБ                       | 24 ГБ+               |
| Диск               | 50 ГБ                      | 200 ГБ+              |
| GPU                | NVIDIA Turing+ (RTX 2000+) | A100, H100, RTX 4090 |

{% hint style="info" %}
SGLang достигает наилучшей производительности на GPU Ampere+ с включённым FlashInfer. Для MoE-моделей, таких как Mixtral или DeepSeek, рекомендуется многопроцессорная конфигурация (multi-GPU).
{% endhint %}

## Быстрое развёртывание на CLORE.AI

**Docker-образ:** `lmsysorg/sglang:latest`

**Порты:** `22/tcp`, `30000/http`

**Переменные окружения:**

| Переменная             | Пример      | Описание                            |
| ---------------------- | ----------- | ----------------------------------- |
| `HF_TOKEN`             | `hf_xxx...` | Токен HuggingFace для gated-моделей |
| `CUDA_VISIBLE_DEVICES` | `0,1`       | Какие GPU использовать              |

## Пошаговая настройка

### 1. Арендуйте GPU-сервер на CLORE.AI

Перейдите на [CLORE.AI Marketplace](https://clore.ai/marketplace) и выберите сервер:

* **Модели 7B**: минимум 16 ГБ VRAM (RTX 4080, A10)
* **Модели 13B**: 24 ГБ VRAM (RTX 3090, RTX 4090, A5000)
* **Модели 70B**: 80 ГБ+ VRAM (A100 80GB) или multi-GPU
* **MoE-модели (Mixtral 8x7B)**: 48 ГБ VRAM или 2×24 ГБ

### 2. Подключитесь по SSH к вашему серверу

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

### 3. Скачайте Docker-образ SGLang

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

### 4. Запустите SGLang-сервер

**Базовый запуск (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
```

**С токеном 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 на 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 (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. Проверьте состояние сервера

```bash
# Просмотр логов
docker logs -f sglang

# Проверка состояния (подождите ~2–3 минуты, пока модель загружается)
curl http://localhost:30000/health

# Получить информацию о модели
curl http://localhost:30000/get_model_info
```

### 6. Доступ извне через прокси CLORE.AI

В вашей панели CLORE.AI доступен `http_pub` URL для порта 30000:

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

Используйте этот URL как базовый URL в любом клиенте, совместимом с OpenAI.

***

## Примеры использования

### Пример 1: OpenAI-совместимые chat completions

```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": "Вы — полезный ассистент по программированию."},
      {"role": "user", "content": "Напишите реализацию быстрой сортировки (quicksort) на Python."}
    ],
    "max_tokens": 512,
    "temperature": 0.2
  }'
```

### Пример 2: потоковый ответ (streaming response)

```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": "Объясните, как работает внимание (attention) в трансформерах."}
    ],
    "max_tokens": 800,
    "stream": true
  }' \
  --no-buffer
```

### Пример 3: Python-клиент OpenAI

```python
from openai import OpenAI

# Укажите на ваш CLORE.AI SGLang-сервер
client = OpenAI(
    base_url="http://localhost:30000/v1",
    api_key="none",  # По умолчанию SGLang не требует аутентификации
)

response = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    messages=[
        {"role": "system", "content": "Вы — эксперт по анализу данных."},
        {"role": "user", "content": "Что такое градиентный бустинг?"},
    ],
    max_tokens=400,
    temperature=0.7,
)

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

### Пример 4: пакетный инференс с помощью собственного API SGLang

Собственный API SGLang предоставляет дополнительный контроль:

```python
import requests

# Генерация completion'ов
response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "Будущее ИИ — это",
        "sampling_params": {
            "max_new_tokens": 200,
            "temperature": 0.8,
            "top_p": 0.95,
        },
    },
)
print(response.json()["text"])
```

### Пример 5: ограниченный вывод в формате JSON

SGLang поддерживает генерацию структурированного вывода:

```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": "Извлечь информацию: John Smith, 35 лет, проживает в Нью-Йорке.",
        "sampling_params": {
            "max_new_tokens": 100,
            "temperature": 0.0,
        },
        "json_schema": schema,
    },
)
print(response.json()["text"])
# Вывод: {"name": "John Smith", "age": 35, "city": "New York"}
```

***

## Конфигурация

### Ключевые параметры запуска

| Параметр                | По умолчанию           | Описание                                                            |
| ----------------------- | ---------------------- | ------------------------------------------------------------------- |
| `--model-path`          | обязательно            | ID модели HuggingFace или локальный путь                            |
| `--host`                | `127.0.0.1`            | Привязать хост (используйте `0.0.0.0` для внешнего доступа)         |
| `--port`                | `30000`                | Порт сервера                                                        |
| `--tp`                  | `1`                    | Степень тензорного параллелизма (количество GPU)                    |
| `--dp`                  | `1`                    | Степень параллелизма данных                                         |
| `--dtype`               | `auto`                 | `float16`, `bfloat16`, `float32`                                    |
| `--mem-fraction-static` | `0.88`                 | Доля VRAM для KV-кеша                                               |
| `--max-prefill-tokens`  | auto                   | Максимум токенов в одном шаге предварительного заполнения (prefill) |
| `--context-length`      | максимум модели        | Переопределить максимальную длину контекста                         |
| `--trust-remote-code`   | false                  | Разрешить пользовательский код модели                               |
| `--quantization`        | none                   | `awq`, `gptq`, `fp8`                                                |
| `--load-format`         | `auto`                 | `auto`, `pt`, `safetensors`                                         |
| `--tokenizer-path`      | такой же, как у модели | Путь к пользовательскому токенизатору                               |

### Опции квантизации

**AWQ (рекомендуется для скорости):**

```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 (для 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
```

***

## Советы по повышению производительности

### 1. RadixAttention — ключевое преимущество

RadixAttention в SGLang автоматически повторно использует KV-кеш для общих префиксов в подсказках. Это особенно полезно для:

* Чат-ботов с длинными системными подсказками
* RAG-приложений с повторяющимся контекстом
* Пакетных API-вызовов, которые разделяют один и тот же префикс

Дополнительная конфигурация не требуется — функция всегда включена.

### 2. Увеличьте размер KV-кеша

```bash
--mem-fraction-static 0.90  # Использовать 90% VRAM для KV-кеша
```

Будьте осторожны, не устанавливайте слишком высокое значение — оставьте место для весов модели.

### 3. Разбивка prefill для длинных контекстов

```bash
--chunked-prefill-size 4096  # Обрабатывать длинные подсказки по частям
```

### 4. Включите бэкенд FlashInfer

SGLang автоматически использует FlashInfer, когда он доступен (GPU Ampere+):

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

### 5. Многопроцессорный тензорный параллелизм (Multi-GPU)

Для моделей, которые не помещаются на одном GPU:

```bash
--tp 4  # Использовать 4 GPU
```

Каждый GPU должен иметь достаточно VRAM для шардирования части модели.

### 6. Настройка на пропускную способность (throughput) против задержки (latency)

**Низкая задержка (один пользователь):**

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

**Высокая пропускная способность (много пользователей):**

```bash
--max-running-requests 64 \
--schedule-policy lpm  # Планировщик по совпадению по наибольшему префиксу (Longest Prefix Match)
```

***

## Устранение неполадок

### Проблема: "torch.cuda.OutOfMemoryError"

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

**Решение:** Уменьшите долю памяти или используйте квантизацию:

```bash
--mem-fraction-static 0.80
# или
--quantization awq
```

### Проблема: Сервер не запускается (зависает при загрузке)

```bash
# Проверьте доступность CUDA
docker exec -it sglang nvidia-smi

# Проверьте прогресс скачивания модели
docker logs -f sglang 2>&1 | tail -50
```

### Проблема: "trust\_remote\_code required"

Добавьте `--trust-remote-code` в команду запуска для моделей с кастомной архитектурой (DeepSeek, Falcon и т.д.).

### Проблема: Медленная генерация на MoE-моделях

MoE-модели (Mixtral, DeepSeek) ограничены пропускной способностью памяти. Убедитесь, что вы используете:

```bash
--dtype bfloat16  # Лучше, чем float16 для MoE
--tp 2            # Разделить по GPU, если доступно
```

### Проблема: Ошибки длины контекста

```bash
# Переопределить длину контекста
--context-length 32768
```

### Проблема: Порт 30000 недоступен

Убедитесь, что порт открыт в конфигурации вашего заказа на CLORE.AI. Проверьте http\_pub URL в панели заказа, а не localhost.

***

## Ссылки

* [GitHub](https://github.com/sgl-project/sglang)
* [Документация](https://sgl-project.github.io/start/install.html)
* [Docker Hub](https://hub.docker.com/r/lmsysorg/sglang)
* [Поддерживаемые модели](https://github.com/sgl-project/sglang?tab=readme-ov-file#supported-models)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)

***

## Рекомендации по GPU от Clore.ai

| Сценарий использования  | Рекомендуемый GPU | Оц. стоимость на Clore.ai |
| ----------------------- | ----------------- | ------------------------- |
| Разработка/Тестирование | RTX 3090 (24GB)   | \~$0.12/gpu/hr            |
| Продакшен (7B–13B)      | RTX 4090 (24GB)   | \~$0.70/gpu/hr            |
| Крупные модели (70B+)   | A100 80GB / H100  | \~$1.20/gpu/hr            |

> 💡 Все примеры в этом руководстве можно развернуть на [Clore.ai](https://clore.ai/marketplace) GPU-серверах. Просматривайте доступные GPU и арендуйте по часу — без обязательств, с полным доступом root.


---

# 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-ru/yazykovye-modeli/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.