Anotação de Spans

Destaque e rotule trechos de texto no Potato para NER, extração de relações e sentimento. Configure tipos de span, cores, spans sobrepostos e atalhos de teclado.

A anotação de spans permite que anotadores selecionem e rotulem partes do texto, sendo comumente usada para reconhecimento de entidades nomeadas (NER), etiquetagem morfossintática e tarefas de destaque de texto.

Interface de anotação de spans com destaque de entidades Anotação de spans com rótulos de entidades codificados por cor no Potato

Configuração Básica

yaml

annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Highlight named entities in the text"
    labels:
      - PERSON
      - ORGANIZATION
      - LOCATION

Opções de Configuração

Rótulos de Entidade

Defina os tipos de span que os anotadores podem criar:

yaml

labels:
  - PERSON
  - ORGANIZATION
  - LOCATION
  - DATE
  - EVENT

Cores

Personalize as cores para distinção visual:

yaml

colors:
  PERSON: "#3b82f6"
  ORGANIZATION: "#10b981"
  LOCATION: "#f59e0b"
  DATE: "#8b5cf6"
  EVENT: "#ec4899"

As cores podem ser em hexadecimal (#ff0000) ou RGB (rgb(255, 0, 0)).

Atalhos de Teclado

Acelere a anotação com atalhos de teclado:

yaml

keyboard_shortcuts:
  PERSON: "1"
  ORGANIZATION: "2"
  LOCATION: "3"
  DATE: "4"

Dicas de Ferramenta

Forneça orientação para cada rótulo:

yaml

tooltips:
  PERSON: "Names of people, characters, or personas"
  ORGANIZATION: "Companies, agencies, institutions"
  LOCATION: "Physical locations, addresses, geographic regions"

Spans Sobrepostos

Permitir Sobreposição

Habilite spans que podem se sobrepor:

yaml

- annotation_type: span
  name: entities
  labels:
    - PERSON
    - ROLE
  allow_overlapping: true

Isso é útil quando o mesmo texto pode ter vários rótulos (por exemplo, "Dr. Smith" é tanto uma PERSON quanto possui um ROLE).

Desabilitar Sobreposição (Padrão)

yaml

- annotation_type: span
  name: entities
  labels:
    - PERSON
    - ORGANIZATION
  allow_overlapping: false  # Default behavior

Modos de Seleção de Span

Seleção em Nível de Palavra

Selecione apenas palavras completas:

yaml

- annotation_type: span
  name: entities
  selection_mode: word
  labels:
    - ENTITY

Seleção em Nível de Caractere

Permita a seleção de palavras parciais:

yaml

- annotation_type: span
  name: entities
  selection_mode: character
  labels:
    - ENTITY

Spans Pré-Anotados

Carregue anotações existentes para revisão ou correção:

json

{
  "id": "doc1",
  "text": "John Smith works at Microsoft in Seattle.",
  "spans": [
    {"start": 0, "end": 10, "label": "PERSON"},
    {"start": 20, "end": 29, "label": "ORGANIZATION"},
    {"start": 33, "end": 40, "label": "LOCATION"}
  ]
}

Configure para carregar as pré-anotações:

yaml

- annotation_type: span
  name: entities
  load_pre_annotations: true
  pre_annotation_field: spans

Configurações Comuns de NER

NER Padrão (4 Tipos)

yaml

- annotation_type: span
  name: ner
  description: "Label named entities"
  labels:
    - PER    # Person
    - ORG    # Organization
    - LOC    # Location
    - MISC   # Miscellaneous
  colors:
    PER: "#3b82f6"
    ORG: "#10b981"
    LOC: "#f59e0b"
    MISC: "#6b7280"
  keyboard_shortcuts:
    PER: "1"
    ORG: "2"
    LOC: "3"
    MISC: "4"

NER Estendido (Estilo OntoNotes)

yaml

- annotation_type: span
  name: ner_extended
  labels:
    - PERSON
    - NORP        # Nationalities, religious/political groups
    - FAC         # Facilities
    - ORG
    - GPE         # Geopolitical entities
    - LOC
    - PRODUCT
    - EVENT
    - WORK_OF_ART
    - LAW
    - LANGUAGE
    - DATE
    - TIME
    - PERCENT
    - MONEY
    - QUANTITY
    - ORDINAL
    - CARDINAL

NER Biomédico

yaml

- annotation_type: span
  name: bio_ner
  labels:
    - GENE
    - PROTEIN
    - DISEASE
    - DRUG
    - SPECIES
  colors:
    GENE: "#22c55e"
    PROTEIN: "#3b82f6"
    DISEASE: "#ef4444"
    DRUG: "#f59e0b"
    SPECIES: "#8b5cf6"

NER de Mídias Sociais

yaml

- annotation_type: span
  name: social_ner
  labels:
    - PERSON
    - ORGANIZATION
    - LOCATION
    - PRODUCT
    - CREATIVE_WORK
    - GROUP

Span com Atributos

Adicione atributos aos spans para uma anotação mais rica:

yaml

annotation_schemes:
  - annotation_type: span
    name: entities
    labels:
      - PERSON
      - ORGANIZATION
 
  - annotation_type: radio
    name: entity_type
    description: "What type of entity is this?"
    show_for_span: entities
    labels:
      - Named
      - Nominal
      - Pronominal

Múltiplos Esquemas de Span

Anote diferentes aspectos separadamente:

yaml

annotation_schemes:
  # Named entities
  - annotation_type: span
    name: entities
    description: "Label named entities"
    labels:
      - PERSON
      - ORGANIZATION
      - LOCATION
 
  # Sentiment expressions
  - annotation_type: span
    name: sentiment_spans
    description: "Highlight sentiment expressions"
    labels:
      - POSITIVE
      - NEGATIVE
    colors:
      POSITIVE: "#22c55e"
      NEGATIVE: "#ef4444"

Anotação de Span em Múltiplos Campos

Novo na v2.1.0

A anotação de spans pode mirar campos de texto específicos em dados de múltiplos campos usando a opção target_field. Isso é útil quando seus dados contêm vários campos de texto e você deseja anotar spans em um campo específico.

Configuração

yaml

annotation_schemes:
  - annotation_type: span
    name: source_entities
    description: "Label entities in the source text"
    target_field: "source_text"
    labels:
      - PERSON
      - ORGANIZATION
 
  - annotation_type: span
    name: summary_entities
    description: "Label entities in the summary"
    target_field: "summary"
    labels:
      - PERSON
      - ORGANIZATION

Formato de Dados de Múltiplos Campos

Seus dados devem incluir os campos de texto separados:

json

{
  "id": "doc1",
  "source_text": "John Smith works at Microsoft in Seattle.",
  "summary": "Smith is employed by Microsoft."
}

Formato de Saída

Ao usar target_field, as anotações são indexadas por campo:

json

{
  "id": "doc1",
  "source_entities": {
    "source_text": [
      {"start": 0, "end": 10, "text": "John Smith", "label": "PERSON"},
      {"start": 20, "end": 29, "text": "Microsoft", "label": "ORGANIZATION"}
    ]
  },
  "summary_entities": {
    "summary": [
      {"start": 0, "end": 5, "text": "Smith", "label": "PERSON"},
      {"start": 22, "end": 31, "text": "Microsoft", "label": "ORGANIZATION"}
    ]
  }
}

Para um exemplo completo e funcional, veja project-hub/simple_examples/simple-multi-span/ no repositório do Potato.

Opções de Exibição

Mostrar Rótulo no Span

Exiba o texto do rótulo dentro dos spans destacados:

yaml

- annotation_type: span
  name: entities
  show_label_in_span: true

Estilo de Sublinhado

Use sublinhados em vez de destaque de fundo:

yaml

- annotation_type: span
  name: entities
  display_style: underline

Formato de Saída

As anotações de span são salvas com deslocamentos de caractere:

json

{
  "id": "doc1",
  "entities": [
    {
      "start": 0,
      "end": 10,
      "text": "John Smith",
      "label": "PERSON"
    },
    {
      "start": 20,
      "end": 29,
      "text": "Microsoft",
      "label": "ORGANIZATION"
    }
  ]
}

Exemplo Completo: Tarefa de NER

yaml

annotation_task_name: "Named Entity Recognition"
 
data_files:
  - path: data/documents.json
    text_field: text
 
annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Highlight and label all named entities"
    labels:
      - PERSON
      - ORGANIZATION
      - LOCATION
      - DATE
      - MONEY
    colors:
      PERSON: "#3b82f6"
      ORGANIZATION: "#10b981"
      LOCATION: "#f59e0b"
      DATE: "#8b5cf6"
      MONEY: "#ec4899"
    keyboard_shortcuts:
      PERSON: "1"
      ORGANIZATION: "2"
      LOCATION: "3"
      DATE: "4"
      MONEY: "5"
    tooltips:
      PERSON: "Names of people"
      ORGANIZATION: "Companies, agencies, institutions"
      LOCATION: "Cities, countries, addresses"
      DATE: "Dates and time expressions"
      MONEY: "Monetary values"
    allow_overlapping: false
    selection_mode: word
 
  - annotation_type: radio
    name: difficulty
    description: "How difficult was this document to annotate?"
    labels:
      - Easy
      - Medium
      - Hard

Spans Descontínuos

Novo na v2.2.0

Habilite spans de texto não contíguos com o parâmetro allow_discontinuous. Isso permite que os anotadores selecionem múltiplos segmentos de texto não adjacentes como uma única anotação de span, útil para entidades descontínuas ou expressões divididas.

yaml

- annotation_type: span
  name: entities
  labels:
    - PERSON
    - ORGANIZATION
  allow_discontinuous: true

Quando habilitado, os anotadores podem manter uma tecla modificadora pressionada enquanto selecionam segmentos de texto adicionais para incluí-los no span atual. A saída inclui múltiplos pares de início/fim para cada segmento.

Integração com Vinculação de Entidades

Novo na v2.2.0

As anotações de span podem ser vinculadas a bases de conhecimento externas (Wikidata, UMLS ou APIs REST personalizadas) adicionando um bloco de configuração entity_linking ao esquema de span:

yaml

- annotation_type: span
  name: entities
  labels:
    - PERSON
    - ORGANIZATION
    - LOCATION
  entity_linking:
    enabled: true
    knowledge_bases:
      - name: wikidata
        type: wikidata
        language: en

Quando a vinculação de entidades está habilitada, um ícone de link aparece na barra de controle de cada span. Clicar nele abre uma janela de busca para encontrar e vincular entidades correspondentes da base de conhecimento. Veja a documentação de Vinculação de Entidades para todos os detalhes.

Boas Práticas

Use cores distintas para uma diferenciação visual fácil
Forneça dicas de ferramenta claras com exemplos para cada tipo de entidade
Habilite atalhos de teclado para uma anotação mais rápida
Use seleção em nível de palavra a menos que precise de precisão de caractere
Considere a pré-anotação para fluxos de correção mais rápidos
Teste as configurações de sobreposição com base nas suas diretrizes de anotação

Leitura Complementar

Vinculação de Entidades - Vincule spans a bases de conhecimento
Cadeias de Correferência - Agrupe menções correferentes
Anotação de Eventos - Estruturas de eventos n-árias com argumentos de span
Vinculação de Spans - Crie relacionamentos entre spans
Exibição de Instância - Exibição de conteúdo de múltiplos campos com alvos de span
Configuração da Interface - Personalize as cores dos spans
Recursos de Produtividade - Atalhos de teclado

Para detalhes de implementação, veja a documentação de origem.