Skip to content

ユーザーシミュレーター

設定可能な動作を持つ複数のアノテーターをシミュレートする自動テストツール。

ユーザーシミュレーター

ユーザーシミュレーターは、設定可能な動作と能力レベルを持つ複数のユーザーをシミュレートして、Potatoアノテーションタスクの自動テストを可能にします。

概要

シミュレーターは以下に有用です：

  • 品質管理テスト：注意チェック、ゴールドスタンダード、ブロック動作のテスト
  • ダッシュボードテスト：管理者ダッシュボード用のリアルなアノテーションデータの生成
  • スケーラビリティテスト：多数の同時ユーザーでサーバーのストレステスト
  • AI支援の評価：人間のような動作に対するLLM精度の比較
  • 能動学習テスト：反復的なアノテーションワークフローのシミュレーション

クイックスタート

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

設定

YAML設定ファイル

シミュレーター設定のYAMLファイルを作成します：

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

能力レベル

レベル精度説明
perfect100%常にゴールドスタンダードと一致
good80-90%高品質なアノテーター
average60-70%一般的なクラウドワーカー
poor40-50%低品質なアノテーター
random~1/Nラベルからランダム選択
adversarial0%意図的に誤回答（品質管理テスト用）

アノテーション戦略

ランダム戦略（デフォルト）

ラベルを一様にランダムに選択します：

yaml
strategy: random

バイアス戦略

ラベルの好みに基づく重み付き選択：

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

LLM戦略

テキスト内容に基づいてLLMでアノテーションを生成します：

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

Ollamaを使用したローカルLLMの場合：

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

CLIオプション

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)

品質管理テスト

注意チェックの検出をテストします：

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

出力ファイル

シミュレーション後、結果は出力ディレクトリにエクスポートされます：

  • summary_{timestamp}.json - 集計統計
  • user_results_{timestamp}.json - ユーザーごとの詳細結果
  • annotations_{timestamp}.csv - フラット形式のすべてのアノテーション

サマリーの例

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

プログラムからの使用

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()

テストとの統合

シミュレーターは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

トラブルシューティング

ログイン失敗

  • サーバーが匿名登録を許可しているか、require_password: falseが設定されていることを確認
  • サーバーログで認証エラーを確認

インスタンスが利用できない

  • データファイルが正しく読み込まれていることを確認
  • 割り当て戦略の設定を確認

LLM戦略が動作しない

  • APIキーが設定されていることを確認
  • Ollamaの場合、サーバーが実行中であることを確認
  • モデル名が正しいことを確認

関連情報

実装の詳細については、ソースドキュメントを参照してください。