Aller au contenu principal

Exploitation avancée

Ce guide s'adresse aux administrateurs qui exploitent Leticia au quotidien : comment diagnostiquer un incident, dépanner les cas courants et régler la latence de l'IA. Toutes les pages citées ici sont réservées aux comptes administrateurs.

Diagnostiquer : les quatre sources​

Avant de changer quoi que ce soit, regardez ce que l'application dit d'elle-même.

  • Journal (menu → Journal) : le flux d'événements en direct. Filtrez par niveau - concentrez-vous sur WARNING, ERROR et CRITICAL. Chaque erreur affiche son traceback dépliable sur sa ligne. Le bouton Pause fige le rafraîchissement le temps de lire, et le chargement est paginé (« Charger plus ») pour ne pas tout tirer d'un coup. Le bouton Copier les logs produit un bloc de texte prêt à joindre à une demande de support.
  • Fichier de log : le Journal est aussi écrit dans logs/leticia.log (rotation automatique) dans le dossier de données de l'application (%APPDATA%\Leticia sous Windows). Il survit aux redémarrages et permet une analyse hors-ligne.
  • /health : http://<serveur>:8000/health renvoie l'état et la version. C'est la sonde à utiliser pour un monitoring externe.
  • Tableau de bord (menu → Dashboard) : les métriques de session - latence IA, jetons prompt / completion, et une courbe de latence sur 14 jours. C'est le point de départ de tout réglage de performance (voir plus bas).

Dépannage courant​

L'IA ne répond pas ou renvoie des erreurs​

  1. Ouvrez le Journal et cherchez les lignes ERROR du logger IA : le message distingue une clé invalide (401), un modèle inconnu (404), un quota dépassé (429) ou un serveur injoignable.
  2. Vérifiez Paramètres → LLM : provider, clé API, URL de base et modèle. Pour un provider local (Ollama, LM Studio…), l'URL de base doit pointer vers la machine qui héberge le modèle, joignable depuis le serveur Leticia.
  3. Le provider de secours (s'il est activé) prend le relais automatiquement sur une panne transitoire. Côté joueur, un message d'attente puis un repli en personnage évitent tout écran cassé - ces textes se règlent dans les options avancées du LLM.

Les réponses sont lentes​

C'est un réglage à part entière : voir Régler la latence.

La reconnaissance vocale (STT) ou la synthèse (TTS) échoue​

  • Paramètres → STT / TTS : chaque capacité a son propre provider et son provider de secours, indépendants du LLM. Vérifiez la langue pour le STT et la voix pour le TTS (les voix sont propres à chaque provider).
  • Un micro muet côté navigateur bloque le STT avant même l'appel réseau : vérifiez l'autorisation micro du navigateur de la borne.

Le micro de la borne ne s'active pas (contexte sécurisé)​

Si la borne n'affiche jamais la demande d'accès au micro et que le bouton Parler reste désactivé, ce n'est pas un réglage de Leticia : c'est le navigateur qui bloque totalement l'accès au micro sur les pages non sécurisées.

Les navigateurs n'exposent l'API micro (getUserMedia) que dans un contexte sécurisé : une page servie en HTTPS, ou en http://localhost. Une borne ouverte sur l'adresse LAN du serveur, par ex. http://192.168.1.50:8000/kiosk, est en HTTP simple sur une IP : le navigateur considère la page comme non sécurisée et retire l'API micro. Aucune autorisation n'est alors proposée.

Trois façons de régler ça, de la plus propre à la plus rapide :

  1. Servir la borne en HTTPS. Placez un reverse proxy (Caddy, Nginx, Traefik) avec un certificat devant le serveur et pointez la borne sur https://…/kiosk. C'est la solution durable, et elle fonctionne pour toutes les bornes du réseau.
  2. Autoriser l'origine dans le navigateur de la borne. La borne étant configurée une seule fois, on peut dire à son Chromium de traiter cette adresse comme sûre : politique d'entreprise OverrideSecurityRestrictionsOnInsecureOrigin (liste contenant http://192.168.1.50:8000), ou lancement avec --unsafely-treat-insecure-origin-as-secure="http://192.168.1.50:8000" et un --user-data-dir dédié.
  3. Ouvrir la borne sur la machine du serveur. Si l'écran joueur tourne sur le même poste que le serveur, utilisez http://localhost:8000/kiosk : localhost est un contexte sécurisé, le micro fonctionne sans configuration.

Une fois la borne servie en contexte sécurisé, la première utilisation du micro déclenche la demande d'autorisation du navigateur ; acceptez-la une fois, elle est mémorisée pour ce poste.

Les clients ou la borne ne trouvent pas le serveur​

  • Leticia s'annonce en mDNS sous leticia.local. Si ce nom ne résout pas (réseaux qui filtrent le multicast, VLAN cloisonnés), utilisez directement l'adresse IP LAN du serveur, par ex. http://192.168.1.50:8000.
  • Vérifiez que le port 8000 est ouvert dans le pare-feu du serveur et que clients et serveur sont sur le même réseau.

Une borne kiosk reste bloquée​

  • Écran d'appairage avec un code : la borne attend d'être approuvée par un GM dans Administration → Bornes joueur. Tant qu'elle n'est pas approuvée, son jeton ne peut rien faire d'autre que consulter son statut.
  • Borne approuvée mais figée sur l'écran d'attente : aucune partie live n'est associée à ce terminal. Lancez la partie depuis la session en choisissant ce terminal.

Une mise à jour échoue​

  • Reprenez la procédure de la page Mise à jour. Une sauvegarde pré-mise-à-jour est créée automatiquement ; en cas de souci, elle est restaurable depuis Paramètres → Données.
  • Sous Windows, si l'installeur ne se relance pas, relancez Leticia manuellement : vos données dans %APPDATA%\Leticia sont intactes.

Base de données​

  • Le schéma est versionné et migré automatiquement au démarrage : une version publiée met sa base à jour toute seule, y compris une base plus ancienne. Aucun geste manuel n'est requis.
  • En cas de doute, partez d'une sauvegarde (voir Sauvegarde & restauration) : sauvegarde manuelle avant une opération sensible, sauvegardes quotidiennes automatiques avec rétention.

Régler la latence​

Lire les chiffres​

Sur le tableau de bord, trois mesures comptent :

  • jetons prompt : la taille de ce qu'on envoie au modèle (contexte, historique, instructions) ;
  • jetons completion : la taille de la réponse générée ;
  • latence : le temps total de la requête.

Une latence qui monte avec le prompt pointe vers le contexte ; une latence qui monte avec la completion pointe vers la longueur des réponses ou la vitesse du modèle.

Les leviers, du plus efficace au moins​

Réglez-les dans Paramètres → LLM (options avancées), un seul à la fois, puis remesurez sur le tableau de bord.

  1. Coupez la réflexion du modèle (thinking). Les modèles Gemini récents (2.5 et 3) raisonnent avant de répondre : c'est excellent pour un devoir de maths, catastrophique pour un suspect qui doit répliquer du tac au tac - on a mesuré des réponses à plus de 20 s pour cette seule raison. Le réglage Réflexion du modèle (thinking) est désactivé par défaut : laissez-le ainsi en exploitation. Ne l'activez que si vous préférez la profondeur des réponses à leur vitesse.
  2. Rapprochez le modèle. Un modèle local sur le LAN (Ollama, LM Studio) supprime la latence réseau vers un cloud. C'est presque toujours le plus gros gain. À défaut, choisissez une région cloud proche.
  3. Choisissez un modèle plus rapide. Un modèle plus petit répond plus vite ; pour un interrogatoire, la vivacité prime souvent sur l'érudition.
  4. Plafonnez les réponses. Max tokens (par défaut 256) borne la completion : des réponses courtes et incisives sont plus rapides et plus crédibles pour un personnage.
  5. Gardez le streaming activé. Il ne change pas la latence totale mais la rend invisible : le texte s'affiche au fil de l'eau plutôt qu'après un blanc.
  6. Gardez l'optimisation du cache KV activée. Leticia garde un préfixe de requête stable pour que le provider réutilise son cache d'un tour à l'autre - désactivez-la seulement pour diagnostiquer.
  7. Maîtrisez le contexte. Le résumé roulant de l'historique et le clipping de contexte limitent la croissance du prompt sur les longues sessions ; history max messages borne le nombre de tours envoyés bruts.
  8. Fiabilité, pas vitesse : timeout, nombre de tentatives et provider de secours ne rendent pas les réponses plus rapides mais évitent les blocages ; un timeout trop long peut donner l'impression d'une app lente sur une panne - réglez-le à une valeur réaliste pour votre modèle.

Méthode​

Changez un paramètre, jouez quelques échanges, comparez la courbe de latence sur le tableau de bord. Un réglage qui n'améliore pas la mesure n'est pas un bon réglage - revenez en arrière et essayez le levier suivant.