Déployer sur Amazon Mechanical Turk

Amazon Mechanical Turk (MTurk) fournit un accès à une main-d'oeuvre importante et à la demande pour les tâches d'annotation. Potato s'intègre avec MTurk via le type de HIT ExternalQuestion : votre serveur Potato sert d'interface d'annotation, et MTurk gère le recrutement des travailleurs, le suivi des assignations et le paiement. Ce guide couvre le processus complet de configuration.

Prérequis

1. Compte AWS avec MTurk activé
2. Compte MTurk Requester (production ou sandbox) sur requester.mturk.com
3. Serveur Potato accessible via une URL publique (HTTPS recommandé)
4. Environnement Python avec Potato installé
5. Familiarité de base avec les concepts MTurk (HITs, Workers, Assignments)

Comment fonctionne l'intégration

Potato ne gère pas les HITs MTurk directement. L'intégration suit ce flux :

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 utilise le paramètre workerId pour identifier le travailleur (via login.type: url_direct)
4. Le travailleur complète la tâche d'annotation sur votre serveur Potato
5. À la fin, Potato redirige le travailleur vers l'endpoint de soumission de MTurk

Configuration

La clé de l'intégration MTurk est de définir le type de connexion sur url_direct avec url_argument: workerId. Cela indique à Potato d'extraire l'identité du travailleur du paramètre de requête URL que MTurk passe automatiquement.

login:
  type: url_direct
  url_argument: workerId

C'est la seule configuration spécifique à MTurk dans Potato. Tout le reste -- création de HIT, qualifications, paiement, approbation -- est géré 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
output_annotation_format: json

Configuration sur MTurk

Étape 1 : Démarrer votre serveur Potato

Lancez votre serveur Potato sur une machine accessible publiquement :

potato start config.yaml -p 8080

Étape 2 : Créer le XML ExternalQuestion

<?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>

Étape 3 : Créer le HIT avec boto3

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'
)
 
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,
    AssignmentDurationInSeconds=3600,
    AutoApprovalDelayInSeconds=604800,
    Question=question_xml,
)
 
print(f"Created HIT: {response['HIT']['HITId']}")

Calcul des coûts

MTurk facture des frais en plus de la récompense que vous payez aux travailleurs :

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

Bonnes pratiques

1. Commencez par le Sandbox : Testez toujours le flux complet dans le sandbox avant de dépenser de l'argent
2. Rémunération équitable : Visez au moins 12-15 $/heure
3. Descriptions claires des HIT : Des titres et descriptions bien rédigés attirent de meilleurs travailleurs
4. Approbation rapide : Les travailleurs apprécient un paiement rapide
5. Gérez les rejets avec précaution : Les rejets affectent le taux d'approbation des travailleurs
6. Utilisez HTTPS : Certains navigateurs bloquent le contenu mixte
7. Définissez hide_navbar: true : Empêche les travailleurs de naviguer hors de la tâche
8. Surveillez votre serveur : Assurez-vous que votre serveur Potato reste en ligne pendant la durée du HIT

Comparaison : MTurk vs Prolific

Prochaines étapes

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

Documentation complète sur MTurk sur /docs/deployment/mturk-integration. Pour les détails d'implémentation, voir la documentation source.