Intégration avec MTurk

Ce guide fournit des instructions pour déployer des tâches d'annotation Potato sur Amazon Mechanical Turk (MTurk).

Vue d'ensemble

Potato s'intègre à MTurk via le type de HIT External Question :

1. Vous créez un HIT de type External Question sur MTurk pointant vers votre serveur Potato
2. Les travailleurs cliquent sur votre HIT et sont redirigés vers votre serveur Potato
3. Potato extrait l'identifiant du travailleur et d'autres paramètres de l'URL
4. Les travailleurs effectuent la tâche d'annotation
5. Une fois terminé, les travailleurs cliquent sur « Submit HIT to MTurk »

Paramètres d'URL

MTurk transmet quatre paramètres à l'URL de votre External Question :

Prérequis

Exigences du serveur

1. Serveur accessible publiquement avec :

   • Port ouvert (généralement 8080 ou 443)
   • HTTPS recommandé (requis pour certains navigateurs)
   • Connexion internet stable

2. Environnement Python avec Potato installé

Exigences MTurk

1. Compte Requester MTurk : Inscrivez-vous sur requester.mturk.com
2. Compte approvisionné : Ajoutez des fonds pour la production (le sandbox est gratuit)

Démarrage rapide

Étape 1 : Créer votre configuration Potato

# mturk_task.yaml
annotation_task_name: "Sentiment Classification"
task_description: "Classify the sentiment of short text snippets."
 
# MTurk login configuration
login:
  type: url_direct
  url_argument: workerId
 
# Optional completion code
completion_code: "TASK_COMPLETE"
 
# Crowdsourcing settings
hide_navbar: true
jumping_to_id_disabled: true
assignment_strategy: random
max_annotations_per_user: 10
max_annotations_per_item: 3
 
# Data files
data_files:
  - data/items.json
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels:
      - positive
      - neutral
      - negative

Étape 2 : Démarrer votre serveur

# Start the server
potato start mturk_task.yaml -p 8080
 
# Or with HTTPS (recommended)
potato start mturk_task.yaml -p 443 --ssl-cert cert.pem --ssl-key key.pem

Étape 3 : Créer votre HIT sur MTurk

Créez un HIT de type External Question à l'aide de ce modèle XML :

<?xml version="1.0" encoding="UTF-8"?>
<ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd">
  <ExternalURL>https://your-server.com:8080/?workerId=${workerId}&amp;assignmentId=${assignmentId}&amp;hitId=${hitId}&amp;turkSubmitTo=${turkSubmitTo}</ExternalURL>
  <FrameHeight>800</FrameHeight>
</ExternalQuestion>

Important : Utilisez & au lieu de & en XML.

Référence de configuration

Paramètres requis

login:
  type: url_direct      # Required: enables URL-based authentication
  url_argument: workerId  # Required: MTurk uses 'workerId' parameter

Paramètres recommandés

hide_navbar: true           # Prevent workers from skipping
jumping_to_id_disabled: true
assignment_strategy: random
max_annotations_per_user: 10
max_annotations_per_item: 3
task_description: "Brief description for the preview page."
completion_code: "YOUR_CODE"

Tests dans le Sandbox

Testez toujours dans le MTurk Sandbox avant de passer en production.

URLs du Sandbox

Tests locaux

Testez localement les paramètres d'URL de MTurk :

# Test normal workflow
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=TEST_ASSIGNMENT&hitId=TEST_HIT"
 
# Test preview mode
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE&hitId=TEST_HIT"

Intégration de l'API MTurk (facultatif)

Pour les fonctionnalités avancées, activez l'intégration de l'API MTurk :

pip install boto3

Créez configs/mturk_config.yaml :

aws_access_key_id: "YOUR_ACCESS_KEY"
aws_secret_access_key: "YOUR_SECRET_KEY"
sandbox: true  # Set to false for production
hit_id: "YOUR_HIT_ID"

Activez-la dans votre configuration principale :

mturk:
  enabled: true
  config_file_path: configs/mturk_config.yaml

Créer des HIT par programmation

import boto3
 
mturk = boto3.client(
    'mturk',
    region_name='us-east-1',
    endpoint_url='https://mturk-requester-sandbox.us-east-1.amazonaws.com'
)
 
question_xml = '''<?xml version="1.0" encoding="UTF-8"?>
<ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd">
  <ExternalURL>https://your-server.com:8080/?workerId=${workerId}&amp;assignmentId=${assignmentId}&amp;hitId=${hitId}&amp;turkSubmitTo=${turkSubmitTo}</ExternalURL>
  <FrameHeight>800</FrameHeight>
</ExternalQuestion>'''
 
response = mturk.create_hit(
    Title='Sentiment Classification Task',
    Description='Classify the sentiment of short text snippets.',
    Keywords='sentiment, classification, text',
    Reward='0.50',
    MaxAssignments=100,
    LifetimeInSeconds=86400,
    AssignmentDurationInSeconds=3600,
    AutoApprovalDelayInSeconds=604800,
    Question=question_xml
)
 
print(f"Created HIT: {response['HIT']['HITId']}")

Bonnes pratiques

Conception des tâches

1. Instructions claires : Fournissez des exemples détaillés
2. Temps raisonnable : Ne pressez pas les travailleurs
3. Rémunération équitable : Au moins l'équivalent du salaire minimum (12-15 $/heure)
4. Durée gérable : 5 à 15 minutes par HIT est idéal

Contrôle de la qualité

1. Tests de qualification : Sélectionnez les travailleurs en amont
2. Vérifications d'attention : Incluez des questions de contrôle
3. Redondance : Plusieurs travailleurs par élément (3 ou plus recommandés)
4. Examen d'échantillons : Vérifiez manuellement un sous-ensemble

Aspects techniques

1. Gérer les cas limites : Les travailleurs peuvent recharger ou revenir en arrière
2. Enregistrer la progression : Sauvegarde automatique si possible
3. Erreurs gérées proprement : Affichez des messages d'erreur utiles

Dépannage

Les travailleurs voient la page d'aperçu après avoir accepté

• Vérifiez que le paramètre assignmentId est correctement transmis
• La page d'aperçu se rafraîchit automatiquement ; demandez aux travailleurs de patienter

Le bouton d'envoi ne fonctionne pas

• Consultez la console du navigateur pour repérer les erreurs
• Vérifiez que le paramètre turkSubmitTo est présent
• Vérifiez les problèmes de CORS ou de contenu mixte

Les travailleurs ne peuvent pas se connecter

• Vérifiez que login.url_argument est défini sur workerId
• Assurez-vous que login.type est url_direct

Pour aller plus loin

• Intégration du crowdsourcing - Configuration générale du crowdsourcing
• Contrôle de la qualité - Vérifications d'attention et standards de référence
• Attribution des tâches - Stratégies d'attribution

Pour les détails d'implémentation, consultez la documentation source.