localaiforum
Connexion
Guide › Travailler avec les modèles

Dépannage : symptôme → cause → correctif

L'inférence locale échoue selon des motifs. La même douzaine de symptômes couvre presque chaque demande d'aide, et chacun a une cause ennuyeuse et un correctif de deux minutes. Parcourez le tableau, appliquez le correctif, puis lisez les chiffres pour confirmer que vous êtes vraiment réparé.

Le tableau de diagnostic

Symptôme Cause probable Correctif
la sortie contient des jetons de rôle (user:, `< im_start >`)
réponse vide immédiate le gabarit rend un chat « fini », ou mauvais jeton EOS corrigez le gabarit ; vérifiez l'EOS : prompting
répète votre question au lieu de répondre modèle base, pas un modèle instruct utilisez un GGUF instruct/chat
plus de mémoire au chargement poids + quant dépassent la VRAM quant plus petit ou modèle plus petit : calcul de VRAM
plus de mémoire en pleine génération le cache KV dépasse la marge contexte plus court, cache KV q8_0 : cache KV
1–3 tok/s malgré un GPU couches encore sur CPU délestage complet (n_gpu_layers) : paramètres moteur
premier jeton lent, flux rapide ensuite limité par le préremplissage : prompts très longs raccourcir les prompts, batch, préremplissage plus rapide : vitesse
répétition sans fin, boucles de phrases échantillonneur trop permissif, pénalités éteintes temp ≤ 0.8, repeat_penalty 1.05–1.1 : échantillonnage
la sortie coréenne est du charabia ou raide modèle faible en coréen familles multilingues (Qwen, Gemma) : familles de modèles
sortie tronquée en pleine phrase fenêtre de contexte pleine ou max_tokens trop bas élaguez le contexte ou montez la limite de sortie
JSON invalide d'un bon modèle échantillonnage libre décodage contraint : sortie structurée
le modèle ignore vos instructions perdu au milieu sur les longs prompts objectif d'abord, charge ensuite, répétez la demande : prompting
crash ou coredump au chargement téléchargement corrompu vérifiez la somme de contrôle, retéléchargez

Lisez-le symptôme d'abord, pas cause d'abord : appariez ce que vous voyez, appliquez le correctif, mesurez à nouveau. La plupart des rapports « mon modèle est cassé » finissent aux lignes 1, 2 ou 6.

Le pré-vol de cinq minutes

Avant tout débogage profond, collectez les faits :

nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv   # GPU + VRAM
ls -lh model.gguf                                                   # taille vs VRAM
llama-server --version                                              # build du moteur

Si le fichier modèle est plus gros que la VRAM libre, la ligne 4 est votre réponse et aucune option ne vous sauvera. Si memory.used grimpe régulièrement pendant la génération, c'est le cache KV, pas une fuite.

À quoi ressemble le normal

Avant de déboguer la performance, connaissez les ordres de grandeur. Vitesse de décodage d'un modèle 7–8B Q4_K_M, lot 1 :

Matériel Décodage tok/s
GPU milieu de gamme (classe RTX 3060/4060) 30–60
GPU haut de gamme (classe RTX 3090/4090) 100–150
Apple série M (mémoire unifiée) 20–40
CPU seul (8 cœurs moderne) 3–8

Deux formules expliquent l'essentiel :

tok/s de décodage ≈ bande passante mémoire (GB/s) ÷ taille du modèle (GB)
VRAM nécessaire  ≈ poids + cache KV + 1–2 GB de frais généraux

Un quant 7B de 4.5 GB sur une carte à 288 GB/s plafonne près de 64 tok/s en théorie ; attendez ~45–55 réels. Si vous êtes à 2× du tableau, votre matériel n'est pas le bug.

Le temps jusqu'au premier jeton (TTFT) devrait être bien sous la seconde pour des prompts courts ; il croît avec la longueur du prompt divisée par le débit de préremplissage (qui tourne à 10–100× la vitesse de décodage). Un prompt de 10k jetons qui prend 20 s avant le premier jeton est limité par le préremplissage, pas cassé.

Comptabilité VRAM : si les poids se sont bien chargés mais que vous faites un OOM plus tard, c'est le cache KV ou la longueur de contexte, pas le quant — cache KV.

Le protocole : échangez une variable

Les bugs se cachent quand vous changez deux choses à la fois. Isolez le long de cette chaîne — modèle → moteur → config → prompt :

  1. Référence. Modèle connu-bon, moteur connu-bon, options par défaut. Le chat marche ? Alors la pile va bien.
  2. Échangez le modèle (même moteur, mêmes options). Ça casse ? C'est le fichier ou son gabarit.
  3. Échangez le moteur (même modèle). Ça casse ? Bug moteur ou traduction d'option.
  4. Bissectez vos options. Restaurez les défauts, réajoutez les options une à une jusqu'à la casse.
  5. Videz le prompt rendu. Quand la sortie est bizarre-mais-tourne, le gabarit rendu est là où vit la vérité.

Prenez des notes en chemin — « marche à temp 0.8, casse avec min_p 0.2 » est un diagnostic ; « essayé des trucs, toujours mauvais » non.

Bien demander de l'aide

Un bon message d'aide est un compte-rendu de labo. Incluez :

  • Fichier modèle : nom exact, quant et source (qwen2.5-7b-instruct-q4_k_m.gguf, quel dépôt).
  • Moteur et version : date de build de llama.cpp, version d'Ollama, release de vLLM — les moteurs changent chaque semaine.
  • Options exactes ou appel d'API : toute la ligne de commande ou le corps de requête, pas une paraphrase.
  • Matériel : GPU + VRAM (ou Mac + RAM), CPU s'il porte des couches.
  • Chiffres observés : tok/s, TTFT, VRAM utilisée, et le texte d'erreur exact s'il y en a un.
  • Ce que vous avez déjà essayé et ce qui a changé en conséquence.

Squelette à copier-coller :

Modèle:    qwen2.5-7b-instruct-q4_k_m.gguf (dépôt bartowski)
Moteur:    llama.cpp b4321 (llama-server)
Options:   -ngl 99 -c 8192 --temp 0.7
Matériel:  RTX 4060 8GB / Ryzen 7 / 32GB RAM
Observé:   charge en 21s, ~35 tok/s, TTFT ~1.2s, puis OOM à ~6k ctx
Essayé:    -c 4096 → pas de crash ; q8_0 KV → pas de crash

Avec ces six faits, la plupart des problèmes se mappent à une ligne du tableau ci-dessus en une réponse. Ce forum existe exactement pour ces messages — apportez le compte-rendu de labo et vous aurez le correctif.

Voir aussi : paramètres moteur · calcul de VRAM · cache KV · échantillonnage

Guide