هذه الصفحة غير متوفرة بلغتك بعد. يتم عرض النسخة الإنجليزية.

Annotazione di eventi

Crea strutture di eventi N-ari con trigger e argomenti tipizzati per l'estrazione di informazioni.

Annotazione di eventi

L'annotazione di eventi consente la creazione di strutture di eventi N-ari per compiti di estrazione di informazioni. Gli eventi sono composti da uno span trigger (la parola o frase che indica l'evento) e dagli span degli argomenti (span di entità con ruoli semantici tipizzati).

Questo tipo di annotazione è comunemente usato per l'estrazione di informazioni, il rilevamento di eventi, l'etichettatura dei ruoli semantici e la costruzione di grafi di conoscenza.

Configurazione di base

L'annotazione di eventi richiede prima uno schema di annotazione span definito, che fornisce gli span di entità usati come trigger e argomenti.

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

Opzioni di configurazione

Tipi di eventi

Ogni tipo di evento definisce:

Proprietà	Tipo	Obbligatorio	Descrizione
`type`	string	Sì	Nome del tipo di evento (ad es., "ATTACK", "HIRE")
`color`	string	No	Colore per la visualizzazione (predefinito: assegnato automaticamente)
`trigger_labels`	list	No	Etichette span consentite come trigger (vuoto = qualsiasi span)
`arguments`	list	Sì	Elenco delle definizioni degli argomenti

Argomenti

Ogni argomento definisce:

Proprietà	Tipo	Obbligatorio	Descrizione
`role`	string	Sì	Nome del ruolo semantico (ad es., "attacker", "target")
`entity_types`	list	No	Etichette span consentite per questo ruolo (vuoto = qualsiasi span)
`required`	boolean	No	Se questo argomento deve essere compilato (predefinito: false)

Visualizzazione

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)

Flusso di lavoro

Crea span di entità: Annota gli span di entità usando lo strumento di annotazione span (fai clic e trascina per selezionare il testo, poi scegli un'etichetta)
Seleziona il tipo di evento: Fai clic su un pulsante del tipo di evento (ad es., "ATTACK") per entrare in modalità creazione evento
Seleziona il trigger: Fai clic su uno span per impostarlo come trigger dell'evento. Se è configurato trigger_labels, possono essere selezionati solo span con etichette corrispondenti
Assegna gli argomenti: Per ogni ruolo degli argomenti, fai clic sul pulsante del ruolo per attivarlo, poi fai clic su uno span per assegnarlo. Gli argomenti obbligatori devono essere compilati prima che l'evento possa essere creato
Crea evento: Una volta compilati tutti gli argomenti obbligatori, fai clic su "Crea evento" per salvare
Visualizza eventi: Gli eventi creati appaiono nella sezione "Eventi esistenti" con i loro trigger e argomenti elencati

Formato dei dati

Input

L'annotazione di eventi funziona con qualsiasi formato di dati basato su testo:

json

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

Output

Gli eventi vengono memorizzati con la seguente struttura:

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"
      }
    }
  ]
}

Visualizzazione ad arco

La visualizzazione ad arco mostra:

Un hub (cerchio pieno) nella posizione del trigger
Raggi (frecce) che collegano a ogni argomento
Etichette di ruolo su ogni raggio
Gli eventi sono codificati a colori per tipo

Più eventi vengono impilati verticalmente per evitare sovrapposizioni.

Esempio completo

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

Buone pratiche

Usa nomi di tipo descrittivi - Scegli nomi di tipo di evento chiari e non ambigui che riflettano il significato semantico
Vincola i trigger in modo appropriato - Usa trigger_labels per limitare quali span possono essere trigger. Per eventi basati su verbi, crea un'etichetta dedicata "EVENT_TRIGGER"
Bilancia argomenti obbligatori e facoltativi - Contrassegna gli argomenti principali come obbligatori, ma consenti argomenti facoltativi per il contesto che potrebbe non essere sempre presente
Usa i vincoli sui tipi di entità - Applica vincoli semantici sugli argomenti (ad es., un "attaccante" dovrebbe essere una PERSON o un'ORGANIZATION)

Ulteriori letture

Annotazione Span - Necessaria per definire gli span di entità
Span Linking - Alternativa per relazioni binarie
Catene di coreferenza - Per la coreferenza delle entità

Per i dettagli di implementazione, consulta la documentazione sorgente.