# Mistral.rs

**Inferencia LLM rapidísima escrita en Rust** — servidor listo para producción con soporte GGUF, GGML, SafeTensors y API compatible con OpenAI.

> 🦀 **Construido en Rust** para rendimiento máximo | Soporte GGUF y modelos de visión | Licencia Apache-2.0

***

## ¿Qué es Mistral.rs?

Mistral.rs es un motor de inferencia LLM de alto rendimiento escrito íntegramente en **Rust**. Originalmente centrado en los modelos Mistral, ahora admite todo el panorama de LLMs modernos. La base en Rust ofrece:

* **Abstracciones sin costo** — sin pausas de recolección de basura durante la inferencia
* **Seguridad de memoria** — sin excepciones de puntero nulo ni fugas de memoria
* **Rendimiento determinista** — latencia consistente sin la sobrecarga de JVM/Python
* **Optimizaciones en tiempo de compilación** — SIMD, subprocesos y kernels GPU optimizados en tiempo de compilación

### Características clave

* **Soporte GGUF** — ejecutar cualquier modelo cuantizado (Q4\_K\_M, Q8\_0, etc.)
* **ISQ (Cuantización In-Situ)** — cuantizar al vuelo en el momento de la carga
* **PagedAttention** — caché KV eficiente con agrupamiento continuo
* **Modelos Visión-Lenguaje** — soporte para LLaVA, Phi-3 Vision, Idefics
* **Decodificación especulativa** — inferencia más rápida con modelos borrador
* **X-LoRA** — soporte escalable para adaptadores afinados
* **API REST compatible con OpenAI** — reemplazo plug-and-play

### Familias de modelos compatibles

| Familia         | Formato           | Motor     |
| --------------- | ----------------- | --------- |
| 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       | Visión    |
| Phi-3 Vision    | SafeTensors       | Visión    |

***

## Inicio rápido en Clore.ai

### Paso 1: Encuentra un servidor GPU

En [clore.ai](https://clore.ai) mercado:

* **Mínimo:** 8GB VRAM (para modelos 7B Q4)
* **Recomendado:** RTX 3090/4090 (24GB) para modelos más grandes
* Se requiere CUDA 11.8+

### Paso 2: Desplegar Mistral.rs con Docker

```
Imagen Docker: ghcr.io/ericlbuehler/mistral.rs:cuda
```

**Mapeos de puertos:**

| Puerto del contenedor | Propósito         |
| --------------------- | ----------------- |
| `22`                  | Acceso SSH        |
| `8080`                | Servidor REST API |

**Variantes de imagen disponibles:**

```bash
# CUDA (la mayoría de servidores Clore.ai)
ghcr.io/ericlbuehler/mistral.rs:cuda

# Solo CPU
ghcr.io/ericlbuehler/mistral.rs:cpu

# Metal (Apple Silicon - no para Clore.ai)
ghcr.io/ericlbuehler/mistral.rs:metal
```

### Paso 3: Conectar y verificar

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

# Verificar binario mistral.rs
mistralrs-server --help
```

***

## Ejecutando el servidor

### Inicio rápido con modelo GGUF

```bash
# Servir un modelo GGUF directamente desde HuggingFace
mistralrs-server \
  --port 8080 \
  --log info \
  gguf \
  -m TheBloke/Llama-2-7B-Chat-GGUF \
  -f llama-2-7b-chat.Q4_K_M.gguf
```

### Servir Mistral 7B (SafeTensors)

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

### Servir con Cuantización In-Situ (ISQ)

ISQ cuantiza el modelo en el momento de la carga — no se necesita un modelo pre-cuantizado:

```bash
# Cargar Llama 3 8B y cuantizar a Q4K al vuelo
mistralrs-server \
  --port 8080 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K

# Opciones ISQ disponibles:
# Q4_0, Q4_1, Q5_0, Q5_1, Q8_0
# Q2K, Q3K, Q4K, Q5K, Q6K, Q8K
# HQQ4, HQQ8 (Cuantización Semi-Cuadrática)
```

### Modelo Visión-Lenguaje

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

### Decodificación especulativa

```bash
# Usar un modelo borrador pequeño para acelerar la generación
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  # Tokens especulativos
```

{% hint style="success" %}
**Decodificación especulativa** puede proporcionar **aceleración de 2–3x** para la mayoría de cargas conversacionales donde el modelo borrador pequeño predice con precisión los siguientes tokens.
{% endhint %}

***

## Uso de la API

### Endpoints compatibles con OpenAI

| Endpoint                 | Método | Descripción                   |
| ------------------------ | ------ | ----------------------------- |
| `/v1/chat/completions`   | POST   | Completados de chat           |
| `/v1/completions`        | POST   | Completaciones de texto       |
| `/v1/models`             | GET    | Listar modelos                |
| `/v1/images/generations` | POST   | Generación de imágenes (VLMs) |
| `/v1/re_isq`             | POST   | Re-cuantizar modelo cargado   |
| `/health`                | GET    | Verificación de salud         |

### Ejemplo en Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://<ip-nodo-clore>:<puerto-api>/v1",
    api_key="none"  # No se requiere autenticación por defecto
)

# Completado de chat
response = client.chat.completions.create(
    model="llama-3-8b",  # El nombre del modelo es flexible
    messages=[
        {"role": "system", "content": "Eres un asistente útil de programación."},
        {"role": "user", "content": "Escribe una función en Python para invertir una lista enlazada"}
    ],
    temperature=0.1,  # Temperatura baja para generación de código
    max_tokens=1024
)
print(response.choices[0].message.content)
```

### Respuesta por streaming

```python
with client.chat.completions.create(
    model="llama-3-8b",
    messages=[{"role": "user", "content": "Cuéntame una historia sobre un robot."}],
    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()
```

### Entrada de visión/imagen

```python
import base64
from pathlib import Path

# Cargar imagen
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": "¿Qué ves en esta imagen?"
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)
```

### Ejemplos cURL

```bash
# Chat básico
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-7b",
    "messages": [{"role": "user", "content": "¿Qué es Rust?"}],
    "temperature": 0.7,
    "max_tokens": 256
  }'

# Listar modelos
curl http://localhost:8080/v1/models

# Verificación de salud
curl http://localhost:8080/health
```

***

## Opciones de configuración

### Flags del servidor

```bash
mistralrs-server \
  --port 8080 \                    # Puerto API (por defecto: 1234)
  --host 0.0.0.0 \                 # Dirección de enlace
  --log info \                     # Nivel de log: off/error/warn/info/debug/trace
  --token-source env:HF_TOKEN \    # Fuente del token de HuggingFace
  --max-seqs 16 \                  # Máximo de secuencias concurrentes
  --no-paged-attn \                # Deshabilitar PagedAttention (usar para depuración)
  --prefix-cache-n 16 \            # Entradas de caché de prefijo
  plain \                          # Subcomando de tipo de modelo
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### Referencia de cuantización ISQ

| Opción ISQ | Bits | Calidad | 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    | ★★★★★   | \~8GB     |
| `HQQ4`     | 4    | ★★★★☆   | \~4.5GB   |
| `HQQ8`     | 8    | ★★★★★   | \~8GB     |

{% hint style="info" %}
**HQQ (Cuantización Semi-Cuadrática)** a menudo logra mejor calidad que GGUF Q4 al mismo nivel de bits, especialmente para tareas que siguen instrucciones.
{% endhint %}

***

## Funciones avanzadas

### X-LoRA (Mezcla de adaptadores LoRA)

Ejecutar múltiples adaptadores afinados seleccionados dinámicamente por token:

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

### Re-cuantizar en tiempo de ejecución

```bash
# Cambiar la cuantización sin reiniciar
curl http://localhost:8080/v1/re_isq \
  -H "Content-Type: application/json" \
  -d '{"isq_type": "Q8_0"}'
```

### Registro de solicitudes

```bash
# Habilitar registro de solicitudes a archivo
mistralrs-server \
  --port 8080 \
  --log info \
  --request-logging-file ./requests.jsonl \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

***

## Ajuste de rendimiento

### Optimizar para rendimiento (Throughput)

```bash
# Mayor max-seqs para solicitudes concurrentes
mistralrs-server \
  --port 8080 \
  --max-seqs 32 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### Optimizar para baja latencia

```bash
# Menor max-seqs, deshabilitar compartir caché de prefijo
mistralrs-server \
  --port 8080 \
  --max-seqs 4 \
  --prefix-cache-n 0 \
  plain \
  -m meta-llama/Meta-Llama-3-8B-Instruct \
  --isq Q4K
```

### Monitorear rendimiento

```bash
# Vigilar uso de GPU durante la inferencia
watch -n 1 nvidia-smi

# Perfilar con 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:
```

***

## Construir desde el código fuente

Si la imagen Docker no coincide con tu versión de CUDA:

```bash
# Instalar Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Clonar y compilar
git clone https://github.com/EricLBuehler/mistral.rs.git
cd mistral.rs

# Compilar con soporte CUDA
cargo build --release --features cuda

# Ubicación del binario
./target/release/mistralrs-server --help
```

{% hint style="warning" %}
**Tiempo de compilación:** La compilación de Rust es lenta. Espera 10–20 minutos para una compilación completa. Usa `sccache` para acelerar compilaciones incrementales: `cargo install sccache && RUSTC_WRAPPER=sccache cargo build --release --features cuda`
{% endhint %}

***

## Solución de problemas

### Biblioteca CUDA no encontrada

```bash
# Verificar bibliotecas CUDA
ldconfig -p | grep libcuda
ls /usr/local/cuda/lib64/

# Establecer ruta de bibliotecas
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
```

### Falla la descarga del modelo

```bash
# Establecer token de HuggingFace
export HF_TOKEN=your_token_here

# O usar la opción --token-source
mistralrs-server \
  --token-source env:HF_TOKEN \
  ...

# O descargar manualmente primero
huggingface-cli download meta-llama/Meta-Llama-3-8B-Instruct --local-dir ./llama3-8b
mistralrs-server ... plain -m ./llama3-8b --isq Q4K
```

### Puerto 8080 en uso

```bash
# Encontrar y terminar proceso
fuser -k 8080/tcp

# Usar otro puerto
mistralrs-server --port 9090 ...
```

### Memoria insuficiente durante la cuantización

```bash
# ISQ cuantiza en GPU — reduce primero otros usos de GPU
# O cambia a GGUF (pre-cuantizado, menor memoria pico)
mistralrs-server \
  gguf \
  -m TheBloke/Llama-2-7B-Chat-GGUF \
  -f llama-2-7b-chat.Q4_K_M.gguf
```

{% hint style="danger" %}
**ISQ vs GGUF:** ISQ cuantiza en el momento de la carga usando memoria GPU (pico temporal). Si tienes poca VRAM, usa archivos GGUF pre-cuantizados de TheBloke o similares — usan menor memoria pico durante la carga.
{% endhint %}

***

## Recomendaciones de GPU en Clore.ai

Mistral.rs es un motor nativo en Rust — su baja sobrecarga significa que obtienes más rendimiento por dólar de GPU frente a servidores basados en Python.

| GPU       | VRAM  | Precio en Clore.ai | Uso recomendado                                      | Rendimiento (Mistral 7B Q4) |
| --------- | ----- | ------------------ | ---------------------------------------------------- | --------------------------- |
| RTX 3090  | 24 GB | \~$0.12/h          | Mejor opción económica — 7B Q4/Q8, modelos de visión | \~120 tok/s                 |
| RTX 4090  | 24 GB | \~$0.70/h          | Alto rendimiento 7B–34B, decodificación especulativa | \~200 tok/s                 |
| A100 40GB | 40 GB | \~$1.20/h          | Producción 34B–70B servicio Q4                       | \~160 tok/s                 |
| A100 80GB | 80 GB | \~$2.00/h          | Precisión completa 70B, multi-modelo                 | \~185 tok/s                 |

**Por qué la RTX 3090 destaca aquí:** Los kernels Rust CUDA de Mistral.rs evitan la sobrecarga del GIL de Python y las pausas de recolección de basura que afectan a los servidores Python. Una RTX 3090 ejecutando Mistral 7B Q4\_K\_M ofrece ~~120 tok/s — comparable a vLLM en el mismo hardware a una fracción del costo (~~$0.12/hr frente a proveedores en la nube que cobran $1–2/hr).

**Decodificación especulativa:** Empareja un modelo grande (34B) con un modelo borrador pequeño (3B) para una aceleración de 2–3× sin pérdida de calidad. La RTX 4090 es ideal para este patrón.

***

## Recursos

* 🐙 **GitHub:** [github.com/EricLBuehler/mistral.rs](https://github.com/EricLBuehler/mistral.rs)
* 📦 **Registro de contenedores:** [ghcr.io/ericlbuehler/mistral.rs](https://ghcr.io/ericlbuehler/mistral.rs)
* 📚 **Documentación:** [ericlbuehler.github.io/mistral.rs](https://ericlbuehler.github.io/mistral.rs/mistralrs/)
* 💬 **Discord:** [discord.gg/SZrecqK8qw](https://discord.gg/SZrecqK8qw)
* 🤗 **Modelos 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-es/modelos-de-lenguaje/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.