> 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-es/modelos-de-lenguaje/mistral-rs.md).

# Mistral.rs

**Inferencia LLM ultrarrápida escrita en Rust** — servidor listo para producción con compatibilidad con GGUF, GGML, SafeTensors y API compatible con OpenAI.

> 🦀 **Construido en Rust** para máximo rendimiento | compatibilidad con 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 completamente en **Rust**. Originalmente centrado en modelos Mistral, ahora admite todo el panorama de los LLM modernos. La base de Rust proporciona:

* **Abstracciones de costo cero** — sin pausas por recolección de basura durante la inferencia
* **Seguridad de memoria** — sin excepciones por punteros nulos ni fugas de memoria
* **Rendimiento determinista** — latencia constante sin la sobrecarga de JVM/Python
* **Optimizaciones en tiempo de compilación** — SIMD, hilos y kernels GPU optimizados en tiempo de compilación

### Características clave

* **Compatibilidad con GGUF** — ejecuta cualquier modelo cuantizado (Q4\_K\_M, Q8\_0, etc.)
* **ISQ (cuantización in situ)** — cuantiza sobre la marcha al cargar
* **PagedAttention** — caché KV eficiente con batching continuo
* **Modelos de visión y lenguaje** — compatibilidad con LLaVA, Phi-3 Vision e Idefics
* **Decodificación especulativa** — inferencia más rápida con modelos borrador
* **X-LoRA** — compatibilidad escalable con adaptadores afinados
* **API REST compatible con OpenAI** — reemplazo directo

### Familias de modelos compatibles

| Familia         | Formato           | Motor        |
| --------------- | ----------------- | ------------ |
| Llama 2/3       | GGUF, SafeTensors | CUDA en Rust |
| Mistral/Mixtral | GGUF, SafeTensors | CUDA en Rust |
| Phi-2/3         | GGUF, SafeTensors | CUDA en Rust |
| Gemma           | GGUF, SafeTensors | CUDA en Rust |
| Qwen 2          | GGUF, SafeTensors | CUDA en Rust |
| Starcoder 2     | GGUF              | CUDA en Rust |
| 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:** 8 GB de VRAM (para modelos Q4 de 7B)
* **Recomendado:** RTX 3090/4090 (24 GB) para modelos más grandes
* Se requiere CUDA 11.8+

### Paso 2: Desplegar el Docker de Mistral.rs

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

**Mapeo de puertos:**

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

**Variantes de imagen disponibles:**

```bash
# CUDA (la mayoría de los servidores de 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>

# Comprueba el binario de mistral.rs
mistralrs-server --help
```

***

## Ejecutando el servidor

### Inicio rápido con modelo GGUF

```bash
# Sirve 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 al cargar — no se necesita un modelo precuantizado:

```bash
# Carga Llama 3 8B y cuantiza a Q4K sobre la marcha
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 Half-Quadratic)
```

### Modelo de visión y lenguaje

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

### Decodificación especulativa

```bash
# Usa un pequeño modelo borrador 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 **una aceleración de 2–3x** para la mayoría de las cargas de trabajo conversacionales donde el pequeño modelo borrador predice con precisión los siguientes tokens.
{% endhint %}

***

## Uso de la API

### Puntos finales compatibles con OpenAI

| Endpoint                 | Método | Descripción                   |
| ------------------------ | ------ | ----------------------------- |
| `/v1/chat/completions`   | POST   | Completaciones de chat        |
| `/v1/completions`        | POST   | Completions de texto          |
| `/v1/models`             | GET    | Listar modelos                |
| `/v1/images/generations` | POST   | Generación de imágenes (VLMs) |
| `/v1/re_isq`             | POST   | Recuantizar el modelo cargado |
| `/health`                | GET    | Comprobación de estado        |

### Ejemplo en Python

```python
from openai import OpenAI

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

# Finalización de chat
response = client.chat.completions.create(
    model="llama-3-8b",  # El nombre del modelo es flexible
    messages=[
        {"role": "system", "content": "Eres un asistente de programación útil."},
        {"role": "user", "content": "Escribe una función de 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 en streaming

```python
con 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 de 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
  }'

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

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

***

## Opciones de configuración

### Flags del servidor

```bash
mistralrs-server \\
  --port 8080 \\                    # Puerto de la API (predeterminado: 1234)
  --host 0.0.0.0 \\                 # Dirección de enlace
  --log info \\                     # Nivel de registro: 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 \\                # Deshabilita PagedAttention (úsalo para depuración)
  --prefix-cache-n 16 \\            # Entradas de caché de prefijos
  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.5 GB  |
| `Q3K`      | 3    | ★★★☆☆   | \~3.5 GB  |
| `Q4_0`     | 4    | ★★★★☆   | \~4.5 GB  |
| `Q4K`      | 4    | ★★★★☆   | \~4.5 GB  |
| `Q5K`      | 5    | ★★★★★   | \~5.5 GB  |
| `Q6K`      | 6    | ★★★★★   | \~6.5 GB  |
| `Q8_0`     | 8    | ★★★★★   | \~8 GB    |
| `HQQ4`     | 4    | ★★★★☆   | \~4.5 GB  |
| `HQQ8`     | 8    | ★★★★★   | \~8 GB    |

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

***

## Funciones avanzadas

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

Ejecuta múltiples adaptadores afinados que se seleccionan 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
```

### Recuantización en tiempo de ejecución

```bash
# Cambia 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
# Habilita el registro de solicitudes en archivo
mistralrs-server \\
  --port 8080 \\
  --log info \\
  --request-logging-file ./requests.jsonl \\
  plain \\
  -m meta-llama/Meta-Llama-3-8B-Instruct \\
  --isq Q4K
```

***

## Ajuste del rendimiento

### Optimizar para rendimiento

```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, deshabilita la compartición de caché de prefijos
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
# Observa el uso de la GPU durante la inferencia
watch -n 1 nvidia-smi

# Perfila 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:
```

***

## Compilación desde el código fuente

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

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

# Clona y compila
git clone https://github.com/EricLBuehler/mistral.rs.git
cd mistral.rs

# Compila con compatibilidad con 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 entre 10 y 20 minutos para una compilación completa. Usa `sccache` para acelerar las compilaciones incrementales: `cargo install sccache && RUSTC_WRAPPER=sccache cargo build --release --features cuda`
{% endhint %}

***

## Solución de problemas

### Biblioteca CUDA no encontrada

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

# Establece la ruta de las bibliotecas
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
```

### Fallo en la descarga del modelo

```bash
# Establece el token de HuggingFace
export HF_TOKEN=your_token_here

# O usa la bandera --token-source
mistralrs-server \\
  --token-source env:HF_TOKEN \\
  ...

# O descarga 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
# Encuentra y termina el proceso
fuser -k 8080/tcp

# Usa un puerto diferente
mistralrs-server --port 9090 ...
```

### Memoria insuficiente durante la cuantización

```bash
# ISQ cuantiza en la GPU — reduce primero el uso de otras GPU
# O cambia a GGUF (precuantizado, 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 al cargar usando memoria de la GPU (pico temporal). Si vas justo de VRAM, usa archivos GGUF precuantizados de TheBloke o similares — utilizan menos memoria pico durante la carga.
{% endhint %}

***

## Recomendaciones de GPU para Clore.ai

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

| GPU       | VRAM  | Precio de Clore.ai                        | Uso recomendado                                              | Rendimiento (Mistral 7B Q4) |
| --------- | ----- | ----------------------------------------- | ------------------------------------------------------------ | --------------------------- |
| RTX 3090  | 24 GB | $0.07–0.21/h                              | Mejor opción económica — modelos 7B Q4/Q8, modelos de visión | \~120 tok/s                 |
| RTX 4090  | 24 GB | $0.14–0.42/h                              | 7B–34B de alto rendimiento, decodificación especulativa      | \~200 tok/s                 |
| A100 40GB | 40 GB | [bare metal](https://clore.ai/bare-metal) | Servicio en producción Q4 de 34B–70B                         | \~160 tok/s                 |
| A100 80GB | 80 GB | [bare metal](https://clore.ai/bare-metal) | 70B de precisión completa, multimodelo                       | \~185 tok/s                 |

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

**Decodificación especulativa:** Combina un modelo grande (34B) con un pequeño modelo borrador (3B) para obtener una aceleración de 2–3x sin pérdida de calidad. 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
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-es/modelos-de-lenguaje/mistral-rs.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.