Spaces:

matis35
/

feedbacks-scoring

Sleeping

Allez sur https://huggingface.co/new-dataset
Créez un nouveau dataset PRIVÉ :
- Nom : ffgen-annotations-storage (ou autre)
- Type : Dataset
- Visibilité : Private ⚠️ Très important !
Laissez-le vide, l'app créera automatiquement la structure

Étape 2 : Configurer les Secrets HF

2.1 Créer un Token HuggingFace

Allez dans vos settings HF : https://huggingface.co/settings/tokens
Créez un nouveau token avec les permissions write
Copiez le token (format : hf_xxxxxxxxxxxx)

2.2 Ajouter les Secrets dans le Space

Allez dans votre Space : https://huggingface.co/spaces/VOTRE-USERNAME/feedbacks-scoring-app
Cliquez sur Settings
Scrollez vers Variables and secrets
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/ :

{
  "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 :

{"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 :

# 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

Commitez tous les changements :

git add .
git commit -m "Add authentication, dispatch and HF persistence"

Poussez vers HF :

git push origin main

Le Space va rebuilder automatiquement (prend 3-5 minutes)
Une fois prêt, vérifiez que l'app démarre correctement

Utilisation pour les Annotateurs

Workflow complet

Accès à l'application
- URL : https://huggingface.co/spaces/VOTRE-USERNAME/feedbacks-scoring-app
- Entrer le mot de passe fourni
Sélection de l'identité
- Choisir son identifiant dans la liste
- Le système affiche automatiquement la portion assignée
Chargement du dataset
- Option 1 : Upload d'un fichier JSONL
- Option 2 : Chargement depuis HF Hub
- Le dataset est automatiquement filtré selon la portion
Annotation
- Scorer les feedbacks (1-5)
- Ajouter des commentaires optionnels
- La progression est sauvegardée automatiquement
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
Export (optionnel)
- Télécharger le JSONL en local pour backup

Instructions à donner aux annotateurs

Bienvenue sur l'outil d'annotation FFGen !

Mot de passe : [VOTRE_MOT_DE_PASSE]

Choisissez votre identifiant dans la liste

Chargez le dataset (demandez le lien HF ou le fichier)

Annotez les feedbacks selon les critères fournis

Important : Sauvegardez sur HF toutes les 30-60 minutes

Vous pouvez fermer et reprendre plus tard

Questions ? Contactez [VOTRE_EMAIL]

Récupération des Annotations

Méthode 1 : Via HuggingFace Hub (recommandé)

Allez sur votre dataset de stockage : https://huggingface.co/datasets/VOTRE-USERNAME/ffgen-annotations-storage
Dans le dossier annotations/, vous trouverez tous les fichiers :
- annotation_annotator_1_20250127_143022.json
- annotation_annotator_2_20250127_151533.json
- etc.
Téléchargez-les ou utilisez la CLI :

huggingface-cli download \
    VOTRE-USERNAME/ffgen-annotations-storage \
    --repo-type dataset \
    --local-dir ./annotations

Méthode 2 : Via l'API 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 :

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