Vinculação de Entidades

Vincule anotações de segmento no Potato a bases de conhecimento externas — Wikidata, UMLS ou APIs de entidades personalizadas — com busca por typeahead e pontuações de confiança configuráveis.

A vinculação de entidades permite que os anotadores conectem anotações de segmento a bases de conhecimento externas (KBs) como Wikidata ou UMLS. Isso cria vínculos semânticos entre menções no texto e entidades canônicas, o que é valioso para reconhecimento de entidades nomeadas, normalização de conceitos e construção de grafos de conhecimento.

Como Funciona

Quando a vinculação de entidades está ativada para um esquema de anotação de segmentos:

Os anotadores destacam o texto e atribuem um rótulo (por exemplo, "PERSON", "ORGANIZATION")
Um ícone de vínculo aparece na barra de controle do segmento
Clicar no ícone abre uma janela de busca para encontrar entidades correspondentes na KB
O ID da entidade selecionada é armazenado junto com a anotação do segmento
Segmentos vinculados exibem um ícone preenchido e mostram detalhes da entidade ao passar o cursor

Início Rápido

Ative a vinculação de entidades adicionando a configuração entity_linking a um esquema de segmentos:

yaml

annotation_schemes:
  - annotation_type: span
    name: ner
    description: Named Entity Recognition with KB linking
    labels:
      - name: PERSON
        tooltip: "People's names"
      - name: ORGANIZATION
        tooltip: "Companies, agencies, institutions"
      - name: LOCATION
        tooltip: "Places, cities, countries"
    entity_linking:
      enabled: true
      knowledge_bases:
        - name: wikidata
          type: wikidata
          language: en

Opções de Configuração

Opção	Tipo	Padrão	Descrição
`enabled`	boolean	`false`	Ativa a vinculação de entidades para este esquema
`knowledge_bases`	list	`[]`	Lista de configurações de KB
`auto_search`	boolean	`true`	Busca automaticamente quando a janela abre
`required`	boolean	`false`	Exige o vínculo da entidade antes de salvar o segmento
`multi_select`	boolean	`false`	Permite vincular a várias entidades

Configuração da Base de Conhecimento

Opção	Tipo	Padrão	Descrição
`name`	string	obrigatório	Identificador único desta KB
`type`	string	obrigatório	Tipo de KB: `wikidata`, `umls` ou `rest`
`api_key`	string	`null`	Chave de API para serviços autenticados
`base_url`	string	`null`	URL base para APIs REST
`language`	string	`"en"`	Código do idioma para os resultados da busca
`timeout`	integer	`10`	Tempo limite da requisição em segundos

Bases de Conhecimento Suportadas

Wikidata

Base de conhecimento gratuita e aberta com mais de 100 milhões de entidades. Não requer chave de API.

yaml

entity_linking:
  enabled: true
  knowledge_bases:
    - name: wikidata
      type: wikidata
      language: en

Oferece rótulos multilíngues, apelidos de entidades (por exemplo, "NYC" encontra "New York City") e links para artigos da Wikipédia.

UMLS

Terminologia médica e biomédica abrangente. Requer uma chave de API gratuita do UTS.

yaml

entity_linking:
  enabled: true
  knowledge_bases:
    - name: umls
      type: umls
      api_key: ${UMLS_API_KEY}

Inclui conceitos médicos, medicamentos, doenças, procedimentos e referências cruzadas a mais de 200 vocabulários de origem (SNOMED CT, ICD-10, MeSH, RxNorm).

APIs REST Personalizadas

Conecte-se a qualquer base de conhecimento que tenha uma API REST:

yaml

entity_linking:
  enabled: true
  knowledge_bases:
    - name: internal_kb
      type: rest
      base_url: https://api.example.com
      api_key: optional_api_key
      extra_params:
        search_endpoint: /search
        entity_endpoint: /entity/{entity_id}
        search_query_param: q
        results_path: data.results
        entity_id_field: id
        label_field: name
        description_field: description

Múltiplas Bases de Conhecimento

Configure várias KBs para permitir que os anotadores escolham a fonte mais apropriada:

yaml

entity_linking:
  enabled: true
  knowledge_bases:
    - name: wikidata
      type: wikidata
      language: en
    - name: umls
      type: umls
      api_key: ${UMLS_API_KEY}
    - name: company_entities
      type: rest
      base_url: https://internal.company.com/api/entities

Um menu suspenso na janela de busca permite que os anotadores alternem entre as bases de conhecimento configuradas.

Modo de Seleção Múltipla

Ative a seleção múltipla para permitir vincular um segmento a várias entidades, o que é útil para menções ambíguas:

yaml

entity_linking:
  enabled: true
  multi_select: true
  knowledge_bases:
    - name: wikidata
      type: wikidata
      language: en

Formato dos Dados

Segmentos com entidades vinculadas incluem campos adicionais na saída:

json

{
  "id": "instance_001",
  "text": "Albert Einstein was born in Ulm, Germany in 1879.",
  "annotations": {
    "ner": {
      "spans": [
        {
          "text": "Albert Einstein",
          "start": 0,
          "end": 15,
          "label": "PERSON",
          "kb_id": "Q937",
          "kb_source": "wikidata",
          "kb_label": "Albert Einstein"
        },
        {
          "text": "Ulm",
          "start": 28,
          "end": 31,
          "label": "LOCATION",
          "kb_id": "Q3012",
          "kb_source": "wikidata",
          "kb_label": "Ulm"
        }
      ]
    }
  }
}

Boas Práticas

Ative a busca automática para maior eficiência - pré-preenche a busca com o texto do segmento
Não exija o vínculo a menos que seja essencial - não bloqueie a anotação se a entidade não for encontrada
Defina tempos limite adequados para redes lentas
Combine a KB com o tipo de entidade - use Wikidata para entidades gerais, UMLS para termos biomédicos e APIs personalizadas para entidades de domínio específico
Use a seleção múltipla para menções ambíguas - abreviações, nomes comuns, termos polissêmicos

Leitura Complementar

Anotação de Segmentos - Configuração básica da anotação de segmentos
Cadeias de Correferência - Agrupamento de menções de entidades
Anotação de Eventos - Estruturas de eventos n-árias

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