> 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-fr/modeles-de-langage/mlc-llm.md).

# MLC-LLM

**Déploiement universel de LLM via la compilation ML** — exécutez n'importe quel grand modèle de langage sur n'importe quel matériel avec des performances maximales grâce à la compilation pour l'apprentissage automatique.

> 🌟 **20 000+ étoiles sur GitHub** | Maintenu par l'équipe MLC AI | Licence Apache-2.0

***

## Qu'est-ce que MLC-LLM ?

MLC-LLM (Machine Learning Compilation for Large Language Models) est un cadre universel qui permet le déploiement efficace de grands modèles de langage sur divers backends matériels. En tirant parti de **TVM (Tensor Virtual Machine)** comme backend de compilation, MLC-LLM compile les modèles LLM directement en code natif pour le matériel — atteignant des performances quasi optimales sans ingénierie spécifique au matériel.

### Capacités clés

* **Prise en charge universelle du matériel** — NVIDIA CUDA, AMD ROCm, Apple Metal, Vulkan, WebGPU
* **API REST compatible OpenAI** — remplacement direct pour les workflows existants
* **Formats de modèles multiples** — Llama, Mistral, Gemma, Phi, Qwen, Falcon, et plus
* **Quantification 4-bit / 8-bit** — exécutez de grands modèles sur des GPU grand public
* **Interface de discussion** — interface web intégrée pour des tests immédiats
* **Outils Python & CLI** — options d'intégration flexibles

### Pourquoi utiliser MLC-LLM sur Clore.ai ?

La place de marché GPU de Clore.ai vous donne accès à des GPU NVIDIA haute performance à des tarifs de location compétitifs. L'approche de compilation de MLC-LLM maximise le débit de chaque GPU — ce qui le rend idéal pour :

* Inférence d'API en production à grande échelle
* Recherche et benchmarking sur différentes tailles de modèles
* Service économique avec modèles quantifiés
* Déploiement multi-modèles sur une seule instance GPU

***

## Démarrage rapide sur Clore.ai

### Étape 1 : Trouver un serveur GPU

1. Aller à [clore.ai](https://clore.ai) place de marché
2. Filtrer les serveurs : **GPU NVIDIA**, minimum **8 Go de VRAM** (16 Go+ recommandé pour les modèles 7B+)
3. Pour des performances optimales : RTX 3090, RTX 4090, A100 ou H100

### Étape 2 : Déployer MLC-LLM

{% hint style="info" %}
**Remarque :** MLC-LLM ne publie pas d'image Docker pré-construite officielle sur Docker Hub. L'approche de déploiement recommandée est d'utiliser une image de base NVIDIA CUDA et d'installer MLC-LLM via pip. Utilisez `nvidia/cuda:12.1.0-devel-ubuntu22.04` comme image de base sur Clore.ai.
{% endhint %}

Utilisez une image de base NVIDIA CUDA dans la configuration de votre commande Clore.ai :

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

**Mappages de ports :**

| Port du conteneur | Usage            |
| ----------------- | ---------------- |
| `22`              | Accès SSH        |
| `8000`            | Serveur API REST |

**Variables d'environnement recommandées :**

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

**Script de démarrage** (exécuter après SSH) :

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

### Étape 3 : Se connecter via SSH

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

***

## Installation et configuration

### Option A : Utiliser des modèles pré-compilés (le plus rapide)

MLC-AI maintient une bibliothèque de modèles pré-compilés sur Hugging Face. Aucune compilation requise :

```bash
# Récupérer et exécuter un Llama 3 8B pré-compilé (quantifié 4 bits)
python -m mlc_llm serve HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000
```

### Option B : Compiler votre propre modèle

Pour des modèles personnalisés ou des exigences spécifiques de quantification :

```bash
# Étape 1 : Convertir les poids du modèle
python -m mlc_llm convert_weight \
  ./chemin/vers/le/model \
  --quantization q4f16_1 \
  --output ./compiled/model-q4f16_1

# Étape 2 : Générer la configuration du modèle
python -m mlc_llm gen_config \
  ./chemin/vers/le/model \
  --quantization q4f16_1 \
  --conv-template llama-3 \
  --output ./compiled/model-q4f16_1

# Étape 3 : Compiler le modèle
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" %}
**Temps de compilation :** La compilation d'un modèle 7B prend généralement 10 à 30 minutes lors de la première exécution. Les artefacts compilés sont mis en cache et réutilisés lors des lancements suivants.
{% endhint %}

***

## Exécution du serveur API

### Démarrer le serveur compatible 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
```

### Sortie du démarrage du serveur

```
[2024-01-01 12:00:00] INFO : Chargement du modèle depuis HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
[2024-01-01 12:00:15] INFO : Modèle chargé avec succès
[2024-01-01 12:00:15] INFO : Démarrage du serveur sur 0.0.0.0:8000
[2024-01-01 12:00:15] INFO : API compatible OpenAI disponible à http://0.0.0.0:8000/v1
```

### Points de terminaison API disponibles

| Point de terminaison         | Méthode | Description                         |
| ---------------------------- | ------- | ----------------------------------- |
| `/v1/chat/completions`       | POST    | Complétions de chat (format OpenAI) |
| `/v1/completions`            | POST    | Complétions de texte                |
| `/v1/models`                 | GET     | Lister les modèles disponibles      |
| `/v1/debug/dump_event_trace` | GET     | Débogage des performances           |

***

## Exemples d'utilisation de l'API

### Complétions de chat (Python)

```python
from openai import OpenAI

# Pointez vers votre serveur Clore.ai
client = OpenAI(
    base_url="http://<clore-node-ip>:<api-port>/v1",
    api_key="none"  # MLC-LLM n'exige pas d'authentification par défaut
)

response = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Expliquez l'informatique quantique en termes simples."}
    ],
    temperature=0.7,
    max_tokens=512
)

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

### Réponse en streaming

```python
stream = client.chat.completions.create(
    model="Llama-3-8B-Instruct-q4f16_1-MLC",
    messages=[{"role": "user", "content": "Écris une courte histoire sur l'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)
```

### Exemple 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": "Quel est 2+2 ?"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'
```

***

## Modèles pré-compilés disponibles

MLC-AI fournit des modèles compilés prêts à l'emploi sur Hugging Face :

### Série Llama 3

```bash
# 8B Instruct (recommandé pour la plupart des cas d'utilisation)
HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC

# 70B Instruct (nécessite 40 Go+ de VRAM ou 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" %}
**Liste complète des modèles :** Parcourez tous les modèles pré-compilés sur [huggingface.co/mlc-ai](https://huggingface.co/mlc-ai)
{% endhint %}

***

## Options de quantification

MLC-LLM prend en charge plusieurs schémas de quantification. Choisissez en fonction de votre budget VRAM :

| Quantification | Bits                            | Qualité | VRAM (7B) | VRAM (13B) |
| -------------- | ------------------------------- | ------- | --------- | ---------- |
| `q4f16_1`      | 4 bits                          | ★★★★☆   | \~4GB     | \~7 Go     |
| `q4f32_1`      | 4 bits (accumulateur f32)       | ★★★★☆   | \~4GB     | \~7 Go     |
| `q8f16_1`      | 8 bits                          | ★★★★★   | \~8GB     | \~14GB     |
| `q0f16`        | 16 bits (pas de quantification) | ★★★★★   | \~14GB    | \~26 Go    |
| `q0f32`        | 32 bits (pas de quantification) | ★★★★★   | \~28 Go   | \~52 Go    |

{% hint style="warning" %}
**Recommandation VRAM :** Laissez toujours 2–3 Go de marge pour les frais CUDA et le cache KV. Un modèle 7B avec `q4f16_1` nécessite \~6–7 Go au total pour une charge de travail typique.
{% endhint %}

***

## Déploiement Multi-GPU

Pour les grands modèles (70B+) nécessitant plusieurs GPU :

```bash
# Activer le parallélisme tensoriel sur 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
```

Vérifiez la topologie GPU avant le déploiement :

```bash
nvidia-smi topo -m  # Vérifier la connectivité NVLink/PCIe
```

{% hint style="info" %}
**Meilleures performances :** Le multi-GPU fonctionne mieux avec des cartes connectées NVLink (par ex. paires A100 80GB SXM). Les GPU connectés en PCIe présenteront des goulots d'étranglement sur les grands modèles.
{% endhint %}

***

## Interface Web de chat

MLC-LLM inclut une interface web intégrée accessible une fois le serveur en fonctionnement :

```bash
# Démarrer le serveur avec l'interface web activée
python -m mlc_llm serve \
  HF://mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC \
  --host 0.0.0.0 \
  --port 8000 \
  --enable-debug  # Facultatif : active le point de terminaison de débogage
```

Accédez à l'interface à : `http://<clore-node-ip>:<api-port>`

***

## Optimisation des performances

### Optimiser la taille de lot

```bash
# Augmenter la taille de lot pour un débit plus élevé (nécessite plus de 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
```

### Surveiller l'utilisation GPU

```bash
# Dans un terminal séparé
watch -n 1 nvidia-smi

# Surveillance plus détaillée
nvidia-smi dmon -s u  # Métriques d'utilisation en streaming
```

### Mesurer le débit

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

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

***

## Configuration Docker Compose

Pour un déploiement prêt pour la production sur Clore.ai utilisant une image de base NVIDIA CUDA avec MLC-LLM installé via 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 :
```

***

## Dépannage

### Échec du téléchargement du modèle

```bash
# Vérifier la connectivité Internet
curl -I https://huggingface.co

# Télécharger manuellement avec huggingface-cli
pip install huggingface_hub
huggingface-cli download mlc-ai/Llama-3-8B-Instruct-q4f16_1-MLC
```

### Mémoire insuffisante (OOM)

```bash
# Réduire la longueur du contexte
python -m mlc_llm serve MODEL \
  --max-total-sequence-length 4096  # Réduire par rapport à la valeur par défaut

# Utiliser une quantification plus agressive
# Passer de q8f16_1 à q4f16_1
```

### Incompatibilité de version CUDA

```bash
# Vérifier la version CUDA
nvcc --version
nvidia-smi | grep CUDA

# Pour les serveurs CUDA 12.1, installer :
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu121 mlc-ai-nightly-cu121

# Pour les serveurs CUDA 12.2+, installer :
pip install --pre -U -f https://mlc.ai/wheels mlc-llm-nightly-cu122 mlc-ai-nightly-cu122
```

{% hint style="danger" %}
**Piège courant :** Les wheels pip de MLC-LLM sont spécifiques à la version de CUDA. Assurez-vous d'installer la variante correspondant à la version CUDA de votre serveur. Consultez les wheels disponibles sur [mlc.ai/wheels](https://mlc.ai/wheels).
{% endhint %}

### Serveur inaccessible

```bash
# Vérifier que le port est à l'écoute
ss -tlnp | grep 8000

# Vérifiez le pare-feu
iptables -L -n | grep 8000

# Tester localement d'abord
curl http://localhost:8000/v1/models
```

***

## Recommandations GPU Clore.ai

L'approche de compilation de MLC-LLM offre un débit quasi optimal sur chaque niveau de GPU. Choisissez en fonction de la taille du modèle et du budget :

| GPU       | VRAM  | Prix Clore.ai | Idéal pour                         | Débit (Llama 3 8B Q4) |
| --------- | ----- | ------------- | ---------------------------------- | --------------------- |
| RTX 3090  | 24 Go | \~0,12 $/h    | Modèles 7B–13B, service économique | \~85 tok/s            |
| RTX 4090  | 24 Go | \~0,70 $/h    | Modèles 7B–34B, service rapide     | \~140 tok/s           |
| A100 40GB | 40 Go | \~1,20 $/h    | 34B–70B, API de production         | \~110 tok/s           |
| A100 80GB | 80 Go | \~2,00 $/h    | 70B+, service multi-modèles        | \~130 tok/s           |
| H100 SXM  | 80 Go | \~3,50 $/h    | Débit maximal, FP8                 | \~280 tok/s           |

**Point de départ recommandé :** Le RTX 3090 à \~0,12 $/h offre le meilleur rapport prix-performance pour le service de Llama 3 8B et Mistral 7B via MLC-LLM. Les noyaux compilés extraient une utilisation presque maximale des GPU grand public.

Pour les modèles 70B (par ex. Llama 3 70B Q4) : utilisez A100 40GB (\~1,20 $/h) ou deux RTX 3090 via le parallélisme tensoriel.

***

## Ressources

* 📦 **Wheels Pip :** [mlc.ai/wheels](https://mlc.ai/wheels) (installer via pip, aucune image Docker Hub disponible)
* 🐙 **GitHub :** [github.com/mlc-ai/mlc-llm](https://github.com/mlc-ai/mlc-llm)
* 📚 **Documentation :** [llm.mlc.ai/docs](https://llm.mlc.ai/docs)
* 🤗 **Modèles pré-compilés :** [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:

```
GET https://docs.clore.ai/guides/guides_v2-fr/modeles-de-langage/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.