# Guide des LLM embarqués

**Version**: 1.0.0-rc.4
**Dernière mise à jour**: 2026-07-20

---

## Vue d'ensemble

ClioDeck peut fonctionner avec des modèles de langage (LLM) embarqués, permettant une utilisation hors-ligne complète pour la génération de texte. Cette fonctionnalité utilise [node-llama-cpp](https://github.com/withcatai/node-llama-cpp) pour exécuter des modèles au format GGUF directement dans l'application.

### Fonctionnement

```
┌─────────────────────────────────────────────────────────────┐
│                    Mode de fonctionnement                    │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  Provider: AUTO (par défaut)                                  │
│                                                               │
│     1. Ollama disponible ?                                    │
│        └── OUI → Utiliser Ollama                              │
│        └── NON → 2. Modèle embarqué disponible ?              │
│                    └── OUI → Utiliser modèle embarqué         │
│                    └── NON → Échec du provider (aucun message │
│                                littéral de ce type n'existe    │
│                                dans le code)                   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

### Limitations importantes

| Fonctionnalité | Ollama | Modèle embarqué |
|---------------|--------|-----------------|
| **Génération de texte** | Oui | Oui |
| **Embeddings (RAG)** | Oui | Oui |
| **Streaming** | Oui | Oui |
| **Performance** | Meilleure | Correcte |

**Le modèle embarqué peut désormais servir les deux rôles — au niveau du
code.** `generationProvider` et `embeddingProvider` se choisissent
indépendamment dans la configuration, et `embedded` est une valeur valide
pour les deux : un RAG complet sans Ollama et sans clé cloud est possible en
théorie, avec *Nomic Embed Text v2 MoE* (344 Mo, 768 dimensions,
multilingue) comme modèle d'embeddings.

> **Mais pas encore depuis l'interface.** À ce jour, les paramètres
> **LLM** ne permettent de choisir que `generationProvider` (le tableau
> ci-dessous). **Depuis la RC4**, `embeddingProvider` a son propre contrôle
> dans Réglages → Embeddings, avec le téléchargement du modèle embarqué.
> Avant la RC4, il fallait éditer `cliodeck-config.json` à la main.
>
> Changer de fournisseur d'embeddings rend inutilisables tous les index
> existants — les vecteurs d'un modèle ne se comparent pas à ceux d'un
> autre, et rien ne lève d'erreur. La RC4 le dit avant d'appliquer le
> changement, et reconstruit le registre sans attendre un redémarrage.

En mode **Auto** (le réglage par défaut, pour `generationProvider` comme
pour `embeddingProvider`), ClioDeck préfère Ollama quand il est joignable
et ne bascule sur l'embarqué qu'en repli — voir le diagramme ci-dessus.
Pour les embeddings spécifiquement, ce repli automatique ne s'active que
si le modèle embarqué et le modèle Ollama partagent la même dimension de
vecteur (`embeddingWithFallback()` dans `cliodeck-config-adapter.ts`) —
mélanger des dimensions corromprait silencieusement la recherche par
similarité, donc un décalage de dimension est volontairement laissé en
échec plutôt que de produire un repli trompeur.

---

## Modèles disponibles

### Qwen2.5-0.5B-Instruct (recommandé)

| Caractéristique | Valeur |
|----------------|--------|
| **Taille** | ~469 Mo |
| **Contexte** | 32 768 tokens |
| **Langues** | 29+ (dont FR, EN, DE) |
| **Performance** | Rapide sur CPU |
| **Cas d'usage** | Usage général, machines modestes |

### Qwen2.5-1.5B-Instruct

| Caractéristique | Valeur |
|----------------|--------|
| **Taille** | ~1.04 Go (1066 Mo) |
| **Contexte** | 32 768 tokens |
| **Langues** | 29+ (dont FR, EN, DE) |
| **Performance** | Correcte sur CPU |
| **Cas d'usage** | Meilleure qualité, machines plus puissantes |

---

## Installation

### 1. Accéder aux paramètres

1. Ouvrez ClioDeck
2. Cliquez sur **Paramètres** (icône engrenage)
3. Accédez à la section **LLM embarqué**

### 2. Télécharger un modèle

1. Sélectionnez le modèle souhaité dans la liste
2. Cliquez sur **Télécharger**
3. Attendez la fin du téléchargement (barre de progression)

Le modèle est téléchargé depuis Hugging Face et stocké dans :
- **macOS** : `~/Library/Application Support/cliodeck/models/`
- **Linux** : `~/.config/cliodeck/models/`

### 3. Configurer le provider (génération)

Dans les paramètres LLM, choisissez la stratégie — **ce réglage ne
concerne que la génération de texte** ; il n'existe pas d'équivalent
pour les embeddings dans l'interface (voir l'encart plus haut) :

| Option | Comportement |
|--------|-------------|
| **Auto** (défaut) | Ollama si disponible, sinon embarqué |
| **Ollama** | Force l'utilisation d'Ollama uniquement |
| **Embarqué** | Force l'utilisation du modèle embarqué |

---

## Utilisation

### Mode automatique (recommandé)

En mode **Auto**, ClioDeck choisit automatiquement :

1. **Ollama démarré** → Chat utilise Ollama
2. **Ollama arrêté, modèle téléchargé** → Chat utilise le modèle embarqué
3. **Rien de disponible** → Message d'erreur explicatif

### Comportement du RAG

Quand vous posez une question avec RAG activé :

| Étape | Provider |
|-------|----------|
| Génération de l'embedding de la question | Celui configuré dans `embeddingProvider` (config uniquement, pas encore réglable depuis l'UI) — Ollama, embarqué, ou cloud |
| Recherche dans le vector store | - |
| Génération de la réponse | Celui configuré dans `generationProvider` (réglable dans Paramètres → LLM) — Ollama, embarqué, ou cloud |

Si aucun provider d'embeddings n'est disponible (ni Ollama joignable, ni
modèle embarqué téléchargé, ni clé cloud), le RAG ne peut pas fonctionner.
Le chat bascule alors en mode "conversation simple" sans contexte
documentaire.

---

## Configuration avancée

### Paramètres de génération

Le modèle embarqué utilise des paramètres optimisés pour les réponses académiques :

```typescript
{
  maxTokens: 2048,      // Longueur max de la réponse
  temperature: 0.1,     // Faible pour des réponses précises
  topP: 0.85,           // Nucleus sampling
  contextSize: 4096     // Fenêtre de contexte effective (modèle supporte 32768 max)
}
```

> **Note** : Le modèle Qwen2.5 supporte jusqu'à 32 768 tokens, mais ClioDeck utilise une fenêtre de 4096 tokens pour optimiser la mémoire et la vitesse.

### Format de prompt

Le modèle Qwen utilise le format **ChatML** :

```
<|im_start|>system
Tu es un assistant académique spécialisé...
<|im_end|>
<|im_start|>user
Ma question...
<|im_end|>
<|im_start|>assistant
```

---

## Performance

### Temps de chargement

| Modèle | Premier chargement | Chargement suivant |
|--------|-------------------|-------------------|
| Qwen2.5-0.5B | 5-10 secondes | 2-3 secondes |
| Qwen2.5-1.5B | 10-20 secondes | 5-8 secondes |

### Vitesse de génération

Sur un CPU moderne (Apple M1/M2, Intel i5+) :

| Modèle | Tokens/seconde |
|--------|---------------|
| Qwen2.5-0.5B | 15-25 t/s |
| Qwen2.5-1.5B | 8-15 t/s |

### Utilisation mémoire

| Modèle | RAM approximative |
|--------|------------------|
| Qwen2.5-0.5B | 1-1.5 Go |
| Qwen2.5-1.5B | 2-3 Go |

---

## Dépannage

### Le modèle ne se charge pas

**Symptôme** : Message "Embedded LLM not initialized"

**Causes possibles** :
1. Modèle non téléchargé
2. Fichier GGUF corrompu
3. `node-llama-cpp` non installé

**Solutions** :
- Re-téléchargez le modèle depuis les paramètres
- Vérifiez que le fichier existe dans le dossier `models/`
- Consultez les logs de l'application

### Génération très lente

**Causes possibles** :
1. Modèle trop gros pour la machine
2. Autre application utilisant le CPU intensivement

**Solutions** :
- Passez au modèle Qwen2.5-0.5B (plus léger)
- Fermez les applications gourmandes en ressources

### Aucun provider LLM disponible

Le chat échoue quand :
1. Ollama n'est pas démarré
2. ET aucun modèle embarqué n'est téléchargé

(Le libellé exact de l'erreur affichée n'a pas été vérifié comme une chaîne littérale du code — le mécanisme ci-dessus est confirmé, pas le texte exact.)

**Solutions** :
1. Démarrez Ollama : `ollama serve`
2. OU téléchargez un modèle embarqué dans les paramètres

### Les embeddings ne fonctionnent pas

En pratique aujourd'hui, sans édition manuelle de `cliodeck-config.json`,
les embeddings passent par **Ollama** — c'est le seul provider que
l'interface expose pour ce rôle :

- Installez Ollama, téléchargez un modèle d'embeddings
  (`ollama pull nomic-embed-text`), puis démarrez le service
  (`ollama serve`).

Si vous avez réglé `embeddingProvider: "embedded"` à la main dans le
fichier de configuration, vérifiez que *Nomic Embed Text v2 MoE* est bien
téléchargé (son fichier GGUF doit exister sur disque — il n'y a pas
d'indicateur dans l'UI pour le confirmer autrement).

---

## Comparaison Ollama vs Embarqué

| Critère | Ollama | Embarqué |
|---------|--------|----------|
| **Installation** | Séparée | Intégrée |
| **Modèles disponibles** | Nombreux | 2 génération (Qwen) + 1 embeddings (Nomic v2) |
| **Embeddings** | Oui — mais l'UI ne permet de choisir que **quel modèle Ollama** utiliser (`ollamaEmbeddingModel`), pas de choisir Ollama comme provider explicitement | Oui côté moteur, mais aucun réglage dans l'UI, ni pour choisir le provider ni le modèle (voir plus haut) |
| **Qualité génération** | Excellente | Bonne |
| **Mode hors-ligne** | Oui, une fois les modèles téléchargés | Oui |
| **Mémoire** | Séparée | Partagée avec l'app |
| **Configuration** | Flexible | Simple |

### Quand utiliser quoi ?

**Utilisez Ollama** quand :
- Vous voulez choisir parmi de nombreux modèles de génération
- Vous avez suffisamment de RAM (16+ Go)
- Vous voulez la meilleure qualité de génération disponible localement

**Utilisez le modèle embarqué** quand :
- Vous voulez un RAG complet et hors ligne sans rien installer d'autre — possible aujourd'hui uniquement via édition manuelle du fichier de configuration, en attendant que l'UI expose `embeddingProvider`
- Ollama n'est pas installé/disponible
- Vos machines sont modestes (le RAG fonctionne quand même)

---

## Références techniques

- [node-llama-cpp](https://github.com/withcatai/node-llama-cpp) - Bibliothèque d'exécution
- [Qwen2.5](https://github.com/QwenLM/Qwen2.5) - Famille de modèles
- [GGUF Format](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md) - Format de modèle
- [Hugging Face](https://huggingface.co/) - Source des modèles