Simulateur d'utilisateurs

Name: Potato
Author: Potato

Simulez plusieurs annotateurs simultanés dans Potato pour les tests d'intégration — configurez stratégies d'annotation, vitesse et niveaux d'accord pour des tests de charge réalistes.

Le simulateur d'utilisateurs permet de tester automatiquement les tâches d'annotation Potato en simulant plusieurs utilisateurs aux comportements et niveaux de compétence configurables.

Vue d'ensemble

Le simulateur sert à :

Tester le contrôle qualité : éprouvez les contrôles d'attention, les étalons de référence et le comportement de blocage
Tester le tableau de bord : générez des données d'annotation réalistes pour le tableau de bord d'administration
Tester la montée en charge : mettez le serveur sous contrainte avec de nombreux utilisateurs simultanés
Évaluer l'assistance IA : comparez l'exactitude d'un LLM à des comportements de type humain
Tester l'apprentissage actif : simulez des flux d'annotation itératifs

Démarrage rapide

bash

# Basic random simulation with 10 users
python -m potato.simulator --server http://localhost:8000 --users 10
 
# With configuration file
python -m potato.simulator --config simulator-config.yaml --server http://localhost:8000
 
# Fast scalability test (no waiting between annotations)
python -m potato.simulator --server http://localhost:8000 --users 50 --parallel 10 --fast-mode

Configuration

Fichier de configuration YAML

Créez un fichier YAML avec les réglages du simulateur :

yaml

simulator:
  # User configuration
  users:
    count: 20
    competence_distribution:
      good: 0.5      # 50% will be "good" annotators (80-90% accuracy)
      average: 0.3   # 30% "average" (60-70% accuracy)
      poor: 0.2      # 20% "poor" (40-50% accuracy)
 
  # Annotation strategy
  strategy: random  # random, biased, llm, pattern
 
  # Timing configuration
  timing:
    annotation_time:
      min: 2.0
      max: 45.0
      mean: 12.0
      std: 6.0
      distribution: normal  # uniform, normal, exponential
 
  # Execution
  execution:
    parallel_users: 5
    delay_between_users: 0.5
    max_annotations_per_user: 50
 
server:
  url: http://localhost:8000

Niveaux de compétence

Niveau	Exactitude	Description
`perfect`	100 %	Correspond toujours à l'étalon de référence
`good`	80-90 %	Annotateur de haute qualité
`average`	60-70 %	Travailleur de foule typique
`poor`	40-50 %	Annotateur de faible qualité
`random`	~1/N	Choix aléatoire parmi les étiquettes
`adversarial`	0 %	Faux intentionnellement (pour tester le contrôle qualité)

Stratégies d'annotation

Stratégie aléatoire (par défaut)

Choisit les étiquettes uniformément au hasard :

yaml

strategy: random

Stratégie biaisée

Choix pondéré selon des préférences d'étiquettes :

yaml

strategy: biased
biased_config:
  label_weights:
    positive: 0.6
    negative: 0.3
    neutral: 0.1

Stratégie LLM

Utilise un LLM pour produire les annotations à partir du contenu textuel :

yaml

strategy: llm
llm_config:
  endpoint_type: openai
  model: gpt-4o-mini
  api_key: ${OPENAI_API_KEY}
  temperature: 0.1
  add_noise: true
  noise_rate: 0.05

Pour des LLM locaux avec Ollama :

yaml

strategy: llm
llm_config:
  endpoint_type: ollama
  model: llama3.2
  base_url: http://localhost:11434

Options en ligne de commande

text

Usage: python -m potato.simulator [OPTIONS]

Required:
  --server, -s URL        Potato server URL

User Configuration:
  --users, -u NUM         Number of simulated users (default: 10)
  --competence DIST       Competence distribution

Strategy:
  --strategy TYPE         Strategy: random, biased, llm, pattern
  --llm-endpoint TYPE     LLM endpoint: openai, anthropic, ollama
  --llm-model NAME        LLM model name

Execution:
  --parallel, -p NUM      Max concurrent users (default: 5)
  --max-annotations, -m   Max annotations per user
  --fast-mode             Disable waiting between annotations

Output:
  --output-dir, -o DIR    Output directory (default: simulator_output)

Tester le contrôle qualité

Testez la détection des contrôles d'attention :

yaml

simulator:
  users:
    count: 10
    competence_distribution:
      adversarial: 1.0  # All users will fail
  quality_control:
    attention_check_fail_rate: 0.5
    respond_fast_rate: 0.3

Fichiers de sortie

Après la simulation, les résultats sont exportés dans le répertoire de sortie :

summary_{timestamp}.json - Statistiques agrégées
user_results_{timestamp}.json - Résultats détaillés par utilisateur
annotations_{timestamp}.csv - Toutes les annotations au format plat

Exemple de résumé

json

{
  "user_count": 20,
  "total_annotations": 400,
  "total_time_seconds": 125.3,
  "attention_checks": {
    "passed": 18,
    "failed": 2,
    "pass_rate": 0.9
  }
}

Utilisation par programme

python

from potato.simulator import SimulatorManager, SimulatorConfig
 
# Create configuration
config = SimulatorConfig(
    user_count=10,
    strategy="random",
    competence_distribution={"good": 0.5, "average": 0.5}
)
 
# Create and run simulator
manager = SimulatorManager(config, "http://localhost:8000")
results = manager.run_parallel(max_annotations_per_user=20)
 
# Print summary and export
manager.print_summary()
manager.export_results()

Intégration aux tests

Le simulateur s'utilise dans des fixtures pytest :

python

import pytest
from potato.simulator import SimulatorManager, SimulatorConfig
 
@pytest.fixture
def simulated_annotations(flask_test_server):
    config = SimulatorConfig(user_count=5, strategy="random")
    manager = SimulatorManager(config, flask_test_server.base_url)
    return manager.run_parallel(max_annotations_per_user=10)
 
def test_dashboard_shows_annotations(simulated_annotations, flask_test_server):
    response = requests.get(f"{flask_test_server.base_url}/admin/api/overview")
    assert response.json()["total_annotations"] > 0

Dépannage

Échecs de connexion

Vérifiez que le serveur autorise l'inscription anonyme ou qu'il a require_password: false
Consultez les journaux du serveur à la recherche d'erreurs d'authentification

Aucune instance disponible

Vérifiez que les fichiers de données sont chargés correctement
Contrôlez les réglages de la stratégie d'attribution

La stratégie LLM ne fonctionne pas

Vérifiez que la clé d'API est définie
Pour Ollama, assurez-vous que le serveur tourne
Vérifiez que le nom du modèle est correct

Pour aller plus loin

Contrôle qualité - Testez les contrôles d'attention et les étalons de référence
Tableau de bord d'administration - Consultez les données simulées
Guide de débogage - Résolvez les problèmes

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