Skip to content

1.7 Embedded LLM Guide

Jump to bottom
Frédéric Clavert edited this page Jul 26, 2026 · 10 revisions

Guide des LLM embarqués

Version: 1.0.0-rc.3 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 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 :

{
  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

Clone this wiki locally