Déployer sur Amazon Mechanical Turk

Amazon Mechanical Turk (MTurk) vous donne accès à une vaste main-d'oeuvre à la demande pour vos tâches d'annotation. Potato se branche sur MTurk via le type de HIT ExternalQuestion : votre serveur Potato sert d'interface d'annotation, et MTurk se charge de recruter les travailleurs, de suivre les assignations et de les payer. Voici comment mettre tout cela en place.

Prérequis

1. Un compte AWS avec MTurk activé
2. Un compte MTurk Requester (production ou sandbox) sur requester.mturk.com
3. Un serveur Potato accessible à une URL publique (utilisez HTTPS)
4. Un environnement Python avec Potato installé
5. Une certaine familiarité avec les concepts MTurk (HITs, Workers, Assignments)

Comment fonctionne l'intégration

Potato ne gère pas directement les HITs MTurk. Le flux se déroule ainsi :

1. Vous créez un HIT ExternalQuestion sur MTurk qui pointe vers l'URL de votre serveur Potato
2. Un travailleur accepte le HIT sur MTurk et est redirigé vers votre serveur Potato avec des paramètres de requête (workerId, assignmentId, hitId, turkSubmitTo)
3. Potato lit le paramètre workerId pour identifier le travailleur (via login.type: url_direct)
4. Le travailleur réalise la tâche d'annotation sur votre serveur Potato
5. Une fois terminé, Potato le redirige vers l'endpoint de soumission de MTurk

Configuration

L'intégration MTurk se résume à une seule chose : définir le type de connexion sur url_direct avec url_argument: workerId. Cela indique à Potato d'extraire l'identité du travailleur depuis le paramètre de requête URL que MTurk transmet automatiquement.

login:
  type: url_direct
  url_argument: workerId

C'est le seul réglage spécifique à MTurk dans Potato. La création des HIT, les qualifications, le paiement et l'approbation se passent tous du côté MTurk.

Exemple de configuration complète

annotation_task_name: "Sentiment Classification"
task_description: "Classify the sentiment of short text snippets."
 
# MTurk login: extract worker ID from URL parameter
login:
  type: url_direct
  url_argument: workerId
 
# UI settings recommended for crowdsourcing
hide_navbar: true
jumping_to_id_disabled: true
 
# Assignment settings
assignment_strategy: random
max_annotations_per_user: 20
max_annotations_per_item: 3
 
# Data
data_files:
  - data/items.json
 
item_properties:
  id_key: id
  text_key: text
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels:
      - Positive
      - Negative
      - Neutral
 
# Output
output_annotation_dir: annotation_output
export_annotation_format: json

Mise en place sur MTurk

Étape 1 : Démarrer votre serveur Potato

Lancez votre serveur Potato sur une machine accessible publiquement :

potato start config.yaml -p 8080

Assurez-vous que le serveur est accessible depuis internet (par exemple, https://your-server.com:8080/).

Étape 2 : Créer le XML ExternalQuestion

MTurk intègre des sites web externes dans un HIT au moyen d'un format XML appelé ExternalQuestion. Voici le XML dont vous avez besoin :

<?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 & dans le XML. MTurk remplace les marqueurs ${...} par des valeurs réelles lorsqu'un travailleur accepte le HIT.

Étape 3 : Créer le HIT sur MTurk

Vous pouvez créer des HITs via la console MTurk Requester ou de façon programmatique avec le SDK AWS (boto3). Les paramètres du HIT comme le titre, la description, la récompense, la durée et les qualifications résident tous du côté MTurk, pas dans Potato.

Avec boto3 (Python)

import boto3
 
# Use sandbox for testing
mturk = boto3.client(
    'mturk',
    region_name='us-east-1',
    endpoint_url='https://mturk-requester-sandbox.us-east-1.amazonaws.com'
)
 
# For production, omit endpoint_url or use:
# endpoint_url='https://mturk-requester.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='Read short texts and classify their sentiment as positive, negative, or neutral.',
    Keywords='sentiment, classification, text, NLP',
    Reward='0.50',
    MaxAssignments=100,
    LifetimeInSeconds=86400,         # 1 day
    AssignmentDurationInSeconds=3600, # 1 hour
    AutoApprovalDelayInSeconds=604800, # 7 days
    Question=question_xml,
    QualificationRequirements=[
        {
            'QualificationTypeId': '000000000000000000L0',  # Approval rate
            'Comparator': 'GreaterThanOrEqualTo',
            'IntegerValues': [97]
        },
        {
            'QualificationTypeId': '00000000000000000040',  # Number approved
            'Comparator': 'GreaterThanOrEqualTo',
            'IntegerValues': [500]
        },
        {
            'QualificationTypeId': '00000000000000000071',  # Locale
            'Comparator': 'In',
            'LocaleValues': [
                {'Country': 'US'},
                {'Country': 'GB'},
                {'Country': 'CA'},
                {'Country': 'AU'}
            ]
        }
    ]
)
 
print(f"Created HIT: {response['HIT']['HITId']}")

Étape 4 : Définir les qualifications (sur MTurk)

Vous définissez les qualifications des travailleurs du côté MTurk lorsque vous créez le HIT. Filtres courants :

• Taux d'approbation : exiger un pourcentage minimum d'approbation des HIT, par exemple 97 % ou plus
• HITs approuvés : exiger un nombre minimum de HITs déjà approuvés, par exemple 500 ou plus
• Locale : limiter aux travailleurs de certains pays
• Masters : utiliser les travailleurs Masters présélectionnés par MTurk (cela coûte plus cher)
• Qualifications personnalisées : créer vos propres tests de qualification via la console MTurk

Gestion de l'achèvement

Lorsqu'un travailleur a terminé tous les items qui lui ont été assignés, Potato doit le rediriger vers MTurk afin que l'assignation soit soumise. MTurk transmet un paramètre d'URL turkSubmitTo qui indique à Potato où envoyer la requête POST d'achèvement.

Une fois la tâche terminée, le travailleur voit un bouton « Submit HIT ». En cliquant dessus, l'assignation est renvoyée à MTurk pour votre examen et votre approbation.

Tester dans le Sandbox MTurk

Testez l'ensemble du processus dans le Sandbox MTurk avant de dépenser de l'argent réel en production.

Tests en local

Vous pouvez tester le flux des paramètres d'URL en local, sans MTurk :

# Simulate a worker accessing your task
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=TEST_ASSIGN&hitId=TEST_HIT"
 
# Simulate the preview mode (before a worker accepts the HIT)
curl "http://localhost:8080/?workerId=TEST_WORKER&assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE&hitId=TEST_HIT"

Lorsque assignmentId vaut ASSIGNMENT_ID_NOT_AVAILABLE, le travailleur prévisualise le HIT et ne l'a pas encore accepté.

Gérer les HITs et les approbations

Vous gérez les HITs avec les propres outils de MTurk, qu'il s'agisse de suivre l'avancement, d'approuver ou de rejeter des assignations, ou d'attribuer des primes :

• Console MTurk Requester : une interface web pour gérer les HITs, examiner les assignations et envoyer des messages aux travailleurs
• boto3 (le SDK AWS pour Python) : accès programmatique pour les opérations par lots

# Example: List assignments for a HIT
assignments = mturk.list_assignments_for_hit(
    HITId='YOUR_HIT_ID',
    AssignmentStatuses=['Submitted']
)
 
# Approve an assignment
mturk.approve_assignment(AssignmentId='ASSIGNMENT_ID')
 
# Reject an assignment (use sparingly)
mturk.reject_assignment(
    AssignmentId='ASSIGNMENT_ID',
    RequesterFeedback='Did not complete all items.'
)

Calcul des coûts

MTurk facture des frais qui s'ajoutent à la récompense que vous versez aux travailleurs :

• Frais de base : 20 % du montant de la récompense
• Qualification Masters : 5 % supplémentaires
• 10 assignations ou plus par HIT : 20 % supplémentaires

Par exemple, si vous payez 0,50 $ par assignation sur 100 assignations :

• Coût de base : 100 x 0,50 $ x 1,20 = 60,00 $
• Avec Masters : 100 x 0,50 $ x 1,25 = 62,50 $

Ce qu'il vaut la peine de faire

1. Commencez dans le sandbox. Déroulez tout le processus là-bas avant qu'aucun argent ne change de mains.
2. Payez équitablement. Calculez le taux horaire (récompense / temps estimé x 60) et visez 12 à 15 $ de l'heure, voire davantage.
3. Rédigez des descriptions de HIT claires. De bons titres et descriptions attirent de meilleurs travailleurs.
4. Approuvez vite. Les travailleurs remarquent les paiements rapides, alors approuvez dès que la qualité semble correcte.
5. Soyez prudent avec les rejets. Ils nuisent au taux d'approbation des travailleurs et à votre propre réputation de requester, alors utilisez-les avec parcimonie.
6. Utilisez HTTPS. Certains navigateurs bloquent le contenu mixte, et HTTPS maintient l'iframe fonctionnelle.
7. Définissez hide_navbar: true pour que les travailleurs ne puissent pas s'éloigner de la tâche dans Potato.
8. Gardez votre serveur en ligne pendant toute la durée de vie du HIT.

MTurk vs Prolific

Pour aller plus loin

• Comparez avec l'intégration Prolific
• Mettez en place un contrôle qualité
• Calculez l'accord inter-annotateurs

Pour tous les détails de configuration de MTurk, consultez la documentation source. Si vous menez un effort de crowdsourcing plus important, le guide de crowdsourcing couvre la gestion des travailleurs et le suivi de la qualité à travers les plateformes.

Documentation complète sur MTurk sur /docs/deployment/mturk-integration.