Files
aimsight-libredesk/docs/production.md
T
maximeandClaude Opus 5.5 369f2e0a44 Service d'accès : les projets du client au clic sur « Generate reply »
- acces/ : conteneur (bibliothèque standard) qui répond à l'outil get_customer_access de LibreDesk.
  L'e-mail du contact (X-Libredesk-Contact-Email, ajouté par LibreDesk, jamais par le LLM) est
  traduit en compte auth0|… par l'export d'Auth0 (utilisateurs.json), puis en projets par les
  UserGroup de la base du dashboard (database.db, lecture seule) : project, serial, role.
  Jeton Bearer obligatoire ; fichier ou base illisible → 502, jamais une liste vide.
- exporter_utilisateurs.py : l'export Auth0, lancé avec le .env du dashboard.
- Données et secrets hors de git (acces/.env, database.db, utilisateurs.json), .env interdit à Claude.
- Production : en service provisoire sur le PC de Maxime (point 14), vérifié sur un vrai
  « Generate reply » (1 projet renvoyé). Architecture draw.io : la partie accès.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 13:50:31 +01:00

123 lines
15 KiB
Markdown

# 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.
- [x] **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 ».
- [x] **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é.
- [x] **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.**
- [x] **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.
- [x] **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.
- [x] **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`.
- [x] **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.
- [x] **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`).
- [x] **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**.
- [ ] **7. État des lieux du serveur, sans rien changer** (Maxime, en SSH).
```bash
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).
```bash
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 login exchange.sensima.ch && docker pull exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:0.40.16-567m && docker logout exchange.sensima.ch` ; ou, si le registre l'a refusée, depuis le poste : `docker save exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:0.40.16-567m | gzip | ssh <serveur> 'gunzip | docker load'`. Vérifier : `docker image ls exchange.sensima.ch/maxime.pasquier/ollama-bge-m3` montre le tag `0.40.16-567m`.
Puis écrire `~/ollama/.env` sur le serveur. 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) :
```bash
cd ~/ollama && docker compose up -d --no-build
```
Vérification : `docker ps --filter name=ollama-bge-m3` montre `Up … (healthy)` ; `docker inspect ollama-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 `ollama-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`.
- 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 (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 (« Ollama is running »), arrêter Ollama (`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 lister `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é `ollama`, *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).
- [x] **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=ollama-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.