Info::IA:RAG:wiki sync.py intégration et enrichissement d'une page wiki dans le RAG
KEYWORDS: IA, RAG, PCWIKI
Le 15/09/2026:
Fonctionnement de la synchronisation pcWiki/LOCATOR → RAG Open WebUI (run_sync.sh + wiki_sync.py)
Version : 1.1
Date : 2026-09-15
Machine concernée : srv18 (192.168.1.18)
Scripts : /root/IA/wiki-sync/run_sync.sh (orchestrateur, bash) et /root/IA/wiki-sync/wiki_sync.py (moteur de synchro MediaWiki, python)
Déclenché par : cron root, toutes les 2 minutes — */2 * * * * /root/IA/wiki-sync/run_sync.sh >> /root/IA/wiki-sync/cron.log 2>&1
Remarque sur le nom : le script réellement lancé par cron s'appelle
run_sync.sh (pas run_rsync.sh) — ce dernier nom
n'existe pas sur srv18. run_sync.sh lui-même délègue la partie
wiki à wiki_sync.py (un .py, pas un .sh).
Vue d'ensemble
run_sync.sh est le script réellement lancé par cron. Il fait
trois choses, dans l'ordre :
- il pose un verrou (
flock) puis appellewiki_sync.py,
qui synchronise les pages du wiki MediaWiki interne
(pcwiki.pcstreet.org) vers la base de connaissances
(« Knowledge ») d'Open WebUI qui sert de RAG « Wiki PCStreet » ;
- il synchronise en plus, lui-même directement en bash (fonction
sync_locator()), les fiches d'inventaire LOCATOR (fichiers.locsous/home/LOCATOR, rapatriés par ailleurs via unrsync -aexterne — c'est cersyncamont qui explique la confusion de nom avec « run_rsync.sh ») vers la même base de connaissances ;
- il envoie un e-mail récapitulatif si au moins une page wiki ou une fiche
LOCATOR a été synchronisée.
Pour la partie wiki, wiki_sync.py traite chaque page ainsi :
- récupérée via l'API MediaWiki ;
- convertie de wikitext en Markdown ;
- enrichie sémantiquement par un appel LLM (résumé + mots-clés) ;
- uploadée dans Open WebUI et rattachée à la base de connaissances du RAG.
wiki_sync.py gère trois modes : synchro complète
(--full), synchro incrémentale (mode par défaut, ne traite que
les pages modifiées depuis le dernier run), et backfill de ré-enrichissement
(--reenrich).
Ce que tu appelais « table des matières »
Il n'y a en réalité pas de table des matières classique (liste de
liens vers les sections) générée par le script. Ce qui y ressemble est un
mécanisme denrichissement sémantique : un résumé en une phrase et une
liste de mots-clés, générés par LLM et insérés dans le document juste avant
son indexation dans le RAG. Ce dispositif comble l'écart de vocabulaire
entre une question posée en langage naturel et une fiche technique brute
(cf. /root/rag-eval-queries.md, cas B1/B5 et C1 « Philip »,
2026-09-09).
Étape 1 — Conversion wikitext → Markdown
Fonction : wikitext_to_markdown() / _apply_regex_conversions()
(lignes 347-460).
- Si
mwparserfromhellest disponible, le wikitext est d'abord
parsé proprement (suppression des balises<noinclude>,<includeonly>,<onlyinclude>) ; sinon, conversion basique par regex uniquement (fallback).
- Les titres MediaWiki
==Titre==à=====Titre=====
sont convertis en titres Markdown##à#####, ce qui préserve la hiérarchie des sections dans le document final.
- Gras/italique, liens internes/externes, listes à puces/numérotées,
lignes horizontales, balises HTML courantes (<br>,<code>,<pre>,<ref>...), templates complexes, images et catégories sont également convertis ou nettoyés.
- Le titre de la page est ajouté en en-tête :
# Titre.
Étape 2 — Enrichissement sémantique (résumé + mots-clés)
Fonction : generate_enrichment() (lignes 462-525). Activé
uniquement si ENRICHMENT_ENABLED=true (variable d'environnement,
opt-in, désactivé par défaut).
En un seul appel LLM (modèle gpt-oss-120b par défaut, cf.
ENRICHMENT_MODEL), le script demande deux informations sur le
Markdown de la page (texte intégral envoyé, non tronqué à 4000 caractères
comme dans une ancienne version — jusqu'à ENRICHMENT_MAX_INPUT_CHARS
= 60000 caractères) :
- SUMMARY : une phrase factuelle expliquant à quel besoin/problème la
fiche répond, pour que le retrieval sémantique retrouve la page même sans recouvrement lexical avec une question paraphrasée.
- KEYWORDS : la liste de tous les noms propres, alias, lieux et
termes rares présents littéralement dans le texte (aucune invention), pour les cas où un nom isolé est noyé dans un chunk dense et invisible pour le seul embedding.
Le prompt système précise Reasoning: low : sur gpt-oss-120b
(format harmony), un raisonnement caché trop long peut à lui seul dépasser
le budget de tokens et tronquer la réponse avant même la ligne KEYWORDS —
d'où aussi la marge ENRICHMENT_MAX_TOKENS = 4000 (mesuré :
~1830 tokens nécessaires sur le cas le plus dense rencontré, « Carnet
d'adresses.txt »).
Étape 3 — Injection dans le document
Fonction appelante : sync_page() (lignes 718-722) ; injection
périodique : inject_keywords_periodically() (lignes 528-558).
- Le résumé est inséré une seule fois, immédiatement après le
titre : # Titre\n\n{résumé}\n\n....
- Les mots-clés sont réinjectés à intervalles réguliers (tous
lesKEYWORDS_INJECTION_INTERVAL= 700 caractères par défaut, toujours sur une frontière de ligne complète) sous la forme[KEYWORDS: ...], uniquement si le document dépasseKEYWORDS_INJECTION_MIN_LENGTH= 1200 caractères.
- Raison de cette répétition : Open WebUI redécoupe ensuite le document en
chunks (taille ~1000 caractères, overlap 150, configurés côté serveur). Un résumé ou un mot-clé posé une seule fois en tête de page ne profite qu'au premier chunk ; pour un document long (ex. un carnet d'adresses), un nom cité une seule fois en profondeur resterait invisible pour l'embedding de son propre chunk sans cette réinjection.
- Un marqueur final est toujours posé après la dernière ligne, même si
l'intervalle n'est pas atteint : sans cela, la « queue » du document (après le dernier marqueur périodique) ne contenait jamais de mots-clés — bug constaté avec un nom cité en toute fin de « Carnet d'adresses.txt » (~700 derniers caractères non couverts).
Important : le hash de comparaison (content_hash(), pour
la synchro incrémentale) est calculé sur le Markdown avant
enrichissement, afin que la détection de changement reste stable même si le
résumé LLM varie légèrement d'un run à l'autre sur un contenu wiki
inchangé.
Étape 4 — Upload vers Open WebUI
Fonctions : owui_upload_file(),
owui_add_file_to_knowledge() (lignes 565-627).
- Le Markdown enrichi est sauvegardé localement dans
/root/IA/wiki-sync/markdown/<titre_normalisé>.txt.
- Si la page avait déjà été synchronisée auparavant, l'ancienne version est
d'abord retirée de la base de connaissances puis supprimée d'Open WebUI (évite les doublons dans le RAG).
- Le nouveau fichier est uploadé via l'API Open WebUI
(POST /api/v1/files/), puis rattaché à la base de connaissances cible (POST /api/v1/knowledge/{knowledge_id}/file/add) — identifiant de la base :b0d9c9f6-f38b-45af-878a-383c80d34566(« Wiki PCStreet »).
- L'état de synchronisation (revid, file_id, hash, date) est persisté dans
/root/IA/wiki-sync/sync_state.json.
Le wrapper run_sync.sh
C'est ce script, et non wiki_sync.py directement, qui est
inscrit dans le crontab root. Il orchestre trois étapes.
1. Verrouillage
Un verrou flock sur /root/IA/wiki-sync/.run_sync.lock
empêche deux exécutions concurrentes (cron toutes les 2 minutes + lancements
manuels) : deux runs simultanés sur les mêmes pages provoquaient des
« Duplicate content detected » côté Open WebUI (même hash, file_id
différent). Si un run est déjà en cours, le nouveau se termine
immédiatement (log dans cron.log), sans erreur.
2. Synchro wiki (délégation à wiki_sync.py)
Le venv Python dédié (/root/IA/open-webui.debian12/venv) est
activé, puis wiki_sync.py est appelé avec les arguments reçus
par run_sync.sh ("$@" — par défaut aucun, donc
mode incrémental). La sortie est dupliquée dans
/root/IA/wiki-sync/last_run.log. Un échec de cette étape n'est
pas fatal : la synchro LOCATOR qui suit doit tourner quand même.
3. Synchro LOCATOR (fonction sync_locator)
En parallèle du wiki, run_sync.sh intègre aussi dans le même
RAG les fiches d'inventaire LOCATOR : des fichiers texte
*.loc sous /home/LOCATOR (rapatriés par ailleurs
via un rsync -a externe à ce script — c'est ce rsync amont, et
non ce script-ci, qui explique le nom « run_rsync.sh » évoqué au départ).
- Détection par contenu, pas par date :
rsync -a
préserve la date d'origine des fichiers, donc un.locfraîchement arrivé garde une vieille date de modification et serait raté par une détection basée surfind -newer. Le script calcule donc un hash MD5 du Markdown généré pour chaque fiche.
- Génération du Markdown : pour chaque
.loc, un petit
Markdown est fabriqué à la volée — titre lisible (chemin avec/et_remplacés par des espaces, ex.garage/etagere_haute.loc→ « garage > etagere haute »), ligne d'emplacement, puis une ligne par champ du fichier (les commentaires#et lignes vides sont supprimés,:devient « — »).
- État persisté dans
/root/IA/wiki-sync/locator_files.map
(colonnes : chemin relatif, file_id Open WebUI, hash MD5).
Une fiche déjà synchronisée et de hash inchangé est ignorée.
- Comme pour le wiki, une ancienne version est retirée de la base de
connaissances puis supprimée d'Open WebUI avant l'upload de la nouvelle.
- Upload et rattachement suivent le même schéma d'API Open WebUI que pour le
wiki (POST /api/v1/files/puisPOST /api/v1/knowledge/{id}/file/add), versLOC_KNOWLEDGE_ID— par défaut la même base que le wiki (OWUI_KNOWLEDGE_ID), modifiable via.env.
4. Notification e-mail
Si au moins une page wiki (détectée via grep "Synchronisé" sur
last_run.log) ou une fiche LOCATOR a été synchronisée pendant
le run, un e-mail récapitulatif (liste des pages/fiches) est envoyé via
ssmtp à l'adresse configurée (MAIL_TO).
Modes d'exécution
- Par défaut (
run_incremental_sync()) : synchronise
uniquement les pages modifiées depuis le dernier run (API MediaWiki
list=recentchanges). Si aucune synchro précédente n'existe,
bascule automatiquement en synchro complète.
--full(run_full_sync()) : reparcourt
toutes les pages de tous les namespaces du wiki.
--reenrich(run_reenrich()) : force le
ré-enrichissement + ré-upload de toutes les pages déjà synchronisées, en
ignorant le hash de comparaison — utilisé une fois après activation de
ENRICHMENT_ENABLED pour rattraper les pages indexées avant
cette bascule.
--page <titre>: synchronise une seule page (test).--dry-run: liste les pages qui seraient synchronisées,
sans rien modifier.
Variables d'environnement (configuration)
| Variable | Défaut | Rôle |
|---|---|---|
WIKI_API_URL |
https://pcwiki.pcstreet.org/api.php |
Endpoint API MediaWiki |
OWUI_BASE_URL |
http://localhost:8081 |
Open WebUI |
OWUI_EMAIL |
pchevalier@pcstreet.fr |
Compte Open WebUI utilisé pour l'upload |
OWUI_PASSWORD |
(vide, obligatoire) | Mot de passe du compte ci-dessus |
OWUI_KNOWLEDGE_ID |
b0d9c9f6-f38b-45af-878a-383c80d34566 |
Base de connaissances cible (RAG « Wiki PCStreet ») |
ENRICHMENT_ENABLED |
false |
Active le résumé + mots-clés LLM (opt-in) |
ENRICHMENT_LLM_URL |
http://192.168.1.111:8090/v1/chat/completions |
Endpoint LLM d'enrichissement |
ENRICHMENT_MODEL |
gpt-oss-120b |
Modèle utilisé pour le résumé/mots-clés |
ENRICHMENT_MAX_INPUT_CHARS |
60000 |
Taille max du texte envoyé au LLM |
ENRICHMENT_MAX_TOKENS |
4000 |
Budget de tokens de complétion (marge pour le raisonnement caché de gpt-oss-120b) |
KEYWORDS_INJECTION_INTERVAL |
700 |
Intervalle (caractères) entre deux réinjections de mots-clés |
KEYWORDS_INJECTION_MIN_LENGTH |
1200 |
Taille minimale du document pour déclencher la réinjection périodique |
Ces valeurs sont définies dans /root/IA/wiki-sync/.env (fichier
non versionné, permissions restreintes).
Fichiers associés
/root/IA/wiki-sync/run_sync.sh— wrapper appelé par cron
toutes les 2 minutes (verrou, appel wiki_sync.py, sync LOCATOR, email).
/root/IA/wiki-sync/wiki_sync.py— moteur de synchro
MediaWiki → Open WebUI, appelé par le wrapper ci-dessus.
/root/IA/wiki-sync/.run_sync.lock— verrou anti-concurrence
(flock) utilisé parrun_sync.sh.
/root/IA/wiki-sync/sync_state.json— état de synchronisation
wiki (revid/file_id/hash par page).
/root/IA/wiki-sync/locator_files.map— état de synchronisation
LOCATOR (chemin/file_id/hash par fiche .loc).
/root/IA/wiki-sync/markdown/— copie locale des documents
Markdown envoyés à Open WebUI (partie wiki).
/root/IA/wiki-sync/wiki_sync.log,cron.log,
last_run.log,last_run_locator.log— journaux d'exécution.
/home/LOCATOR— arborescence des fiches.loc
(alimentée par un rsync -a externe à ces deux scripts).
/root/rag-eval-queries.md— jeu de questions d'évaluation du
RAG ayant motivé l'ajout de l'enrichissement sémantique.
Copie du script run_sync.sh
Copie intégrale de /root/IA/wiki-sync/run_sync.sh au
2026-09-15 — c'est le script réellement inscrit dans le crontab root :
#!/bin/bash
set -euo pipefail
# sh /root/IA/wiki-sync/run_sync.sh 2>&1 |tee -a /root/IA/wiki-sync/cron.log 2>&1
# cron fournit un PATH minimal (/usr/bin:/bin) qui n'inclut pas /usr/sbin
# ou se trouve ssmtp -> on force un PATH complet.
export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
SYNC_DIR="/root/IA/wiki-sync"
VENV_DIR="/root/IA/open-webui.debian12/venv"
MAIL_TO="pchevalier@pcstreet.fr"
# Empeche les executions concurrentes (cron toutes les 5 min + lancements
# manuels) : deux runs simultanes sur les memes pages provoquent des
# "Duplicate content detected" cote Open WebUI (meme hash, file_id different).
LOCK_FILE="$SYNC_DIR/.run_sync.lock"
exec 200>"$LOCK_FILE"
if ! flock -n 200; then
echo "$(date '+%Y-%m-%d %H:%M:%S') [INFO] run_sync.sh deja en cours, run ignore." >> "$SYNC_DIR/cron.log"
exit 0
fi
LOCATOR_DIR="${LOCATOR_DIR:-/home/LOCATOR}"
set -a
source "$SYNC_DIR/.env"
set +a
# Defaults alignes sur wiki_sync.py (surcharges par .env si presents)
OWUI_BASE_URL="${OWUI_BASE_URL:-http://192.168.1.18:8081}"
OWUI_EMAIL="${OWUI_EMAIL:-pchevalier@pcstreet.fr}"
OWUI_PASSWORD="${OWUI_PASSWORD:-}"
OWUI_KNOWLEDGE_ID="${OWUI_KNOWLEDGE_ID:-b0d9c9f6-f38b-45af-878a-383c80d34566}"
# Par defaut, meme base RAG que le wiki (modifiable via .env)
LOC_KNOWLEDGE_ID="${LOC_KNOWLEDGE_ID:-$OWUI_KNOWLEDGE_ID}"
LOC_LOG="$SYNC_DIR/last_run_locator.log"
LOC_MAP="$SYNC_DIR/locator_files.map"
LOC_COUNT=0
LOC_PAGES=""
# --- helpers Open WebUI -----------------------------------------------------
owui_json_field() {
# lit du JSON sur stdin, imprime le champ $1 (vide si absent / erreur)
python3 -c 'import sys, json
field = sys.argv[1]
try:
print(json.load(sys.stdin).get(field, "") or "")
except Exception:
print("")' "$1"
}
owui_token() {
curl -s -X POST "$OWUI_BASE_URL/api/v1/auths/signin" \
-H 'Content-Type: application/json' \
-d "{\"email\":\"$OWUI_EMAIL\",\"password\":\"$OWUI_PASSWORD\"}" \
| owui_json_field token
}
# --- synchronisation LOCATOR (.loc) ----------------------------------------
# Detection par CONTENU (md5), pas par mtime : les .loc sont rapatries via
# 'rsync -a' qui preserve la date d'origine, donc un fichier fraichement
# arrive garde une vieille mtime et serait rate par 'find -newer'.
# Etat : $LOC_MAP, lignes rel <TAB> file_id <TAB> md5
sync_locator() {
if [[ ! -d "$LOCATOR_DIR" ]]; then
echo "LOCATOR: repertoire $LOCATOR_DIR absent, ignore."
return 0
fi
if [[ -z "$OWUI_PASSWORD" ]]; then
echo "LOCATOR: OWUI_PASSWORD non defini, sync .loc ignoree." >&2
return 0
fi
: > "$LOC_LOG"
# tous les .loc, recursivement
local files=()
mapfile -d '' files < <(find "$LOCATOR_DIR" -type f -name '*.loc' -print0)
if [[ "${#files[@]}" -eq 0 ]]; then
echo "LOCATOR: aucun fichier .loc."
return 0
fi
local token=""
local f rel human title words sum old_id old_sum safe upload_name tmp \
file_id code
for f in "${files[@]}"; do
rel="${f#"$LOCATOR_DIR"/}"
# chemin rendu cherchable : '/' et '_' -> espaces (verger, garage...)
human="${rel%.loc}"
title="${human//\// > }"; title="${title//_/ }"
words="${human//\// }"; words="${words//_/ }"
# markdown genere : titre + emplacement en clair + lignes en phrases.
# '#' = commentaires .loc (ignores), ':' = separateur de champs.
tmp="$(mktemp --suffix=.md)"
{
printf '# LOCATOR : %s\n\n' "$title"
printf 'Emplacement (inventaire LOCATOR) : %s.\n\n' "$words"
sed -e '/^[[:space:]]*#/d' -e '/^[[:space:]]*$/d' \
-e 's/:/ — /g' -e 's/^/- /' -- "$f"
} > "$tmp"
# detection par hash du CONTENU GENERE : un changement de format
# (ce bloc) re-pousse proprement toutes les fiches au prochain run.
sum="$(md5sum < "$tmp" | cut -d' ' -f1)"
# etat precedent (file_id + md5) pour ce chemin
old_id=""
old_sum=""
if [[ -f "$LOC_MAP" ]]; then
old_id="$(awk -F '\t' -v p="$rel" '$1==p{print $2}' \
"$LOC_MAP" | tail -n1)" || true
old_sum="$(awk -F '\t' -v p="$rel" '$1==p{print $3}' \
"$LOC_MAP" | tail -n1)" || true
fi
# deja synchronise et sortie inchangee -> on saute
if [[ -n "$old_sum" && "$old_sum" == "$sum" ]]; then
rm -f "$tmp"
continue
fi
# authentification differee : seulement s'il y a du travail
if [[ -z "$token" ]]; then
token="$(owui_token)" || true
if [[ -z "$token" ]]; then
echo "LOCATOR: authentification Open WebUI echouee." >&2
rm -f "$tmp"
return 0
fi
fi
safe="LOCATOR_${rel//\//_}"
safe="${safe// /_}"
upload_name="${safe}.md"
# si une version precedente existe, la retirer (remplacement propre)
if [[ -n "$old_id" ]]; then
curl -s -X POST \
"$OWUI_BASE_URL/api/v1/knowledge/$LOC_KNOWLEDGE_ID/file/remove" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json' \
-d "{\"file_id\":\"$old_id\"}" >/dev/null || true
curl -s -X DELETE "$OWUI_BASE_URL/api/v1/files/$old_id" \
-H "Authorization: Bearer $token" >/dev/null || true
fi
# upload du fichier
file_id="$(curl -s -X POST "$OWUI_BASE_URL/api/v1/files/" \
-H "Authorization: Bearer $token" \
-F "file=@${tmp};type=text/markdown;filename=${upload_name}" \
| owui_json_field id)" || true
rm -f "$tmp"
if [[ -z "$file_id" ]]; then
echo "LOCATOR: echec upload $rel" >&2
continue
fi
# rattachement : on CONTROLE le code HTTP. 'curl -s' seul renvoie 0
# meme sur erreur HTTP, ce qui masquait les echecs de /file/add.
code="$(curl -s -o /dev/null -w '%{http_code}' -X POST \
"$OWUI_BASE_URL/api/v1/knowledge/$LOC_KNOWLEDGE_ID/file/add" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json' \
-d "{\"file_id\":\"$file_id\"}")" || true
if [[ "$code" == "200" ]]; then
# mise a jour de l'etat rel -> file_id -> md5(sortie)
if [[ -f "$LOC_MAP" ]]; then
awk -F '\t' -v p="$rel" '$1!=p' "$LOC_MAP" > "$LOC_MAP.tmp"
else
: > "$LOC_MAP.tmp"
fi
printf '%s\t%s\t%s\n' "$rel" "$file_id" "$sum" >> "$LOC_MAP.tmp"
mv -f "$LOC_MAP.tmp" "$LOC_MAP"
LOC_COUNT=$(( LOC_COUNT + 1 ))
echo "LOC Synchronise: $rel" | tee -a "$LOC_LOG"
else
echo "LOCATOR: echec ajout KB $rel (HTTP $code)" >&2
curl -s -X DELETE "$OWUI_BASE_URL/api/v1/files/$file_id" \
-H "Authorization: Bearer $token" >/dev/null || true
fi
done
if [[ "$LOC_COUNT" -gt 0 ]]; then
LOC_PAGES="$(sed 's/^LOC Synchronise: / - /' "$LOC_LOG")"
fi
return 0
}
# --- 1) synchronisation wiki (inchangee) -----------------------------------
source "$VENV_DIR/bin/activate"
# Echec wiki non fatal : la sync LOCATOR doit tourner quand meme.
python3 "$SYNC_DIR/wiki_sync.py" "$@" 2>&1 | tee "$SYNC_DIR/last_run.log" || true
# --- 2) synchronisation LOCATOR (.loc) -------------------------------------
sync_locator
# --- 3) notification e-mail (wiki + LOCATOR) -------------------------------
WIKI_PAGES=""
WIKI_COUNT=0
if grep -q "Synchronisé" "$SYNC_DIR/last_run.log"; then
WIKI_PAGES=$(grep "Synchronisé" "$SYNC_DIR/last_run.log" \
| sed 's/.*Synchronisé: / - /')
WIKI_COUNT=$(grep -c "Synchronisé" "$SYNC_DIR/last_run.log")
fi
TOTAL=$(( WIKI_COUNT + LOC_COUNT ))
if [[ "$TOTAL" -gt 0 ]]; then
{
echo "To: $MAIL_TO"
echo "From: pchevalier@pcstreet.fr"
echo "Subject: [Wiki Sync] $WIKI_COUNT wiki + $LOC_COUNT locator"
echo "Content-Type: text/plain; charset=UTF-8"
echo ""
echo "Synchronisation terminee le $(date '+%d/%m/%Y a %H:%M')"
echo ""
if [[ "$WIKI_COUNT" -gt 0 ]]; then
echo "Pages wiki PCStreet mises a jour ($WIKI_COUNT) :"
echo "$WIKI_PAGES"
echo ""
fi
if [[ "$LOC_COUNT" -gt 0 ]]; then
echo "Fiches LOCATOR (.loc) inserees ($LOC_COUNT) :"
echo "$LOC_PAGES"
echo ""
fi
echo "-- wiki_sync sur srv18"
} | ssmtp "$MAIL_TO"
fi
Copie du script wiki_sync.py
Copie intégrale de /root/IA/wiki-sync/wiki_sync.py au 2026-09-15
(seule adaptation : la ligne contenant littéralement <pre>
et </pre> — un motif regex du script — a été échappée en
entités HTML pour ne pas casser le bloc <pre> ci-dessous ;
le comportement du code n'est pas affecté) :
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
wiki_sync.py — Synchronisation MediaWiki → Open WebUI Knowledge Base
=====================================================================
- Récupère les pages du wiki via l'API MediaWiki
- Convertit le wikitext en Markdown
- Uploade les fichiers dans la base de connaissances Open WebUI
- Mode incrémental : ne synchronise que les pages modifiées depuis le dernier run
- Gestion robuste des erreurs et logging
Auteur : Claude HAL pour Patrick Chevalier
Date : 2026-04-19
"""
import json
import logging
import os
import re
import sys
import time
import hashlib
import tempfile
from datetime import datetime, timezone
from pathlib import Path
from typing import Optional
import requests
try:
import mwparserfromhell
HAS_MWPARSER = True
except ImportError:
HAS_MWPARSER = False
print("AVERTISSEMENT: mwparserfromhell non installé. "
"Conversion wikitext basique uniquement.", file=sys.stderr)
# =============================================================================
# CONFIGURATION — Adapter ces valeurs à votre environnement
# =============================================================================
# MediaWiki
WIKI_API_URL = os.getenv("WIKI_API_URL",
"https://pcwiki.pcstreet.org/api.php")
# Open WebUI
OWUI_BASE_URL = os.getenv("OWUI_BASE_URL", "http://localhost:8081")
OWUI_EMAIL = os.getenv("OWUI_EMAIL", "pchevalier@pcstreet.fr")
OWUI_PASSWORD = os.getenv("OWUI_PASSWORD", "") # À définir !
OWUI_KNOWLEDGE_ID = os.getenv("OWUI_KNOWLEDGE_ID",
"b0d9c9f6-f38b-45af-878a-383c80d34566")
# Répertoires de travail
SYNC_DIR = Path(os.getenv("SYNC_DIR", "/root/IA/wiki-sync"))
MARKDOWN_DIR = SYNC_DIR / "markdown"
STATE_FILE = SYNC_DIR / "sync_state.json"
LOG_FILE = SYNC_DIR / "wiki_sync.log"
# Namespaces à synchroniser (-1 = tous, sinon liste ex: [0, 4, 12])
# 0=Principal, 1=Discussion, 2=Utilisateur, 4=Projet, 6=Fichier,
# 8=MediaWiki, 10=Modèle, 12=Aide, 14=Catégorie
NAMESPACES = None # None = tous les namespaces
# Limites
BATCH_SIZE = 50 # Pages par requête API MediaWiki
MAX_RETRIES = 3
RETRY_DELAY = 5 # secondes
# Enrichissement sémantique : résumé en une phrase généré par LLM et
# préfixé au chunk avant indexation, pour combler l'écart de vocabulaire
# entre une question en langage naturel et une fiche technique brute
# (cf. /root/rag-eval-queries.md sur HAL, cas B1/B5, 2026-09-09).
# Désactivé par défaut : opt-in explicite via variable d'environnement.
ENRICHMENT_ENABLED = os.getenv("ENRICHMENT_ENABLED", "false").lower() == "true"
ENRICHMENT_LLM_URL = os.getenv("ENRICHMENT_LLM_URL",
"http://192.168.1.111:8090/v1/chat/completions")
ENRICHMENT_MODEL = os.getenv("ENRICHMENT_MODEL", "gpt-oss-120b")
ENRICHMENT_TIMEOUT = int(os.getenv("ENRICHMENT_TIMEOUT", "120"))
# Ancienne valeur 4000 : tronquait avant même de voir les pages longues
# (ex. Carnet d'adresses.txt, ~30 Ko) -> mots-clés en fin de page jamais vus
# par le LLM. gpt-oss-120b a un contexte large (128k), pas de raison de
# tronquer aussi court.
ENRICHMENT_MAX_INPUT_CHARS = int(os.getenv("ENRICHMENT_MAX_INPUT_CHARS", "60000"))
# gpt-oss-120b (format harmony) génère un raisonnement caché avant la
# réponse finale ; sur une page dense (beaucoup de noms), ce raisonnement
# peut à lui seul dépasser 1500 tokens et tronquer la réponse AVANT même
# la ligne KEYWORDS (finish_reason=length, content vide, tout est parti
# dans reasoning_content). Mesuré : ~1830 tokens de complétion nécessaires
# sur Carnet d'adresses.txt (le cas le plus dense rencontré) une fois le
# raisonnement réduit via "Reasoning: low" ci-dessous. Marge conservée.
ENRICHMENT_MAX_TOKENS = int(os.getenv("ENRICHMENT_MAX_TOKENS", "4000"))
# Sous le chunk_size Open WebUI (1000 car., overlap 150) pour garantir
# qu'un marqueur KEYWORDS tombe dans la fenêtre de chaque chunk généré.
KEYWORDS_INJECTION_INTERVAL = int(os.getenv("KEYWORDS_INJECTION_INTERVAL", "700"))
# Sous ce seuil, un seul résumé en tête de page suffit déjà (page tenant en
# 1-2 chunks) : pas besoin de réinjection périodique, comportement inchangé.
KEYWORDS_INJECTION_MIN_LENGTH = int(os.getenv("KEYWORDS_INJECTION_MIN_LENGTH", "1200"))
# =============================================================================
# LOGGING
# =============================================================================
def setup_logging():
"""Configure le logging vers fichier et console."""
SYNC_DIR.mkdir(parents=True, exist_ok=True)
MARKDOWN_DIR.mkdir(parents=True, exist_ok=True)
logger = logging.getLogger("wiki_sync")
logger.setLevel(logging.INFO)
# Handler fichier
fh = logging.FileHandler(LOG_FILE, encoding="utf-8")
fh.setLevel(logging.INFO)
# Handler console
ch = logging.StreamHandler()
ch.setLevel(logging.INFO)
formatter = logging.Formatter(
"%(asctime)s [%(levelname)s] %(message)s",
datefmt="%Y-%m-%d %H:%M:%S"
)
fh.setFormatter(formatter)
ch.setFormatter(formatter)
logger.addHandler(fh)
logger.addHandler(ch)
return logger
log = setup_logging()
# =============================================================================
# ÉTAT DE SYNCHRONISATION
# =============================================================================
def load_state() -> dict:
"""Charge l'état de la dernière synchronisation."""
if STATE_FILE.exists():
with open(STATE_FILE, "r", encoding="utf-8") as f:
return json.load(f)
return {
"last_sync": None,
"pages_synced": {}, # title -> {"revid": ..., "file_id": ..., "hash": ...}
}
def save_state(state: dict):
"""Sauvegarde l'état de synchronisation."""
with open(STATE_FILE, "w", encoding="utf-8") as f:
json.dump(state, f, ensure_ascii=False, indent=2)
# =============================================================================
# AUTHENTIFICATION OPEN WEBUI
# =============================================================================
def owui_get_token() -> str:
"""Obtient un token JWT depuis Open WebUI."""
if not OWUI_PASSWORD:
log.error("OWUI_PASSWORD non défini ! Utilisez la variable d'environnement.")
sys.exit(1)
resp = requests.post(
f"{OWUI_BASE_URL}/api/v1/auths/signin",
json={"email": OWUI_EMAIL, "password": OWUI_PASSWORD},
timeout=30
)
if resp.status_code != 200:
log.error("Échec authentification Open WebUI: %s", resp.text)
sys.exit(1)
data = resp.json()
token = data.get("token")
if not token:
log.error("Pas de token dans la réponse: %s", data)
sys.exit(1)
log.info("Authentification Open WebUI réussie (user: %s)", data.get("name"))
return token
# =============================================================================
# API MEDIAWIKI
# =============================================================================
def wiki_get_all_pages() -> list[dict]:
"""Récupère la liste complète des pages avec leur dernière révision."""
pages = []
params = {
"action": "query",
"list": "allpages",
"aplimit": BATCH_SIZE,
"format": "json",
}
if NAMESPACES is not None:
# On doit itérer sur chaque namespace
ns_list = NAMESPACES
else:
# Récupérer tous les namespaces disponibles
ns_resp = requests.get(WIKI_API_URL, params={
"action": "query",
"meta": "siteinfo",
"siprop": "namespaces",
"format": "json"
}, timeout=30)
ns_data = ns_resp.json()
ns_list = [
int(ns_id) for ns_id in ns_data["query"]["namespaces"]
if int(ns_id) >= 0 # Exclure les namespaces spéciaux (négatifs)
]
for ns in ns_list:
ap_continue = None
while True:
p = {**params, "apnamespace": ns}
if ap_continue:
p["apcontinue"] = ap_continue
for attempt in range(MAX_RETRIES):
try:
resp = requests.get(WIKI_API_URL, params=p, timeout=60)
resp.raise_for_status()
data = resp.json()
break
except Exception as e:
if attempt < MAX_RETRIES - 1:
log.warning("Erreur API (tentative %d/%d): %s",
attempt + 1, MAX_RETRIES, e)
time.sleep(RETRY_DELAY)
else:
log.error("Échec API après %d tentatives: %s",
MAX_RETRIES, e)
raise
for page in data["query"].get("allpages", []):
pages.append(page)
if "continue" in data:
ap_continue = data["continue"].get("apcontinue")
else:
break
log.info("Total pages trouvées dans le wiki: %d", len(pages))
return pages
def wiki_get_page_content(title: str) -> Optional[dict]:
"""Récupère le contenu wikitext et les métadonnées d'une page."""
params = {
"action": "query",
"titles": title,
"prop": "revisions|info",
"rvprop": "content|timestamp|ids",
"rvlimit": 1,
"format": "json",
}
for attempt in range(MAX_RETRIES):
try:
resp = requests.get(WIKI_API_URL, params=params, timeout=60)
resp.raise_for_status()
data = resp.json()
break
except Exception as e:
if attempt < MAX_RETRIES - 1:
log.warning("Erreur récupération '%s' (tentative %d): %s",
title, attempt + 1, e)
time.sleep(RETRY_DELAY)
else:
log.error("Impossible de récupérer '%s': %s", title, e)
return None
pages = data["query"]["pages"]
page_id = list(pages.keys())[0]
if page_id == "-1":
log.warning("Page introuvable: %s", title)
return None
page = pages[page_id]
revisions = page.get("revisions", [])
if not revisions:
return None
return {
"title": page["title"],
"pageid": page["pageid"],
"revid": revisions[0]["revid"],
"timestamp": revisions[0]["timestamp"],
"content": revisions[0].get("*", ""),
}
def wiki_get_modified_pages(since: str) -> list[dict]:
"""Récupère les pages modifiées depuis une date ISO."""
pages = []
params = {
"action": "query",
"list": "recentchanges",
"rcstart": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
"rcend": since,
"rcdir": "older",
"rclimit": BATCH_SIZE,
"rctype": "edit|new",
"rcprop": "title|timestamp|ids",
"rcnamespace": "|".join(str(ns) for ns in NAMESPACES) if NAMESPACES else None,
"format": "json",
}
# Supprimer les paramètres None
params = {k: v for k, v in params.items() if v is not None}
rc_continue = None
seen_titles = set()
while True:
p = {**params}
if rc_continue:
p["rccontinue"] = rc_continue
for attempt in range(MAX_RETRIES):
try:
resp = requests.get(WIKI_API_URL, params=p, timeout=60)
resp.raise_for_status()
data = resp.json()
break
except Exception as e:
if attempt < MAX_RETRIES - 1:
time.sleep(RETRY_DELAY)
else:
raise
for rc in data["query"].get("recentchanges", []):
if rc["title"] not in seen_titles:
seen_titles.add(rc["title"])
pages.append(rc)
if "continue" in data:
rc_continue = data["continue"].get("rccontinue")
else:
break
log.info("Pages modifiées depuis %s: %d", since, len(pages))
return pages
# =============================================================================
# CONVERSION WIKITEXT → MARKDOWN
# =============================================================================
def wikitext_to_markdown(title: str, wikitext: str) -> str:
"""Convertit du wikitext en Markdown."""
if HAS_MWPARSER:
return _convert_with_mwparser(title, wikitext)
else:
return _convert_basic(title, wikitext)
def _convert_with_mwparser(title: str, wikitext: str) -> str:
"""Conversion avancée via mwparserfromhell."""
parsed = mwparserfromhell.parse(wikitext)
# Supprimer les balises <noinclude>, <includeonly>, etc.
for tag in parsed.filter_tags():
tag_name = str(tag.tag).lower()
if tag_name in ("noinclude", "includeonly", "onlyinclude"):
try:
parsed.remove(tag)
except ValueError:
pass
text = str(parsed)
# Conversion des éléments wiki → Markdown
text = _apply_regex_conversions(text)
# Ajouter le titre en en-tête
md = f"# {title}\n\n{text}"
return md.strip()
def _convert_basic(title: str, wikitext: str) -> str:
"""Conversion basique par regex (fallback)."""
text = _apply_regex_conversions(wikitext)
md = f"# {title}\n\n{text}"
return md.strip()
def _apply_regex_conversions(text: str) -> str:
"""Applique les conversions regex wikitext → Markdown."""
# Titres : ====Titre==== → #### Titre
text = re.sub(r"^={5}\s*(.+?)\s*={5}", r"##### \1", text, flags=re.MULTILINE)
text = re.sub(r"^={4}\s*(.+?)\s*={4}", r"#### \1", text, flags=re.MULTILINE)
text = re.sub(r"^={3}\s*(.+?)\s*={3}", r"### \1", text, flags=re.MULTILINE)
text = re.sub(r"^={2}\s*(.+?)\s*={2}", r"## \1", text, flags=re.MULTILINE)
# Gras et italique
text = re.sub(r"'{5}(.+?)'{5}", r"***\1***", text)
text = re.sub(r"'{3}(.+?)'{3}", r"**\1**", text)
text = re.sub(r"'{2}(.+?)'{2}", r"*\1*", text)
# Liens internes : [[Page|Texte]] → [Texte](Page)
text = re.sub(r"\[\[([^\]|]+)\|([^\]]+)\]\]", r"[\2](\1)", text)
text = re.sub(r"\[\[([^\]]+)\]\]", r"[\1](\1)", text)
# Liens externes : [http://url texte] → [texte](http://url)
text = re.sub(r"\[(\bhttps?://\S+)\s+(.+?)\]", r"[\2](\1)", text)
text = re.sub(r"\[(\bhttps?://\S+)\]", r"[\1](\1)", text)
# Listes à puces : * → -
text = re.sub(r"^\*{4}\s*", r" - ", text, flags=re.MULTILINE)
text = re.sub(r"^\*{3}\s*", r" - ", text, flags=re.MULTILINE)
text = re.sub(r"^\*{2}\s*", r" - ", text, flags=re.MULTILINE)
text = re.sub(r"^\*\s*", r"- ", text, flags=re.MULTILINE)
# Listes numérotées : # → 1.
text = re.sub(r"^#{3}\s*", r" 1. ", text, flags=re.MULTILINE)
text = re.sub(r"^#{2}\s*", r" 1. ", text, flags=re.MULTILINE)
text = re.sub(r"^#\s*", r"1. ", text, flags=re.MULTILINE)
# Lignes horizontales
text = re.sub(r"^-{4,}", r"---", text, flags=re.MULTILINE)
# Balises HTML courantes
text = re.sub(r"<br\s*/?>", "\n", text, flags=re.IGNORECASE)
text = re.sub(r"</?(?:div|span|center|small|big)[^>]*>", "", text,
flags=re.IGNORECASE)
text = re.sub(r"<code>(.*?)</code>", r"`\1`", text,
flags=re.IGNORECASE | re.DOTALL)
text = re.sub(r"<pre>(.*?)</pre>", r"```\n\1\n```", text,
flags=re.IGNORECASE | re.DOTALL)
text = re.sub(r"(.*?)", r"\1", text,
flags=re.IGNORECASE | re.DOTALL)
text = re.sub(r"<ref[^>]*>.*?</ref>", "", text,
flags=re.IGNORECASE | re.DOTALL)
text = re.sub(r"<ref[^/]*/>", "", text, flags=re.IGNORECASE)
# Templates : {{template|...}} → on garde le contenu lisible
# Supprime les templates complexes mais garde le texte simple
text = re.sub(r"\{\{[^{}]{200,}\}\}", "", text, flags=re.DOTALL)
# Images : [[Fichier:xxx|...]] ou [[File:xxx|...]] → supprimé
text = re.sub(r"\[\[(?:Fichier|File|Image):[^\]]+\]\]", "", text,
flags=re.IGNORECASE)
# Catégories : [[Catégorie:xxx]] → supprimé
text = re.sub(r"\[\[(?:Catégorie|Category):[^\]]+\]\]", "", text,
flags=re.IGNORECASE)
# Tables wiki → on les garde en texte brut (le Markdown de tables
# est trop limité pour les tables wiki complexes)
# On nettoie juste les balises
text = re.sub(r"^\{\|.*$", "", text, flags=re.MULTILINE)
text = re.sub(r"^\|\}.*$", "", text, flags=re.MULTILINE)
text = re.sub(r"^\|-.*$", "", text, flags=re.MULTILINE)
text = re.sub(r"^!\s*", "**", text, flags=re.MULTILINE)
# Nettoyage final
text = re.sub(r"\n{3,}", "\n\n", text) # Max 2 lignes vides consécutives
text = re.sub(r"[ \t]+$", "", text, flags=re.MULTILINE) # Trailing spaces
return text
def generate_enrichment(title: str, markdown: str) -> tuple:
"""Génère en UN seul appel LLM :
- un résumé en une phrase (ancré dans le contenu réel, pas d'invention),
pour que le retrieval sémantique retrouve la fiche même sans
recouvrement lexical avec une question paraphrasée ;
- une liste de mots-clés (noms propres, alias, lieux, termes rares)
présents littéralement dans le texte, pour les cas où un nom isolé
est noyé dans un chunk dense et invisible pour l'embedding seul
(cf. rag-eval-queries.md sur HAL, cas C1 "Philip").
Retourne (summary, keywords), chacun pouvant être None si désactivé ou
en échec — l'appelant doit alors utiliser le Markdown non enrichi
(jamais bloquant).
Le texte n'est PAS tronqué à 4000 caractères comme avant : une page de
plusieurs dizaines de Ko (ex. Carnet d'adresses.txt, ~30 Ko) doit être
vue en entier par le LLM pour que l'extraction de mots-clés couvre tout
le contenu, pas seulement le début."""
if not ENRICHMENT_ENABLED:
return None, None
try:
resp = requests.post(
ENRICHMENT_LLM_URL,
json={
"model": ENRICHMENT_MODEL,
"temperature": 0.2,
"messages": [
{"role": "system", "content": (
"Reasoning: low\n"
"Tu analyses une fiche technique interne en français. "
"Réponds EXACTEMENT sur deux lignes, rien d'autre :\n"
"SUMMARY: une phrase factuelle qui explique à quel "
"besoin/problème la fiche répond (pas de détails "
"techniques précis, juste le sujet et l'usage), pour "
"aider un moteur de recherche à la retrouver via une "
"question en langage naturel.\n"
"KEYWORDS: la liste, séparée par des virgules, de TOUS "
"les noms propres, noms de personnes, alias, lieux et "
"termes rares/uniques présents dans le texte (aucune "
"invention, uniquement ce qui apparaît littéralement "
"dans le texte fourni)."
)},
{"role": "user", "content": markdown[:ENRICHMENT_MAX_INPUT_CHARS]},
],
"max_tokens": ENRICHMENT_MAX_TOKENS,
},
timeout=ENRICHMENT_TIMEOUT,
)
resp.raise_for_status()
content = resp.json()["choices"][0]["message"]["content"].strip()
summary = None
keywords = None
for line in content.splitlines():
line = line.strip()
if line.upper().startswith("SUMMARY:"):
summary = line.split(":", 1)[1].strip() or None
elif line.upper().startswith("KEYWORDS:"):
keywords = line.split(":", 1)[1].strip() or None
return summary, keywords
except Exception as e:
log.warning(" Enrichissement LLM: échec pour '%s' (%s), upload brut", title, e)
return None, None
def inject_keywords_periodically(markdown: str, keywords: str,
interval: int = KEYWORDS_INJECTION_INTERVAL) -> str:
"""Réinjecte la ligne de mots-clés à intervalles réguliers (sur des
frontières de ligne, jamais en coupant une ligne en deux) pour qu'elle
reste à proximité de n'importe quel chunk découpé plus tard par Open
WebUI (chunk_size/overlap configurés côté serveur), même profond dans
un document long. Un résumé placé une seule fois en tête de page ne
profite qu'au premier chunk ; ce remède s'applique uniquement aux
documents assez longs pour dépasser un seul chunk."""
marker = f"[KEYWORDS: {keywords}]"
lines = markdown.split("\n")
out = []
count_since_last = 0
for line in lines:
out.append(line)
count_since_last += len(line) + 1
if count_since_last >= interval:
out.append("")
out.append(marker)
out.append("")
count_since_last = 0
# Toujours poser un marqueur final : sans ça, la "queue" du document
# (tout ce qui suit le dernier marqueur périodique, jusqu'à `interval`
# caractères) ne contient jamais de mots-clés — bug constaté avec un nom
# cité en toute fin de Carnet d'adresses.txt (~700 derniers caractères
# non couverts).
if count_since_last > 0:
out.append("")
out.append(marker)
out.append("")
return "\n".join(out)
# =============================================================================
# API OPEN WEBUI — UPLOAD FICHIERS
# =============================================================================
def owui_upload_file(token: str, filepath: Path, filename: str) -> Optional[str]:
"""Uploade un fichier dans Open WebUI et retourne le file_id."""
headers = {"Authorization": f"Bearer {token}"}
with open(filepath, "rb") as f:
files = {"file": (filename, f, "text/plain")}
for attempt in range(MAX_RETRIES):
try:
resp = requests.post(
f"{OWUI_BASE_URL}/api/v1/files/",
headers=headers,
files=files,
timeout=120
)
if resp.status_code == 200:
data = resp.json()
file_id = data.get("id")
log.info(" Fichier uploadé: %s → id=%s", filename, file_id)
return file_id
else:
log.warning(" Erreur upload (tentative %d): %s %s",
attempt + 1, resp.status_code, resp.text[:200])
except Exception as e:
log.warning(" Exception upload (tentative %d): %s",
attempt + 1, e)
if attempt < MAX_RETRIES - 1:
time.sleep(RETRY_DELAY)
log.error(" Échec upload définitif: %s", filename)
return None
def owui_add_file_to_knowledge(token: str, knowledge_id: str,
file_id: str) -> bool:
"""Ajoute un fichier à une base de connaissances."""
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
for attempt in range(MAX_RETRIES):
try:
resp = requests.post(
f"{OWUI_BASE_URL}/api/v1/knowledge/{knowledge_id}/file/add",
headers=headers,
json={"file_id": file_id},
timeout=120
)
if resp.status_code == 200:
return True
else:
log.warning(" Erreur ajout knowledge (tentative %d): %s %s",
attempt + 1, resp.status_code, resp.text[:200])
except Exception as e:
log.warning(" Exception ajout knowledge (tentative %d): %s",
attempt + 1, e)
if attempt < MAX_RETRIES - 1:
time.sleep(RETRY_DELAY)
return False
def owui_remove_file_from_knowledge(token: str, knowledge_id: str,
file_id: str) -> bool:
"""Supprime un fichier d'une base de connaissances."""
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
try:
resp = requests.post(
f"{OWUI_BASE_URL}/api/v1/knowledge/{knowledge_id}/file/remove",
headers=headers,
json={"file_id": file_id},
timeout=60
)
return resp.status_code == 200
except Exception:
return False
def owui_delete_file(token: str, file_id: str) -> bool:
"""Supprime un fichier d'Open WebUI."""
headers = {"Authorization": f"Bearer {token}"}
try:
resp = requests.delete(
f"{OWUI_BASE_URL}/api/v1/files/{file_id}",
headers=headers,
timeout=60
)
return resp.status_code == 200
except Exception:
return False
# =============================================================================
# SYNCHRONISATION
# =============================================================================
def sanitize_filename(title: str) -> str:
"""Convertit un titre wiki en nom de fichier valide."""
name = title.replace("/", "_").replace("\\", "_")
name = name.replace(":", "_").replace("?", "").replace("*", "")
name = name.replace('"', "").replace("<", "").replace(">", "")
name = name.replace("|", "_")
name = re.sub(r"_+", "_", name)
name = name.strip("_. ")
if not name:
name = "page_sans_titre"
return name
def content_hash(content: str) -> str:
"""Calcule un hash MD5 du contenu pour détecter les changements."""
return hashlib.md5(content.encode("utf-8")).hexdigest()
def sync_page(token: str, title: str, state: dict, force: bool = False) -> bool:
"""Synchronise une page wiki vers Open WebUI.
force=True ignore le test de hash (utilisé par --reenrich pour forcer
le ré-enrichissement de pages déjà synchronisées et inchangées côté wiki).
"""
log.info("Synchronisation: %s", title)
# Récupérer le contenu de la page
page_data = wiki_get_page_content(title)
if not page_data or not page_data["content"].strip():
log.info(" Page vide ou introuvable, ignorée: %s", title)
return False
# Convertir en Markdown
markdown = wikitext_to_markdown(title, page_data["content"])
# Vérifier si le contenu a changé via hash — calculé sur le Markdown AVANT
# enrichissement, pour que la synchro incrémentale reste stable même si
# le résumé LLM varie légèrement d'un run à l'autre sur un contenu inchangé.
new_hash = content_hash(markdown)
page_state = state["pages_synced"].get(title, {})
if not force and page_state.get("hash") == new_hash:
log.info(" Contenu inchangé (hash identique), ignoré: %s", title)
return False
# Enrichissement sémantique (opt-in, cf. ENRICHMENT_ENABLED) : résumé en
# une phrase préfixé en tête de page, sans impact sur le hash de
# comparaison. Pour les pages longues (plusieurs chunks Open WebUI), les
# mots-clés extraits par le même appel LLM sont en plus réinjectés à
# intervalles réguliers dans tout le document : un résumé posé une
# seule fois en tête ne profite qu'au premier chunk, ce qui laisse un
# nom cité une seule fois en profondeur (ex. dans un carnet d'adresses)
# invisible pour l'embedding de son propre chunk.
summary, keywords = generate_enrichment(title, markdown)
if summary:
markdown = markdown.replace(f"# {title}\n\n", f"# {title}\n\n{summary}\n\n", 1)
if keywords and len(markdown) > KEYWORDS_INJECTION_MIN_LENGTH:
markdown = inject_keywords_periodically(markdown, keywords)
# Sauvegarder le fichier Markdown localement
filename = sanitize_filename(title) + ".txt"
filepath = MARKDOWN_DIR / filename
with open(filepath, "w", encoding="utf-8") as f:
f.write(markdown)
# Si le fichier existait déjà dans Open WebUI, le supprimer d'abord
old_file_id = page_state.get("file_id")
if old_file_id:
log.info(" Suppression de l'ancienne version (file_id=%s)", old_file_id)
owui_remove_file_from_knowledge(token, OWUI_KNOWLEDGE_ID, old_file_id)
owui_delete_file(token, old_file_id)
time.sleep(0.5)
# Uploader le nouveau fichier
file_id = owui_upload_file(token, filepath, filename)
if file_id:
time.sleep(3) # Attendre le traitement embedding
if not file_id:
return False
# Ajouter à la base de connaissances
if owui_add_file_to_knowledge(token, OWUI_KNOWLEDGE_ID, file_id):
state["pages_synced"][title] = {
"revid": page_data["revid"],
"file_id": file_id,
"hash": new_hash,
"filename": filename,
"synced_at": datetime.now(timezone.utc).isoformat(),
}
log.info(" ✓ Synchronisé: %s", title)
return True
else:
log.error(" ✗ Échec ajout à la knowledge base: %s", title)
# Nettoyer le fichier orphelin
owui_delete_file(token, file_id)
return False
def run_full_sync():
"""Synchronisation complète (première exécution)."""
log.info("=" * 60)
log.info("SYNCHRONISATION COMPLÈTE")
log.info("=" * 60)
state = load_state()
token = owui_get_token()
# Récupérer toutes les pages
pages = wiki_get_all_pages()
success = 0
errors = 0
skipped = 0
for i, page in enumerate(pages, 1):
title = page["title"]
log.info("[%d/%d] Traitement: %s", i, len(pages), title)
try:
if sync_page(token, title, state):
success += 1
else:
skipped += 1
except Exception as e:
log.error("Erreur sur '%s': %s", title, e)
errors += 1
# Sauvegarder l'état régulièrement (toutes les 10 pages)
if i % 10 == 0:
state["last_sync"] = datetime.now(timezone.utc).isoformat()
save_state(state)
# Petite pause pour ne pas surcharger les APIs
time.sleep(0.3)
state["last_sync"] = datetime.now(timezone.utc).isoformat()
save_state(state)
log.info("=" * 60)
log.info("RÉSULTAT: %d synchronisées, %d ignorées, %d erreurs",
success, skipped, errors)
log.info("=" * 60)
def run_incremental_sync():
"""Synchronisation incrémentale (pages modifiées uniquement)."""
log.info("=" * 60)
log.info("SYNCHRONISATION INCRÉMENTALE")
log.info("=" * 60)
state = load_state()
if not state["last_sync"]:
log.info("Pas de synchronisation précédente, "
"lancement d'une synchro complète.")
run_full_sync()
return
token = owui_get_token()
# Récupérer les pages modifiées depuis la dernière synchro
last = state["last_sync"].replace("+00:00", "Z").split(".")[0] + "Z"
modified = wiki_get_modified_pages(last)
if not modified:
log.info("Aucune page modifiée depuis %s", state["last_sync"])
state["last_sync"] = datetime.now(timezone.utc).isoformat()
save_state(state)
return
success = 0
errors = 0
for i, page in enumerate(modified, 1):
title = page["title"]
log.info("[%d/%d] Mise à jour: %s", i, len(modified), title)
try:
if sync_page(token, title, state):
success += 1
except Exception as e:
log.error("Erreur sur '%s': %s", title, e)
errors += 1
time.sleep(0.3)
state["last_sync"] = datetime.now(timezone.utc).isoformat()
save_state(state)
log.info("=" * 60)
log.info("RÉSULTAT INCRÉMENTAL: %d mises à jour, %d erreurs",
success, errors)
log.info("=" * 60)
def run_reenrich():
"""Backfill : force le ré-enrichissement + ré-upload de toutes les pages
déjà synchronisées, en ignorant le hash de comparaison. À lancer une fois
après activation de ENRICHMENT_ENABLED pour rattraper les pages indexées
avant cette bascule (la synchro incrémentale normale n'y touche plus tant
que le contenu wiki source ne change pas, cf. hash calculé avant
enrichissement dans sync_page())."""
log.info("=" * 60)
log.info("RÉ-ENRICHISSEMENT COMPLET (backfill)")
log.info("=" * 60)
if not ENRICHMENT_ENABLED:
log.error("ENRICHMENT_ENABLED=false — activez-le (.env) avant --reenrich.")
sys.exit(1)
state = load_state()
token = owui_get_token()
titles = list(state["pages_synced"].keys())
log.info("Pages à ré-enrichir: %d", len(titles))
success = 0
errors = 0
for i, title in enumerate(titles, 1):
log.info("[%d/%d] Ré-enrichissement: %s", i, len(titles), title)
try:
if sync_page(token, title, state, force=True):
success += 1
except Exception as e:
log.error("Erreur sur '%s': %s", title, e)
errors += 1
if i % 10 == 0:
state["last_sync"] = datetime.now(timezone.utc).isoformat()
save_state(state)
time.sleep(0.3)
state["last_sync"] = datetime.now(timezone.utc).isoformat()
save_state(state)
log.info("=" * 60)
log.info("RÉSULTAT RÉ-ENRICHISSEMENT: %d traitées, %d erreurs", success, errors)
log.info("=" * 60)
# =============================================================================
# POINT D'ENTRÉE
# =============================================================================
def main():
import argparse
parser = argparse.ArgumentParser(
description="Synchronisation MediaWiki → Open WebUI Knowledge Base"
)
parser.add_argument(
"--full", action="store_true",
help="Force une synchronisation complète (toutes les pages)"
)
parser.add_argument(
"--dry-run", action="store_true",
help="Affiche les pages à synchroniser sans rien modifier"
)
parser.add_argument(
"--page", type=str,
help="Synchronise une seule page (pour test)"
)
parser.add_argument(
"--reenrich", action="store_true",
help="Backfill: force le ré-enrichissement de toutes les pages déjà synchronisées"
)
args = parser.parse_args()
log.info("Démarrage wiki_sync.py")
log.info("Wiki: %s", WIKI_API_URL)
log.info("Open WebUI: %s", OWUI_BASE_URL)
log.info("Knowledge ID: %s", OWUI_KNOWLEDGE_ID)
if args.page:
# Mode test : une seule page
token = owui_get_token()
state = load_state()
sync_page(token, args.page, state)
save_state(state)
elif args.dry_run:
state = load_state()
if state["last_sync"]:
last = state["last_sync"].replace("+00:00", "Z").split(".")[0] + "Z"
modified = wiki_get_modified_pages(last)
log.info("Pages à synchroniser:")
for p in modified:
log.info(" - %s (modifiée le %s)", p["title"], p["timestamp"])
else:
pages = wiki_get_all_pages()
log.info("Première synchro: %d pages à traiter", len(pages))
elif args.full:
run_full_sync()
elif args.reenrich:
run_reenrich()
else:
run_incremental_sync()
if __name__ == "__main__":
main()