이벤트 주석

정보 추출 및 ACE 스타일 이벤트 탐지 작업을 위해 이벤트 트리거, 유형이 지정된 인자, 엔티티 역할을 사용하여 Potato에서 N항 이벤트 구조를 주석합니다.

이벤트 주석을 사용하면 정보 추출 작업을 위한 N항 이벤트 구조를 만들 수 있습니다. 이벤트는 트리거 스팬(이벤트를 나타내는 단어 또는 구)과 인자 스팬(유형이 지정된 의미 역할을 가진 엔티티 스팬)으로 구성됩니다.

이 주석 유형은 정보 추출, 이벤트 탐지, 의미역 결정, 지식 그래프 구축에서 자주 사용됩니다.

기본 설정

이벤트 주석을 사용하려면 먼저 스팬 주석 스키마를 정의해야 하며, 이 스키마가 트리거와 인자로 사용되는 엔티티 스팬을 제공합니다.

yaml

annotation_schemes:
  # Step 1: Define entity spans
  - annotation_type: span
    name: entities
    description: "Label entities in the text"
    labels:
      - name: PERSON
        color: "#3b82f6"
      - name: ORGANIZATION
        color: "#10b981"
      - name: LOCATION
        color: "#f59e0b"
      - name: WEAPON
        color: "#ef4444"
      - name: EVENT_TRIGGER
        color: "#8b5cf6"
        tooltip: "Words indicating events"
 
  # Step 2: Define event types and arguments
  - annotation_type: event_annotation
    name: events
    description: "Annotate events with triggers and arguments"
    span_schema: entities
    event_types:
      - type: "ATTACK"
        color: "#dc2626"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "attacker"
            entity_types: ["PERSON", "ORGANIZATION"]
            required: true
          - role: "target"
            entity_types: ["PERSON", "ORGANIZATION", "LOCATION"]
            required: true
          - role: "weapon"
            entity_types: ["WEAPON"]
            required: false

설정 옵션

이벤트 유형

각 이벤트 유형은 다음을 정의합니다.

속성	유형	필수	설명
`type`	string	예	이벤트 유형 이름(예: "ATTACK", "HIRE")
`color`	string	아니요	시각화에 사용할 색상(기본값: 자동 할당)
`trigger_labels`	list	아니요	트리거로 허용되는 스팬 레이블(비어 있으면 모든 스팬)
`arguments`	list	예	인자 정의 목록

인자

각 인자는 다음을 정의합니다.

속성	유형	필수	설명
`role`	string	예	의미 역할 이름(예: "attacker", "target")
`entity_types`	list	아니요	이 역할에 허용되는 스팬 레이블(비어 있으면 모든 스팬)
`required`	boolean	아니요	이 인자를 반드시 채워야 하는지 여부(기본값: false)

시각적 표시

yaml

visual_display:
  enabled: true           # Show arc visualization (default: true)
  arc_position: above     # Position of arcs: "above" (default)
  show_labels: true       # Show role labels on arcs (default: true)

작업 흐름

엔티티 스팬 생성: 스팬 주석 도구를 사용하여 엔티티 스팬을 주석합니다(클릭하고 드래그하여 텍스트를 선택한 다음 레이블을 선택)
이벤트 유형 선택: 이벤트 유형 버튼(예: "ATTACK")을 클릭하여 이벤트 생성 모드로 진입합니다
트리거 선택: 스팬을 클릭하여 이벤트 트리거로 설정합니다. trigger_labels가 설정되어 있으면 일치하는 레이블을 가진 스팬만 선택할 수 있습니다
인자 할당: 각 인자 역할에 대해 역할 버튼을 클릭하여 활성화한 다음 스팬을 클릭하여 할당합니다. 이벤트를 생성하기 전에 필수 인자를 반드시 채워야 합니다
이벤트 생성: 모든 필수 인자가 채워지면 "Create Event"를 클릭하여 저장합니다
이벤트 보기: 생성된 이벤트는 트리거와 인자가 나열된 "Existing Events" 섹션에 표시됩니다

데이터 형식

입력

이벤트 주석은 텍스트 기반의 모든 데이터 형식에서 작동합니다.

json

[
  {
    "id": "event_1",
    "text": "John attacked the building with a rifle."
  }
]

출력

이벤트는 다음 구조로 저장됩니다.

json

{
  "event_annotations": [
    {
      "id": "event_abc123",
      "schema": "events",
      "event_type": "ATTACK",
      "trigger_span_id": "span_xyz789",
      "arguments": [
        {"role": "attacker", "span_id": "span_def456"},
        {"role": "target", "span_id": "span_ghi012"},
        {"role": "weapon", "span_id": "span_jkl345"}
      ],
      "properties": {
        "color": "#dc2626",
        "trigger_text": "attacked",
        "trigger_label": "EVENT_TRIGGER"
      }
    }
  ]
}

시각적 표시

아크 시각화는 다음을 보여줍니다.

트리거 위치의 허브(채워진 원)
각 인자로 연결되는 스포크(화살표)
각 스포크의 역할 레이블
이벤트는 유형별로 색상이 지정됩니다

여러 이벤트는 겹침을 피하기 위해 수직으로 쌓입니다.

전체 예시

yaml

annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Label entities in the text"
    labels:
      - name: PERSON
        color: "#3b82f6"
      - name: ORGANIZATION
        color: "#10b981"
      - name: LOCATION
        color: "#f59e0b"
      - name: WEAPON
        color: "#ef4444"
      - name: EVENT_TRIGGER
        color: "#8b5cf6"
 
  - annotation_type: event_annotation
    name: events
    description: "Annotate events"
    span_schema: entities
    event_types:
      - type: "ATTACK"
        color: "#dc2626"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "attacker"
            entity_types: ["PERSON", "ORGANIZATION"]
            required: true
          - role: "target"
            entity_types: ["PERSON", "ORGANIZATION", "LOCATION"]
            required: true
          - role: "weapon"
            entity_types: ["WEAPON"]
            required: false
 
      - type: "HIRE"
        color: "#2563eb"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "employer"
            entity_types: ["ORGANIZATION"]
            required: true
          - role: "employee"
            entity_types: ["PERSON"]
            required: true
 
      - type: "TRAVEL"
        color: "#059669"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "traveler"
            entity_types: ["PERSON"]
            required: true
          - role: "destination"
            entity_types: ["LOCATION"]
            required: true
          - role: "origin"
            entity_types: ["LOCATION"]
            required: false

모범 사례

설명적인 유형 이름 사용 - 의미를 반영하는 명확하고 모호하지 않은 이벤트 유형 이름을 선택합니다
트리거를 적절히 제한 - trigger_labels를 사용하여 어떤 스팬이 트리거가 될 수 있는지 제한합니다. 동사 기반 이벤트의 경우 전용 "EVENT_TRIGGER" 레이블을 만듭니다
필수 인자와 선택 인자의 균형 - 핵심 인자는 필수로 표시하되, 항상 존재하지는 않을 수 있는 맥락에는 선택 인자를 허용합니다
엔티티 유형 제약 사용 - 인자에 의미적 제약을 적용합니다(예: "attacker"는 PERSON 또는 ORGANIZATION이어야 함)

더 읽어보기

스팬 주석 - 엔티티 스팬을 정의하는 데 필요합니다
스팬 연결 - 이항 관계를 위한 대안입니다
상호참조 체인 - 엔티티 상호참조를 위한 것입니다

구현 세부 사항은 원본 문서를 참조하세요.