Hugging Face's logo

Spaces:
Ma-Ri-Ba-Ku
/
Picarones
Sleeping

App Files Community
Picarones / INSTALL.md
Claude
chore: remplacer toutes les références bnf/picarones par maribakulj/Picarones
cecde1f unverified
preview code
|
raw
history blame contribute delete
10.7 kB

Guide d'installation — Picarones

Guide détaillé pour Linux, macOS et Windows. Pour une installation en 5 minutes : voir README.md.

Sommaire

  1. Prérequis
  2. Installation Linux (Ubuntu/Debian)
  3. Installation macOS
  4. Installation Windows
  5. Configuration des moteurs OCR
  6. Configuration des APIs
  7. Lancement de l'interface web
  8. Installation Docker
  9. Vérification de l'installation
  10. Résolution des problèmes courants

1. Prérequis

Composant Version minimale Obligatoire
Python 3.11 Oui
pip 23.0+ Oui
Git 2.x Oui (pour cloner)
Tesseract 5.0+ Pour le moteur Tesseract
Pero OCR 0.1+ Pour le moteur Pero OCR
Docker 24.x Pour déploiement containerisé

2. Installation Linux (Ubuntu/Debian)

2.1 Python et pip 

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip git
python3.11 --version   # Vérifier : Python 3.11.x

2.2 Tesseract OCR 

# Tesseract 5 (PPA pour Ubuntu < 22.04)
sudo add-apt-repository ppa:alex-p/tesseract-ocr5 -y
sudo apt update
sudo apt install tesseract-ocr

# Modèles de langues (choisir selon votre corpus)
sudo apt install tesseract-ocr-fra   # Français
sudo apt install tesseract-ocr-lat   # Latin
sudo apt install tesseract-ocr-eng   # Anglais
sudo apt install tesseract-ocr-deu   # Allemand
sudo apt install tesseract-ocr-ita   # Italien
sudo apt install tesseract-ocr-spa   # Espagnol

# Vérifier
tesseract --version   # Tesseract 5.x.x
tesseract --list-langs

2.3 Picarones 

git clone https://github.com/maribakulj/Picarones.git
cd picarones

# Créer un environnement virtuel (recommandé)
python3.11 -m venv .venv
source .venv/bin/activate

# Installation de base
pip install -e .

# Installation avec interface web (FastAPI + uvicorn)
pip install -e ".[web]"

# Installation complète (tous les extras)
pip install -e ".[web,hf,dev]"

2.4 Pero OCR (optionnel) 

# Pero OCR nécessite quelques dépendances système
sudo apt install libgl1 libglib2.0-0

pip install pero-ocr

# Télécharger un modèle pré-entraîné
# Voir https://github.com/DCGM/pero-ocr pour les modèles disponibles

3. Installation macOS

3.1 Homebrew (si non installé) 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3.2 Python et Tesseract 

brew install python@3.11 tesseract

# Modèles de langues Tesseract
brew install tesseract-lang   # Installe tous les modèles

# Ou modèles individuels via les données de tessdata
# Voir https://github.com/tesseract-ocr/tessdata

3.3 Picarones 

git clone https://github.com/maribakulj/Picarones.git
cd picarones

python3.11 -m venv .venv
source .venv/bin/activate

pip install -e ".[web]"

3.4 Résolution d'un problème courant macOS

Si pytesseract ne trouve pas Tesseract :

# Trouver le chemin de Tesseract
which tesseract   # Ex : /opt/homebrew/bin/tesseract

# L'indiquer explicitement dans votre script Python :
import pytesseract
pytesseract.pytesseract.tesseract_cmd = '/opt/homebrew/bin/tesseract'

Ou définir la variable d'environnement :

export TESSDATA_PREFIX=/opt/homebrew/share/tessdata/

4. Installation Windows

4.1 Python

  1. Télécharger Python 3.11+ depuis python.org
  2. Cocher "Add Python to PATH" lors de l'installation
  3. Vérifier : python --version dans PowerShell

4.2 Tesseract

  1. Télécharger l'installateur depuis UB-Mannheim/tesseract
  2. Choisir la version 5.x (64-bit recommandé)
  3. Pendant l'installation : cocher les modèles de langues souhaités (Français, Latin…)
  4. Ajouter Tesseract au PATH :
    • Chercher "Variables d'environnement" dans le menu Démarrer
    • Ajouter C:\Program Files\Tesseract-OCR à la variable Path
  5. Vérifier : tesseract --version dans PowerShell

4.3 Git

Télécharger depuis git-scm.com et installer.

4.4 Picarones 

git clone https://github.com/maribakulj/Picarones.git
cd picarones

python -m venv .venv
.venv\Scripts\activate

pip install -e ".[web]"

4.5 Problème d'encodage Windows

Si vous rencontrez des erreurs d'encodage, définir :

$env:PYTHONIOENCODING = "utf-8"

Ou dans votre profil PowerShell : [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

5. Configuration des moteurs OCR

5.1 Tesseract — Configuration avancée 

# Vérifier les modèles installés
tesseract --list-langs

# Tester sur une image
tesseract image.jpg sortie -l fra --psm 6

# Configuration dans Picarones
picarones run --corpus ./corpus/ --engines tesseract --lang fra --psm 6

Modes PSM (Page Segmentation Mode) recommandés :

PSM Usage
6 (défaut) Bloc de texte uniforme
3 Détection automatique de la mise en page
11 Texte épars, sans mise en page
1 Détection automatique avec OSD

5.2 Pero OCR 

# Télécharger un modèle pré-entraîné (exemple)
mkdir -p ~/.pero/models
# Voir https://github.com/DCGM/pero-ocr/releases

# Configurer via YAML
cat > pero_config.yaml << 'EOF'
name: pero_printed
type: pero_ocr
config_path: /path/to/pero_model/config.yaml
EOF

5.3 Kraken (optionnel) 

pip install kraken

# Télécharger un modèle
kraken get 10.5281/zenodo.XXXXXXX

# Lister les modèles installés
kraken list

5.4 Ollama (LLMs locaux) 

# Installer Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Démarrer le service
ollama serve

# Télécharger un modèle
ollama pull llama3
ollama pull gemma2

# Vérifier
ollama list

6. Configuration des APIs

Les clés API sont lues depuis les variables d'environnement. Ne jamais les écrire dans le code.

6.1 Fichier .env (recommandé)

Créer un fichier .env à la racine du projet (ajouté au .gitignore) :

# .env — Ne pas commiter ce fichier !

# OpenAI (GPT-4o, GPT-4o mini)
OPENAI_API_KEY=sk-...

# Anthropic (Claude Sonnet, Haiku)
ANTHROPIC_API_KEY=sk-ant-...

# Mistral (Mistral Large, Pixtral, Mistral OCR)
MISTRAL_API_KEY=...

# Google Vision
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

# AWS Textract
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=eu-west-1

# Azure Document Intelligence
AZURE_DOC_INTEL_ENDPOINT=https://...cognitiveservices.azure.com/
AZURE_DOC_INTEL_KEY=...

Charger avec python-dotenv ou directement dans le shell :

# Linux/macOS
export $(cat .env | grep -v '^#' | xargs)

# Ou avec python-dotenv
pip install python-dotenv

6.2 Vérification des APIs 

# Tester les APIs configurées
picarones engines   # affiche les moteurs disponibles et leur statut

7. Lancement de l'interface web 

# Installer les dépendances web
pip install -e ".[web]"

# Lancer le serveur (localhost uniquement)
picarones serve

# Ou avec adresse publique (Docker, serveur distant)
picarones serve --host 0.0.0.0 --port 8000

# Mode développement (rechargement automatique)
picarones serve --reload --verbose

# Accéder dans le navigateur
# http://localhost:8000

8. Installation Docker

8.1 Utiliser l'image Docker officielle 

# Construire l'image
docker build -t picarones:latest .

# Lancer le service
docker run -p 8000:8000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -v $(pwd)/corpus:/app/corpus \
  picarones:latest

# Accéder dans le navigateur
# http://localhost:8000

8.2 Docker Compose (Picarones + Ollama) 

# Lancer tous les services
docker compose up -d

# Avec Ollama pour les LLMs locaux
docker compose --profile ollama up -d

# Arrêter
docker compose down

Voir docker-compose.yml pour la configuration complète.

8.3 Variables d'environnement pour Docker

Créer un fichier .env.docker :

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...

docker compose --env-file .env.docker up -d

9. Vérification de l'installation 

# 1. Version et dépendances
picarones info

# 2. Moteurs disponibles
picarones engines

# 3. Rapport de démonstration (sans moteur OCR réel)
picarones demo --docs 3 --output test_demo.html
# Ouvrir test_demo.html dans un navigateur

# 4. Suivi longitudinal (demo)
picarones history --demo

# 5. Analyse de robustesse (demo)
picarones robustness --corpus . --engine tesseract --demo

# 6. Suite de tests complète
make test
# ou
pytest

10. Résolution des problèmes courants

tesseract: command not found 

# Ubuntu : réinstaller
sudo apt install tesseract-ocr

# macOS : vérifier Homebrew
brew install tesseract

# Windows : vérifier le PATH
where tesseract   # doit retourner un chemin

Error: No module named 'picarones' 

# Réinstaller en mode éditable
pip install -e .

# Vérifier l'environnement virtuel actif
which python   # doit pointer vers .venv/bin/python

pytesseract.pytesseract.TesseractNotFoundError 

# Linux/macOS : vérifier le PATH
which tesseract

# Windows : vérifier l'installation et le PATH
# Puis dans Python :
import pytesseract
pytesseract.pytesseract.tesseract_cmd = r"C:\Program Files\Tesseract-OCR\tesseract.exe"

Erreur d'encodage UTF-8 (Windows) 

$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONUTF8 = "1"

Interface web inaccessible 

# Vérifier que le port n'est pas occupé
lsof -i :8000   # Linux/macOS
netstat -ano | findstr :8000   # Windows

# Utiliser un autre port
picarones serve --port 8080

ImportError: No module named 'fastapi' 

pip install -e ".[web]"

Tesseract lent sur de grands corpus 

# Augmenter le parallélisme (si votre machine le permet)
picarones run --corpus ./corpus/ --engines tesseract   # traitement séquentiel par défaut

Désinstallation 

# Dans l'environnement virtuel
pip uninstall picarones

# Supprimer l'historique SQLite (optionnel)
rm -rf ~/.picarones/

# Supprimer l'environnement virtuel
deactivate
rm -rf .venv/