Skip to content

イベントアノテーション

情報抽出のためのトリガーと型付き引数を持つ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

設定オプション

イベントタイプ

各イベントタイプで定義するもの：

プロパティタイプ必須説明
typestringはいイベントタイプ名（例："ATTACK"、"HIRE"）
colorstringいいえ可視化用のカラー（デフォルト：自動割り当て）
trigger_labelslistいいえトリガーとして許可されるスパンラベル（空 = 任意のスパン）
argumentslistはい引数定義のリスト

引数

各引数で定義するもの：

プロパティタイプ必須説明
rolestringはいセマンティックロール名（例："attacker"、"target"）
entity_typeslistいいえこのロールに許可されるスパンラベル（空 = 任意のスパン）
requiredbooleanいいえこの引数の入力が必須かどうか（デフォルト：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)

使用ワークフロー

  1. エンティティスパンを作成: スパンアノテーションツールでエンティティスパンをアノテーション（クリックしてドラッグでテキストを選択し、ラベルを選択）
  2. イベントタイプを選択: イベントタイプボタン（例："ATTACK"）をクリックしてイベント作成モードに入る
  3. トリガーを選択: スパンをクリックしてイベントトリガーとして設定。trigger_labelsが設定されている場合、一致するラベルのスパンのみ選択可能
  4. 引数を割り当て: 各引数ロールについて、ロールボタンをクリックしてアクティブにし、スパンをクリックして割り当て。必須引数はイベント作成前に入力必須
  5. イベントを作成: すべての必須引数が入力されたら、「イベントを作成」をクリックして保存
  6. イベントを表示: 作成されたイベントは「既存のイベント」セクションにトリガーと引数のリストとともに表示

データ形式

入力

イベントアノテーションはテキストベースのデータ形式で動作：

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

ベストプラクティス

  1. 説明的なタイプ名を使用 - セマンティックな意味を反映する明確で曖昧のないイベントタイプ名を選択
  2. トリガーを適切に制約 - trigger_labelsを使用してどのスパンがトリガーになれるかを制限。動詞ベースのイベントには専用の"EVENT_TRIGGER"ラベルを作成
  3. 必須と任意の引数のバランス - コア引数は必須にし、常に存在するとは限らないコンテキスト用にオプションの引数を許可
  4. エンティティタイプ制約を使用 - 引数にセマンティック制約を適用（例："attacker"はPERSONまたはORGANIZATIONであるべき）

関連資料

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