# Mistral.rs

**Молниеносный вывод LLM, написанный на Rust** — готовый к продакшену сервер с поддержкой GGUF, GGML, SafeTensors и совместимым с OpenAI API.

> 🦀 **Создано на Rust** для максимальной производительности | поддержка GGUF и моделей для зрения | Лицензия Apache-2.0

***

## Что такое Mistral.rs?

Mistral.rs — это высокопроизводительный движок вывода LLM, полностью написанный на **Rust**. Изначально ориентированный на модели Mistral, теперь он поддерживает весь спектр современных LLM. Основа на Rust обеспечивает:

* **Абстракции без стоимости** — отсутствие пауз из-за сборщика мусора во время вывода
* **Безопасность памяти** — никаких ошибок с нулевыми указателями или утечек памяти
* **Детерминированная производительность** — стабильная задержка без накладных расходов JVM/Python
* **Оптимизации на этапе компиляции** — SIMD, многопоточность и GPU-ядра оптимизированы на этапе сборки

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

* **Поддержка GGUF** — запуск любых квантизированных моделей (Q4\_K\_M, Q8\_0 и т.д.)
* **ISQ (In-Situ Quantization)** — квантизация на лету при загрузке
* **PagedAttention** — эффективный KV-кеш с непрерывной пакетной обработкой
* **Модели зрения и языка** — поддержка LLaVA, Phi-3 Vision, Idefics
* **Спекулятивное декодирование** — более быстрый вывод с черновыми моделями
* **X-LoRA** — масштабируемая поддержка тонконастроенных адаптеров
* **REST API, совместимый с OpenAI** — замена без изменений

### Поддерживаемые семейства моделей

| Семейство       | Формат            | Движок    |
| --------------- | ----------------- | --------- |
| Llama 2/3       | GGUF, SafeTensors | Rust CUDA |
| Mistral/Mixtral | GGUF, SafeTensors | Rust CUDA |
| Phi-2/3         | GGUF, SafeTensors | Rust CUDA |
| Gemma           | GGUF, SafeTensors | Rust CUDA |
| Qwen 2          | GGUF, SafeTensors | Rust CUDA |
| Starcoder 2     | GGUF              | Rust CUDA |
| LLaVA 1.5/1.6   | SafeTensors       | Зрение    |
| Phi-3 Vision    | SafeTensors       | Зрение    |

***

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

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

На [clore.ai](https://clore.ai) рынок:

* **Минимум:** 8 ГБ VRAM (для моделей 7B Q4)
* **Рекомендуется:** RTX 3090/4090 (24 ГБ) для больших моделей
* Требуется CUDA 11.8+

### Шаг 2: Разверните Mistral.rs в Docker

```
Docker-образ: ghcr.io/ericlbuehler/mistral.rs:cuda
```

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

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

**Доступные варианты образа:**

```bash
# CUDA (большинство серверов Clore.ai)
ghcr.io/ericlbuehler/mistral.rs:cuda

# Только CPU
ghcr.io/ericlbuehler/mistral.rs:cpu

# Metal (Apple Silicon - не для Clore.ai)
ghcr.io/ericlbuehler/mistral.rs:metal
```

### Шаг 3: Подключение и проверка

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

# Проверьте бинарный файл mistral.rs
mistralrs-server --help
```

***

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

### Быстрый старт с моделью GGUF

```bash
# Подать модель GGUF напрямую с HuggingFace
mistralrs-server \
  --port 8080 \
  --log info \
  gguf \
  -m TheBloke/Llama-2-7B-Chat-GGUF \
  -f llama-2-7b-chat.Q4_K_M.gguf
```

### Запустить Mistral 7B (SafeTensors)

```bash
mistralrs-server \
  --port 8080 \
  plain \
  -m mistralai/Mistral-7B-Instruct-v0.3 \
  --isq Q4K
```

### Запуск с In-Situ Quantization (ISQ)

ISQ квантизирует модель при загрузке — предварительно квантизированная модель не требуется:

```bash
# Загрузить Llama 3 8B и квантизировать в Q4K на лету
mistralrs-server \
  --port 8080 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K

# Доступные опции ISQ:
# Q4_0, Q4_1, Q5_0, Q5_1, Q8_0
# Q2K, Q3K, Q4K, Q5K, Q6K, Q8K
# HQQ4, HQQ8 (полуквадратичная квантизация)
```

### Модель зрения и языка

```bash
mistralrs-server \
  --port 8080 \
  vision-plain \
  -m llava-hf/llava-1.5-7b-hf \
  --isq Q4K
```

### Спекулятивная декодировка

```bash
# Используйте небольшую черновую модель для ускорения генерации
mistralrs-server \
  --port 8080 \
  speculative \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K \
  -d meta-llama/Meta-Llama-3-1B-Instruct \
  --draft-isq Q4K \
  -n 5  # Спекулятивные токены
```

{% hint style="success" %}
**Спекулятивное декодирование** может дать **2–3× ускорение** для большинства разговорных задач, где небольшая черновая модель точно предсказывает следующие токены.
{% endhint %}

***

## Использование API

### Конечные точки, совместимые с OpenAI

| Конечная точка           | Метод | Описание                                 |
| ------------------------ | ----- | ---------------------------------------- |
| `/v1/chat/completions`   | POST  | Чат-компле́ты                            |
| `/v1/completions`        | POST  | Текстовые завершения                     |
| `/v1/models`             | GET   | Список моделей                           |
| `/v1/images/generations` | POST  | Генерация изображений (VLM)              |
| `/v1/re_isq`             | POST  | Повторная квантизация загруженной модели |
| `/health`                | GET   | Проверка состояния                       |

### Пример на Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://<clore-node-ip>:<api-port>/v1",
    api_key="none"  # По умолчанию аутентификация не требуется
)

# Chat completion
response = client.chat.completions.create(
    model="llama-3-8b",  # Имя модели гибкое
    messages=[
        {"role": "system", "content": "Вы — полезный ассистент по программированию."},
        {"role": "user", "content": "Напишите функцию на Python для обращения односвязного списка"}
    ],
    temperature=0.1,  # Низкая температура для генерации кода
    max_tokens=1024
)
print(response.choices[0].message.content)
```

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

```python
with client.chat.completions.create(
    model="llama-3-8b",
    messages=[{"role": "user", "content": "Расскажи мне историю про робота."}],
    stream=True,
    max_tokens=512
) as stream:
    for chunk in stream:
        delta = chunk.choices[0].delta
        if hasattr(delta, 'content') and delta.content:
            print(delta.content, end="", flush=True)
print()
```

### Ввод изображения/зрения

```python
import base64
from pathlib import Path

# Загрузить изображение
image_data = base64.b64encode(Path("photo.jpg").read_bytes()).decode()

response = client.chat.completions.create(
    model="llava-1.5-7b",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                },
                {
                    "type": "text",
                    "text": "Что вы видите на этом изображении?"
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)
```

### Примеры cURL

```bash
# Базовый чат
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-7b",
    "messages": [{"role": "user", "content": "Что такое Rust?"}],
    "temperature": 0.7,
    "max_tokens": 256
  }'

# Список моделей
curl http://localhost:8080/v1/models

# Проверка состояния
curl http://localhost:8080/health
```

***

## Параметры конфигурации

### Флаги сервера

```bash
mistralrs-server \
  --port 8080 \                    # Порт API (по умолчанию: 1234)
  --host 0.0.0.0 \                 # Адрес привязки
  --log info \                     # Уровень логирования: off/error/warn/info/debug/trace
  --token-source env:HF_TOKEN \    # Источник токена HuggingFace
  --max-seqs 16 \                  # Максимальное количество параллельных последовательностей
  --no-paged-attn \                # Отключить PagedAttention (используйте для отладки)
  --prefix-cache-n 16 \            # Записей в префикс-кеше
  plain \                          # Подкоманда типа модели
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### Справочник по ISQ квантизации

| Опция ISQ | Биты | Качество | VRAM (7B) |
| --------- | ---- | -------- | --------- |
| `Q2K`     | 2    | ★★☆☆☆    | \~2.5GB   |
| `Q3K`     | 3    | ★★★☆☆    | \~3.5GB   |
| `Q4_0`    | 4    | ★★★★☆    | \~4.5GB   |
| `Q4K`     | 4    | ★★★★☆    | \~4.5GB   |
| `Q5K`     | 5    | ★★★★★    | \~5.5GB   |
| `Q6K`     | 6    | ★★★★★    | \~6.5GB   |
| `Q8_0`    | 8    | ★★★★★    | \~8 ГБ    |
| `HQQ4`    | 4    | ★★★★☆    | \~4.5GB   |
| `HQQ8`    | 8    | ★★★★★    | \~8 ГБ    |

{% hint style="info" %}
**HQQ (полуквадратичная квантизация)** часто достигает лучшего качества, чем GGUF Q4 на том же уровне битов, особенно для задач, следующих инструкциям.
{% endhint %}

***

## Расширенные возможности

### X-LoRA (смесь адаптеров LoRA)

Запускайте несколько тонконастроенных адаптеров, динамически выбираемых для каждого токена:

```bash
mistralrs-server \
  --port 8080 \
  x-lora-plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K \
  -x ./xlora-config.json
```

### Повторная квантизация во время выполнения

```bash
# Изменить квантизацию без перезапуска
curl http://localhost:8080/v1/re_isq \
  -H "Content-Type: application/json" \
  -d '{"isq_type": "Q8_0"}'
```

### Логирование запросов

```bash
# Включить логирование запросов в файл
mistralrs-server \
  --port 8080 \
  --log info \
  --request-logging-file ./requests.jsonl \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

***

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

### Оптимизация пропускной способности

```bash
# Увеличьте max-seqs для параллельных запросов
mistralrs-server \
  --port 8080 \
  --max-seqs 32 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### Оптимизация для низкой задержки

```bash
# Уменьшите max-seqs, отключите совместное использование префикс-кеша
mistralrs-server \
  --port 8080 \
  --max-seqs 4 \
  --prefix-cache-n 0 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### Мониторинг производительности

```bash
# Наблюдайте за использованием GPU во время вывода
watch -n 1 nvidia-smi

# Профилируйте с помощью nvtop
apt-get install nvtop && nvtop
```

***

## Docker Compose

```yaml
version: '3.8'
services:
  mistral-rs:
    image: ghcr.io/ericlbuehler/mistral.rs:cuda
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - HF_TOKEN=${HUGGING_FACE_HUB_TOKEN}
    ports:
      - "8080:8080"
    volumes:
      - hf-cache:/root/.cache/huggingface
    command: >
      mistralrs-server
      --port 8080
      --host 0.0.0.0
      --log info
      --max-seqs 16
      --token-source env:HF_TOKEN
      plain
      -m meta-llama/Meta-Llama-3-8B-Instruct
      --isq Q4K
    restart: unless-stopped

volumes:
  hf-cache:
```

***

## Сборка из исходников

Если Docker-образ не соответствует вашей версии CUDA:

```bash
# Установите Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Клонируйте и соберите
git clone https://github.com/EricLBuehler/mistral.rs.git
cd mistral.rs

# Сборка с поддержкой CUDA
cargo build --release --features cuda

# Местоположение бинарника
./target/release/mistralrs-server --help
```

{% hint style="warning" %}
**Время сборки:** Компиляция Rust медленная. Ожидайте 10–20 минут для полной сборки. Используйте `sccache` чтобы ускорить инкрементальные сборки: `cargo install sccache && RUSTC_WRAPPER=sccache cargo build --release --features cuda`
{% endhint %}

***

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

### Библиотека CUDA не найдена

```bash
# Проверьте библиотеки CUDA
ldconfig -p | grep libcuda
ls /usr/local/cuda/lib64/

# Установите путь к библиотеке
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
```

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

```bash
# Установите токен HuggingFace
export HF_TOKEN=your_token_here

# Или используйте флаг --token-source
mistralrs-server \
  --token-source env:HF_TOKEN \
  ...

# Или сначала скачайте вручную
huggingface-cli download meta-llama/Meta-Llama-3-8B-Instruct --local-dir ./llama3-8b
mistralrs-server ... plain -m ./llama3-8b --isq Q4K
```

### Порт 8080 занят

```bash
# Найдите и завершите процесс
fuser -k 8080/tcp

# Используйте другой порт
mistralrs-server --port 9090 ...
```

### Недостаточно памяти при квантизации

```bash
# ISQ квантизирует на GPU — сначала уменьшите другое использование GPU
# Или переключитесь на GGUF (предварительно квантизированное, меньше пиковой памяти)
mistralrs-server \
  gguf \
  -m TheBloke/Llama-2-7B-Chat-GGUF \
  -f llama-2-7b-chat.Q4_K_M.gguf
```

{% hint style="danger" %}
**ISQ против GGUF:** ISQ квантизирует при загрузке, используя память GPU (временный всплеск). Если у вас мало VRAM, используйте предварительно квантизированные файлы GGUF от TheBloke или аналогичных — они используют меньшую пик-память при загрузке.
{% endhint %}

***

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

Mistral.rs — нативный движок на Rust — его низкие накладные расходы означают большую пропускную способность за доллар GPU по сравнению с серверами на Python.

| GPU       | VRAM  | Цена Clore.ai | Рекомендуемое использование                                      | Пропускная способность (Mistral 7B Q4) |
| --------- | ----- | ------------- | ---------------------------------------------------------------- | -------------------------------------- |
| RTX 3090  | 24 ГБ | \~$0.12/ч     | Лучший бюджетный вариант — 7B Q4/Q8, модели для зрения           | \~120 ток/с                            |
| RTX 4090  | 24 ГБ | \~$0.70/ч     | Высокая пропускная способность 7B–34B, спекулятивная декодировка | \~200 ток/с                            |
| A100 40GB | 40 ГБ | \~$1.20/ч     | Продакшен для 34B–70B Q4                                         | \~160 ток/с                            |
| A100 80GB | 80 ГБ | \~$2.00/ч     | Полная точность 70B, мульти-модель                               | \~185 ток/с                            |

**Почему RTX 3090 здесь превосходна:** CUDA-ядра Rust в Mistral.rs избегают накладных расходов Python GIL и пауз сборщика мусора, которые мешают серверам на Python. RTX 3090, запускающая Mistral 7B Q4\_K\_M, обеспечивает ~~120 ток/с — сопоставимо с vLLM на том же железе за часть стоимости (~~$0.12/час против $1–2/час у облачных провайдеров).

**Спекулятивная декодировка:** Сочетайте большую модель (34B) с небольшой черновой моделью (3B) для 2–3× ускорения без потери качества. RTX 4090 идеальна для такого подхода.

***

## Ресурсы

* 🐙 **GitHub:** [github.com/EricLBuehler/mistral.rs](https://github.com/EricLBuehler/mistral.rs)
* 📦 **Репозиторий образов контейнеров:** [ghcr.io/ericlbuehler/mistral.rs](https://ghcr.io/ericlbuehler/mistral.rs)
* 📚 **Документация:** [ericlbuehler.github.io/mistral.rs](https://ericlbuehler.github.io/mistral.rs/mistralrs/)
* 💬 **Discord:** [discord.gg/SZrecqK8qw](https://discord.gg/SZrecqK8qw)
* 🤗 **Модели GGUF:** [huggingface.co/TheBloke](https://huggingface.co/TheBloke)


---

# 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/mistral-rs.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.