From 430c56a9f475cc79ec8a52414901a23bdffc1606 Mon Sep 17 00:00:00 2001
From: Folzo <folzo@hotmail.com>
Date: Wed, 8 Apr 2026 21:42:54 +0200
Subject: [PATCH] docs(effi-ocr): add troubleshooting guide

---
 effi-ocr/TROUBLESHOOTING.md | 80 +++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 effi-ocr/TROUBLESHOOTING.md

diff --git a/effi-ocr/TROUBLESHOOTING.md b/effi-ocr/TROUBLESHOOTING.md
new file mode 100644
index 0000000..a0b34dc
--- /dev/null
+++ b/effi-ocr/TROUBLESHOOTING.md
@@ -0,0 +1,80 @@
+# Dépannage effi-OCR
+
+## Problèmes Connus
+
+### 1. "Fichier non trouvé" - Erreur Common
+
+**Symptôme :**
+```
+Erreur: Fichier non trouvé pour l'ID: page_image.jpg (cherché dans /app/backend/data/uploads/)
+```
+
+**Cause :**
+effi-ocr est sur une autre machine que OpenWebUI. Les chemins de fichiers ne sont pas partagés.
+
+**Solution :**
+Installer effi-ocr sur le **MÊME serveur** qu'OpenWebUI (effi-server 192.168.1.27)
+
+---
+
+### 2. effi-ocr loop / se bloque
+
+**Symptôme :**
+Le modèle répète "call the tool call the tool..." en boucle.
+
+**Causes possibles :**
+- Tool mal configuré dans OpenWebUI
+- URL OCR_URL incorrecte
+- Le modèle a un problème avec le tool calling
+
+**Solutions :**
+1. Vérifier que `OCR_URL` pointe vers le bon serveur
+2. Recréer le tool OCR dans OpenWebUI
+3. Désactiver Sub Agent/Planner Agent temporairement
+
+---
+
+### 3. OCR retourne du texte vide
+
+**Causes possibles :**
+- Image de mauvaise qualité
+- Langue incorrecte (utiliser `fra+eng`)
+- Prétraitement désactivé
+
+**Solutions :**
+1. Tester avec une image plus claire
+2. Utiliser `lang=fra+eng` pour documents mixtes
+3. Activer le prétraitement
+
+---
+
+## Checklist Diagnostic
+
+- [ ] effi-ocr tourne sur le port 8300
+- [ ] OCR_URL est correct dans OpenWebUI
+- [ ] effi-ocr est sur le MÊME serveur qu'OpenWebUI
+- [ ] Le tool OCR est correctement créé dans Admin → Tools
+- [ ] Le fichier uploadé existe dans /app/backend/data/uploads/
+
+---
+
+## Commandes de Test
+
+### Vérifier effi-ocr (sur le serveur où il tourne)
+```bash
+curl http://localhost:8300/health
+```
+
+### Tester OCR avec une image
+```bash
+curl -X POST -F "file=@test.jpg" -F "lang=fra" http://localhost:8300/ocr
+```
+
+### Vérifier les fichiers uploadés (OpenWebUI)
+```bash
+ls -la /app/backend/data/uploads/
+```
+
+---
+
+*Dernière mise à jour: Avril 2026*