Files
aimsight-libredesk/docs/production.md
T
maximeandClaude Opus 5.5 0fa7c4936b Image embeddings-bge-m3 : jeton exigé devant Ollama
L'image ollama-bge-m3 devient embeddings-bge-m3 (image et conteneur), avec
une description OCI pour la page du paquet dans Gitea.

Caddy 2.10.2, devant Ollama, ne laisse passer que les requêtes qui portent
« Authorization: Bearer <EMBEDDINGS_JETON> » (la « API key » des embeddings
dans LibreDesk) ; Ollama n'écoute plus que dans le conteneur
(127.0.0.1:11435). Le jeton est donné au lancement (ollama/.env, hors de
git), jamais rangé dans l'image publique ; sans jeton valable, le conteneur
refuse de démarrer.

verifier_ollama.py lit le jeton à côté de lui et vérifie aussi qu'une
requête sans jeton est refusée ; 3_brancher_ia.py le donne à l'instance de
test. Essais réels hors ligne et gestes de production (points 1 ter, 6 bis)
dans docs/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:28:41 +01:00

18 KiB

Production : le brouillon dans LibreDesk

LibreDesk en production : helpdesk.sensima.ch (v2.9.0). Design : superpowers/specs/2026-11-12-support-libredesk-design.md. Constats et simulation : verifications.md.

Chaque geste est présenté à Maxime et fait seulement avec son accord explicite, un à la fois. Après chacun, la vérification indiquée. Cocher ici ce qui est fait.

Rien de ce qui suit n'envoie de message : « Generate reply » pose un brouillon dans l'éditeur, un humain l'envoie.

Décision de Maxime (2026-11-12) : les brouillons de l'essai local suffisent pour un premier essai ; on n'ajoute plus de simulation locale, on essaie directement sur la production. Le risque est faible : le brouillon ne part qu'au clic d'un agent, et un mauvais brouillon n'a pas de conséquence pour l'instant.

Déjà fait (repris de Support-AI)

  • 0. Relecture du savoir métier par Maxime. Les 9 extraits de snippets/textes/ dont la source est « Savoir métier AIMsight » ont été réécrits à la main à partir des notes d'analyse : vérifier qu'ils sont justes et bons à dire à un client.
  • 0 bis. Assistant (2026-11-11). Admin → IA → Assistants : support_assistant désactivé (il répondrait seul aux clients si une règle lui confiait une conversation). Vérification : statut « Disabled ».
  • 0 ter. Rien d'automatique (vérifié le 2026-11-11). Admin → Automations : aucune règle ; Admin → IA → Tools : aucun outil ; aucun webhook ; Admin → IA → Suggestions : « Learn from resolved conversations » désactivé.
  • 1 provisoire. LM Studio sur le PC de Maxime (2026-11-11). text-embedding-bge-m3 (bge-m3 Q8_0) sur http://10.0.2.140:1234/v1 (adresse Wi-Fi attribuée par DHCP). Le PC doit rester allumé, LM Studio lancé avec son serveur actif. Remplacé par Ollama ci-dessous.
  • 1 bis provisoire. L'image Ollama sur le PC de Maxime (2026-11-12), à la place de LM Studio, pour essayer le paquet comme le fera le serveur : dossier ~/essai-production/ollama avec seulement les deux fichiers compose et verifier_ollama.py, .env = OLLAMA_BIND=10.0.2.140 + OLLAMA_PORT=11435, docker compose up -d --no-build (image tirée de Gitea sans login : le paquet est public). Pare-feu de WSL (Hyper-V, bloque tout en entrée par défaut, sans interface graphique) ouvert par Maxime : règle Ollama-LibreDesk, TCP 11435, d'abord depuis 10.0.0.0/8, puis resserrée au seul serveur LibreDesk 10.0.1.184 ; à retirer après l'essai (Remove-NetFirewallHyperVRule -Name "Ollama-LibreDesk"). Embeddings dans LibreDesk : http://10.0.2.140:11435/v1, bge-m3:567m, clé ollama, dimensions vides (0). Test réussi ; 118 appels /v1/embeddings depuis LibreDesk (10.0.1.184), tous en 200. Mêmes limites que LM Studio : PC allumé, adresse Wi-Fi qui peut changer.
  • 1 ter. Le jeton sur le PC de Maxime (image embeddings-bge-m3, branche embeddings-token). L'image renommée exige Authorization: Bearer <EMBEDDINGS_JETON> ; Ollama n'écoute plus que dans le conteneur, Caddy devant lui. Elle est déjà construite sur le PC : pas besoin de l'avoir poussée sur Gitea pour cet essai. L'ancienne image accepte n'importe quelle clé : on change donc d'abord la clé dans LibreDesk, puis le conteneur, sans coupure.
    1. Tirer un jeton (Maxime, jamais montré à Claude) : python3 -c 'import secrets; print(secrets.token_urlsafe(32))', et l'ajouter à ~/essai-production/ollama/.env : EMBEDDINGS_JETON=<jeton>.
    2. LibreDesk, Admin → IA → Providers, Embedding : API key = le jeton ; URL, modèle et dimensions inchangés (dimensions vide ou 0 : bge-m3 rend 1024 nombres, pas 1536). Test connection, puis Save. La clé n'entre pas dans l'empreinte des extraits : pas de recalcul.
    3. Copier les nouveaux compose.yml et verifier_ollama.py dans ~/essai-production/ollama, puis cd ~/essai-production/ollama && docker compose up -d --no-build (remplace ollama-bge-m3 par embeddings-bge-m3, quelques secondes sans base).
    4. Vérification : python3 ~/essai-production/ollama/verifier_ollama.py http://10.0.2.140:11435/v1 → OK bge-m3:567m, 1024 dimensions, jeton exigé (le jeton est lu dans le .env voisin) ; dans LibreDesk, Test connection réussit ; un « Generate reply » s'appuie sur la base. Retour en arrière : dans le compose.yml de ~/essai-production/ollama, remettre l'image ollama-bge-m3:0.40.16-567m et container_name: ollama-bge-m3, docker compose up -d --no-build ; la clé de LibreDesk peut rester (l'ancienne image l'ignore).
  • 2. Embeddings (2026-11-11). Fournisseur OpenAI, URL http://10.0.2.140:1234/v1, modèle text-embedding-bge-m3, clé lm-studio, embedding max tokens 2048.
  • 3. Complétion (2026-11-11). Max tokens 4096 ; Custom instructions = snippets/consignes_redaction.md ; Claude Sonnet 5.5, https://api.anthropic.com/v1, effort medium.
  • 4. Import de la base (2026-11-11). 118 extraits actifs. Agent « Import base » (id 127) : clé révoquée, agent désactivé. Pour un réimport : regénérer une clé, réactiver l'agent, mettre la clé dans .env (export LIBREDESK_ADMIN_KEY=…, export LIBREDESK_ADMIN_SECRET=…), tâche « Snippets : envoyer en simulation (PRODUCTION) » puis « Snippets : ENVOYER (PRODUCTION) », puis tout révoquer.
  • 5. Premiers brouillons (2026-11-11, Maxime) : deux brouillons sur de vraies conversations, rien envoyé par l'IA.

Ollama sur le serveur

But : remplacer LM Studio par Ollama (bge-m3:567m) sur le serveur de LibreDesk. LibreDesk recalcule seul les vecteurs des 118 extraits quand on enregistre la nouvelle adresse (vérifié sur l'instance de test, verifications.md).

  • 6. L'image. Sur le poste, tâche « Ollama : construire » (ou docker compose -f ollama/compose.yml build), puis vérification hors ligne (verifications.md). Puis, avec l'accord de Maxime, la pousser au registre Gitea : jeton Gitea à portée write:package, docker login exchange.sensima.ch, docker push exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:0.40.16-567m, puis docker logout exchange.sensima.ch (le login garde le jeton en clair dans ~/.docker/config.json). Vérification : l'image apparaît dans Packages du compte. Si le registre la refuse (taille), on la transportera par SSH au point 8. Construite et vérifiée hors ligne le 2026-11-12 (2,43 Go, sans clé privée : chaque conteneur crée la sienne au démarrage). Poussée le 2026-11-12, digest sha256:332fbdec63583c8b2ac59a168cbd8c3e39624047662b912e58d9f3f7fff99530. Pour le serveur (point 8) : un autre jeton, package en lecture seule.

  • 6 bis. L'image renommée, avec jeton. exchange.sensima.ch/maxime.pasquier/embeddings-bge-m3:0.40.16-567m, construite et vérifiée hors ligne le 2026-11-18 (2,49 Go ; verifications.md). À pousser comme au point 6, avec l'accord de Maxime. Puis, dans Gitea, la rattacher au dépôt (paramètres du paquet → lier au dépôt aimsight-libredesk). L'ancien paquet ollama-bge-m3 ne sera supprimé qu'une fois plus rien ne l'utilise (point 1 ter fait), avec l'accord de Maxime.

  • 7. État des lieux du serveur, sans rien changer (Maxime, en SSH).

    docker version && id && uname -m
    docker ps --format '{{.Names}}  {{.Image}}  {{.Networks}}  {{.Ports}}'
    ip -brief addr
    free -h && df -h /var/lib/docker
    sudo ss -ltnp
    systemctl is-enabled docker
    

    Et la configuration de Caddy, en lecture (docker exec <caddy> cat /etc/caddy/Caddyfile, ou /etc/caddy/Caddyfile). Point d'arrêt : on s'arrête et Maxime décide si Docker manque, si Maxime n'est pas dans le groupe docker (ou sans sudo), si uname -m n'est pas x86_64, si ip -brief addr montre l'adresse publique 46.14.212.91 sur une interface du serveur, si la mémoire libre est sous 2 Go, ou si le disque a moins de 5 Go libres. Noter : le nom du conteneur et du réseau de LibreDesk (s'il est dans Docker), l'adresse interne du serveur (10.…), et que le port 11434 est libre.

  • 8. Installer Ollama. Copier sur le serveur seulement les deux fichiers compose et le script de vérification, jamais le Dockerfile : sans lui, le serveur ne peut pas construire l'image (une construction tirerait environ 10 Go sur le disque de LibreDesk).

    ssh <serveur> mkdir -p ollama && scp ollama/compose.yml ollama/compose.reseau.yml ollama/verifier_ollama.py <serveur>:ollama/
    

    Récupérer l'image : docker pull exchange.sensima.ch/maxime.pasquier/embeddings-bge-m3:0.40.16-567m (paquet public : sans login) ; ou, si le registre l'a refusée, depuis le poste : docker save exchange.sensima.ch/maxime.pasquier/embeddings-bge-m3:0.40.16-567m | gzip | ssh <serveur> 'gunzip | docker load'. Vérifier : docker image ls exchange.sensima.ch/maxime.pasquier/embeddings-bge-m3 montre le tag 0.40.16-567m. Puis écrire ~/ollama/.env sur le serveur (chmod 600), avec, dans tous les cas, un jeton propre au serveur (pas celui du PC) : EMBEDDINGS_JETON=<jeton>, tiré par python3 -c 'import secrets; print(secrets.token_urlsafe(32))'. Sans lui, le conteneur refuse de démarrer. Docker Compose le lit à chaque commande lancée depuis ~/ollama : les réglages ne dépendent d'aucune option à retenir, et un simple docker compose … garde toujours Ollama au bon endroit. Selon l'état des lieux :

    • LibreDesk dans Docker (cas attendu) :
      COMPOSE_FILE=compose.yml:compose.reseau.yml
      RESEAU_LIBREDESK=<réseau de LibreDesk>
      
      Adresse pour LibreDesk : http://ollama:11434/v1. Le port n'est publié que sur 127.0.0.1 du serveur.
    • LibreDesk hors de Docker :
      OLLAMA_BIND=<adresse interne du serveur>
      
      Adresse pour LibreDesk : http://<adresse interne>:11434/v1. Lancer, dans les deux cas (--no-build : si l'image manque, Compose s'arrête au lieu de la construire) :
    cd ~/ollama && docker compose up -d --no-build
    

    Vérification : docker ps --filter name=embeddings-bge-m3 montre Up … (healthy) ; docker inspect embeddings-bge-m3 --format '{{.HostConfig.RestartPolicy.Name}}' rend unless-stopped ; dans le cas Docker, docker network inspect <réseau de LibreDesk> --format '{{range .Containers}}{{.Name}} {{end}}' liste embeddings-bge-m3.

  • 9. Vérifier Ollama.

    • Depuis le serveur : python3 ~/ollama/verifier_ollama.py http://127.0.0.1:11434/v1 (ou l'adresse interne) → OK bge-m3:567m, 1024 dimensions, jeton exigé. Le jeton est lu dans ~/ollama/.env, à côté du script ; le script vérifie aussi qu'une requête sans jeton est refusée.
    • Depuis le réseau de LibreDesk (cas Docker) : docker run --rm --network <réseau> -v ~/ollama:/o:ro python:3.12-alpine python /o/verifier_ollama.py http://ollama:11434/v1 → même résultat (le .env monté avec /o donne le jeton ; il faut que le serveur puisse tirer python:3.12-alpine ; sinon le test du point 10 depuis LibreDesk fait foi).
    • De l'extérieur : depuis un téléphone en 4G (Wi-Fi coupé), ouvrir http://46.14.212.91:11434 : la page ne doit pas répondre. Si elle répond (« jeton manquant ou invalide »), le jeton protège encore, mais le port est exposé : arrêter le service (cd ~/ollama && docker compose down) et revoir le point 7 avec la personne qui gère le serveur.
    • Si python3 manque ou est trop ancien sur le serveur : curl -s http://127.0.0.1:11434/v1/models doit rendre jeton manquant ou invalide ; avec le jeton (set -a && . ~/ollama/.env && set +a && curl -s -H "Authorization: Bearer $EMBEDDINGS_JETON" http://127.0.0.1:11434/v1/models), la liste avec bge-m3:567m.
    • Ne pas redémarrer le service Docker pour essayer : cela redémarrerait aussi LibreDesk. systemctl is-enabled docker (point 7) et la politique unless-stopped suffisent ; le prochain redémarrage planifié du serveur le confirmera (vérifier alors docker ps).
  • 10. Brancher LibreDesk sur Ollama. Admin → IA → Providers, Embeddings : fournisseur OpenAI, URL de l'étape 8, modèle bge-m3:567m, clé = le jeton du serveur (EMBEDDINGS_JETON de ~/ollama/.env), dimensions 0, embedding max tokens 2048. Bouton de test, puis enregistrer seulement s'il réussit. Vérification : le test réussit ; la complétion n'a pas changé.

  • 11. Le recalcul. LibreDesk recalcule seul les 118 extraits (environ une minute). Dans ses journaux (docker logs <conteneur LibreDesk> --since 10m 2>&1 | grep -E "embedding provider changed|reconciled embeddings|error generating embeddings") :

    • « embedding provider changed, reindexing knowledge base » avec new_base_url = l'adresse d'Ollama ;
    • puis « reconciled embeddings … reindexed=118 » ;
    • et aucune « error generating embeddings » après. Attention : « reindexed=118 » compte les extraits tentés ; s'il y a des erreurs, LibreDesk retente chaque minute (Ollama joignable ?), attendre qu'elles cessent.
  • 12. Premier brouillon avec Ollama. Sur une vraie conversation dont la question est dans la base, « Generate reply » : le brouillon arrive et s'appuie sur la base (docker logs … | grep search_articles montre des scores autour de 0,5). Ne rien envoyer ; effacer le brouillon ou le laisser à l'agent qui suit la conversation.

  • 13. LM Studio n'est plus nécessaire. Le PC de Maxime peut être éteint ; garder LM Studio installé quelques jours pour le retour en arrière.

Retour en arrière

Admin → IA → Providers, Embeddings : remettre http://10.0.2.140:1234/v1, text-embedding-bge-m3, clé lm-studio (LM Studio lancé sur le PC de Maxime), tester, enregistrer : LibreDesk recalcule de nouveau. Puis, sur le serveur si besoin : cd ~/ollama && docker compose down.

Le service d'accès (les projets du client)

Au clic sur « Generate reply », le LLM peut appeler l'outil get_customer_access : LibreDesk ajoute l'e-mail du contact (X-Libredesk-Contact-Email), le service acces/ renvoie les projets que ce client voit sur le dashboard ({"projects": [{"project", "serial", "role"}]}). Code et données : acces/ (README du dépôt).

  • 14 provisoire. Sur le PC de Maxime (2026-11-18), comme Ollama au point 1 bis.
    • Données, hors de git : acces/database.db (copie de la base du dashboard du 2026-11-12) et acces/utilisateurs.json (export d'Auth0, e-mail → auth0|…, acces/exporter_utilisateurs.py, lancé par Maxime avec le .env du dashboard).
    • acces/.env (jamais lu par Claude) : ACCES_JETON, ACCES_BIND=10.0.2.140, ACCES_PORT=18080. Construction (sur le poste) : docker compose -f acces/compose.yml build ; lancement : docker compose -f acces/compose.yml up -d --no-build.
    • Pare-feu de WSL ouvert par Maxime : règle Acces-LibreDesk, TCP 18080, depuis le seul serveur LibreDesk 10.0.1.184 (retrait : Remove-NetFirewallHyperVRule -Name "Acces-LibreDesk").
    • Outil dans Admin → IA → Tools : get_customer_access, GET http://10.0.2.140:18080/customer/access, en-tête Authorization: Bearer <ACCES_JETON>, paramètres {"type":"object","properties":{}}, activé pour Generate reply, sans approbation.
    • Vérifié : un « Generate reply » en production → docker logs libredesk-acces montre 10.0.1.184 … e-mail présent, 1 projet(s) puis 200. Le journal ne contient jamais l'adresse.
    • Mêmes limites qu'Ollama : PC allumé, adresse Wi-Fi qui peut changer ; HTTP en clair sur le réseau interne. Données figées : rafraîchir la base et l'export à la main. Les admins globaux du dashboard (rôle Auth0) reçoivent une liste vide.
    • Si l'outil est en erreur : docker ps --filter name=libredesk-acces, puis docker compose -f acces/compose.yml up -d --no-build ; en dernier recours, désactiver l'outil (le brouillon se fait alors sans les projets).
  • 15. Les consignes : dire au LLM quoi faire des projets (snippets/consignes_redaction.md).
  • 16. Sur le serveur, à côté d'Ollama (après le point 7) : acces/compose.reseau.yml, URL http://acces:8080/customer/access, et une base du dashboard tenue à jour.

Au quotidien

  • Si Ollama est arrêté, « Generate reply » rend quand même un brouillon, mais sans la base de connaissances, et rien ne le signale à l'agent (journaux de LibreDesk : AI provider unavailable, search_articles en erreur). Si les brouillons deviennent vagues : docker ps --filter name=embeddings-bge-m3 et python3 ~/ollama/verifier_ollama.py … sur le serveur. Pour le relancer (un arrêt manuel n'est pas relancé seul), toujours cd ~/ollama && docker compose up -d --no-build plutôt que docker start : si LibreDesk a recréé son réseau entre-temps, seul Compose y rattache Ollama.
  • Ollama est rattaché au réseau de LibreDesk (cas Docker) : tant qu'il y est, un docker compose down de LibreDesk ne peut pas supprimer ce réseau (avertissement « Resource is still in use », ou erreur avec l'ancien docker-compose). Arrêter Ollama d'abord (cd ~/ollama && docker compose down), puis le relancer après LibreDesk.
  • Retoucher la base : modifier le fichier dans snippets/textes/, puis réimporter (point 4). Un extrait renommé ou retiré du corpus est signalé (« dans LibreDesk mais pas dans le corpus ») et n'est pas supprimé : le désactiver ou le supprimer à la main dans Admin → IA → Snippets.
  • Changer de version d'Ollama : modifier ollama/Dockerfile, reconstruire, revérifier hors ligne (docker run --network none …, puis ollama/verifier_ollama.py), puis refaire les points 6, 8 et 9. Même modèle, même adresse : pas de recalcul.

Plus tard

  • Les guides de lecture et les fiches d'incident, une fois réécrits (décision de Maxime : hors de la première version).
  • Les règles d'automatisation simples (étiquettes, attribution) : à décider.
  • Une alerte si Ollama ne répond plus (décision de Maxime : le redémarrage automatique suffit pour commencer).

Petites faiblesses connues

  • Les puces « • » des PDF ne sont pas converties en listes dans quelques extraits (cosmétique).
  • L'import réactive un extrait désactivé à la main quand son contenu change, écrase un extrait appris de même titre, et n'affiche que des comptes en écriture. La liste des extraits n'est pas paginée.
  • Lancer l'import depuis un Python Windows pourrait mal lire les accents : toujours passer par WSL.
  • 4_essayer_brouillons.py est fragile si la réponse est vide ou tardive.
  • La clé d'import a le rôle Admin ; un rôle limité à ai:manage suffirait.