Spaces:
Sleeping
Sleeping
| # Configuration de l'Application d'Annotation | |
| Cette documentation explique comment configurer l'application pour un déploiement en production sur Hugging Face Spaces avec plusieurs annotateurs. | |
| ## Table des matières | |
| 1. [Vue d'ensemble](#vue-densemble) | |
| 2. [Étape 1 : Créer le Dataset de stockage](#étape-1--créer-le-dataset-de-stockage) | |
| 3. [Étape 2 : Configurer les Secrets HF](#étape-2--configurer-les-secrets-hf) | |
| 4. [Étape 3 : Configurer les Annotateurs](#étape-3--configurer-les-annotateurs) | |
| 5. [Étape 4 : Pousser sur HF Spaces](#étape-4--pousser-sur-hf-spaces) | |
| 6. [Utilisation pour les Annotateurs](#utilisation-pour-les-annotateurs) | |
| 7. [Récupération des Annotations](#récupération-des-annotations) | |
| --- | |
| ## Vue d'ensemble | |
| L'application implémente 3 systèmes de sécurité et persistance : | |
| 1. **Authentification** : Mot de passe unique pour accéder à l'app | |
| 2. **Dispatch** : Chaque annotateur voit uniquement sa portion du dataset | |
| 3. **Persistance** : Sauvegarde automatique sur un Dataset HuggingFace privé | |
| --- | |
| ## Étape 1 : Créer le Dataset de stockage | |
| 1. Allez sur https://huggingface.co/new-dataset | |
| 2. Créez un nouveau dataset **PRIVÉ** : | |
| - Nom : `ffgen-annotations-storage` (ou autre) | |
| - Type : Dataset | |
| - Visibilité : **Private** ⚠️ Très important ! | |
| 3. Laissez-le vide, l'app créera automatiquement la structure | |
| --- | |
| ## Étape 2 : Configurer les Secrets HF | |
| ### 2.1 Créer un Token HuggingFace | |
| 1. Allez dans vos settings HF : https://huggingface.co/settings/tokens | |
| 2. Créez un nouveau token avec les permissions **write** | |
| 3. Copiez le token (format : `hf_xxxxxxxxxxxx`) | |
| ### 2.2 Ajouter les Secrets dans le Space | |
| 1. Allez dans votre Space : `https://huggingface.co/spaces/VOTRE-USERNAME/feedbacks-scoring-app` | |
| 2. Cliquez sur **Settings** | |
| 3. Scrollez vers **Variables and secrets** | |
| 4. Ajoutez les secrets suivants : | |
| | Nom | Valeur | Description | | |
| |-----|--------|-------------| | |
| | `APP_PASSWORD` | `VotreMotDePasse2025!` | Mot de passe pour accéder à l'app | | |
| | `HF_TOKEN` | `hf_xxxxxxxxxxxx` | Token avec droits d'écriture | | |
| | `HF_DATASET_REPO` | `VOTRE-USERNAME/ffgen-annotations-storage` | Nom du dataset de stockage | | |
| **Important** : | |
| - Le token doit avoir les droits d'écriture | |
| - Le dataset doit être privé pour protéger les annotations | |
| --- | |
| ## Étape 3 : Configurer les Annotateurs | |
| ### Option A : Configuration automatique (recommandé) | |
| Créez un fichier `annotators.json` dans le dossier `data/` : | |
| ```json | |
| { | |
| "annotator_1": { | |
| "name": "Alice Dupont", | |
| "start_idx": 0, | |
| "end_idx": 100, | |
| "description": "Première portion du dataset" | |
| }, | |
| "annotator_2": { | |
| "name": "Bob Martin", | |
| "start_idx": 100, | |
| "end_idx": 200, | |
| "description": "Deuxième portion" | |
| }, | |
| "annotator_3": { | |
| "name": "Charlie Durand", | |
| "start_idx": 200, | |
| "end_idx": 300, | |
| "description": "Troisième portion" | |
| } | |
| } | |
| ``` | |
| ### Option B : Configuration via Secret HF | |
| Ajoutez un secret `ANNOTATOR_CONFIG` avec la configuration JSON en une ligne : | |
| ```json | |
| {"annotator_1":{"name":"Alice","start_idx":0,"end_idx":100},"annotator_2":{"name":"Bob","start_idx":100,"end_idx":200}} | |
| ``` | |
| ### Utilisation du script de génération FFGen | |
| Si vous avez déjà utilisé le script `create_annotation_study.py` de FFGen : | |
| ```bash | |
| # Depuis FFGen/3_data_processing/ | |
| python create_annotation_study.py \ | |
| matis35/code-feedback-infonce \ | |
| --num-samples 300 \ | |
| --num-subsets 3 \ | |
| --output-dir annotation_study | |
| ``` | |
| Cela crée 3 subsets de ~100 items chacun + gold standard. | |
| Pour l'app, configurez les annotateurs correspondants : | |
| - annotator_1 : subset_01 (indices 0-100) | |
| - annotator_2 : subset_02 (indices 100-200) | |
| - annotator_3 : subset_03 (indices 200-300) | |
| --- | |
| ## Étape 4 : Pousser sur HF Spaces | |
| 1. Commitez tous les changements : | |
| ```bash | |
| git add . | |
| git commit -m "Add authentication, dispatch and HF persistence" | |
| ``` | |
| 2. Poussez vers HF : | |
| ```bash | |
| git push origin main | |
| ``` | |
| 3. Le Space va rebuilder automatiquement (prend 3-5 minutes) | |
| 4. Une fois prêt, vérifiez que l'app démarre correctement | |
| --- | |
| ## Utilisation pour les Annotateurs | |
| ### Workflow complet | |
| 1. **Accès à l'application** | |
| - URL : `https://huggingface.co/spaces/VOTRE-USERNAME/feedbacks-scoring-app` | |
| - Entrer le mot de passe fourni | |
| 2. **Sélection de l'identité** | |
| - Choisir son identifiant dans la liste | |
| - Le système affiche automatiquement la portion assignée | |
| 3. **Chargement du dataset** | |
| - Option 1 : Upload d'un fichier JSONL | |
| - Option 2 : Chargement depuis HF Hub | |
| - Le dataset est automatiquement filtré selon la portion | |
| 4. **Annotation** | |
| - Scorer les feedbacks (1-5) | |
| - Ajouter des commentaires optionnels | |
| - La progression est sauvegardée automatiquement | |
| 5. **Sauvegarde** | |
| - **Importante** : Cliquer sur "☁️ Sauvegarder sur HF" régulièrement | |
| - Cette sauvegarde est permanente (survit aux redémarrages) | |
| - La sauvegarde locale est perdue tous les 48h | |
| 6. **Export (optionnel)** | |
| - Télécharger le JSONL en local pour backup | |
| ### Instructions à donner aux annotateurs | |
| > **Bienvenue sur l'outil d'annotation FFGen !** | |
| > | |
| > 1. Mot de passe : `[VOTRE_MOT_DE_PASSE]` | |
| > 2. Choisissez votre identifiant dans la liste | |
| > 3. Chargez le dataset (demandez le lien HF ou le fichier) | |
| > 4. Annotez les feedbacks selon les critères fournis | |
| > 5. **Important** : Sauvegardez sur HF toutes les 30-60 minutes | |
| > 6. Vous pouvez fermer et reprendre plus tard | |
| > | |
| > Questions ? Contactez [VOTRE_EMAIL] | |
| --- | |
| ## Récupération des Annotations | |
| ### Méthode 1 : Via HuggingFace Hub (recommandé) | |
| 1. Allez sur votre dataset de stockage : | |
| `https://huggingface.co/datasets/VOTRE-USERNAME/ffgen-annotations-storage` | |
| 2. Dans le dossier `annotations/`, vous trouverez tous les fichiers : | |
| - `annotation_annotator_1_20250127_143022.json` | |
| - `annotation_annotator_2_20250127_151533.json` | |
| - etc. | |
| 3. Téléchargez-les ou utilisez la CLI : | |
| ```bash | |
| huggingface-cli download \ | |
| VOTRE-USERNAME/ffgen-annotations-storage \ | |
| --repo-type dataset \ | |
| --local-dir ./annotations | |
| ``` | |
| ### Méthode 2 : Via l'API Python | |
| ```python | |
| from huggingface_hub import HfApi, hf_hub_download | |
| import json | |
| api = HfApi(token="hf_xxxxxxxxxxxx") | |
| # Lister tous les fichiers | |
| files = api.list_repo_files( | |
| repo_id="VOTRE-USERNAME/ffgen-annotations-storage", | |
| repo_type="dataset" | |
| ) | |
| # Télécharger et charger chaque annotation | |
| for file in files: | |
| if file.startswith("annotations/"): | |
| local_path = hf_hub_download( | |
| repo_id="VOTRE-USERNAME/ffgen-annotations-storage", | |
| filename=file, | |
| repo_type="dataset", | |
| token="hf_xxxxxxxxxxxx" | |
| ) | |
| with open(local_path, 'r') as f: | |
| data = json.load(f) | |
| print(f"Annotator: {data['annotator_name']}") | |
| print(f"Scores: {len(data['scores'])}") | |
| ``` | |
| ### Méthode 3 : Utiliser le script de merge FFGen | |
| Si vous avez des gold items pour calculer l'accord inter-annotateurs : | |
| ```bash | |
| cd FFGen/3_data_processing | |
| # Analyser l'accord | |
| python analyze_agreement.py \ | |
| ../../annotations/annotation_*.json \ | |
| --gold-file annotation_study/matis35_code-feedback-infonce_gold_standard.json | |
| # Merger les scores | |
| python merge_scores.py \ | |
| ../../annotations/annotation_*.json \ | |
| -o final_annotations.jsonl | |
| ``` | |
| --- | |
| ## Dépannage | |
| ### Le Space ne démarre pas | |
| - Vérifiez que tous les secrets sont bien configurés | |
| - Regardez les logs du Space (onglet Logs) | |
| - Vérifiez que le `HF_TOKEN` a les droits d'écriture | |
| ### L'authentification ne marche pas | |
| - Vérifiez que `APP_PASSWORD` est bien dans les secrets | |
| - Pas d'espaces avant/après le mot de passe | |
| ### La sauvegarde HF échoue | |
| - Vérifiez que `HF_TOKEN` a les droits d'écriture | |
| - Vérifiez que `HF_DATASET_REPO` existe et est privé | |
| - Regardez les messages d'erreur dans l'app | |
| ### Un annotateur voit le dataset complet | |
| - Vérifiez la configuration dans `annotators.json` | |
| - Vérifiez que les indices start_idx/end_idx sont corrects | |
| - Rechargez le dataset après modification de la config | |
| ### Les annotations sont perdues | |
| - Rappelez aux annotateurs de sauvegarder sur HF | |
| - La sauvegarde locale est réinitialisée tous les 48h | |
| - Les sauvegardes HF sont permanentes | |
| --- | |
| ## Architecture Technique | |
| ``` | |
| ┌─────────────────────────────────────────────────────────┐ | |
| │ HF Space (Public) │ | |
| │ ┌────────────────────────────────────────────────────┐ │ | |
| │ │ 1. Authentification (APP_PASSWORD) │ │ | |
| │ │ ↓ │ │ | |
| │ │ 2. Sélection Annotateur │ │ | |
| │ │ ↓ │ │ | |
| │ │ 3. Filtrage Dataset (start_idx, end_idx) │ │ | |
| │ │ ↓ │ │ | |
| │ │ 4. Interface d'Annotation │ │ | |
| │ │ ↓ │ │ | |
| │ │ 5. Sauvegarde Cloud (HF_TOKEN) │ │ | |
| │ └────────────────────────────────────────────────────┘ │ | |
| └────────────────────┬────────────────────────────────────┘ | |
| │ | |
| ↓ | |
| ┌─────────────────────────────────────────────────────────┐ | |
| │ HF Dataset (Private): annotations-storage │ | |
| │ ┌────────────────────────────────────────────────────┐ │ | |
| │ │ annotations/ │ │ | |
| │ │ ├── annotation_annotator_1_timestamp.json │ │ | |
| │ │ ├── annotation_annotator_2_timestamp.json │ │ | |
| │ │ └── annotation_annotator_3_timestamp.json │ │ | |
| │ └────────────────────────────────────────────────────┘ │ | |
| └─────────────────────────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## Sécurité et Bonnes Pratiques | |
| ✅ **À faire** : | |
| - Utiliser des mots de passe forts (12+ caractères) | |
| - Garder le dataset de stockage **PRIVÉ** | |
| - Révoquer les tokens après l'étude | |
| - Sauvegarder régulièrement sur HF | |
| - Tester avec un annotateur avant le déploiement complet | |
| ❌ **À éviter** : | |
| - Partager le token HF publiquement | |
| - Utiliser le même mot de passe que vos autres comptes | |
| - Rendre le dataset de stockage public | |
| - Compter uniquement sur la sauvegarde locale | |
| - Modifier la config en cours d'annotation | |
| --- | |
| ## Support | |
| Pour toute question ou problème : | |
| - Issues GitHub : [LIEN_REPO] | |
| - Email : [VOTRE_EMAIL] | |
| - Documentation FFGen : `FFGen/README.md` | |