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. 隱私合規：考慮時間戳的資料保留政策

延伸閱讀

有關實現細節，請參閱原始碼文件。