Votre Open WebUI est installé, vos PDF sont indexés, et pourtant l’assistant invente une aide qui n’existe pas ou rate l’article du règlement sous ses yeux. Ce n’est pas (toujours) la faute du LLM : c’est souvent le pipeline RAG. Ce tutoriel explique chaque réglage utile — taille de chunks, overlap, embedding, top-k, recherche hybride, reranker — et propose une méthode A/B sans faux pourcentages. Prérequis : instance Open WebUI déjà en place ([[ta02|install Docker]]) et idéalement la chaîne de [[ta01|Qwen + RAG]].
Comment marche le RAG dans Open WebUI
Le document est découpé en morceaux, chaque morceau est transformé en vecteur par l’embedding, une recherche trouve les morceaux proches de la question, éventuellement une recherche mots-clés complète le tableau, un reranker peut réordonner, puis le LLM rédige à partir des extraits retenus. Si l’étape « trouver les bons extraits » échoue, le plus gros Qwen du monde brodera. Votre premier réflexe : afficher ou inspecter les sources renvoyées pour une question connue.
Les libellés de menus changent selon les versions. Cherchez les zones Admin liées aux documents, aux embeddings et aux paramètres de retrieval, ainsi que l’attache Knowledge au modèle ou au chat. Si un curseur de ce tutoriel n’a pas le même nom, ciblez la fonction, pas le wording d’un screenshot obsolète.
Diagnostiquer avant de toucher aux curseurs
Posez une question dont la réponse est une phrase exacte d’un PDF. Trois cas. (1) Aucune source / sources absurdes → indexation, Knowledge non liée, ou embedding inadapté. (2) Bonne source, mauvaise réponse → prompt système, température, ou LLM trop créatif. (3) Source presque bonne (mauvais paragraphe) → chunking, top-k, hybride, reranker. Cette triage évite de « régler le reranker » quand la Knowledge n’est simplement pas attachée — erreur vue en atelier à Lille comme à Amiens.
- Vérifier que la Knowledge est bien liée au chat / modèle personnalisé
- Vérifier que l’indexation du fichier s’est terminée sans erreur
- Lire les extraits renvoyés avant de juger la prose du LLM
- Ne changer qu’un paramètre à la fois, avec une grille de questions
Taille des morceaux et chevauchement
Un chunk trop grand mélange plusieurs idées : la similarité devient floue. Un chunk trop petit coupe une condition juridique au milieu : le modèle ne voit que la moitié de la règle. L’overlap (chevauchement) recolle un peu les frontières. Pour des délibérations ou règlements de salles, partez d’une taille modérée et d’un overlap suffisant pour ne pas perdre une phrase charnière, puis ajustez selon vos échecs observés.
Après chaque changement de chunk size / overlap, une ré-indexation est souvent nécessaire. Planifiez-la : sur un corpus de guides d’aides d’une collectivité de Compiègne, ré-indexer n’est pas gratuit en temps. Documentez la paire (size, overlap) dans le README de l’instance.
Le modèle d’embedding
L’embedding dicte la notion de « proximité ». Sur un corpus français administratif, un modèle multilingue orienté retrieval est en général plus sûr qu’un embedding anglophone généraliste. La famille bge-m3 et d’autres candidats multilingues reviennent souvent : vérifiez le tag / identifiant exact du jour dans votre stack. Changer d’embedding impose en pratique de reconstruire l’index.
Le tutoriel embeddings pour RAG français détaille comment comparer qualitativement. Ici, retenez : si des questions paraphrasées échouent alors que la formulation exacte réussit, l’embedding ou l’hybride mots-clés méritent votre attention.
Top-k : combien d’extraits montrer au LLM
Un top-k trop bas prive le modèle du paragraphe utile. Un top-k trop haut noie le prompt de bruit et coûte du contexte. Montez-le seulement si vous voyez le bon extrait régulièrement classé juste après la coupure. Surveillez aussi la taille totale : k élevés + chunks grands = contexte saturé, réponses plus lentes et plus confuses.
En usage équipe sur un mini-PC à Dunkerque, un top-k raisonnable améliore la stabilité plus qu’une course au maximum. Notez la valeur retenue à côté de votre batterie de tests.
Recherche hybride (vectoriel + mots-clés)
La recherche vectorielle capture le sens (« dispositif d’aide à la rénovation » ≈ « subvention isolation »). Les mots-clés capturent les formes exactes : acronymes locaux, noms de délibérations, codes internes. La recherche hybride mélange les deux — souvent précieuse sur des corpus HdF riches en sigles. Si votre interface propose un poids ou un mode hybride / BM25, activez-le quand les échecs portent sur des termes rares.
Attention : l’hybride ne répare pas un PDF scanné non OCR. Le mot-clé absent du texte extractible ne matchera rien. Corrigez d’abord la qualité documentaire.
Reranker : quand l’ajouter
Le reranker reclasse un ensemble de candidats déjà récupérés. Il aide quand le bon document est « dans le lot » mais mal ordonné. Il coûte du calcul et ajoute une pièce à maintenir. Activez-le après avoir stabilisé chunking, embedding et top-k. Si le bon extrait n’est même pas candidat, le reranker ne peut pas l’inventer.
Vérifiez la doc de votre version Open WebUI pour le modèle de rerank proposé et ses prérequis GPU. Sur une machine juste en VRAM, un reranker peut faire basculer l’expérience de « fluide » à « inutilisable ».
Pas à pas : campagne de réglage A/B
Construire la batterie de vingt questions
Dix factuelles (phrase exacte), cinq de synthèse, cinq hors corpus. Pour un corpus public régional, inspirez-vous de vraies questions d’usagers d’une maison France Services à Lens ou d’une asso à Saint-Quentin. Écrivez aussi la réponse attendue et le fichier source. Sans cela, vous « sentirez » au lieu de mesurer. Si quelque chose échoue, arrêtez-vous et notez le message exact avant de retenter. Une capture d’écran des logs vaut mieux qu’une reformulation de mémoire, surtout quand un collègue de Douai ou Arras reprendra le dossier le lendemain.
Figer une configuration A de référence
Notez embedding, chunk size, overlap, top-k, hybride on/off, reranker on/off, modèle LLM, prompt système. Lancez les vingt questions. Cochez OK seulement si la source est bonne et la réponse fidèle. Comptez les OK sans transformer ce ratio en statistique publiée miracle : c’est votre boussole interne. Gardez un bloc-notes ouvert : commande tapée, résultat attendu, résultat obtenu. Cette trace courte accélère le dépannage et évite de croire qu’« on a déjà essayé » sans preuve. Complétez par un test de non-régression : refaites le même geste après avoir fermé puis rouvert l’outil, afin de confirmer que la configuration survit au redémarrage et reste compréhensible pour un collègue qui n’a pas suivi toute la session.
Changer un seul levier pour la configuration B
Exemple : activer l’hybride, ou passer à un autre overlap. Ré-indexez si nécessaire. Rejouez la même batterie. Comparez question par question. Si B gagne sur les acronymes mais perd sur les synthèses, vous tenez un vrai arbitrage métier, pas un mythe de réglage universel. Vérifiez aussi l’environnement : VPN, proxy, antivirus, espace disque. Beaucoup d’échecs attribués au modèle viennent d’un réseau d’entreprise à Lille ou d’un disque plein après plusieurs pulls. Ajoutez une vérification métier : demandez à une personne du terrain de reformuler le besoin en une phrase, puis vérifiez que votre réglage répond vraiment à cette phrase, pas seulement au scénario technique imaginé au départ.
Traiter d’abord les échecs « source absente »
Tout échec où l’extrait utile n’apparaît pas est prioritaire sur le style de la réponse. Chunking, embedding, hybride, top-k, qualité OCR. Le LLM ne peut pas citer un paragraphe qu’il n’a pas reçu — rappel simple, trop souvent oublié en démonstration. Quand l’étape réussit, marquez-la explicitement dans votre checklist. Les bascules trop rapides vers l’étape suivante masquent des configs demi-installées qui cassent plus tard en démo publique. Documentez le contournement éventuel (petit modèle, localhost, hors VPN) pour ne pas rester bloqué en démonstration publique : un plan B écrit vaut mieux qu’une improvisation sous le regard d’un public à Lille ou Amiens.
Ensuite seulement, discipliner le LLM
Quand les sources sont bonnes, resserrez le prompt : répondre uniquement d’après les extraits, citer le fichier, dire « je ne trouve pas » sinon. Baissez la créativité. Si malgré de bonnes sources le modèle divague, changez de LLM ou de température avant de retoucher le reranker. Si vous travaillez à deux, faites reformuler le geste par la personne la moins technique. Ce qui n’est pas dit clairement maintenant reviendra en ticket flou après l’atelier. Mesurez aussi le confort subjectif (bruit, chaleur, temps d’attente ressenti) : un réglage « correct » sur le papier mais pénible au quotidien ne sera pas adopté par une équipe de collectivité ou d’association.
Documenter et former un référent
Une page interne : valeurs finales, date, comment ré-indexer, qui a le droit d’ajouter des PDF. Sans référent, chaque collègue retouche un curseur « pour voir » et l’instance d’Amiens redevient imprévisible. La gouvernance du RAG fait partie du réglage. Testez une fois « à froid » après redémarrage de la machine. Un service qui ne survit pas au reboot n’est pas prêt pour une permanence à Valenciennes ou Amiens. Si le résultat est ambigu, changez une seule variable et rejouez immédiatement le même protocole : c’est la seule façon d’apprendre quelque chose d’exploitable plutôt que d’empiler des impressions contradictoires.
Repères pour le français administratif
Les textes publics régionaux aiment les phrases longues, les listes de conditions et les sigles. Favorisez un splitting qui respecte paragraphes et titres si l’outil le permet. Indexez un petit glossaire des sigles locaux avec le corpus. Préparez des questions paraphrasées (« aide à … » vs nom officiel du dispositif). C’est sur ces paraphrases que l’embedding et l’hybride se jugent.
Évitez de mélanger dans la même Knowledge des documents périmés et des documents en vigueur sans marquage clair : le RAG citera parfois l’ancienne règle avec assurance. Un préfixe de nom de fichier `VIGUEUR_` / `ARCHIVE_` aide les humains — et parfois le retrieval.
Erreurs courantes
- Knowledge créée mais non liée au modèle personnalisé
- Changement d’embedding sans ré-indexation
- PDF image sans OCR
- Top-k élevé qui satura le contexte
- Reranker activé trop tôt sur une machine juste en VRAM
- Prompt qui autorise à « compléter » quand l’extrait manque
- Corpus non versionné : impossible de savoir quoi ré-indexer
Sur un poste partagé à Valenciennes, ajoutez l’erreur humaine : deux admins qui testent en même temps des embeddings différents. Verrouillez les droits admin.
Performance et GPU
Le RAG mobilise l’embedding (parfois un second modèle), éventuellement le reranker, puis le LLM. Sur 12 Go de VRAM « conseillés » en ordre de grandeur, tout faire tenir en parallèle peut être juste. Stratégies : embedding CPU si acceptable, reranker off, LLM plus léger, ou file d’attente. Mesurez la latence ressentie avec votre batterie, pas avec un espoir.
En période de rush (forum de rentrée à Lille, permanence associative à Roubaix), préférez une config « sobre » documentée plutôt que la config de labo maximale. La disponibilité bat la sophistication. Affichez un bandeau interne si vous désactivez temporairement le reranker pour tenir la charge.
Cas pratiques sur corpus régionaux
Guide d’aides habitat : les usagers paraphrasent (« isolation combles » vs nom administratif). Embedding + hybride sont critiques ; ajoutez un glossaire des dispositifs. Règlement d’une salle municipale à Arras : phrases conditionnelles longues — chunks trop petits cassent les « si … alors ». Délibérations publiées à Amiens : titres et numéros de séance utiles en mots-clés ; l’hybride aide.
Mélange FAQ grand public + documents RH internes : séparez les Knowledge. Un agent d’accueil ne doit pas interroger par erreur un fonds sensible. La séparation des bases est un réglage d’organisation autant que de technique. Reliez la politique à données sensibles.
| Symptôme | Levier à tester |
|---|---|
| Rate les paraphrases | Embedding / hybride / questions d’entraînement |
| Rate les sigles locaux | Hybride mots-clés / glossaire indexé |
| Coupe les conditions juridiques | Chunk size + overlap |
| Cite une ancienne version | Séparer archives / vigueur ; nettoyer corpus |
| Invente malgré bonnes sources | Prompt système + température + LLM |
Gouvernance des curseurs
Décidez qui a le droit de modifier embedding, chunking et reranker. Journalisez les changements (date, auteur, ancienne valeur, nouvelle, résultat sur la batterie). Sans ce journal, l’instance Open WebUI d’une collectivité de Cambrai devient un terrain de jeux et plus un service. Un changement = une entrée, même « mineure ».
Planifiez une revue trimestrielle alignée sur les mises à jour logicielles : relire le changelog Open WebUI, rejouer dix questions sentinelles, décider de upgrader ou non. Cette cadence évite autant le gel perpétuel que le yo-yo. Conservez les grilles de réponses dans un dossier daté : elles deviennent votre mémoire institutionnelle quand le référent RAG change de poste à Lille ou Amiens.
Questions fréquentes
Pourquoi mon RAG répond à côté ?
Dans la majorité des cas de terrain, les extraits fournis au LLM sont mauvais ou absents, ou le prompt laisse le modèle inventer. Affichez les sources. Si elles sont fausses, réparez chunking, embedding, hybride, index. Si elles sont justes, disciplinez le LLM. Cette dualité règle plus de tickets que n’importe quel curseur isolé. Pour trancher chez vous, reproduisez le scénario sur la machine réelle avec un protocole court écrit à l’avance. Une conclusion d’atelier à Roubaix ne se transfère pas telle quelle sur un portable différent.
Quelle taille de chunk « idéale » ?
Il n’existe pas de valeur universelle honnête. Elle dépend de la mise en page de vos PDF et de vos questions. Partez d’une valeur modérée, testez les phrases frontières, ajustez. Documentez le choix. Méfiez-vous des chiffres magiques recopiés d’un blog sans rapport avec votre corpus de délibérations. Gardez une fiche datée : question, hypothèse, test, résultat. Cette hygiène évite les débats sans fin et construit une mémoire utile pour la prochaine personne référente. Archivez enfin la preuve (commande, extrait de log, capture datée) dans le dossier du projet : dans trois mois, cette preuve évitera de reconstruire le diagnostic à partir de souvenirs flous.
Dois-je toujours activer le reranker ?
Non. Activez-le quand le bon extrait est souvent présent mais mal classé, et que votre machine le supporte. Sinon, il ajoute de la complexité pour un gain faible. Stabilisez d’abord les bases. Sur une config marginale, le désactiver peut rendre l’outil à nouveau fluide pour l’équipe. Si deux camps s’opposent dans l’équipe, imposez un A/B sur la même batterie de prompts plutôt qu’un vote d’opinion. Le terrain tranche plus vite que les digressions de salon.
La recherche hybride remplace-t-elle un bon embedding ?
Non, elle le complète. L’hybride sauve les identifiants et acronymes ; l’embedding porte les paraphrases. Les deux se nourrissent d’un texte extractible de qualité. Sur des guides d’aides régionaux, la combinaison est souvent pertinente — à valider avec vos questions paraphrasées. Méfiez-vous des captures hors contexte trouvées en ligne. Sans connaître quantification, contexte et charge machine, un chiffre spectaculaire ne dit rien de votre poste à Beauvais. Complétez par un test de non-régression : refaites le même geste après avoir fermé puis rouvert l’outil, afin de confirmer que la configuration survit au redémarrage et reste compréhensible pour un collègue qui n’a pas suivi toute la session.
Comment parler de « taux de réussite » sans mentir ?
Comptez vos OK sur votre batterie interne, pour décider. Ne publiez pas ce ratio comme une étude scientifique ni comme un benchmark IAHDF. Précisez le corpus, la date, la version Open WebUI. L’honnêteté méthodologique fait partie de la culture que nous voulons en Hauts-de-France. Quand le problème semble intermittent, journalisez l’heure, la température perçue et les autres apps ouvertes. Les coïncidences thermiques et mémoire sont fréquentes sur machines partagées. Ajoutez une vérification métier : demandez à une personne du terrain de reformuler le besoin en une phrase, puis vérifiez que votre réglage répond vraiment à cette phrase, pas seulement au scénario technique imaginé au départ.