# LocalAI

Exécutez une API compatible OpenAI auto-hébergée avec LocalAI.

{% hint style="success" %}
Tous les exemples peuvent être exécutés sur des serveurs GPU loués via [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Exigences du serveur

| Paramètre          | Minimum          | Recommandé |
| ------------------ | ---------------- | ---------- |
| RAM                | 8 Go             | 16 Go+     |
| VRAM               | 6 Go             | 8 Go+      |
| Réseau             | 200 Mbps         | 500 Mbps+  |
| Temps de démarrage | **5-10 minutes** | -          |

{% hint style="warning" %}
**Important :** LocalAI met 5 à 10 minutes à s'initialiser complètement au premier démarrage. Un HTTP 502 pendant cette période est normal - le service télécharge et charge les modèles.
{% endhint %}

{% hint style="info" %}
LocalAI est léger. Pour exécuter des LLM (modèles 7B+), choisissez des serveurs avec 16 Go+ de RAM et 8 Go+ de VRAM.
{% endhint %}

## Qu'est-ce que LocalAI ?

LocalAI fournit :

* Remplacement OpenAI API prêt à l'emploi
* Prise en charge de plusieurs formats de modèles
* Génération de texte, d'images, d'audio et d'embeddings
* Pas de GPU requis (mais plus rapide avec GPU)

## Modèles pris en charge

| Type       | Formats     | Exemples            |
| ---------- | ----------- | ------------------- |
| LLM        | GGUF, GGML  | Llama, Mistral, Phi |
| Embeddings | GGUF        | all-MiniLM, BGE     |
| Images     | Diffusers   | SD 1.5, SDXL        |
| Audio      | Whisper     | Speech-to-text      |
| TTS        | Piper, Bark | Texte en parole     |

## Déploiement rapide

**Image Docker :**

```
localai/localai:master-aio-gpu-nvidia-cuda-12
```

**Ports :**

```
22/tcp
8080/http
```

**Aucune commande nécessaire** - le serveur démarre automatiquement.

### Vérifiez que cela fonctionne

Après le déploiement, trouvez votre `http_pub` URL dans **Mes commandes** et testez :

```bash
# Vérifier si le service est prêt
curl https://your-http-pub.clorecloud.net/readyz

# Lister les modèles disponibles
curl https://your-http-pub.clorecloud.net/v1/models

# Obtenir la version
curl https://your-http-pub.clorecloud.net/version
```

{% hint style="warning" %}
Si vous obtenez HTTP 502, attendez 5 à 10 minutes - LocalAI met plus de temps à s'initialiser que d'autres services.
{% endhint %}

## Modèles préinstallés

LocalAI est livré avec plusieurs modèles disponibles immédiatement :

| Nom du modèle              | Type       | Description                   |
| -------------------------- | ---------- | ----------------------------- |
| `gpt-4`                    | Chat       | LLM à usage général           |
| `gpt-4o`                   | Chat       | LLM à usage général           |
| `gpt-4o-mini`              | Chat       | LLM plus petit et plus rapide |
| `whisper-1`                | STT        | Speech-to-text                |
| `tts-1`                    | TTS        | Texte en parole               |
| `text-embedding-ada-002`   | Embeddings | Vecteurs de dimension 384     |
| `jina-reranker-v1-base-en` | Reranking  | Reclassement de documents     |

{% hint style="info" %}
Ces modèles fonctionnent immédiatement après le démarrage sans configuration supplémentaire.
{% endhint %}

## Accéder à votre service

Lorsqu'il est déployé sur CLORE.AI, accédez à LocalAI via l' `http_pub` URL :

```bash
# Complétion de chat
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-4",
        "messages": [{"role": "user", "content": "Bonjour !"}]
    }'
```

{% hint style="info" %}
Tous `localhost:8080` les exemples ci-dessous fonctionnent lorsqu'ils sont connectés via SSH. Pour un accès externe, remplacez par votre `https://your-http-pub.clorecloud.net/` URL.
{% endhint %}

## Déploiement Docker (Alternative)

```bash
docker run -d \
    --gpus all \
    -p 8080:8080 \
    -v /workspace/models:/models \
    -e THREADS=4 \
    -e CONTEXT_SIZE=4096 \
    localai/localai:master-aio-gpu-nvidia-cuda-12
```

## Télécharger des modèles

### Depuis la galerie de modèles

LocalAI possède une galerie de modèles intégrée :

```bash
# Lister les modèles disponibles
curl http://localhost:8080/models/available

# Installer depuis la galerie
curl http://localhost:8080/models/apply -d '{"id": "mistral-7b-instruct"}'
```

### Depuis Hugging Face

```bash
mkdir -p /workspace/models

# Llama 3.1 8B GGUF
wget https://huggingface.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/resolve/main/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf \
    -O /workspace/models/llama-3.1-8b.gguf

# Mistral 7B GGUF
wget https://huggingface.co/bartowski/Mistral-7B-Instruct-v0.3-GGUF/resolve/main/Mistral-7B-Instruct-v0.3-Q4_K_M.gguf \
    -O /workspace/models/mistral-7b.gguf
```

## Configuration du modèle

Créez un fichier de configuration YAML pour chaque modèle :

**models/llama-3.1-8b.yaml :**

```yaml
name: llama-3.1-8b
backend: llama-cpp
parameters :
  model: llama-3.1-8b.gguf
  context_size: 4096
  threads: 8
  gpu_layers: 35
template :
  chat : |
    {{.Input}}
    ### Réponse :
  completion : |
    {{.Input}}
```

## Utilisation de l'API

### Chat Completions (compatible OpenAI)

```python
import openai

# Pour un accès externe, utilisez votre URL http_pub :
client = openai.OpenAI(
    base_url="https://your-http-pub.clorecloud.net/v1",
    api_key="non-nécessaire"
)

# Ou via un tunnel SSH :
# client = openai.OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="mistral-7b",
    messages=[
        {"role": "system", "content": "Vous êtes un assistant serviable."},
        {"role": "user", "content": "Expliquez l'informatique quantique en termes simples."}
    ],
    temperature=0.7,
    max_tokens=500
)

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

### Streaming

```python
stream = client.chat.completions.create(
    model="mistral-7b",
    messages=[{"role": "user", "content": "Écris un poème sur l'IA"}],
    stream=True
)

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

### Embeddings

```python
response = client.embeddings.create(
    model="all-minilm",
    input="The quick brown fox jumps over the lazy dog"
)

embedding = response.data[0].embedding
print(f"Dimension de l'embedding : {len(embedding)}")
```

### Génération d'images

```python
response = client.images.generate(
    model="stablediffusion",
    prompt="un magnifique coucher de soleil sur des montagnes",
    size="512x512",
    n=1
)

image_url = response.data[0].url
```

## Exemples cURL

### Chat

```bash
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistral-7b",
        "messages": [{"role": "user", "content": "Bonjour !"}]
    }'
```

### Embeddings

```bash
curl https://your-http-pub.clorecloud.net/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{
        "model": "text-embedding-ada-002",
        "input": "Votre texte ici"
    }'
```

Réponse :

```json
{
  "data": [{"embedding": [0.1, -0.2, ...], "index": 0}],
  "model": "text-embedding-ada-002",
  "usage": {"prompt_tokens": 4, "total_tokens": 4}
}
```

### Texte en parole (TTS)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{
        "model": "tts-1",
        "input": "Bonjour, bienvenue sur LocalAI !",
        "voice": "alloy"
    }' \
    --output speech.wav
```

Voix disponibles : `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`

### Reconnaissance vocale (STT)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/transcriptions \
    -F "file=@audio.mp3" \
    -F "model=whisper-1"
```

Réponse :

```json
{"text": "Texte transcrit ici..."}
```

### Reranking

Reclassez les documents par pertinence par rapport à une requête :

```bash
curl https://your-http-pub.clorecloud.net/v1/rerank \
    -H "Content-Type: application/json" \
    -d '{
        "model": "jina-reranker-v1-base-en",
        "query": "Qu'est-ce que l'apprentissage automatique ?",
        "documents": [
            "L'apprentissage automatique est un sous-ensemble de l'IA",
            "Il fait beau aujourd'hui",
            "L'apprentissage profond utilise des réseaux neuronaux"
        ],
        "top_n": 2
    }'
```

Réponse :

```json
{
  "results": [
    {"index": 0, "relevance_score": 0.95},
    {"index": 2, "relevance_score": 0.82}
  ]
}
```

## Référence complète de l'API

### Points de terminaison standard (compatibles OpenAI)

| Point de terminaison       | Méthode | Description                    |
| -------------------------- | ------- | ------------------------------ |
| `/v1/models`               | GET     | Lister les modèles disponibles |
| `/v1/chat/completions`     | POST    | Complétion de chat             |
| `/v1/completions`          | POST    | Complétion de texte            |
| `/v1/embeddings`           | POST    | Générer des embeddings         |
| `/v1/audio/speech`         | POST    | Texte en parole                |
| `/v1/audio/transcriptions` | POST    | Speech-to-text                 |
| `/v1/images/generations`   | POST    | Génération d'images            |

### Points de terminaison supplémentaires

| Point de terminaison | Méthode | Description                           |
| -------------------- | ------- | ------------------------------------- |
| `/readyz`            | GET     | Vérification de disponibilité         |
| `/healthz`           | GET     | Vérification de l'état                |
| `/version`           | GET     | Obtenir la version de LocalAI         |
| `/v1/rerank`         | POST    | Reclassement de documents             |
| `/models/available`  | GET     | Lister les modèles de la galerie      |
| `/models/apply`      | POST    | Installer un modèle depuis la galerie |
| `/swagger/`          | GET     | Documentation Swagger UI              |
| `/metrics`           | GET     | Métriques Prometheus                  |

#### Obtenir la version

```bash
curl https://your-http-pub.clorecloud.net/version
```

Réponse :

```json
{"version": "v2.26.0"}
```

#### Documentation Swagger

Ouvrez dans le navigateur pour une documentation API interactive :

```
https://your-http-pub.clorecloud.net/swagger/
```

## Accélération GPU

### Backend CUDA

```yaml
# Dans la config du modèle
parameters :
  gpu_layers: 35  # Nombre de couches sur le GPU
  f16: true       # Utiliser FP16
```

### Déchargement GPU complet

```yaml
parameters :
  gpu_layers: 99  # Toutes les couches sur le GPU
  main_gpu: 0     # ID du GPU principal
```

## Modèles multiples

LocalAI peut servir plusieurs modèles simultanément :

```
models/
├── llama-3.1-8b.yaml
├── llama-3.1-8b.gguf
├── mistral-7b.yaml
├── mistral-7b.gguf
├── whisper.yaml
└── whisper-base.bin
```

Accédez à chacun via le nom du modèle dans les appels API.

## Réglage des performances

### Pour la vitesse

```yaml
parameters :
  threads: 8
  gpu_layers: 99
  batch_size: 512
  use_mmap: true
  use_mlock: true
```

### Pour la mémoire

```yaml
parameters :
  gpu_layers: 20  # Déchargement partiel
  context_size: 2048  # Contexte plus petit
  batch_size: 256
```

## Benchmarks

| Modèle          | GPU      | Tokens/sec |
| --------------- | -------- | ---------- |
| Llama 3.1 8B Q4 | RTX 3090 | \~100      |
| Mistral 7B Q4   | RTX 3090 | \~110      |
| Llama 3.1 8B Q4 | RTX 4090 | \~140      |
| Mixtral 8x7B Q4 | A100     | \~60       |

*Benchmarks mis à jour en janvier 2026.*

## Dépannage

### HTTP 502 sur l'URL http\_pub

LocalAI met plus de temps à démarrer que d'autres services. Attendez **5-10 minutes** et réessayez :

```bash
# Vérifier la disponibilité
curl https://your-http-pub.clorecloud.net/readyz

# Vérifier la santé
curl https://your-http-pub.clorecloud.net/healthz
```

### Le modèle ne se charge pas

* Vérifiez le chemin du fichier dans le YAML
* Vérifiez la compatibilité du format GGUF
* Vérifiez la VRAM disponible

### Réponses lentes

* Augmentez `gpu_layers`
* Activez `use_mmap`
* Réduire `context_size`

### Mémoire insuffisante

* Réduire `gpu_layers`
* Utilisez une quantification plus petite (Q4 au lieu de Q8)
* Réduire la taille de batch

### Problèmes de génération d'images

{% hint style="warning" %}
Stable Diffusion peut présenter des problèmes de compatibilité CUDA sur certaines configurations GPU. Si vous rencontrez des erreurs CUDA lors de la génération d'images, envisagez d'utiliser une image Stable Diffusion dédiée à la place.
{% endhint %}

## Estimation des coûts

Tarifs typiques du marketplace CLORE.AI :

| GPU      | VRAM  | Prix/jour   | Convient pour    |
| -------- | ----- | ----------- | ---------------- |
| RTX 3060 | 12Go  | 0,15–0,30 $ | modèles 7B       |
| RTX 3090 | 24 Go | 0,30–1,00 $ | modèles 13B      |
| RTX 4090 | 24 Go | 0,50–2,00 $ | Inférence rapide |
| A100     | 40Go  | 1,50–3,00 $ | Grands modèles   |

*Prix en USD/jour. Les tarifs varient selon le fournisseur — vérifiez* [*CLORE.AI Marketplace*](https://clore.ai/marketplace) *pour les tarifs actuels.*

## Prochaines étapes

* [Inférence vLLM](https://docs.clore.ai/guides/guides_v2-fr/modeles-de-langage/vllm) - Débit plus élevé
* [Guide Ollama](https://docs.clore.ai/guides/guides_v2-fr/modeles-de-langage/ollama) - Configuration plus simple
* [RAG avec LangChain](https://docs.clore.ai/guides/guides_v2-fr/avance/api-integration) - Construire des applications