Skip to content

주석 기록

Potato에서 모든 주석 작업을 타임스탬프, 주석자 ID, 버전 기록과 함께 추적하여 전체 감사 추적, 실행 취소 지원, 변경 감지를 가능하게 합니다.

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. 개인정보 보호 준수: 타임스탬프에 대한 데이터 보존 정책을 고려합니다

더 읽어보기

구현 세부 사항은 원본 문서를 참고하십시오.