# MLC-LLM

**Despliegue universal de LLM mediante compilación de ML** — ejecuta cualquier modelo de lenguaje grande en cualquier hardware con el máximo rendimiento utilizando compilación de aprendizaje automático.

> 🌟 **Más de 20.000 estrellas en GitHub** | Mantenido por el equipo MLC AI | Licencia Apache-2.0

***

## ¿Qué es MLC-LLM?

MLC-LLM (Compilación de Aprendizaje Automático para Modelos de Lenguaje Grande) es un marco universal que permite el despliegue eficiente de modelos de lenguaje grande en diversos backends de hardware. Aprovechando **TVM (Tensor Virtual Machine)** como su backend de compilación, MLC-LLM compila modelos LLM directamente a código nativo de hardware — logrando un rendimiento casi óptimo sin ingeniería específica de hardware.

### Capacidades clave

* **Compatibilidad universal de hardware** — NVIDIA CUDA, AMD ROCm, Apple Metal, Vulkan, WebGPU
* **API REST compatible con OpenAI** — reemplazo directo para flujos de trabajo existentes
* **Múltiples formatos de modelo** — Llama, Mistral, Gemma, Phi, Qwen, Falcon y más
* **Cuantización de 4 bits / 8 bits** — ejecuta modelos grandes en GPUs de consumo
* **Interfaz de chat** — UI web integrada para pruebas inmediatas
* **Herramientas Python y CLI** — opciones de integración flexibles

### ¿Por qué usar MLC-LLM en Clore.ai?

El marketplace de GPU de Clore.ai te da acceso a GPUs NVIDIA de alto rendimiento a tarifas de alquiler competitivas. El enfoque de compilación de MLC-LLM exprime el máximo rendimiento de cada GPU — haciéndolo ideal para:

* Inferencia en API de producción a escala
* Investigación y benchmarking en distintos tamaños de modelo
* Servir de forma rentable con modelos cuantizados
* Despliegue de múltiples modelos en una sola instancia GPU

***

## Inicio rápido en Clore.ai

### Paso 1: Encuentra un servidor GPU

1. Ve a [clore.ai](https://clore.ai) marketplace
2. Filtrar servidores: **GPU NVIDIA**, mínimo **8GB de VRAM** (16GB+ recomendado para modelos 7B+)
3. Para un rendimiento óptimo: RTX 3090, RTX 4090, A100 o H100

### Paso 2: Desplegar MLC-LLM

{% hint style="info" %}
**Nota:** MLC-LLM no publica una imagen Docker oficial preconstruida en Docker Hub. El enfoque de despliegue recomendado es usar una imagen base NVIDIA CUDA e instalar MLC-LLM vía pip. Usa `nvidia/cuda:12.1.0-devel-ubuntu22.04` como tu imagen base en Clore.ai.
{% endhint %}

Usa una imagen base NVIDIA CUDA en la configuración de tu pedido en Clore.ai:

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

**Mapeos de puertos:**

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

**Variables de entorno recomendadas:**

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

**Script de inicio** (ejecutar después de SSH):

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

### Paso 3: Conectar vía SSH

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

***

## Instalación y configuración

### Opción A: Usar modelos precompilados (Más rápido)

MLC-AI mantiene una biblioteca de modelos precompilados en Hugging Face. No se necesita compilación:

```bash
# Extraer y ejecutar un Llama 3 8B precompilado (cuantizado a 4 bits)
python -m mlc_llm serve HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000
```

### Opción B: Compila tu propio modelo

Para modelos personalizados o requisitos específicos de cuantización:

```bash
# Paso 1: Convertir los pesos del modelo
python -m mlc_llm convert_weight \
  ./path/to/model \
  --quantization q4f16_1 \
  --output ./compiled/model-q4f16_1

# Paso 2: Generar la configuración del modelo
python -m mlc_llm gen_config \
  ./path/to/model \
  --quantization q4f16_1 \
  --conv-template llama-3 \
  --output ./compiled/model-q4f16_1

# Paso 3: Compilar el modelo
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" %}
**Tiempo de compilación:** Compilar un modelo 7B típicamente toma 10–30 minutos en la primera ejecución. Los artefactos compilados se almacenan en caché y se reutilizan en lanzamientos posteriores.
{% endhint %}

***

## Ejecutando el servidor API

### Iniciar el servidor compatible con 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
```

### Salida de inicio del servidor

```
[2024-01-01 12:00:00] INFO: Cargando modelo desde HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
[2024-01-01 12:00:15] INFO: Modelo cargado correctamente
[2024-01-01 12:00:15] INFO: Iniciando servidor en 0.0.0.0:8000
[2024-01-01 12:00:15] INFO: API compatible con OpenAI disponible en http://0.0.0.0:8000/v1
```

### Endpoints API disponibles

| Endpoint                     | Método | Descripción                             |
| ---------------------------- | ------ | --------------------------------------- |
| `/v1/chat/completions`       | POST   | Completaciones de chat (formato OpenAI) |
| `/v1/completions`            | POST   | Completaciones de texto                 |
| `/v1/models`                 | GET    | Listar modelos disponibles              |
| `/v1/debug/dump_event_trace` | GET    | Depuración de rendimiento               |

***

## Ejemplos de uso de la API

### Completaciones de chat (Python)

```python
from openai import OpenAI

# Apunta a tu servidor Clore.ai
client = OpenAI(
    base_url="http://<ip-nodo-clore>:<puerto-api>/v1",
    api_key="none"  # MLC-LLM no requiere autenticación por defecto
)

response = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[
        {"role": "system", "content": "Eres un asistente útil."},
        {"role": "user", "content": "Explica la computación cuántica en términos simples."}
    ],
    temperature=0.7,
    max_tokens=512
)

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

### Respuesta por streaming

```python
stream = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[{"role": "user", "content": "Escribe una historia corta sobre IA."}],
    stream=True,
    max_tokens=1024
)

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

### Ejemplo 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": "¿Cuánto es 2+2?"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'
```

***

## Modelos precompilados disponibles

MLC-AI proporciona modelos compilados listos para usar en Hugging Face:

### Serie Llama 3

```bash
# 8B Instruct (recomendado para la mayoría de casos de uso)
HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC

# 70B Instruct (requiere 40GB+ de VRAM o multi-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" %}
**Lista completa de modelos:** Explora todos los modelos precompilados en [huggingface.co/mlc-ai](https://huggingface.co/mlc-ai)
{% endhint %}

***

## Opciones de cuantización

MLC-LLM soporta múltiples esquemas de cuantización. Elige según tu presupuesto de VRAM:

| Cuantización | Bits                       | Calidad | VRAM (7B) | VRAM (13B) |
| ------------ | -------------------------- | ------- | --------- | ---------- |
| `q4f16_1`    | 4 bits                     | ★★★★☆   | \~4GB     | \~7GB      |
| `q4f32_1`    | 4 bits (acumulación f32)   | ★★★★☆   | \~4GB     | \~7GB      |
| `q8f16_1`    | 8 bits                     | ★★★★★   | \~8GB     | \~14GB     |
| `q0f16`      | 16 bits (sin cuantización) | ★★★★★   | \~14GB    | \~26GB     |
| `q0f32`      | 32 bits (sin cuantización) | ★★★★★   | \~28GB    | \~52GB     |

{% hint style="warning" %}
**Recomendación de VRAM:** Siempre deja 2–3GB de margen para la sobrecarga de CUDA y la caché KV. Un modelo 7B con `q4f16_1` necesita \~6–7GB en total en una carga de trabajo típica.
{% endhint %}

***

## Despliegue multi-GPU

Para modelos grandes (70B+) que requieren múltiples GPUs:

```bash
# Habilitar paralelismo de tensores en 2 GPUs
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
```

Verifica la topología de la GPU antes de desplegar:

```bash
nvidia-smi topo -m  # Comprobar conectividad NVLink/PCIe
```

{% hint style="info" %}
**Mejor rendimiento:** Multi-GPU funciona mejor con tarjetas conectadas por NVLink (p. ej., pares A100 80GB SXM). Las GPUs conectadas por PCIe mostrarán cuellos de botella en modelos grandes.
{% endhint %}

***

## Interfaz web de chat

MLC-LLM incluye una UI web integrada accesible una vez que el servidor esté en funcionamiento:

```bash
# Inicia el servidor con la UI web habilitada
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --enable-debug  # Opcional: habilita endpoint de depuración
```

Accede a la UI en: `http://<clore-node-ip>:<api-port>`

***

## Ajuste de rendimiento

### Optimiza el tamaño de lote

```bash
# Aumenta el tamaño de lote para mayor rendimiento (requiere más 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
```

### Monitorea la utilización de la GPU

```bash
# En una terminal separada
watch -n 1 nvidia-smi

# Monitorización más detallada
nvidia-smi dmon -s u  # Métricas de utilización en streaming
```

### Medir el rendimiento (throughput)

```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": "Cuenta del 1 al 100"}],
    max_tokens=512
)
elapsed = time.time() - start

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

***

## Configuración con Docker Compose

Para un despliegue listo para producción en Clore.ai usando una imagen base NVIDIA CUDA con MLC-LLM instalado vía 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:
```

***

## Solución de problemas

### Falla la descarga del modelo

```bash
# Comprueba la conectividad a Internet
curl -I https://huggingface.co

# Descargar manualmente con huggingface-cli
pip install huggingface_hub
huggingface-cli download mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
```

### Fuera de memoria (OOM)

```bash
# Reduce la longitud del contexto
python -m mlc_llm serve MODEL \
  --max-total-sequence-length 4096  # Reducir desde el valor por defecto

# Usa una cuantización más agresiva
# Cambia de q8f16_1 a q4f16_1
```

### Incompatibilidad de versión de CUDA

```bash
# Comprueba la versión de CUDA
nvcc --version
nvidia-smi | grep CUDA

# Para servidores con CUDA 12.1, instala:
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121

# Para servidores con CUDA 12.2+, instala:
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu122 mlc-ai-nightly-cu122
```

{% hint style="danger" %}
**Trampa común:** Las ruedas pip de MLC-LLM son específicas de la versión de CUDA. Asegúrate de instalar la variante correcta que coincida con la versión de CUDA de tu servidor. Consulta las ruedas disponibles en [mlc.ai/wheels](https://mlc.ai/wheels).
{% endhint %}

### Servidor no accesible

```bash
# Verifica que el puerto esté escuchando
ss -tlnp | grep 8000

# Comprueba el firewall
iptables -L -n | grep 8000

# Prueba localmente primero
curl http://localhost:8000/v1/models
```

***

## Recomendaciones de GPU en Clore.ai

El enfoque de compilación de MLC-LLM ofrece un rendimiento casi óptimo en todos los niveles de GPU. Elige según el tamaño del modelo y el presupuesto:

| GPU       | VRAM  | Precio en Clore.ai | Mejor para                        | Throughput (Llama 3 8B Q4) |
| --------- | ----- | ------------------ | --------------------------------- | -------------------------- |
| RTX 3090  | 24 GB | \~$0.12/h          | Modelos 7B–13B, serving económico | \~85 tok/s                 |
| RTX 4090  | 24 GB | \~$0.70/h          | Modelos 7B–34B, serving rápido    | \~140 tok/s                |
| A100 40GB | 40 GB | \~$1.20/h          | 34B–70B, API de producción        | \~110 tok/s                |
| A100 80GB | 80 GB | \~$2.00/h          | 70B+, serving multi-modelo        | \~130 tok/s                |
| H100 SXM  | 80 GB | \~$3.50/hr         | Máximo rendimiento, FP8           | \~280 tok/s                |

**Punto de partida recomendado:** La RTX 3090 a \~$0.12/hr ofrece la mejor relación precio-rendimiento para servir Llama 3 8B y Mistral 7B vía MLC-LLM. Los kernels compilados extraen una utilización casi máxima de las GPUs de consumo.

Para modelos 70B (p. ej., Llama 3 70B Q4): usa A100 40GB (\~$1.20/hr) o dos RTX 3090s mediante paralelismo de tensores.

***

## Recursos

* 📦 **Pip Wheels:** [mlc.ai/wheels](https://mlc.ai/wheels) (instalar vía pip, no hay imagen en Docker Hub disponible)
* 🐙 **GitHub:** [github.com/mlc-ai/mlc-llm](https://github.com/mlc-ai/mlc-llm)
* 📚 **Documentación:** [llm.mlc.ai/docs](https://llm.mlc.ai/docs)
* 🤗 **Modelos precompilados:** [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-es/modelos-de-lenguaje/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.