Skip to content

アノテーション履歴

監査と分析のためにすべてのアノテーションアクションをタイムスタンプ付きで追跡する。

アノテーション履歴

Potatoは、きめ細かなタイムスタンプメタデータを備えたすべてのアノテーションアクションの包括的な追跡を提供します。これにより、パフォーマンス分析、品質保証、詳細な監査証跡が可能になります。

概要

アノテーション履歴システムは以下を追跡します：

  • すべてのアノテーションアクション：ラベル選択、スパンアノテーション、テキスト入力
  • 正確なタイムスタンプ：サーバー側とクライアント側のタイムスタンプ
  • アクションメタデータ：ユーザー、インスタンス、スキーマ、旧/新値
  • パフォーマンスメトリクス：処理時間、アクション率
  • 不審なアクティビティ：異常に速いまたはバーストアクティビティパターン

アクション追跡

すべてのアノテーション変更は以下の情報を持つAnnotationActionとして記録されます：

フィールド説明
action_id各アクションの一意のUUID
timestampサーバー側のタイムスタンプ
client_timestampブラウザ側のタイムスタンプ（利用可能な場合）
user_idアクションを実行したユーザー
instance_idアノテーション対象のインスタンス
action_type実行されたアクションの種類
schema_nameアノテーションスキーマ名
label_nameスキーマ内の特定のラベル
old_value以前の値（更新/削除時）
new_value新しい値（追加/更新時）
span_dataスパンアノテーションのスパン詳細
server_processing_time_msサーバー処理時間

アクションタイプ

システムは以下のアクションタイプを追跡します：

  • add_label - 新しいラベル選択
  • update_label - ラベル値の変更
  • delete_label - ラベルの削除
  • add_span - 新しいスパンアノテーションの作成
  • update_span - スパンアノテーションの変更
  • delete_span - スパンアノテーションの削除

設定

アノテーション履歴追跡はデフォルトで有効です。追加の設定は不要です。

パフォーマンスメトリクス

システムはアクション履歴からパフォーマンスメトリクスを計算します：

python
from potato.annotation_history import AnnotationHistoryManager
 
metrics = AnnotationHistoryManager.calculate_performance_metrics(actions)
 
# Returns:
{
    'total_actions': 150,
    'average_action_time_ms': 45.2,
    'fastest_action_time_ms': 12,
    'slowest_action_time_ms': 234,
    'actions_per_minute': 8.5,
    'total_processing_time_ms': 6780
}

不審なアクティビティの検出

システムは潜在的に問題のあるアノテーションパターンを検出できます：

python
from potato.annotation_history import AnnotationHistoryManager
 
analysis = AnnotationHistoryManager.detect_suspicious_activity(
    actions,
    fast_threshold_ms=500,      # Actions faster than this are flagged
    burst_threshold_seconds=2   # Actions closer than this are flagged
)
 
# Returns:
{
    'suspicious_actions': [...],
    'fast_actions_count': 5,
    'burst_actions_count': 12,
    'fast_actions_percentage': 3.3,
    'burst_actions_percentage': 8.0,
    'suspicious_score': 15.2,
    'suspicious_level': 'Low'
}

不審レベル

スコアレベル解釈
0-10正常通常のアノテーション行動
10-30低一部速いアクションあり、おそらく許容範囲
30-60中注目すべきパターン、レビューの必要性あり
60-80高懸念されるパターン、レビュー推奨
80-100非常に高品質問題の可能性あり、即座のレビュー

APIリファレンス

AnnotationAction

python
from potato.annotation_history import AnnotationAction
 
action = AnnotationAction(
    action_id="uuid-here",
    timestamp=datetime.now(),
    user_id="annotator1",
    instance_id="doc_001",
    action_type="add_label",
    schema_name="sentiment",
    label_name="positive",
    old_value=None,
    new_value=True
)
 
# Serialize to dictionary
data = action.to_dict()
 
# Deserialize from dictionary
action = AnnotationAction.from_dict(data)

AnnotationHistoryManager

python
from potato.annotation_history import AnnotationHistoryManager
 
# Create a new action with current timestamp
action = AnnotationHistoryManager.create_action(
    user_id="annotator1",
    instance_id="doc_001",
    action_type="add_label",
    schema_name="sentiment",
    label_name="positive",
    old_value=None,
    new_value=True
)
 
# Filter actions by time range
filtered = AnnotationHistoryManager.get_actions_by_time_range(
    actions,
    start_time=datetime(2024, 1, 1),
    end_time=datetime(2024, 1, 31)
)
 
# Filter actions by instance
instance_actions = AnnotationHistoryManager.get_actions_by_instance(
    actions, instance_id="doc_001"
)
 
# Calculate performance metrics
metrics = AnnotationHistoryManager.calculate_performance_metrics(actions)
 
# Detect suspicious activity
analysis = AnnotationHistoryManager.detect_suspicious_activity(actions)

ユースケース

品質保証

品質問題がないかアノテーターの行動を監視する：

python
for user_id in get_all_users():
    user_actions = get_user_actions(user_id)
    analysis = AnnotationHistoryManager.detect_suspicious_activity(user_actions)
 
    if analysis['suspicious_level'] in ['High', 'Very High']:
        flag_for_review(user_id, analysis)

監査証跡

規制コンプライアンスのために変更を追跡する：

python
instance_actions = AnnotationHistoryManager.get_actions_by_instance(
    all_actions, "doc_001"
)
 
audit_log = [action.to_dict() for action in instance_actions]
with open("audit_doc_001.json", "w") as f:
    json.dump(audit_log, f, indent=2)

時間分析

アノテーションのタイミングパターンを理解する：

python
from collections import Counter
 
hours = Counter(action.timestamp.hour for action in all_actions)
print("Peak annotation hours:", hours.most_common(5))

データストレージ

アノテーション履歴はユーザー状態ファイルに保存されます：

text
output/
  annotations/
    user_state_annotator1.json  # Includes action history
    user_state_annotator2.json

エクスポート形式

アクションはISO 8601タイムスタンプでシリアライズされます：

json
{
  "action_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:45.123456",
  "user_id": "annotator1",
  "instance_id": "doc_001",
  "action_type": "add_label",
  "schema_name": "sentiment",
  "label_name": "positive",
  "old_value": null,
  "new_value": true,
  "server_processing_time_ms": 23
}

ベストプラクティス

  1. 定期的な監視：不審なアクティビティレポートを定期的にチェックする
  2. 閾値の調整：タスクの複雑さに基づいて検出閾値を調整する
  3. バックアップのエクスポート：長期保存のために定期的に履歴をエクスポートする
  4. プライバシーコンプライアンス：タイムスタンプのデータ保持ポリシーを検討する

関連情報

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