> 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-ru/yazykovye-modeli/mlc-llm.md).

# MLC-LLM

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

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

***

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

MLC-LLM (Machine Learning Compilation for Large Language Models) — это универсальный фреймворк, который обеспечивает эффективное развертывание больших языковых моделей на различных аппаратных бэкендах. Используя **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-bit / 8-bit** — запускайте большие модели на потребительских GPU
* **Чат-интерфейс** — встроенный веб-интерфейс для мгновенного тестирования
* **Инструменты Python и CLI** — гибкие варианты интеграции

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

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

* Рабочий API inference в production на масштабе
* Исследований и бенчмаркинга для моделей разных размеров
* Экономичного обслуживания с квантованными моделями
* Развертывания нескольких моделей на одном 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.8.1-devel-ubuntu22.04` как базовый образ в Clore.ai.
{% endhint %}

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

```
Образ Docker: nvidia/cuda:12.8.1-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: OpenAI-совместимый API доступен по адресу http://0.0.0.0:8000/v1
```

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

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

***

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

### Завершения чата (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": "Вы — полезный помощник."},
        {"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 accum)        | ★★★★☆    | \~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  # Опционально: включает отладочную конечную точку
```

Откройте интерфейс по адресу: `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"Пропускная способность: {tokens/elapsed:.1f} токенов/сек")
```

***

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

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

```yaml
version: '3.8'
services:
  mlc-llm:
    image: nvidia/cuda:12.8.1-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.8 установите:
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121

# Для серверов с CUDA 13.x установите:
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
```

***

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

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

| GPU        | VRAM  | Цена Clore.ai                               | Лучше всего для                          | Пропускная способность (Llama 3 8B Q4) |
| ---------- | ----- | ------------------------------------------- | ---------------------------------------- | -------------------------------------- |
| RTX 3090   | 24 ГБ | $0.07–0.21/ч                                | Модели 7B–13B, бюджетное обслуживание    | \~85 ток/с                             |
| RTX 4090   | 24 ГБ | $0.14–0.42/ч                                | Модели 7B–34B, быстрое обслуживание      | \~140 ток/с                            |
| A100 40 ГБ | 40 ГБ | [голое железо](https://clore.ai/bare-metal) | 34B–70B, production API                  | \~110 ток/с                            |
| A100 80 ГБ | 80 ГБ | [голое железо](https://clore.ai/bare-metal) | 70B+, обслуживание нескольких моделей    | \~130 ток/с                            |
| H100 SXM   | 80 ГБ | \~$1.04/ч                                   | Максимальная пропускная способность, FP8 | \~280 tok/s                            |

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

Для моделей 70B (например, Llama 3 70B Q4): используйте A100 40GB ([голое железо](https://clore.ai/bare-metal)) или две 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
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-ru/yazykovye-modeli/mlc-llm.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.