chore: initialize project structure and configuration files
This commit is contained in:
TomOPlomo
330
README.md
330
README.md
@@ -0,0 +1,330 @@
|
||||
# 🪨 Geotechnical Layer Extractor
|
||||
|
||||
Un outil d'extraction automatique des couches géologiques à partir de logs de forage au format PDF, utilisant l'intelligence artificielle pour analyser et structurer les données géotechniques.
|
||||
|
||||
## 🎯 Objectif
|
||||
|
||||
Ce projet permet d'extraire automatiquement les informations de couches géologiques (profondeurs et descriptions) depuis des documents PDF de logs de forage, souvent complexes et mal structurés. Il utilise Azure Document Intelligence pour l'OCR et GPT-4 pour l'analyse sémantique du contenu.
|
||||
|
||||
## ✨ Fonctionnalités
|
||||
|
||||
- **Extraction OCR avancée** : Utilise Azure Document Intelligence pour extraire texte et tableaux
|
||||
- **Analyse par IA** : GPT-4 analyse le contenu pour identifier les couches géologiques
|
||||
- **Gestion multi-pages** : Traite correctement les documents de plusieurs pages
|
||||
- **Détection de tableaux** : Identifie et parse les tableaux complexes
|
||||
- **Déduplication intelligente** : Évite les doublons entre pages
|
||||
- **Optimisation de prompts** : Outil pour améliorer automatiquement les prompts
|
||||
- **Export JSON structuré** : Format de sortie standardisé et exploitable
|
||||
|
||||
## 📋 Prérequis
|
||||
|
||||
- Python 3.8 ou supérieur
|
||||
- Compte Azure avec accès à :
|
||||
- Azure Document Intelligence (Form Recognizer)
|
||||
- Azure OpenAI avec accès GPT-4
|
||||
|
||||
## 🚀 Installation
|
||||
|
||||
### 1. Cloner le repository
|
||||
|
||||
```bash
|
||||
git clone https://git.linaster.online/vincent.morisseau/geotech.git
|
||||
cd geotech
|
||||
```
|
||||
|
||||
### 2. Installer les dépendances
|
||||
|
||||
```bash
|
||||
make setup
|
||||
```
|
||||
|
||||
Cela va :
|
||||
- Créer un environnement virtuel Python
|
||||
- Installer tous les packages nécessaires
|
||||
- Créer les dossiers requis
|
||||
|
||||
### 3. Configuration des variables d'environnement
|
||||
|
||||
⚠️ **IMPORTANT** : Les clés API ne doivent jamais être commitées dans Git !
|
||||
|
||||
1. **Copier le fichier d'exemple** :
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. **Éditer le fichier `.env`** et remplir vos clés API Azure :
|
||||
```bash
|
||||
nano .env # ou utilisez votre éditeur préféré
|
||||
```
|
||||
|
||||
3. **Remplir les variables suivantes** dans le fichier `.env` :
|
||||
```env
|
||||
# Azure Document Intelligence
|
||||
AZURE_DOC_ENDPOINT=https://your-resource.cognitiveservices.azure.com/
|
||||
AZURE_DOC_KEY=your-document-intelligence-key-here
|
||||
|
||||
# Azure OpenAI
|
||||
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
|
||||
AZURE_OPENAI_KEY=your-openai-key-here
|
||||
AZURE_DEPLOYMENT=gpt-4o-mini # ou gpt-4o, gpt-4, etc.
|
||||
API_VERSION=2024-12-01-preview
|
||||
```
|
||||
|
||||
⚠️ **Note de sécurité** : Le fichier `.env` est automatiquement ignoré par Git (via `.gitignore`) pour protéger vos clés API.
|
||||
|
||||
### 4. Obtenir les clés Azure
|
||||
|
||||
#### Azure Document Intelligence
|
||||
|
||||
1. **Créer une ressource dans le [portail Azure](https://portal.azure.com)**
|
||||
- Home → Create a resource
|
||||
- IA + Machine Learning → Document Intelligence (Form Recognizer)
|
||||
- Choisir la région (ex: East US 2)
|
||||
- Pricing tier : S0 (Standard)
|
||||
|
||||
2. **Récupérer les credentials**
|
||||
- Aller dans votre ressource → Keys and Endpoint
|
||||
- Copier `KEY 1` et `Endpoint`
|
||||
- Coller ces valeurs dans votre fichier `.env`
|
||||
|
||||
#### Azure OpenAI
|
||||
|
||||
1. **Demander l'accès à Azure OpenAI** (si nécessaire)
|
||||
- [Formulaire de demande d'accès](https://azure.microsoft.com/en-us/products/ai-services/openai-service)
|
||||
- Délai : 24-48h généralement
|
||||
|
||||
2. **Créer une ressource Azure OpenAI**
|
||||
- Home → Create a resource → Azure OpenAI
|
||||
- Choisir la région (recommandé : Sweden Central ou East US 2)
|
||||
|
||||
3. **Déployer un modèle GPT**
|
||||
- Accéder à Azure OpenAI Studio depuis votre ressource
|
||||
- Deployments → Create new deployment
|
||||
- Choisir votre modèle :
|
||||
- `gpt-4o-mini` : Économique, 0,003$/page
|
||||
- `gpt-4o` : Meilleur rapport qualité/prix, 0,042$/page
|
||||
- `gpt-4` : Plus cher mais plus puissant, 0,21$/page
|
||||
|
||||
4. **Récupérer les credentials**
|
||||
- Dans Azure OpenAI Studio → Deployments → View code
|
||||
- Copier l'endpoint, la clé et le nom du déploiement
|
||||
- Coller ces valeurs dans votre fichier `.env`
|
||||
|
||||
### 5. Vérifier la configuration
|
||||
|
||||
```bash
|
||||
# Test de connexion aux services Azure
|
||||
make test
|
||||
|
||||
# Ou vérifier manuellement
|
||||
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print('✅ OK' if os.getenv('AZURE_DOC_KEY') else '❌ .env non configuré')"
|
||||
```
|
||||
|
||||
## 📖 Utilisation
|
||||
|
||||
### Extraction d'un seul PDF
|
||||
|
||||
```bash
|
||||
# Extraction simple (sauvegarde dans output/document.json)
|
||||
make single PDF=document.pdf
|
||||
|
||||
# Ou directement avec le script
|
||||
python extract_single.py document.pdf
|
||||
|
||||
# Spécifier un fichier de sortie custom
|
||||
python extract_single.py document.pdf -o results/custom.json
|
||||
|
||||
# Avec formatage JSON lisible
|
||||
python extract_single.py document.pdf --pretty
|
||||
```
|
||||
|
||||
### Optimisation des prompts
|
||||
|
||||
Pour améliorer la qualité d'extraction sur un ensemble de PDFs de test :
|
||||
|
||||
1. Placer les PDFs de test dans `examples/`
|
||||
2. Placer les résultats attendus dans `output_man/` (format : `1_layers.json` pour `1.pdf`)
|
||||
3. Lancer le test :
|
||||
|
||||
```bash
|
||||
make test-optimizer
|
||||
```
|
||||
|
||||
### Test des connexions Azure
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
## 📁 Structure du projet
|
||||
|
||||
```
|
||||
geotechnical-extractor/
|
||||
├── .env.example # Fichier d'exemple pour les variables d'environnement
|
||||
├── .env # VOS clés API (ignoré par Git)
|
||||
├── .gitignore # Fichiers à ignorer (inclut .env)
|
||||
├── extract_single.py # Script principal d'extraction
|
||||
├── prompt_optimizer.py # Optimiseur de prompts
|
||||
├── requirements.txt # Dépendances Python
|
||||
├── Makefile # Commandes simplifiées
|
||||
├── README.md # Ce fichier
|
||||
├── examples/ # PDFs de test pour l'optimiseur
|
||||
│ ├── 1.pdf
|
||||
│ ├── 2.pdf
|
||||
│ └── ...
|
||||
├── output_man/ # Résultats attendus (vérité terrain)
|
||||
│ ├── 1_layers.json
|
||||
│ ├── 2_layers.json
|
||||
│ └── ...
|
||||
└── output/ # Résultats générés
|
||||
├── document.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 📊 Format de sortie
|
||||
|
||||
Les résultats sont sauvegardés en JSON avec la structure suivante :
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"source_file": "/path/to/document.pdf",
|
||||
"extraction_date": "2025-08-06T10:30:45.123456",
|
||||
"extraction_method": "Azure Document Intelligence + GPT-4",
|
||||
"pages": 6,
|
||||
"layer_count": 12,
|
||||
"extraction_time_seconds": 23.5
|
||||
},
|
||||
"layers": [
|
||||
{
|
||||
"page": 1,
|
||||
"depth_start": 0.0,
|
||||
"depth_end": 0.3,
|
||||
"description": "Terre végétale, brun foncé, présence de racines"
|
||||
},
|
||||
{
|
||||
"page": 1,
|
||||
"depth_start": 0.3,
|
||||
"depth_end": 2.5,
|
||||
"description": "Argile limoneuse, gris-beige, plastique, humide"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Description des champs
|
||||
|
||||
- **metadata** : Informations sur l'extraction
|
||||
- `source_file` : Chemin absolu du PDF source
|
||||
- `extraction_date` : Date et heure de l'extraction
|
||||
- `pages` : Nombre de pages traitées
|
||||
- `layer_count` : Nombre de couches extraites
|
||||
- `extraction_time_seconds` : Durée de l'extraction
|
||||
|
||||
- **layers** : Liste des couches géologiques
|
||||
- `page` : Numéro de page où apparaît la couche
|
||||
- `depth_start` : Profondeur de début en mètres
|
||||
- `depth_end` : Profondeur de fin en mètres
|
||||
- `description` : Description complète du matériau
|
||||
|
||||
## 💰 Coûts estimés
|
||||
|
||||
Entre ~0,003€ et ~0,21€ par page selon le modèle.
|
||||
|
||||
**Recommandation** : Utilisez GPT-4o pour le meilleur rapport qualité/prix
|
||||
|
||||
## 🚨 Résolution des problèmes
|
||||
|
||||
### "Missing Azure credentials"
|
||||
- Vérifier que le fichier `.env` existe
|
||||
- Vérifier que toutes les variables sont remplies dans `.env`
|
||||
- S'assurer d'avoir copié `.env.example` vers `.env`
|
||||
|
||||
### "Resource not found"
|
||||
- Vérifier que l'endpoint Azure est correct (avec ou sans `/` final)
|
||||
- S'assurer que la ressource est déployée et active
|
||||
|
||||
### "Invalid API key"
|
||||
- Vérifier que vous utilisez la bonne clé
|
||||
- Les clés Document Intelligence et OpenAI sont différentes
|
||||
- Vérifier qu'il n'y a pas d'espaces dans les clés
|
||||
|
||||
### "Model not found"
|
||||
- Vérifier le nom exact du déploiement GPT dans `.env`
|
||||
- S'assurer que le modèle est déployé dans votre région
|
||||
- Le nom est sensible à la casse
|
||||
|
||||
### Extraction incomplète
|
||||
- Augmenter la limite de caractères dans le script
|
||||
- Vérifier la qualité du PDF (scan lisible)
|
||||
- Utiliser GPT-4o au lieu de GPT-4o-mini
|
||||
|
||||
### Pages manquantes
|
||||
- Le script traite maintenant jusqu'à 8000 caractères par page
|
||||
- Les tableaux sont marqués avec `[TABLE DATA]` pour une meilleure détection
|
||||
|
||||
## 🛠️ Personnalisation
|
||||
|
||||
### Modifier les prompts
|
||||
|
||||
Les prompts sont définis dans la méthode `get_prompts()` des scripts. Vous pouvez les adapter selon vos besoins spécifiques.
|
||||
|
||||
### Ajuster les limites
|
||||
|
||||
```python
|
||||
# Augmenter la limite de caractères par page
|
||||
max_chars = 10000 # Au lieu de 8000
|
||||
|
||||
# Augmenter les tokens de réponse
|
||||
max_tokens=6000 # Au lieu de 4000
|
||||
```
|
||||
|
||||
### Variables d'environnement supplémentaires
|
||||
|
||||
Vous pouvez ajouter dans votre `.env` :
|
||||
|
||||
```env
|
||||
# Optionnel : niveau de log
|
||||
LOG_LEVEL=DEBUG # ou INFO, WARNING, ERROR
|
||||
|
||||
# Optionnel : taille des chunks pour les PDFs volumineux
|
||||
CHUNK_SIZE=2 # Nombre de pages par chunk
|
||||
```
|
||||
|
||||
### Langues supportées
|
||||
|
||||
Les prompts actuels sont en français mais peuvent être traduits. Le système supporte tous les documents que Document Intelligence peut traiter.
|
||||
|
||||
## 🧹 Maintenance
|
||||
|
||||
```bash
|
||||
# Nettoyer tous les fichiers générés
|
||||
make clean
|
||||
|
||||
# Voir les informations système
|
||||
make info
|
||||
```
|
||||
|
||||
## 📈 Performances
|
||||
|
||||
- **Temps moyen** : 3-5 secondes par page
|
||||
- **Précision** : ~85-95% selon la complexité du document
|
||||
- **Limite** : PDFs jusqu'à 500 pages (limite Azure)
|
||||
|
||||
## 🔒 Sécurité
|
||||
|
||||
- **Ne jamais committer le fichier `.env`** contenant vos clés API
|
||||
- Le fichier `.env` est automatiquement ignoré par Git
|
||||
- Utilisez `.env.example` comme template pour partager la structure
|
||||
- Changez régulièrement vos clés API Azure
|
||||
- Utilisez des variables d'environnement en production
|
||||
|
||||
## 📝 Licence
|
||||
|
||||
Ce projet est sous licence VCGI par Tom BLANCHETON.
|
||||
|
||||
## 🙏 Remerciements
|
||||
|
||||
- Azure Document Intelligence pour l'OCR de qualité
|
||||
- OpenAI pour GPT-4
|
||||
- La communauté géotechnique pour les retours et tests
|
||||
|
||||
Reference in New Issue
Block a user