# MLC-LLM

**Универсальное развертывание LLM через компиляцию ML** — запуск любой большой языковой модели на любом оборудовании с максимальной производительностью с помощью компиляции машинного обучения.

> 🌟 **20 000+ звёзд на GitHub** | Поддерживается командой MLC AI | Лицензия Apache-2.0

***

## Что такое MLC-LLM?

MLC-LLM (компиляция машинного обучения для больших языковых моделей) — универсальная платформа, позволяющая эффективно разворачивать большие языковые модели на различных аппаратных бэкендах. Используя **TVM (Tensor Virtual Machine)** в качестве бэкенда компиляции, MLC-LLM компилирует модели LLM напрямую в нативный код для оборудования — достигая почти оптимальной производительности без аппаратно-специфической инженерии.

### Ключевые возможности

* **Универсальная поддержка оборудования** — NVIDIA CUDA, AMD ROCm, Apple Metal, Vulkan, WebGPU
* **REST API, совместимый с OpenAI** — полная замена для существующих рабочих процессов
* **Несколько форматов моделей** — Llama, Mistral, Gemma, Phi, Qwen, Falcon и другие
* **Квантование 4-бит / 8-бит** — запуск больших моделей на потребительских GPU
* **Интерфейс чата** — встроенный веб-интерфейс для мгновенного тестирования
* **Инструменты для Python и CLI** — гибкие варианты интеграции

### Зачем использовать MLC-LLM на Clore.ai?

Маркетплейс Clore.ai предоставляет доступ к высокопроизводительным GPU NVIDIA по конкурентным ставкам аренды. Подход MLC-LLM на основе компиляции выжимает максимальную пропускную способность из каждого GPU — что делает его идеальным для:

* Inference API в продакшне в масштабе
* Исследований и бенчмаркинга для моделей разных размеров
* Экономичного сервинга с квантизованными моделями
* Развёртывания нескольких моделей на одном GPU-инстансе

***

## Быстрый старт на Clore.ai

### Шаг 1: Найдите GPU-сервер

1. Перейдите на [clore.ai](https://clore.ai) маркетплейс
2. Фильтровать серверы: **NVIDIA GPU**, минимум **8 ГБ VRAM** (рекомендуется 16 ГБ+ для моделей 7B+)
3. Для оптимальной производительности: RTX 3090, RTX 4090, A100 или H100

### Шаг 2: Разверните MLC-LLM

{% hint style="info" %}
**Примечание:** MLC-LLM не публикует официальное предсобранное Docker-изображение в Docker Hub. Рекомендуемый подход к развертыванию — использовать базовое изображение NVIDIA CUDA и установить MLC-LLM через pip. Используйте `nvidia/cuda:12.1.0-devel-ubuntu22.04` в качестве базового образа на Clore.ai.
{% endhint %}

Используйте базовое изображение NVIDIA CUDA в конфигурации заказа на Clore.ai:

```
Docker Image: nvidia/cuda:12.1.0-devel-ubuntu22.04
```

**Проброс портов:**

| Порт контейнера | Назначение      |
| --------------- | --------------- |
| `22`            | Доступ по SSH   |
| `8000`          | REST API сервер |

**Рекомендуемые переменные окружения:**

```
MLC_MODEL=HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
MLC_HOST=0.0.0.0
MLC_PORT=8000
```

**Скрипт запуска** (запустить после SSH):

```bash
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121
```

### Шаг 3: Подключитесь по SSH

```bash
ssh root@<clore-node-ip> -p <assigned-ssh-port>
```

***

## Установка и настройка

### Вариант A: Использовать предскомпилированные модели (быстрее всего)

MLC-AI поддерживает библиотеку предскомпилированных моделей на Hugging Face. Компиляция не требуется:

```bash
# Загрузить и запустить предскомпилированную Llama 3 8B (квантование 4-бит)
python -m mlc_llm serve HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000
```

### Вариант B: Скомпилируйте свою модель

Для пользовательских моделей или специфических требований к квантизации:

```bash
# Шаг 1: Конвертировать веса модели
python -m mlc_llm convert_weight \
  ./path/to/model \
  --quantization q4f16_1 \
  --output ./compiled/model-q4f16_1

# Шаг 2: Сгенерировать конфигурацию модели
python -m mlc_llm gen_config \
  ./path/to/model \
  --quantization q4f16_1 \
  --conv-template llama-3 \
  --output ./compiled/model-q4f16_1

# Шаг 3: Скомпилировать модель
python -m mlc_llm compile \
  ./compiled/model-q4f16_1/mlc-chat-config.json \
  --device cuda \
  --output ./compiled/model-q4f16_1/lib.so
```

{% hint style="info" %}
**Время компиляции:** Компиляция модели 7B обычно занимает 10–30 минут при первом запуске. Скомпилированные артефакты кешируются и переиспользуются при последующих запусках.
{% endhint %}

***

## Запуск API-сервера

### Запустите сервер, совместимый с OpenAI

```bash
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --max-batch-size 4 \
  --max-total-sequence-length 8192
```

### Вывод при старте сервера

```
[2024-01-01 12:00:00] INFO: Загрузка модели из HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
[2024-01-01 12:00:15] INFO: Модель успешно загружена
[2024-01-01 12:00:15] INFO: Запуск сервера на 0.0.0.0:8000
[2024-01-01 12:00:15] INFO: API, совместимый с OpenAI, доступен по адресу http://0.0.0.0:8000/v1
```

### Доступные конечные точки API

| Конечная точка               | Метод | Описание                         |
| ---------------------------- | ----- | -------------------------------- |
| `/v1/chat/completions`       | POST  | Chat completions (формат OpenAI) |
| `/v1/completions`            | POST  | Текстовые завершения             |
| `/v1/models`                 | GET   | Список доступных моделей         |
| `/v1/debug/dump_event_trace` | GET   | Отладка производительности       |

***

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

### Chat Completions (Python)

```python
from openai import OpenAI

# Укажите адрес вашего сервера Clore.ai
client = OpenAI(
    base_url="http://<clore-node-ip>:<api-port>/v1",
    api_key="none"  # По умолчанию MLC-LLM не требует аутентификации
)

response = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Объясните квантовые вычисления простыми словами."}
    ],
    temperature=0.7,
    max_tokens=512
)

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

### Потоковый ответ

```python
stream = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[{"role": "user", "content": "Напишите короткий рассказ об ИИ."}],
    stream=True,
    max_tokens=1024
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

### Пример cURL

```bash
curl http://<clore-node-ip>:<api-port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Llama-3-8B-Instruct-q4f16_1-MLC",
    "messages": [
      {"role": "user", "content": "Сколько будет 2+2?"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'
```

***

## Доступные предскомпилированные модели

MLC-AI предоставляет готовые к использованию скомпилированные модели на Hugging Face:

### Серия Llama 3

```bash
# 8B Instruct (рекомендуется для большинства случаев использования)
HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC

# 70B Instruct (требует 40 ГБ+ VRAM или мульти-GPU)
HF://mlc-ai/Llama-3-70B-Instruct-q4f16_1-MLC
```

### Mistral / Mixtral

```bash
HF://mlc-ai/Mistral-7B-Instruct-v0.3-q4f16_1-MLC
HF://mlc-ai/Mixtral-8x7B-Instruct-v0.1-q4f16_1-MLC
```

### Gemma

```bash
HF://mlc-ai/gemma-2b-it-q4f16_1-MLC
HF://mlc-ai/gemma-7b-it-q4f16_1-MLC
```

### Phi

```bash
HF://mlc-ai/phi-2-q4f16_1-MLC
HF://mlc-ai/Phi-3-mini-4k-instruct-q4f16_1-MLC
```

{% hint style="success" %}
**Полный список моделей:** Просмотрите все предскомпилированные модели на [huggingface.co/mlc-ai](https://huggingface.co/mlc-ai)
{% endhint %}

***

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

MLC-LLM поддерживает несколько схем квантизации. Выбирайте в зависимости от вашего бюджета VRAM:

| Квантование | Биты                        | Качество | VRAM (7B) | VRAM (13B) |
| ----------- | --------------------------- | -------- | --------- | ---------- |
| `q4f16_1`   | 4-бит                       | ★★★★☆    | \~4 ГБ    | \~7 ГБ     |
| `q4f32_1`   | 4-бит (с накоплением в f32) | ★★★★☆    | \~4 ГБ    | \~7 ГБ     |
| `q8f16_1`   | 8-бит                       | ★★★★★    | \~8 ГБ    | \~14 ГБ    |
| `q0f16`     | 16-бит (без квантизации)    | ★★★★★    | \~14 ГБ   | \~26 ГБ    |
| `q0f32`     | 32-бит (без квантизации)    | ★★★★★    | \~28 ГБ   | \~52 ГБ    |

{% hint style="warning" %}
**Рекомендации по VRAM:** Всегда оставляйте 2–3 ГБ запаса для накладных расходов CUDA и KV-кеша. Модель 7B с `q4f16_1` требует \~6–7 ГБ в сумме при типичной нагрузке.
{% endhint %}

***

## Развёртывание на нескольких GPU

Для больших моделей (70B+), требующих нескольких GPU:

```bash
# Включите тензорный параллелизм по 2 GPU
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-70B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-shards 2
```

Проверьте топологию GPU перед развертыванием:

```bash
nvidia-smi topo -m  # Проверить подключение NVLink/PCIe
```

{% hint style="info" %}
**Лучшая производительность:** Мульти-GPU работает лучше всего с картами, подключёнными через NVLink (например, пары A100 80GB SXM). GPU, подключённые по PCIe, будут иметь узкие места при больших моделях.
{% endhint %}

***

## Веб-интерфейс чата

MLC-LLM включает встроенный веб-интерфейс, доступный после запуска сервера:

```bash
# Запустить сервер с включённым веб-интерфейсом
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --enable-debug  # Необязательно: включает отладочную конечную точку
```

Доступ к UI по адресу: `http://<clore-node-ip>:<api-port>`

***

## Настройка производительности

### Оптимизация размера батча

```bash
# Увеличьте размер батча для большей пропускной способности (требует больше VRAM)
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --max-batch-size 8 \
  --max-total-sequence-length 16384 \
  --prefill-chunk-size 2048
```

### Мониторинг загрузки GPU

```bash
# В отдельном терминале
watch -n 1 nvidia-smi

# Более подробный мониторинг
nvidia-smi dmon -s u  # Потоковые метрики загрузки
```

### Бенчмарк пропускной способности

```python
import time
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="none")

start = time.time()
response = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[{"role": "user", "content": "Посчитай от 1 до 100"}],
    max_tokens=512
)
elapsed = time.time() - start

tokens = response.usage.completion_tokens
print(f"Throughput: {tokens/elapsed:.1f} tokens/sec")
```

***

## Настройка Docker Compose

Для продакшен-развёртывания на Clore.ai с использованием базового образа NVIDIA CUDA и установкой MLC-LLM через pip:

```yaml
version: '3.8'
services:
  mlc-llm:
    image: nvidia/cuda:12.1.0-devel-ubuntu22.04
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    ports:
      - "8000:8000"
    volumes:
      - ./models:/root/models
      - mlc-cache:/root/.cache/mlc_llm
    command: >
      bash -c "pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121 &&
      python -m mlc_llm serve
      HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
      --host 0.0.0.0
      --port 8000
      --max-batch-size 4"
    restart: unless-stopped

volumes:
  mlc-cache:
```

***

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

### Сбой загрузки модели

```bash
# Проверьте подключение к интернету
curl -I https://huggingface.co

# Вручную загрузите с помощью huggingface-cli
pip install huggingface_hub
huggingface-cli download mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
```

### Недостаточно памяти (OOM)

```bash
# Уменьшите длину контекста
python -m mlc_llm serve MODEL \
  --max-total-sequence-length 4096  # Уменьшить от значения по умолчанию

# Используйте более агрессивное квантизирование
# Переключитесь с q8f16_1 на q4f16_1
```

### Несоответствие версии CUDA

```bash
# Проверьте версию CUDA
nvcc --version
nvidia-smi | grep CUDA

# Для серверов с CUDA 12.1 установите:
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121

# Для серверов с CUDA 12.2+ установите:
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu122 mlc-ai-nightly-cu122
```

{% hint style="danger" %}
**Распространённая ошибка:** Колёса pip MLC-LLM зависят от версии CUDA. Убедитесь, что установили вариант, соответствующий версии CUDA вашего сервера. Проверьте доступные колёса на [mlc.ai/wheels](https://mlc.ai/wheels).
{% endhint %}

### Сервер недоступен

```bash
# Убедитесь, что порт слушается
ss -tlnp | grep 8000

# Проверьте брандмауэр
iptables -L -n | grep 8000

# Сначала протестируйте локально
curl http://localhost:8000/v1/models
```

***

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

Подход компиляции MLC-LLM обеспечивает близкую к оптимальной пропускную способность на любом уровне GPU. Выбирайте в зависимости от размера модели и бюджета:

| GPU       | VRAM  | Цена Clore.ai | Лучше всего для                          | Пропускная способность (Llama 3 8B Q4) |
| --------- | ----- | ------------- | ---------------------------------------- | -------------------------------------- |
| RTX 3090  | 24 ГБ | \~$0.12/ч     | Модели 7B–13B, бюджетный сервисинг       | \~85 ток/с                             |
| RTX 4090  | 24 ГБ | \~$0.70/ч     | Модели 7B–34B, быстрый сервисинг         | \~140 ток/с                            |
| A100 40GB | 40 ГБ | \~$1.20/ч     | 34B–70B, продакшн API                    | \~110 ток/с                            |
| A100 80GB | 80 ГБ | \~$2.00/ч     | 70B+, сервинг нескольких моделей         | \~130 ток/с                            |
| H100 SXM  | 80 ГБ | \~$3.50/ч     | Максимальная пропускная способность, FP8 | \~280 ток/с                            |

**Рекомендуемая отправная точка:** RTX 3090 примерно за \~$0.12/ч — лучшее соотношение цена/производительность для сервинга Llama 3 8B и Mistral 7B через MLC-LLM. Скомпилированные кернелы извлекают почти максимальную загрузку из потребительских GPU.

Для моделей 70B (например, Llama 3 70B Q4): используйте A100 40GB (\~$1.20/ч) или две RTX 3090 с тензорным параллелизмом.

***

## Ресурсы

* 📦 **Pip-колёса:** [mlc.ai/wheels](https://mlc.ai/wheels) (устанавливается через pip, образа в Docker Hub нет)
* 🐙 **GitHub:** [github.com/mlc-ai/mlc-llm](https://github.com/mlc-ai/mlc-llm)
* 📚 **Документация:** [llm.mlc.ai/docs](https://llm.mlc.ai/docs)
* 🤗 **Предскомпилированные модели:** [huggingface.co/mlc-ai](https://huggingface.co/mlc-ai)
* 💬 **Discord:** [discord.gg/9Xpy2HGBuD](https://discord.gg/9Xpy2HGBuD)


---

# 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/mlc-llm.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.