Vinculação de Spans

Novo na v2.1.0

A vinculação de spans permite que os anotadores criem relacionamentos tipados entre spans (segmentos de texto) que já foram anotados. Isso é útil para tarefas de extração de relações em que você precisa identificar como as entidades se relacionam entre si, como "PERSON works_for ORGANIZATION" ou "PERSON collaborates_with PERSON".

Visão Geral

O recurso de vinculação de spans oferece:

• Relacionamentos tipados: defina vários tipos de link com cores e restrições diferentes
• Links direcionados e não direcionados: suporte para relacionamentos tanto direcionais quanto simétricos
• Links n-ários: crie links entre vários spans (não apenas pares)
• Exibição visual de arcos: veja os relacionamentos renderizados como arcos coloridos acima do texto
• Restrições de rótulo: restrinja quais rótulos de span podem ser origens ou destinos

Configuração

Para usar a vinculação de spans, você precisa de dois esquemas de anotação:

1. Um esquema span para anotar as entidades
2. Um esquema span_link para anotar os relacionamentos

annotation_schemes:
  # First, define the span schema for named entities
  - annotation_type: span
    name: entities
    description: "Highlight named entities"
    labels:
      - name: "PERSON"
        color: "#3b82f6"
      - name: "ORGANIZATION"
        color: "#22c55e"
      - name: "LOCATION"
        color: "#f59e0b"
    sequential_key_binding: true
 
  # Then, define the span_link schema for relationships
  - annotation_type: span_link
    name: relations
    description: "Annotate relationships between entities"
    span_schema: entities  # References the span schema above
    link_types:
      - name: "WORKS_FOR"
        directed: true
        allowed_source_labels: ["PERSON"]
        allowed_target_labels: ["ORGANIZATION"]
        color: "#dc2626"
      - name: "COLLABORATES_WITH"
        directed: false
        allowed_source_labels: ["PERSON"]
        allowed_target_labels: ["PERSON"]
        color: "#06b6d4"

Opções de Configuração

Campos Obrigatórios

Opções de Tipo de Link

Opções de Exibição Visual

visual_display:
  enabled: true        # Show arc visualization
  arc_position: "above"  # Position of arcs
  show_labels: true    # Show link type labels on arcs

Uso

Criando Spans

1. Primeiro, anote o texto selecionando rótulos de span e destacando o texto
2. Cada span destacado fica disponível para vinculação

Criando Links

1. Selecione um tipo de link entre as opções disponíveis
2. Clique nos spans para adicioná-los ao link atual (os spans selecionados são destacados)
3. Clique em "Create Link" para finalizar o link
4. Para links direcionados, o primeiro span selecionado é a origem e o último é o destino

Visualizando Links

• Os links criados aparecem na seção "Existing Links"
• Se a exibição visual estiver habilitada, arcos são desenhados acima do texto conectando os spans vinculados
• Os arcos são codificados por cor de acordo com o tipo de link

Excluindo Links

• Clique no botão de exclusão (x) ao lado de qualquer link na seção "Existing Links"

Formato de Dados

Dados de Entrada

Dados de texto padrão com um campo de ID e de texto:

[
  {
    "id": "item_1",
    "text": "John Smith works at Google as a senior engineer."
  }
]

Formato de Saída

As anotações incluem tanto anotações de span quanto anotações de link:

{
  "id": "item_1",
  "text": "John Smith works at Google as a senior engineer.",
  "entities": [
    {"start": 0, "end": 10, "label": "PERSON", "text": "John Smith"},
    {"start": 20, "end": 26, "label": "ORGANIZATION", "text": "Google"}
  ],
  "relations": [
    {
      "link_type": "WORKS_FOR",
      "span_ids": ["span_abc123", "span_def456"],
      "direction": "directed"
    }
  ]
}

Restrições de Rótulo

Restrinja quais rótulos de span podem participar de cada tipo de link:

link_types:
  - name: "WORKS_FOR"
    directed: true
    allowed_source_labels: ["PERSON"]      # Only PERSON can be source
    allowed_target_labels: ["ORGANIZATION"]  # Only ORGANIZATION can be target

Quando as restrições são violadas, a interface mostra uma mensagem de erro e impede a criação do link.

Links N-ários

Por padrão, os links conectam exatamente 2 spans. Para relacionamentos que envolvem mais entidades:

link_types:
  - name: "MEETING"
    directed: false
    max_spans: 5  # Allow up to 5 participants
    allowed_source_labels: ["PERSON"]
    allowed_target_labels: ["PERSON"]

Exemplo

Veja o exemplo completo e funcional em:

• Configuração: project-hub/simple_examples/simple-span-linking/config.yaml
• Dados: project-hub/simple_examples/simple-span-linking/data.json

Para executar:

cd project-hub/simple_examples
python ../../potato/flask_server.py start simple-span-linking/config.yaml -p 9001

Dicas

1. Anote os spans primeiro: certifique-se de criar as anotações de span antes de tentar vinculá-las
2. Use as cores com eficácia: escolha cores distintas para diferentes tipos de link
3. Considere a direção: use links direcionados quando o relacionamento tiver uma direção clara
4. Atalhos de teclado: os rótulos de span suportam atalhos de teclado (1, 2, 3...) para uma anotação mais rápida

Leitura Complementar

• Anotação de Spans - Anotação básica de spans
• Configuração da Interface - Personalize cores e exibição

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