QUICKSTART.md

Guide de Démarrage Rapide

Configuration en 5 minutes pour déployer l'application d'annotation sécurisée.

Prérequis

• Un compte HuggingFace
• Accès à votre Space matis35/feedbacks-scoring-app
• Le dataset à annoter (format JSONL ou sur HF Hub)

Étape 1 : Créer le Dataset de Stockage (2 min)

1. Allez sur https://huggingface.co/new-dataset
2. Nom : ffgen-annotations-storage
3. Visibilité : Private (très important!)
4. Cliquez sur "Create dataset"
5. Laissez-le vide, ne chargez rien

✅ Vous avez maintenant : matis35/ffgen-annotations-storage

Étape 2 : Créer un Token HF (1 min)

1. Allez sur https://huggingface.co/settings/tokens
2. Cliquez "New token"
3. Nom : annotation-app-write
4. Type : Write (important!)
5. Cliquez "Generate token"
6. Copiez le token (format hf_xxxxxxxxxxxx)

⚠️ Gardez ce token en sécurité, ne le partagez pas!

Étape 3 : Configurer les Secrets (2 min)

1. Allez sur votre Space : https://huggingface.co/spaces/matis35/feedbacks-scoring-app
2. Cliquez sur Settings (en haut)
3. Scrollez vers "Variables and secrets"
4. Ajoutez ces 3 secrets :

Secret 1 : APP_PASSWORD

• Nom : APP_PASSWORD
• Valeur : Choisissez un mot de passe fort (ex: Annotator2025!)
• Type : Secret

Secret 2 : HF_TOKEN

• Nom : HF_TOKEN
• Valeur : Le token copié à l'étape 2 (hf_xxxxx)
• Type : Secret

Secret 3 : HF_DATASET_REPO

• Nom : HF_DATASET_REPO
• Valeur : matis35/ffgen-annotations-storage
• Type : Secret

✅ Les 3 secrets doivent être visibles dans la liste

Étape 4 : Configurer les Annotateurs (2 min)

Option A : Configuration basique (3 annotateurs)

Copiez le fichier exemple :

cd feedbacks-scoring-app
cp data/annotators.json.example data/annotators.json

Éditez data/annotators.json selon votre dataset :

{
  "annotator_1": {
    "name": "Alice",
    "start_idx": 0,
    "end_idx": 100
  },
  "annotator_2": {
    "name": "Bob",
    "start_idx": 100,
    "end_idx": 200
  },
  "annotator_3": {
    "name": "Charlie",
    "start_idx": 200,
    "end_idx": 300
  }
}

Option B : Utiliser vos subsets FFGen

Si vous avez utilisé create_annotation_study.py :

# Vous avez créé 10 subsets avec create_annotation_study.py
# Configurez 10 annotateurs correspondants

# Exemple pour 10 annotateurs, 40 items chacun
python -c "
import json

config = {}
for i in range(10):
    config[f'annotator_{i+1}'] = {
        'name': f'Annotateur {i+1}',
        'start_idx': i * 40,
        'end_idx': (i + 1) * 40,
        'description': f'Subset {i+1}/10'
    }

with open('data/annotators.json', 'w') as f:
    json.dump(config, f, indent=2)

print('✅ Config créée pour 10 annotateurs')
"

Étape 5 : Pousser sur HF (1 min)

cd feedbacks-scoring-app

# Vérifier les changements
git status

# Commiter
git add .
git commit -m "Add secure authentication and HF persistence"

# Pousser vers HF Spaces
git push origin main

Le Space va rebuilder automatiquement (3-5 minutes).

Étape 6 : Tester (2 min)

1. Attendez que le Space soit "Running" (vert)
2. Ouvrez l'app : https://huggingface.co/spaces/matis35/feedbacks-scoring-app
3. Testez la connexion :
   • Entrez le mot de passe (APP_PASSWORD)
   • Sélectionnez un annotateur
   • Vérifiez que ça fonctionne

Étape 7 : Distribuer aux Annotateurs

Envoyez ce message à vos annotateurs :

Bonjour,

Voici les informations pour accéder à l'outil d'annotation :

URL : https://huggingface.co/spaces/matis35/feedbacks-scoring-app
Mot de passe : [VOTRE_APP_PASSWORD]
Votre identifiant : [annotator_X]

Instructions :
1. Ouvrez l'URL et entrez le mot de passe
2. Sélectionnez votre identifiant dans la liste
3. Chargez le dataset (je vous enverrai le lien/fichier)
4. Annotez les feedbacks selon les critères ci-dessous
5. IMPORTANT : Cliquez sur "☁️ Sauvegarder sur HF" toutes les 30-60 minutes
6. Vous pouvez fermer et reprendre plus tard

Critères d'annotation :
- Score 1 : [DÉFINIR]
- Score 2 : [DÉFINIR]
- Score 3 : [DÉFINIR]
- Score 4 : [DÉFINIR]
- Score 5 : [DÉFINIR]

Questions ? Contactez-moi : [VOTRE_EMAIL]

Vérification Post-Déploiement

✅ Checklist de vérification :

• Le Space démarre sans erreur
• L'authentification fonctionne
• La sélection d'annotateur fonctionne
• Le chargement de dataset fonctionne
• Le filtrage par portion fonctionne (vérifier les nombres)
• La sauvegarde HF fonctionne (vérifier dans le dataset)
• L'export JSONL fonctionne
• Les annotateurs peuvent se connecter

Commandes Utiles

Voir les logs du Space

# Via l'interface web : Settings > Logs
# Ou regarder en temps réel depuis l'onglet "Logs"

Vérifier les annotations sauvegardées

# Allez sur : https://huggingface.co/datasets/matis35/ffgen-annotations-storage
# Vous devriez voir un dossier annotations/ avec des fichiers .json

Télécharger toutes les annotations

huggingface-cli download \
    matis35/ffgen-annotations-storage \
    --repo-type dataset \
    --local-dir ./collected_annotations

Analyser l'accord inter-annotateurs (si gold items)

cd FFGen/3_data_processing

python analyze_agreement.py \
    ../../collected_annotations/annotations/*.json \
    --gold-file annotation_study/gold_standard.json

Dépannage Express

Le Space ne démarre pas

# Vérifiez les logs
# Problème courant : secret mal configuré
# Solution : Vérifiez Settings > Variables and secrets

"HF Storage not configured"

# Il manque HF_TOKEN ou HF_DATASET_REPO
# Ajoutez-les dans Settings > Secrets

"Authentication failed"

# APP_PASSWORD incorrect ou manquant
# Vérifiez Settings > Secrets

Un annotateur voit tout le dataset

# Problème dans annotators.json
# Vérifiez start_idx et end_idx
# Rechargez le dataset après correction

Les annotations disparaissent

# Les annotateurs n'ont pas sauvegardé sur HF
# Rappelez-leur de cliquer sur "☁️ Sauvegarder sur HF"
# La sauvegarde locale est perdue tous les 48h

Support

Documentation complète : CONFIGURATION.md

Problèmes ?

• Vérifiez d'abord les logs du Space
• Consultez la section Dépannage de CONFIGURATION.md
• Ouvrez une issue GitHub si nécessaire

---

Temps total : ~15 minutes

Prochain fichier à lire : CONFIGURATION.md pour les détails complets.