Une fois Zigbee2MQTT installé, la question devient concrète : comment ajouter des appareils et construire un maillage fiable dans toute la maison ? Je voulais par exemple ajouter des détecteurs d’ouverture de porte dans le garage. Mais les murs sont trop épais et ils ne se connectaient pas au dongle Zigbee. Voici la procédure pour raccorder une prise connectée et étendre le réseau sur plusieurs pièces. On y voit aussi comment installer un détecteur d’ouverture.
Cet article fait partie de la série Domotique Home Assistant.
Appairer une prise connectée comme répéteur
Les prises connectées Zigbee (ici une Nous A7Z) sont souvent vendues avec une application propriétaire, Tuya ou Nous Smart Home. Mieux vaut l’éviter et connecter la prise directement au réseau Zigbee local via Zigbee2MQTT, déjà installé. Trois avantages : la prise réagit plus vite, sans passer par un serveur distant, tes données restent chez toi, et surtout, une prise branchée sur secteur devient automatiquement un répéteur (routeur) qui agrandit ton maillage Zigbee.
1. Préparer la prise
Branche la prise sur une prise murale et observe le voyant LED sur le bouton latéral :
S’il clignote (lentement ou rapidement) : la prise est déjà en mode appairage.
S’il reste fixe : maintiens le bouton physique enfoncé pendant 5 à 7 secondes. La LED se met à clignoter rapidement, signe que les paramètres d’usine sont réinitialisés et que la prise cherche un réseau.
2. Lancer l’appairage dans Zigbee2MQTT
Ouvre l’interface web de Zigbee2MQTT et clique sur « Permit join » (Autoriser l’appairage), en bas du panneau latéral gauche.
Laisse la prise et Home Assistant communiquer, moins de 30 secondes suffisent. La LED de la prise s’arrête de clignoter et s’éteint. Un nouvel appareil apparaît dans la liste, identifié par défaut sous un nom générique du type « smart zigbee socket ».
Pas besoin de modifier quoi que ce soit à ce stade.
3. Renommer l’appareil
Toujours dans Zigbee2MQTT, ouvre la liste des appareils, clique sur la prise, puis modifie son nom. Donne-lui immédiatement un nom clair et localisé, par exemple « Prise Bureau (entrée) ». Si tu es sur Zigbee2MQTT, coche la case « Mettre à jour l’ID d’entité Home Assistant » pour que les entités soient renommées proprement partout, y compris côté Home Assistant.
Les entités disponibles après l’intégration
Une fois associée, la prise fait remonter automatiquement plusieurs informations dans tes tableaux de bord :
Le commutateur (switch) : pour allumer ou éteindre l’appareil branché, à distance.
La puissance instantanée (sensor.power, en watts) : utile pour voir ce que consomme un appareil en temps réel, ou créer des automatisations, par exemple une alerte quand la machine à laver tombe à 2 W, signe que le cycle est terminé.
La consommation cumulée (sensor.energy, en kWh) : l’entité à intégrer dans l’onglet Énergie de Home Assistant pour suivre tes coûts électriques.
Une fois les appareils appairés, ils apparaissent automatiquement dans l’aperçu de Home Assistant. Dès que tu leur assignes une pièce, ils s’affichent aussi dans l’aperçu de cet espace.
Conseil pour le réseau : comme la prise est branchée sur secteur, elle fait office de routeur. Laisse passer 24 à 48 heures sans la débrancher, le temps que tes autres capteurs sur pile (boutons, thermomètres) se maillent intelligemment à elle si besoin.
Ajouter un détecteur d’ouverture porte ou fenêtre
Les détecteurs Aqara MCCGQ11LM se composent de deux parties : un grand boîtier (le capteur principal) et un petit boîtier (l’aimant). Ils fonctionnent avec une pile bouton CR1632.
Appairage
La procédure suit le même principe que pour la prise, dans Zigbee2MQTT puis Home Assistant :
Repère le petit bouton physique sur une des tranches du grand boîtier.
Reste appuyé dessus pendant environ 5 secondes, jusqu’à ce que la petite LED bleue en façade clignote, puis relâche.
Pendant que Zigbee2MQTT cherche le capteur, appuie brièvement sur ce même bouton toutes les 2 à 3 secondes, pour forcer le capteur à rester éveillé jusqu’à ce que l’association soit complète. C’est une particularité des capteurs Aqara.
Une fois associé, tu dois voir le capteur passer en mode « ouvert » lorsque tu approches le petit boîtier du grand, et inversement en mode « fermé » quand tu les éloignes.
Installation physique
Le grand boîtier se colle sur la partie fixe (le cadre de la porte ou de la fenêtre), le petit aimant sur la partie mobile (le battant). Deux points d’attention :
Une fois la porte fermée, l’écart entre les deux boîtiers ne doit pas dépasser 22 mm.
Les petits repères (une ligne fine gravée sur le côté de chaque boîtier) doivent être alignés l’un en face de l’autre.
Astuce pour le positionnement : une carte bancaire standard fait 0,76 mm d’épaisseur. Deux cartes empilées donnent une cale pratique pour espacer correctement les deux boîtiers avant de les coller définitivement.
Étendre le maillage à plusieurs prises
Ajouter une deuxième ou une troisième prise pose une question classique : faut-il les appairer directement à leur emplacement final, ou peut-on les appairer près du dongle Zigbee pour simplifier la manipulation, puis les déplacer ensuite ?
Pourquoi l’appairage à proximité fonctionne
Le protocole Zigbee forme un réseau maillé (mesh) et dynamique. Lors de l’appairage, l’appareil a seulement besoin de s’enregistrer auprès du coordinateur, ton dongle USB, et d’y enregistrer sa clé de sécurité. Peu importe qu’il passe directement par le dongle ou par un relais à ce moment précis.
La règle d’or après le déplacement : le temps de « guérison »
Si tu appaires une prise destinée au garage dans ton bureau, elle crée d’abord un lien direct avec le dongle. Quand tu la débranches pour l’installer définitivement dans le garage, Home Assistant la voit d’abord « hors ligne » : elle cherche son ancien voisin (le dongle du bureau) et ne le trouve plus.
C’est là que le maillage entre en jeu : la prise émet un signal pour chercher de nouveaux voisins, détecte une autre prise déjà en place à proximité, et se reconnecte au réseau à travers elle. Ce processus de reconfiguration automatique s’appelle la « guérison » (healing) du réseau.
Ce processus n’est pas instantané, il peut prendre entre 10 minutes et un gros quart d’heure. Pas d’inquiétude si l’appareil reste indisponible juste après l’avoir branché à son emplacement définitif.
Méthode recommandée pour plusieurs prises
Pour enchaîner l’ajout de plusieurs prises sans perturber le réseau, suis cet ordre :
Appairer la prise 2 (par exemple, salon) dans le bureau : lance le mode inclusion dans Zigbee2MQTT, branche la prise à proximité, appaire-la et renomme-la.
Placer la prise 2 à son emplacement définitif : débranche-la du bureau et branche-la au salon. Attends 5 à 10 minutes qu’elle se reconnecte au dongle ou à la première prise et se stabilise.
Appairer la prise 3 (par exemple, garage) dans le bureau, pendant que la prise 2 se stabilise ailleurs.
Placer la prise 3 à son emplacement définitif : comme la prise du salon est déjà en place et active, la prise du garage trouvera ce relais plus facilement pour stabiliser son signal.
Vérifier son maillage : LQI et carte réseau
Le LQI, pour Link Quality Indicator (indice de qualité du lien), mesure la force et la fiabilité de la communication entre un appareil Zigbee et son contrôleur ou son routeur. Tu le retrouves directement dans la fiche de chaque appareil sur Zigbee2MQTT.
Un mur en parpaing plein rempli de galets concassés, par exemple, dégrade sensiblement le signal, un peu comme pour le Wi-Fi. Un LQI plus faible sur un appareil isolé dans une pièce éloignée n’est donc pas anormal.
Utiliser la carte Zigbee
Une fois tous les appareils branchés à leur place définitive, attends environ 30 minutes, puis va sur l’interface de Zigbee2MQTT, dans l’onglet Réseau :
Dans le menu déroulant Type d’affichage, choisir « afficher données / carte »
Dans le menu déroulant à droite « Type d’affichage« , choisir « carte »
Clique sur le bouton bleu Charger.
Le chargement prend quelques instants. Tu verras ensuite apparaître les lignes qui relient tes appareils entre eux, preuve visuelle que le maillage fonctionne. On voit que des liens se créent entre éléments. Un des capteurs d’ouverture est relié par l’intermédiaire de la prise A du bureau, l’autre en direct vers le « coordinateur » jaune, le dongle Zigbee de l’ordinateur Home Assistant.
Pour aller plus loin
Cet article fait partie de la série Domotique Home Assistant, qui regroupe les projets domotique créé dans Home Assistant. Je prévois d’y ajouter rapidement un article sur la façon de suivre les consommations d’énergie, avec une connexion quotidienne au site Enedis pour récupérer mes consommations quotidienne. Et un peu après, je voudrais créer un petit système d’alarme qui s’actionne quand des portes sont ouvertes en l’absence de certains téléphones « validés ».
Ce POC trie les pixels d’une image par couleur, comme l’application Attracteurs étranges déformait une image en suivant la trajectoire d’un attracteur mathématique. Mais l’important ici n’est pas l’application. C’est l’environnement, minimal, et la méthode pour construire ce genre de projet avec l’IA, même sans bagage en code.
Le principe du POC
Un fichier HTML unique, sans dépendance externe. Il charge une image, la lit pixel par pixel dans un canvas caché, trie ces pixels par teinte puis par luminosité, et affiche le résultat à côté de l’image d’origine. Tout se passe dans le navigateur, aucune image n’est envoyée à un serveur.
C’est volontairement un projet minimal, pas une application finie. Le but est de montrer qu’on peut obtenir un résultat fonctionnel, rapide et sécurisé, en une poignée d’échanges avec l’IA.
Ci-dessous sur un écran en mode portrait :
ou en mode paysage, avec une autre image
Le cahier des charges avant de coder
Avant d’écrire la moindre ligne de code, la première chose à faire est de poser un cahier des charges, même court. Trois questions suffisent pour ce genre de petit projet :
Que doit faire l’application, précisément ?
Quelles contraintes techniques et de sécurité s’appliquent (aucune donnée envoyée au serveur, un seul fichier autonome) ?
Sur quels supports doit-elle fonctionner (ordinateur, téléphone) ?
Ce dernier point vient d’une leçon apprise sur le projet Attracteurs : l’adaptation au téléphone n’avait pas été anticipée dans le cahier des charges initial, et n’a été détectée qu’en testant sur téléphone après coup. Pour ce projet, la contrainte responsive a été posée dès le départ.
Autre principe utile : ne pas réinventer ce qui existe déjà. Le chargement sécurisé d’image et la lecture des pixels via un canvas caché avaient déjà été validés sur le projet Attracteurs. Il n’y avait aucune raison de repartir de zéro sur ce point, seule la logique de tri était vraiment nouvelle.
Discuter avec l’IA pour jauger la complexité
Une fois le tri de base posé, une idée est venue en cours de route : permettre de survoler l’image triée à la souris pour afficher la couleur du pixel pointé, en RGB et en HSL. Une bonne question à se poser à ce moment-là : est-ce simple à ajouter, ou est-ce que ça mérite d’être traité à part ?
La réponse, discutée avec l’IA, a été de séparer le projet en deux étapes. L’étape A, le tri lui-même, suffisante pour valider le principe. L’étape B, le survol interactif, repoussée à une session suivante. Deux raisons à ce choix : tester une chose à la fois évite de devoir déboguer plusieurs nouveautés en même temps, et une fonctionnalité tactile (le survol au doigt pose des questions différentes de la souris) mérite sa propre réflexion plutôt que d’être ajoutée dans la précipitation.
C’est ce genre d’arbitrage qui fait la différence entre un prompt unique qui tente de tout faire d’un coup, et une conversation qui avance par étapes validées.
Le code complet
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Tri de pixels par couleur</title>
<style>
:root {
--bg: #0b0d12;
--panel: rgba(20, 22, 30, 0.9);
--line: rgba(255, 255, 255, 0.10);
--txt: #e4e5ea;
--dim: #9497a3;
--accent: #2979ff;
}
* { box-sizing: border-box; margin: 0; padding: 0; }
[hidden] { display: none !important; }
body {
background: var(--bg);
color: var(--txt);
font-family: "Segoe UI", system-ui, -apple-system, sans-serif;
font-size: 14px;
padding: 16px;
min-height: 100vh;
}
h1 {
font-size: 15px;
font-weight: 600;
letter-spacing: 0.06em;
text-transform: uppercase;
color: var(--dim);
margin-bottom: 14px;
}
h1 b { color: var(--accent); font-weight: 600; }
#panel {
background: var(--panel);
border: 1px solid var(--line);
border-radius: 10px;
padding: 14px;
margin-bottom: 16px;
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
}
input[type=file] { color: var(--dim); max-width: 100%; }
.btn {
padding: 8px 14px;
border: 1px solid var(--line);
border-radius: 7px;
background: rgba(255,255,255,0.06);
color: var(--txt);
font-size: 13px;
cursor: pointer;
}
.btn:hover { border-color: var(--accent); }
#status {
color: var(--dim);
font-size: 13px;
}
#resultats {
display: flex;
gap: 16px;
flex-wrap: wrap;
}
figure {
flex: 1 1 380px;
min-width: 0;
background: var(--panel);
border: 1px solid var(--line);
border-radius: 10px;
padding: 12px;
}
figure canvas {
display: block;
width: 100%;
height: auto;
border-radius: 6px;
background: #000;
}
figcaption {
color: var(--dim);
font-size: 12px;
text-transform: uppercase;
letter-spacing: 0.06em;
margin-bottom: 8px;
}
@media (max-width: 820px) {
#resultats { flex-direction: column; }
}
</style>
</head>
<body>
<h1>Tri de pixels par <b>couleur</b></h1>
<div id="panel">
<input type="file" id="file" accept="image/*">
<button type="button" class="btn" id="demo" hidden>Image de démonstration</button>
<span id="status">Choisis une image pour commencer.</span>
</div>
<div id="resultats" hidden>
<figure>
<figcaption>Image d'origine</figcaption>
<canvas id="cvOriginal"></canvas>
</figure>
<figure>
<figcaption>Pixels triés par teinte, puis luminosité</figcaption>
<canvas id="cvTrie"></canvas>
</figure>
</div>
<script>
const ui = {
file: document.getElementById("file"),
demo: document.getElementById("demo"),
status: document.getElementById("status"),
resultats: document.getElementById("resultats"),
cvOriginal: document.getElementById("cvOriginal"),
cvTrie: document.getElementById("cvTrie"),
};
const TAILLE_MAX = 1200; // plus grande dimension autorisée pour la taille de travail
const DEMO_DIR = "demo/";
/* ============================================================
Chargement d'une image choisie par l'utilisateur
============================================================ */
ui.file.addEventListener("change", () => {
const f = ui.file.files && ui.file.files[0];
if (!f) return;
const url = URL.createObjectURL(f);
const img = new Image();
img.onload = () => {
URL.revokeObjectURL(url);
traiterImage(img);
};
img.onerror = () => {
URL.revokeObjectURL(url);
ui.status.textContent = "Impossible de lire ce fichier image.";
};
img.src = url;
});
/* ============================================================
Images de démonstration
Le manifeste n'est lu que si l'application est servie en
http(s). En ouverture directe du fichier (file://), l'appel
échoue silencieusement et le bouton reste caché : rien ne
bloque, l'utilisateur charge simplement sa propre image.
============================================================ */
let demoListe = [];
fetch(DEMO_DIR + "manifest.json")
.then(r => r.ok ? r.json() : [])
.then(liste => {
if (Array.isArray(liste) && liste.length) {
demoListe = liste;
ui.demo.hidden = false;
}
})
.catch(() => {});
ui.demo.addEventListener("click", () => {
if (!demoListe.length) return;
const nom = demoListe[Math.floor(Math.random() * demoListe.length)];
const img = new Image();
img.onload = () => traiterImage(img);
img.onerror = () => { ui.status.textContent = "Impossible de charger l'image de démonstration."; };
img.src = DEMO_DIR + nom;
});
/* ============================================================
Redimensionnement interne
La plus grande dimension de l'image est ramenée à TAILLE_MAX
si besoin, pour garder le tri fluide sur tous les appareils.
Le rapport largeur/hauteur d'origine est conservé.
============================================================ */
function calculerTailleTravail(largeur, hauteur) {
const plusGrand = Math.max(largeur, hauteur);
if (plusGrand <= TAILLE_MAX) return { w: largeur, h: hauteur };
const ratio = TAILLE_MAX / plusGrand;
return {
w: Math.max(1, Math.round(largeur * ratio)),
h: Math.max(1, Math.round(hauteur * ratio)),
};
}
/* ============================================================
Conversion RGB vers HSL
Seules la teinte (h, 0-360) et la luminosité (l, 0-1) sont
utilisées ici comme critères de tri.
============================================================ */
function rgbVersHsl(r, g, b) {
r /= 255; g /= 255; b /= 255;
const max = Math.max(r, g, b), min = Math.min(r, g, b);
const l = (max + min) / 2;
if (max === min) return { h: 0, l };
const d = max - min;
let h;
switch (max) {
case r: h = ((g - b) / d + (g < b ? 6 : 0)); break;
case g: h = ((b - r) / d + 2); break;
default: h = ((r - g) / d + 4);
}
h *= 60;
return { h, l };
}
/* ============================================================
Traitement principal : lecture, tri, reconstruction, affichage
============================================================ */
function traiterImage(img) {
ui.status.textContent = "Traitement en cours...";
ui.resultats.hidden = true;
// laisse le navigateur afficher le message de statut avant
// de démarrer le calcul, potentiellement bloquant
requestAnimationFrame(() => {
const { w, h } = calculerTailleTravail(img.naturalWidth, img.naturalHeight);
const n = w * h;
// canvas caché pour la lecture des pixels, image redimensionnée
const cvLecture = document.createElement("canvas");
cvLecture.width = w;
cvLecture.height = h;
const ctxLecture = cvLecture.getContext("2d", { willReadFrequently: true });
ctxLecture.drawImage(img, 0, 0, w, h);
const donnees = ctxLecture.getImageData(0, 0, w, h).data;
// teinte et luminosité de chaque pixel, calculées une seule fois
const teintes = new Float32Array(n);
const luminosites = new Float32Array(n);
for (let i = 0; i < n; i++) {
const j = i * 4;
const { h: teinte, l } = rgbVersHsl(donnees[j], donnees[j + 1], donnees[j + 2]);
teintes[i] = teinte;
luminosites[i] = l;
}
// indices des pixels triés par teinte, puis par luminosité
const indices = new Uint32Array(n);
for (let i = 0; i < n; i++) indices[i] = i;
const indicesTries = Array.from(indices).sort((a, b) => {
if (teintes[a] !== teintes[b]) return teintes[a] - teintes[b];
return luminosites[a] - luminosites[b];
});
// reconstruction de l'image triée : les pixels triés sont replacés
// dans l'ordre de lecture habituel (ligne par ligne), en gardant
// leur couleur exacte d'origine
const imageTrie = ctxLecture.createImageData(w, h);
const sortie = imageTrie.data;
for (let i = 0; i < n; i++) {
const source = indicesTries[i] * 4;
const cible = i * 4;
sortie[cible] = donnees[source];
sortie[cible + 1] = donnees[source + 1];
sortie[cible + 2] = donnees[source + 2];
sortie[cible + 3] = donnees[source + 3];
}
// affichage : image d'origine
ui.cvOriginal.width = w;
ui.cvOriginal.height = h;
ui.cvOriginal.getContext("2d").drawImage(img, 0, 0, w, h);
// affichage : image triée
ui.cvTrie.width = w;
ui.cvTrie.height = h;
ui.cvTrie.getContext("2d").putImageData(imageTrie, 0, 0);
ui.resultats.hidden = false;
ui.status.textContent = `Image traitée : ${w} x ${h} px (${n.toLocaleString("fr-FR")} pixels).`;
});
}
</script>
</body>
</html>
Pour les images de démonstration, un dossier demo/ contient un fichier manifest.json listant simplement leurs noms :
json
["falaise.jpg", "port-breton.png"]
S’il est absent, rien ne bloque, le bouton « Image de démonstration » reste caché et le visiteur charge sa propre image.
Tester en local, sans rien connaître
Trois façons de servir ce fichier avant de le mettre en ligne, du plus accessible au plus technique.
La solution VSCodium, ou VSCode (non testée), avec l’extension Live Server, est la plus simple si tu ne veux rien installer d’autre qu’un éditeur de code. Un clic droit sur le fichier HTML, « Open with Live Server », et la page s’ouvre dans le navigateur avec rechargement automatique à chaque modification.
Un serveur Python local, sur une machine où Python est déjà installé. Dans le dossier contenant le fichier :
python3 -m http.server 8000
Puis ouvrir http://localhost:8000/tri-pixels-couleur.html dans le navigateur. Si le serveur tourne sur une autre machine du même réseau local (un boîtier Linux par exemple), remplacer localhost par l’adresse IP locale de cette machine, du type http://192.168.x.x:8000/tri-pixels-couleur.html.
Sous Windows, la même commande peut nécessiter d’installer Python au préalable (depuis python.org, pas le Microsoft Store), cette option n’a pas été testée dans le cadre de ce projet.
Mettre en ligne, gratuitement
J’ai testé et validé deux options pour ce projet.
option Page Github
GitHub Pages, pour un partage public et gratuit, indépendant de tout hébergement personnel :
Créer un compte GitHub si besoin (github.com, gratuit)
Créer un dépôt public, par exemple tri-pixels-couleur, sans rien cocher (pas de README, pas de licence)
Dans le dépôt, « Add file » puis « Upload files », déposer le fichier HTML renommé en index.html, et si besoin le dossier demo/ avec son manifeste et ses images
Dans « Settings » puis « Pages », section « Build and deployment », choisir « Deploy from a branch », branche main, dossier / (root)
L’URL publique apparaît en haut de cette même page après une à deux minutes, du type https://ton-pseudo.github.io/tri-pixels-couleur/.
Un sous-répertoire de son propre site, avec un vrai hébergement web. Même principe que l’application Attracteurs étranges : déposer le fichier HTML renommé en index.html dans un dossier dédié à la racine du site (via FTP ou le gestionnaire de fichiers de l’hébergeur), avec le dossier demo/ à côté si besoin. L’URL devient propre automatiquement, sans conflit avec les permaliens WordPress. Pour l’application Attracteurs étranges, ça fonctionne parfaitement ici : https://knowledge.parcours-performance.com/attracteurs/
C’est quoi le vibe coding ?
Le terme désigne une façon de coder en dialoguant avec une IA en langage naturel, plutôt qu’en écrivant soi-même chaque ligne. On décrit ce qu’on veut, l’IA propose du code, on teste, on ajuste, on recommence.
Ce projet en est un exemple assez pur : aucune ligne de ce fichier n’a été tapée à la main, tout est passé par une conversation structurée, cahier des charges d’abord, questions une par une, validation avant chaque étape de code.
C’est aussi une bonne méthode pour construire un POC (proof of concept, ou preuve de concept en français. On pourrait aussi dire prototype), c’est-à-dire une version minimale d’une idée, juste assez fonctionnelle pour vérifier qu’elle tient debout, avant d’envisager d’aller plus loin. Cette expérimentation en est un exemple : elle ne visait pas à produire un outil fini, seulement à valider rapidement plusieurs options sécurisées pour mettre en ligne des applications en html et javascript.
Ce principe s’applique à beaucoup d’autres petits projets, créatifs ou utiles. Quelques idées pour continuer à s’entraîner :
Un générateur de palette de couleurs à partir d’une photo
Une page de calcul simple pour une TPE, devis, marge, conversion d’unités
Un petit générateur de mots de passe ou de QR codes, entièrement local
Une visualisation ludique de données personnelles, dépenses, lectures, trajets
Cet article fait partie de la série des articles sur la création d’une IA locale dans mon bureau : Créer une IA locale.
Anonymiser un document, c’est supprimer définitivement les données personnelles qu’il contient. Pseudonymiser, c’est différent : tu remplaces temporairement ces données par un identifiant neutre, tu traites le document sans jamais voir l’information sensible, puis tu réinjectes les vraies données à la fin. Voici comment tester ce principe chez toi, sur un PC modeste, avec des outils open source.
Le principe en 3 étapes
Détecter les données personnelles dans un texte et les remplacer par un jeton neutre (par exemple PERSONNE_1 à la place d’un prénom).
Traiter le texte anonymisé avec une intelligence artificielle, qui ne voit jamais l’identité réelle de la personne.
Réinjecter l’information réelle à la place du jeton dans le résultat final.
L’intérêt : le traitement (recherche, analyse, génération de contenu) se fait sans exposer l’identité de la personne concernée, ce qui limite les risques si le document venait à être mal utilisé ou transmis à un tiers.
Les outils utilisés
Presidio, un outil open source de Microsoft, pour détecter les données personnelles dans le texte (reconnaissance d’entités nommées).
spaCy, une bibliothèque de traitement du langage, utilisée par Presidio pour comprendre le texte en français.
Ollama avec le modèle qwen2.5:3b, pour le traitement IA local, sans aucune donnée envoyée sur internet.
Tout tourne en local sur un Mini PC Linux, sans connexion à un service externe.
Installer l’environnement
Le script tourne dans un environnement Python isolé (un venv), séparé du reste du système. Ça évite que les bibliothèques installées pour ce projet entrent en conflit avec d’autres outils déjà présents sur la machine.
Crée le dossier du projet et vérifie que le paquet nécessaire à la création d’un venv est installé :
mkdir -p ~/docker/pseudonymisation
cd ~/docker/pseudonymisation
dpkg -l | grep python3-venv
Si la commande ne retourne rien, installe le paquet (le numéro de version dépend de ta machine, la commande d’installation exacte apparaît dans le message d’erreur si tu tentes de créer le venv directement) :
sudo apt update
sudo apt upgrade
sudo reboot
Après le redémarrage, reconnecte-toi en SSH et installe le paquet indiqué par le message d’erreur, par exemple :
sudo apt install python3.12-venv
Crée ensuite le venv, sans sudo (une commande avec sudo donnerait les droits root aux fichiers créés, ce qui complique ensuite toute modification) :
cd ~/docker/pseudonymisation
python3 -m venv venv
source venv/bin/activate
La ligne de commande affiche maintenant (venv) au début, signe que l’environnement isolé est actif. Installe les bibliothèques nécessaires et le modèle de langue française :
Le modèle fr_core_news_sm est le plus léger disponible pour le français. Sur un PC peu puissant et pour un test avec des textes courts, il est peut-être suffisant. Un modèle plus complet (fr_core_news_md) existe si la détection s’avère insuffisante.
Enregistre la liste des bibliothèques installées, pour pouvoir tout réinstaller à l’identique en cas de besoin :
pip freeze > requirements.txt
Vérifier que la détection fonctionne
Avant de construire le script complet, un test simple permet de vérifier que Presidio détecte bien un prénom dans une phrase.
Crée le fichier test_detection.py :
from presidio_analyzer import AnalyzerEngine
from presidio_analyzer.nlp_engine import NlpEngineProvider
configuration = {
"nlp_engine_name": "spacy",
"models": [{"lang_code": "fr", "model_name": "fr_core_news_sm"}]
}
provider = NlpEngineProvider(nlp_configuration=configuration)
nlp_engine = provider.create_engine()
analyzer = AnalyzerEngine(nlp_engine=nlp_engine, supported_languages=["fr"])
texte_origine = "Bonjour, je m'appelle Pierre Durand et j'habite à Paris."
resultats = analyzer.analyze(text=texte_origine, language="fr")
for res in resultats:
print(f"Trouvé: {texte_origine[res.start:res.end]} -> Catégorie: {res.entity_type}")
Lance-le :
python test_detection.py
Résultat obtenu :
Trouvé: Pierre Durand -> Catégorie: PERSON
Trouvé: Paris -> Catégorie: LOCATION
La détection fonctionne, on peut construire le script complet.
Créer des documents de test
Pour tester le workflow, j’ai créé 5 courts textes fictifs, chacun avec un prénom, un âge et un animal préféré, rédigés comme des présentations naturelles plutôt que des formulaires. Crée un dossier documents/ et un fichier par personne :
mkdir -p ~/docker/pseudonymisation/documents
cat > ~/docker/pseudonymisation/documents/personne1.txt << 'EOF'
Bonjour, je m'appelle Léa et j'ai 34 ans. Je travaille dans une pépinière depuis quelques années. Si je devais choisir un animal préféré, ce serait sans hésiter l'axolotl, je trouve sa capacité à régénérer ses membres absolument fascinante.
EOF
cat > ~/docker/pseudonymisation/documents/personne2.txt << 'EOF'
Je me présente, je suis Thomas, j'ai 52 ans et je vis à la campagne. Mon animal préféré est le fennec, ses grandes oreilles et son adaptation au désert m'ont toujours impressionné depuis un documentaire vu il y a longtemps.
EOF
cat > ~/docker/pseudonymisation/documents/personne3.txt << 'EOF'
Salut, moi c'est Camille, 27 ans. J'adore les animaux un peu décalés, et mon préféré reste le quokka, ce petit marsupial australien qui semble toujours sourire sur les photos.
EOF
cat > ~/docker/pseudonymisation/documents/personne4.txt << 'EOF'
Je m'appelle Julien et j'ai 45 ans. Passionné de nature depuis l'enfance, mon animal préféré est le pangolin, une créature discrète et méconnue que je trouve pourtant étonnante avec ses écailles.
EOF
cat > ~/docker/pseudonymisation/documents/personne5.txt << 'EOF'
Bonjour, je suis Sophie, j'ai 61 ans et je suis récemment partie à la retraite. Mon animal préféré est l'okapi, cet étrange cousin de la girafe que j'ai découvert lors d'un voyage il y a quelques années.
EOF
Le script d’anonymisation
Ce script lit chaque fichier, détecte les entités présentes (pas seulement le prénom, pour observer aussi ce que Presidio détecte d’autre), les remplace par des jetons, et sauvegarde la correspondance dans un fichier JSON.
Crée anonymisation.py :
import os
import json
from presidio_analyzer import AnalyzerEngine
from presidio_analyzer.nlp_engine import NlpEngineProvider
DOSSIER_SOURCE = "documents"
DOSSIER_ANONYMISE = "documents_anonymises"
DOSSIER_RECONSTRUIT = "documents_reconstruits"
FICHIER_CORRESPONDANCE = "correspondance.json"
configuration = {
"nlp_engine_name": "spacy",
"models": [{"lang_code": "fr", "model_name": "fr_core_news_sm"}]
}
provider = NlpEngineProvider(nlp_configuration=configuration)
nlp_engine = provider.create_engine()
analyzer = AnalyzerEngine(nlp_engine=nlp_engine, supported_languages=["fr"])
os.makedirs(DOSSIER_ANONYMISE, exist_ok=True)
os.makedirs(DOSSIER_RECONSTRUIT, exist_ok=True)
correspondance_globale = {}
for nom_fichier in sorted(os.listdir(DOSSIER_SOURCE)):
if not nom_fichier.endswith(".txt"):
continue
chemin_source = os.path.join(DOSSIER_SOURCE, nom_fichier)
with open(chemin_source, "r", encoding="utf-8") as f:
texte = f.read()
resultats = analyzer.analyze(text=texte, language="fr")
resultats_tries = sorted(resultats, key=lambda r: r.start, reverse=True)
correspondance_fichier = {"prenom": None, "autres_elements_personnels": []}
texte_anonymise = texte
compteur_autres = 0
prenom_trouve = False
for res in resultats_tries:
valeur = texte[res.start:res.end]
if res.entity_type == "PERSON" and not prenom_trouve:
jeton = "PERSONNE_1"
correspondance_fichier["prenom"] = {"jeton": jeton, "valeur": valeur}
prenom_trouve = True
else:
compteur_autres += 1
jeton = f"AUTRE_{compteur_autres}"
correspondance_fichier["autres_elements_personnels"].append(
{"jeton": jeton, "valeur": valeur, "categorie": res.entity_type}
)
texte_anonymise = texte_anonymise[:res.start] + jeton + texte_anonymise[res.end:]
with open(os.path.join(DOSSIER_ANONYMISE, nom_fichier), "w", encoding="utf-8") as f:
f.write(texte_anonymise)
correspondance_globale[nom_fichier] = correspondance_fichier
texte_reconstruit = texte_anonymise
if correspondance_fichier["prenom"]:
texte_reconstruit = texte_reconstruit.replace(
correspondance_fichier["prenom"]["jeton"],
"[ " + correspondance_fichier["prenom"]["valeur"] + " ]"
)
if correspondance_fichier["autres_elements_personnels"]:
texte_reconstruit += "\n\nAutres elements personnels detectes :\n"
for item in correspondance_fichier["autres_elements_personnels"]:
texte_reconstruit += f"- {item['jeton']} : {item['valeur']} ({item['categorie']})\n"
with open(os.path.join(DOSSIER_RECONSTRUIT, nom_fichier), "w", encoding="utf-8") as f:
f.write(texte_reconstruit)
with open(FICHIER_CORRESPONDANCE, "w", encoding="utf-8") as f:
json.dump(correspondance_globale, f, ensure_ascii=False, indent=2)
print("Termine. Verifie documents_anonymises/, documents_reconstruits/ et correspondance.json")
Lance le script :
python anonymisation.py
Le dossier documents_reconstruits/ sert de test intermédiaire : il réinjecte immédiatement le prénom entre crochets ([ Léa ]) pour vérifier visuellement que le mécanisme fonctionne, avant même d’ajouter le traitement IA.
Sur les 5 documents testés, la détection a globalement bien fonctionné, avec deux limites observées :
sur personne1.txt, Presidio n’a détecté aucune entité, y compris le prénom Léa pourtant présent en clair. Le modèle léger fr_core_news_sm peut manquer certains prénoms.
sur personne3.txt, le mot « Salut » a été classé comme un lieu (LOCATION), un faux positif.
Ces limites sont attendues avec un modèle allégé et font partie de ce qu’on cherche à observer dans ce test.
Le traitement par IA
Le texte anonymisé est envoyé à qwen2.5:3b via Ollama, avec une consigne qui demande à la fois l’animal préféré et un signalement de toute donnée personnelle restante dans le texte, une façon de vérifier si l’IA repère les éventuels oublis de l’étape précédente.
Un test sur un seul fichier permet de vérifier le format de réponse avant de généraliser :
import requests
with open("documents_anonymises/personne2.txt", "r", encoding="utf-8") as f:
texte_anonymise = f.read()
prompt = f"""Voici un texte. Reponds uniquement avec ce format exact, sans phrase supplementaire :
Animal prefere : [ton animal trouve]
Attention - donnees personnelles : [liste les elements qui sont des donnees personnelles, ou ecris "aucun"]
Texte : {texte_anonymise}"""
reponse = requests.post(
"http://localhost:11434/api/generate",
json={"model": "qwen2.5:3b", "prompt": prompt, "stream": False}
)
print(reponse.json()["response"])
Une fois le format validé, le script complet traite les 5 documents :
import os
import json
import requests
DOSSIER_ANONYMISE = "documents_anonymises"
FICHIER_RESULTATS = "resultats_ia.json"
resultats = {}
for nom_fichier in sorted(os.listdir(DOSSIER_ANONYMISE)):
if not nom_fichier.endswith(".txt"):
continue
chemin = os.path.join(DOSSIER_ANONYMISE, nom_fichier)
with open(chemin, "r", encoding="utf-8") as f:
texte_anonymise = f.read()
prompt = f"""Voici un texte. Reponds uniquement avec ce format exact, sans phrase supplementaire :
Animal prefere : [ton animal trouve]
Attention - donnees personnelles : [liste les elements qui sont des donnees personnelles, ou ecris "aucun"]
Texte : {texte_anonymise}"""
reponse = requests.post(
"http://localhost:11434/api/generate",
json={"model": "qwen2.5:3b", "prompt": prompt, "stream": False}
)
resultats[nom_fichier] = reponse.json()["response"]
print(f"{nom_fichier} traite.")
with open(FICHIER_RESULTATS, "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print("Termine. Verifie resultats_ia.json")
Sur plusieurs exécutions successives de ce script, un même document (personne5.txt) a systématiquement échoué à respecter le format demandé : au lieu de répondre selon la consigne, le modèle a recopié le texte source. Un autre document a échoué une fois sur trois essais, avant de fonctionner correctement. Ce comportement n’est pas lié au prompt (qui fonctionne pour la majorité des textes), plutôt à une limite connue des petits modèles sur le respect strict d’un format de sortie.
La réinjection finale
Le dernier script combine le prénom réel, l’animal trouvé par l’IA et les éventuelles autres données personnelles détectées, pour produire un document final par personne :
import os
import json
FICHIER_CORRESPONDANCE = "correspondance.json"
FICHIER_RESULTATS_IA = "resultats_ia.json"
DOSSIER_FINAL = "documents_finaux"
with open(FICHIER_CORRESPONDANCE, "r", encoding="utf-8") as f:
correspondance = json.load(f)
with open(FICHIER_RESULTATS_IA, "r", encoding="utf-8") as f:
resultats_ia = json.load(f)
os.makedirs(DOSSIER_FINAL, exist_ok=True)
for nom_fichier, corr in correspondance.items():
prenom = corr["prenom"]["valeur"] if corr["prenom"] else "PRENOM_NON_DETECTE"
reponse_ia = resultats_ia.get(nom_fichier, "")
animal = "non determine (echec du modele IA)"
for ligne in reponse_ia.splitlines():
if ligne.strip().lower().startswith("animal prefere"):
animal = ligne.split(":", 1)[1].strip()
break
contenu_final = f"Prenom : {prenom}\n"
contenu_final += f"Animal prefere : {animal}\n"
if corr["autres_elements_personnels"]:
contenu_final += "\nAutres elements personnels detectes :\n"
for item in corr["autres_elements_personnels"]:
contenu_final += f"- {item['jeton']} : {item['valeur']} ({item['categorie']})\n"
nom_sortie = nom_fichier.replace(".txt", "_final.txt")
with open(os.path.join(DOSSIER_FINAL, nom_sortie), "w", encoding="utf-8") as f:
f.write(contenu_final)
print("Termine. Verifie le dossier documents_finaux/")
Résultat obtenu sur les 5 documents :
Prenom : PRENOM_NON_DETECTE
Animal prefere : axolotl
Prenom : Thomas
Animal prefere : fennec
Prenom : Camille
Animal prefere : Quokka
Autres elements personnels detectes :
- AUTRE_1 : Salut (LOCATION)
Prenom : Julien
Animal prefere : pangolin
Prenom : Sophie
Animal prefere : non determine (echec du modele IA)
Chaque cas d’échec est signalé explicitement dans le document final, plutôt que masqué ou laissé vide, ce qui permet de voir immédiatement où le workflow a besoin d’être amélioré.
Ce qu’on a appris
Un PC ancien de bureautique suffit. Aucune lenteur notable, y compris pendant les 5 appels au modèle IA.
Le modèle spaCy léger a ses limites. Un prénom sur cinq n’a pas été détecté, et un faux positif est apparu sur un autre texte. Un modèle plus complet (fr_core_news_md) mériterait un test comparatif avant un usage réel.
Le petit modèle IA est inconstant sur le format. Un même texte peut réussir ou échouer à respecter la consigne selon l’essai. Une piste pour réduire cette variabilité, non testée ici : fixer le paramètre temperature à 0 dans la requête envoyée à Ollama.
Le principe fonctionne malgré ces limites. Le workflow complet, de la détection à la réinjection, tourne de bout en bout sans erreur bloquante, avec une gestion propre des cas d’échec.
Des cas d’usage possibles en entreprise
Ce principe dépasse largement le simple test avec des animaux préférés. Quelques exemples concrets :
Formulaires de contact ou de prospection : un prospect décrit son besoin, le texte est anonymisé avant d’être traité par une IA qui propose une base de réponse ou de devis, puis l’identité est réinjectée à la fin.
Formation : traiter des retours d’expérience ou des évaluations sans exposer l’identité des participants pendant l’analyse.
Plus largement, tout traitement IA sur des documents contenant des données sensibles, où l’on veut garder un contrôle strict sur qui voit quoi et à quel moment.
Open WebUI ne sait pas lire un PDF scanné : il faut une couche d’OCR. Tika, un service Apache open source, comble ce manque. Voici comment l’installer, le piège à éviter, et ce que ça change vraiment sur un Mini PC.
Cet article fait partie de deux séries :
la série des articles sur Linux et des logiciels installés en containers Docker : projets Ubuntu
la série des articles sur la création d’une IA locale dans mon bureau : Créer une IA locale
Pourquoi Tika
Si tu as suivi l’article sur le RAG dans Open WebUI, tu as déjà l’embedding configuré avec nomic-embed-text, et tu sais que les modèles texte uniquement comme qwen2.5:3b ne lisent que le texte extrait d’un PDF, jamais une image.
Le problème, c’est que rien ne distingue à l’œil un PDF texte natif d’un PDF scanné : seul le contenu diffère. Si tu déposes un PDF scanné sans précaution, Open WebUI l’indexe sans erreur visible, mais le document reste vide de tout texte utilisable. Le modèle répond alors qu’il ne trouve pas l’information, même si elle est sous ses yeux.
Tika résout ce problème : c’est un serveur qui extrait le texte de n’importe quel format de document, PDF compris, et qui sait appliquer une reconnaissance optique de caractères (OCR) quand le PDF est une image plutôt que du texte.
Étape 1 – Installer Tika via Portainer
Avant d’installer un nouveau container, vérifie les ports déjà utilisés :
Tika ne nécessite pas de volume : il traite les fichiers à la volée, sans rien conserver entre les requêtes. Si tu veux un jour personnaliser son comportement (désactiver l’OCR, ajuster sa résolution), cela se fait via un fichier de configuration séparé, mais ce n’est pas nécessaire pour un usage standard.
Crée quand même un répertoire dédié, pour garder une trace du paramétrage en cas de réinstallation sur une autre machine :
Le piège à éviter : l’image apache/tika existe en deux versions. Le tag latest correspond à une version minimale, sans aucune capacité d’OCR. Pour que Tika sache lire un PDF scanné, il faut impérativement le tag latest-full, qui inclut Tesseract OCR. Avec le tag latest seul, l’installation semble fonctionner (le container démarre, le port répond), mais l’extraction d’un PDF image renvoie systématiquement un résultat vide, sans message d’erreur explicite.
Dans Portainer : Stacks > Add stack, nomme-le tika, colle le contenu ci-dessus dans l’éditeur web, puis déploie.
Si le texte du document s’affiche dans le terminal, l’OCR fonctionne. Une sortie vide signale que l’image utilisée n’est pas la version -full.
Étape 2 – Connecter Tika à Open WebUI
Connecte-toi à Open WebUI avec un compte administrateur, puis va dans Panneau d’administration > Réglages > Documents.
Dans Moteur d’extraction de contenu, sélectionne Tika, puis renseigne l’adresse du serveur :
http://tika:9998
Le nom tika correspond au nom du container, résolu automatiquement puisque Tika et Open WebUI partagent le même réseau Docker (ollama_default). Enregistre.
Je n’ai pas testé ce qui se passe pour des documents déjà indexés avant ce changement de moteur : il est possible qu’une réindexation soit nécessaire pour qu’ils bénéficient de l’OCR rétroactivement. Si tu pars d’une base de connaissances neuve, la question ne se pose pas.
Étape 3 – Tester avec un vrai PDF scanné
Pour être certain qu’un PDF est une image et non du texte, essaie de sélectionner du texte avec la souris dans une visionneuse PDF : si rien ne se sélectionne, c’est un scan.
Test en base de connaissances. Dans Espace de travail > Connaissances, ouvre une base existante (ou crée-en une), et dépose le PDF scanné. L’indexation se déroule sans erreur visible. Pose ensuite une question dont la réponse se trouve uniquement dans ce document, à l’agent associé à la base. La réponse est correcte et cite le document.
Test en pièce jointe directe. Dans une conversation normale, joins le même PDF directement au message, sans passer par une base de connaissances. La réponse arrive, correcte également, mais avec un temps de traitement nettement plus long.
Les deux scénarios fonctionnent : l’objectif principal (PDF scanné joint directement dans le chat) est atteint, tout comme le repli (PDF scanné en base de connaissances).
Le verdict : ça marche, mais c’est lent
Sur un Mini PC (Intel i5, 16 Go de RAM) qui fait déjà tourner Home Assistant, Mosquitto, Zigbee2MQTT, Ollama et Open WebUI, l’OCR via Tika consomme des ressources que la machine n’a pas en réserve. Le résultat est juste, mais l’attente se fait sentir, surtout en pièce jointe directe dans le chat.
Ce n’est pas une limite de Tika : l’OCR est par nature gourmand en calcul, quel que soit l’outil utilisé. Sur un matériel plus généreux, ou avec un GPU dédié, le temps de traitement serait nettement réduit.
Dans mon cas, je préfère donc réserver Tika à un usage ponctuel (l’indexation d’un PDF scanné dans une base de connaissances, qui ne se fait qu’une fois), plutôt qu’à un usage répété en pièce jointe directe dans une conversation. Pour les PDF que je sais scannés, je passe en amont par un OCR dédié avec Stirling PDF, déjà installé sur le même Mini PC selon la procédure décrite dans Installer et régler Stirling PDF via Docker. Le PDF ressort avec une couche de texte intégrée, et Open WebUI le traite alors comme un PDF texte natif classique, sans solliciter Tika.
Pour aller plus loin
Cet article fait partie d’une série sur l’IA locale : Créer une IA locale et l’installation de logiciels en containers Docker sous Ubuntu : projets Ubuntu
Ollama et Open WebUI installés, modèles téléchargés – le chat fonctionne. Mais si tu veux interroger tes propres documents sans les envoyer sur un serveur externe, il faut aller un cran plus loin : configurer le RAG. Cet article fait partie de deux séries :
la série des articles sur Linux et des logiciels installés en containers Docker : projets Ubuntu
La série des articles sur la création d’une IA locale dans mon bureau : Créer une IA locale
C’est quoi le RAG ?
RAG est l’acronyme de « Retrieval-Augmented Generation » – en français, génération augmentée par récupération. L’idée est simple : plutôt que de demander au modèle de répondre uniquement à partir de ce qu’il a appris pendant son entraînement, on lui fournit des passages extraits de tes propres documents. Le modèle s’appuie sur ces passages pour construire sa réponse.
En pratique, ça change tout : tu peux créer un assistant qui connaît ta documentation interne, tes notes, tes rapports – et qui répond en citant ses sources. Et si c’est fait dans un système local, rien ne sort vers l’extérieur.
Le rôle de l’embedding
Pour que le RAG fonctionne, le système doit être capable de trouver rapidement les passages pertinents dans tes documents avant de les transmettre au modèle. C’est le rôle de l’embedding – qu’on pourrait traduire par vectorisation sémantique, même si ce terme n’est pas d’usage courant.
Un modèle d’embedding lit chaque paragraphe de tes documents et le convertit en une liste de coordonnées mathématiques – un vecteur. Deux paragraphes qui parlent du même sujet auront des coordonnées proches, même s’ils n’utilisent pas les mêmes mots. Quand tu poses une question, ta question est convertie de la même façon, et le système trouve en quelques millisecondes les paragraphes les plus proches.
Le LLM ne reçoit alors que ces quelques paragraphes pertinents – pas l’intégralité du document. Sur un CPU sans carte graphique dédiée, c’est ce qui rend le système utilisable : le modèle n’a que quelques lignes à lire pour formuler sa réponse.
Les modèles testés dans cet article : qwen2.5:3b comme LLM, nomic-embed-text comme modèle d’embedding
Étape 1 – Télécharger le modèle d’embedding
nomic-embed-text est un modèle léger (~270 Mo), rapide sur CPU, avec une fenêtre de contexte de 8192 tokens – ce qui permet de découper les documents en morceaux suffisamment grands pour conserver le sens.
nomic-embed-text doit apparaître dans la liste aux côtés de tes modèles LLM.
Étape 2 – Configurer l’embedding dans Open WebUI
Dans Open WebUI, connecte-toi avec ton compte administrateur, puis va dans Panneau d’administration > Réglages > Documents.
Dans la section Embedding :
Moteur de modèle d’embedding : sélectionne Ollama
Modèle d’embedding : saisis nomic-embed-text
Clique sur Enregistrer.
Open WebUI délègue désormais toute la vectorisation à Ollama. Les deux modèles – LLM et embedding – tournent sur le même moteur, sans duplication de ressources.
Étape 3 – Créer une base de connaissances
Une base de connaissances est un ensemble de documents indexés sur un thème donné. C’est l’équivalent local d’un Projet Claude ou d’un Gem Gemini – sans que rien ne sorte de ta machine.
Dans Open WebUI, va dans Espace de travail > Connaissances, puis crée une nouvelle base avec un nom explicite (par exemple « Réglementation formation » ou « Documentation projet X »).
Glisse-dépose tes fichiers PDF ou TXT dans la zone dédiée. Le CPU va s’activer quelques secondes – c’est nomic-embed-text qui indexe et vectorise les documents en arrière-plan. Une fois l’indexation terminée, la base est prête.
Quelques points à garder en tête :
Les modèles texte uniquement (qwen2.5:3b, llama3.1, mistral) ne peuvent pas traiter des images – seul le texte extrait des PDF est utilisable
Pour les très longs documents (plus de 50-100 pages), laisse le CPU terminer l’indexation avant d’en ajouter d’autres
Étape 4 – Créer un agent associé à la base
La base de connaissances seule ne fait rien – il faut lui associer un agent, c’est-à-dire un modèle configuré avec un comportement précis.
Dans Espace de travail > Modèles, clique sur Créer un modèle, puis :
Donne-lui un nom explicite (par exemple « Assistant formation »)
Modèle de base : sélectionne qwen2.5:3b
Dans la section Connaissances, associe la base créée à l’étape précédente
Rédige un system prompt
Le system prompt est crucial. Sans instruction claire, le modèle complète avec ses connaissances générales plutôt que de s’appuyer sur tes documents. Un exemple efficace :
« Tu es l’assistant de [ton rôle]. Tu réponds uniquement à partir des documents fournis dans ta base de connaissances. Si une information n’y figure pas, dis-le clairement sans inventer. Ne complète jamais avec tes connaissances générales. »
Sauvegarde. L’agent est prêt.
Ce que ça fait vraiment
Les tests sur cette configuration (Mini PC Ubuntu, Intel i5, 16 Go de RAM) donnent des résultats concluants sur des documents de quelques pages à une vingtaine de pages. Le modèle cite ses sources, répond aux questions dans le périmètre des documents, et indique clairement quand une information est absente.
Quelques limites à connaître :
Documents texte uniquement. Les modèles testés ici (qwen2.5:3b et les autres) ne traitent pas les images. Envoyer une image depuis Open WebUI produit une erreur. Seul le texte extrait des PDF est utilisable par le RAG.
Les PDF scannés nécessitent une étape supplémentaire. Le moteur d’extraction par défaut d’Open WebUI ne sait pas lire un PDF image (un scan sans couche texte). Si tu essaies d’en déposer un dans une base de connaissances, tu obtiendras une erreur silencieuse ou un document vide. La solution est d’ajouter Tika – un service Apache open source – comme moteur d’extraction. Tika s’installe en container Docker séparé et se connecte à Open WebUI via le réseau Docker. Ce point fait l’objet d’un article à venir dans cette série.
Le system prompt fait la différence. Sans instruction explicite de rester dans les sources, le modèle complète avec ses connaissances générales – les réponses paraissent correctes mais ne s’appuient pas sur tes documents. L’instruction « réponds uniquement à partir des documents fournis » change significativement le comportement.
Les réponses ne sont pas déterministes. Le même modèle, la même question, des sessions différentes peuvent produire des réponses légèrement différentes. C’est une caractéristique fondamentale des LLM, pas un dysfonctionnement – et une bonne raison de tester systématiquement après chaque modification de configuration.
Pour aller plus loin
Cet article fait partie d’une série sur l’IA locale : Créer une IA locale et l’installation de logiciels en containers Docker sous ubuntu : Créer une IA locale
Commentaires récents