Legal BERT NER Base Cased PT-BR: entidades em textos jurídicos brasileiros

Localizar automaticamente pessoas, normas e outras entidades em documentos jurídicos motivou este ajuste fino. Publiquei dominguesm/legal-bert-ner-base-cased-ptbr, um BertForTokenClassification sensível a maiúsculas e minúsculas, para reconhecer seis tipos de entidade. A contribuição é a adaptação do encoder ao NER jurídico; ele não interpreta efeitos legais, vigência de normas ou aplicabilidade de citações [1].

Publiquei pesos, tokenizer, configuração, argumentos serializados e eventos TensorBoard. Não disponibilizo o corpus anotado, as predições individualizadas, os scripts vinculados à base nem artefatos que possam expor ou permitir reconstruir informações de processos. Esses materiais estão sujeitos ao Termo de Compromisso do projeto VICTOR [1, 14].

Ficha técnica

O caminho conceitual começa no BERT, encoder Transformer pré-treinado de forma bidirecional e adaptável a tarefas supervisionadas com uma pequena cabeça de saída [2]. Para português brasileiro, o BERTimbau Base preserva a geometria BERT-base e fornece um vocabulário cased de 29.794 itens [3]. Eu continuei esse modelo com linguagem mascarada em textos jurídicos para criar o Legal BERT e, no NER, substituí a cabeça MLM por uma projeção de 768 dimensões para 13 logits por posição [1, 4].

No NER, usei um vocabulário de 29.794 itens. Depois, atualizei o Legal BERT Base para um vocabulário de 52.000 itens. Por isso, a versão atual do modelo-base não reconstitui automaticamente o ponto de partida desse ajuste [4]. Para inferência NER, publiquei pesos e tokenizer compatíveis juntos; para reproduzir o treino, é necessário usar a edição anterior.

Ontologia: o que cada rótulo representa

Associei os IDs a O, B-* e I-* para seis categorias [1]:

Essas glosas ajudam a leitura, mas não posso disponibilizar o guia operacional, os exemplos anotados ou outros artefatos vinculados ao corpus quando eles puderem expor informações restritas [14]. Casos limítrofes permanecem: um tribunal pode ser ORGANIZACAO, enquanto o nome de um julgado é JURISPRUDENCIA; “Constituição Federal” pode ser o título de uma norma, mas “constitucional” isolado não é necessariamente entidade. Também não há rótulos para valores monetários, números processuais como categoria própria, cargos, eventos, contratos ou dados sensíveis.

Inspirei os rótulos no LeNER-Br, mas não usei essa atribuição para identificar o corpus de treinamento [1]. O LeNER-Br reuniu 70 documentos manualmente anotados: 66 textos de casos de tribunais superiores e estaduais e quatro documentos legislativos. O artigo introduziu justamente as categorias específicas de legislação e casos jurídicos, além de pessoa, organização, local e tempo [5]. No espelho Hugging Face, a conversão contém 7.828 sequências de treino, 1.177 de validação e 1.390 de teste, com a mesma lista de 13 rótulos [6]. Esses são splits do LeNER-Br, não os splits que publiquei para este modelo.

Proveniência e divisões do treinamento NER

No ajuste NER, usei 971.932 exemplos de treino, 53.996 de validação e 53.997 de teste. Recebi os dados do Supremo Tribunal Federal (STF) por intermédio do AI.Lab da Universidade de Brasília, sob o Termo de Compromisso vinculado ao VICTOR/LREC 2020 [1, 14]. Assumi a obrigação de preservar sigilo e privacidade, impedir acesso ou transferência a terceiros não autorizados, proteger a mídia e não divulgar nomes ou variáveis identificáveis. As elaborações e conclusões são de minha responsabilidade e podem não refletir a posição do STF. O artigo VICTOR descreve 45.532 Recursos Extraordinários, 692.966 documentos e cerca de 4,6 milhões de páginas digitalizadas, com tarefas de classificação documental e de temas [7].

Não posso disponibilizar a unidade individual dos exemplos, a anotação, a distribuição temporal, os critérios aplicados a cada documento, a deduplicação, a composição das divisões ou qualquer manifesto que permita reconstituir informações da base restrita [14]. O VICTOR original separou recursos em 70%/15%/15% para suas próprias tarefas [7], enquanto usei outra partição no NER. Sem expor os processos que compõem cada split, não consigo oferecer uma verificação pública de vazamento de menções ou peças correlatas.

BIO, WordPiece e alinhamento de subtokens

BIO transforma spans em classificação sequencial. B-X inicia uma entidade do tipo X, I-X continua a mesma entidade e O marca texto externo. Em “Ministério Público do Trabalho”, por exemplo, a sequência esperada pode ser B-ORGANIZACAO I-ORGANIZACAO I-ORGANIZACAO I-ORGANIZACAO. A codificação deriva do uso de rótulos de fronteira para chunking [8] e foi consolidada em avaliações de NER como a CoNLL-2003 [9]. Ela representa spans contíguos e não sobrepostos; entidades aninhadas ou descontínuas não cabem em uma única sequência BIO.

O tokenizer introduz outro nível. Uma palavra pode virar vários WordPieces, mas o corpus normalmente possui um rótulo por palavra. É preciso definir o alinhamento. A recomendação documentada pelo Transformers é rotular apenas o primeiro subtoken e usar -100 nos especiais e subtokens restantes, para que CrossEntropyLoss os ignore [10]. Outra política possível replica rótulos, convertendo a continuação de um B-X em I-X; ela aumenta a supervisão, mas também dá mais peso a palavras muito fragmentadas. O script vinculado à base não pode ser distribuído; por isso, não ofereço essa implementação como parte do material público [14].

Uma implementação explícita para novos ajustes, sem alegar que reproduz o treino original, é:

def tokenize_and_align_labels(batch, tokenizer):
    encoded = tokenizer(
        batch["tokens"],
        is_split_into_words=True,
        truncation=True,
        max_length=512,
    )
    aligned = []
    for row, word_labels in enumerate(batch["ner_tags"]):
        previous = None
        label_ids = []
        for word_id in encoded.word_ids(batch_index=row):
            if word_id is None or word_id == previous:
                label_ids.append(-100)
            else:
                label_ids.append(word_labels[word_id])
            previous = word_id
        aligned.append(label_ids)
    encoded["labels"] = aligned
    return encoded

Truncar em 512 posições pode cortar uma entidade no limite. Um experimento reproduzível deve documentar segmentação, sobreposição de janelas, tratamento do primeiro rótulo da janela seguinte e reconstrução dos offsets no documento original.

Ajuste fino publicado

Treinei com a seguinte configuração, também preservada em training_args.bin [1]:

Usei adamw_hf, nome do otimizador no Transformers da época, e o descrevi genericamente como torch.optim.AdamW na README. Na publicação inicial, não registrei hardware, versão fechada do ambiente, estado do otimizador ou checkpoints intermediários. Não posso distribuir o código do collator e a política de subtokens quando vinculados à base restrita [14]. A cabeça linear e o encoder são ajustados por entropia cruzada nas posições não ignoradas. Como não conduzi baseline controlado com BERTimbau nem ablação sem adaptação jurídica, o F1 final não mede isoladamente o benefício do Legal BERT Base.

Avaliação por token e por span

Para spans, um verdadeiro positivo exige tipo e limites corretos; um span apenas parcialmente sobreposto gera um falso positivo e um falso negativo no critério estrito. Com TP, FP e FN:

Já a acurácia por token conta também a classe O, normalmente abundante. Um modelo pode acertar quase todos os tokens externos e ainda errar fronteiras importantes; por isso, 98,9474% de acurácia não equivale a 98,9474% de entidades corretas. O seqeval, comum nesse fluxo, retorna métricas por tipo e globais e oferece modo estrito com esquema IOB2 explícito [11]. Não posso disponibilizar a chamada vinculada às predições restritas; no material público, não preservei modo, versão nem reparo de sequências BIO inválidas [14].

No último ponto de validação publicado, passo 22.000, constam precisão 0,943868, revocação 0,961418, F1 0,952562, acurácia 0,989425 e perda 0,030162. Esses são os números promovidos no model-index. Separadamente, o cartão publica para o teste de 53.997 exemplos: precisão 0,943240, revocação 0,961433, F1 0,952250 e acurácia 0,989474 [1].

Uma recomputação concreta pode recuperar contagens inteiras de JURISPRUDENCIA a partir do suporte e dos decimais publicados:

Isso confirma a coerência interna da linha, não a avaliação inteira. JURISPRUDENCIA tem o menor F1 e 7.084 falsos positivos reconstruídos, mais que os 5.509 falsos negativos; LOCAL vem em seguida. Todas as classes têm revocação acima da precisão, sinal agregado de mais propensão a spans excedentes do que ausentes. Sem predições, matriz de confusão e exemplos de erro, porém, não é possível afirmar a causa. Uma análise de erros deve estratificar fronteira parcial, tipo trocado, siglas, citações abreviadas, números processuais, OCR, caixa, documento, tribunal e período. Ambiguidade entre organização, local, legislação e jurisprudência e entidades aninhadas são hipóteses a testar, não erros demonstrados pelo cartão.

Inferência com spans e documentos longos

Use uma versão controlada do artefato em produção para evitar alterações silenciosas de pesos ou tokenizer. aggregation_strategy="first" resolve divergências entre subtokens usando o primeiro WordPiece da palavra; stride cria sobreposição para entradas longas. Essa é uma política operacional explícita, não necessariamente a política do treino [10].

from transformers import (
    AutoModelForTokenClassification,
    AutoTokenizer,
    pipeline,
)
 
MODEL_ID = "dominguesm/legal-bert-ner-base-cased-ptbr"
 
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForTokenClassification.from_pretrained(
    MODEL_ID,
    use_safetensors=True,
).eval()
 
ner = pipeline(
    "token-classification",
    model=model,
    tokenizer=tokenizer,
    aggregation_strategy="first",
    stride=64,
    device=-1,
)
 
texto = (
    "O Ministério Público do Trabalho invocou o artigo 114 da "
    "Constituição Federal em Brasília, em 19 de dezembro de 2023."
)
 
for entidade in ner(texto):
    inicio, fim = entidade["start"], entidade["end"]
    print({
        "texto": texto[inicio:fim],
        "tipo": entidade["entity_group"],
        "inicio": inicio,
        "fim": fim,
        "score": round(float(entidade["score"]), 4),
    })

Use os offsets para preservar o texto original; o campo word pode conter representação WordPiece. O score é uma agregação de probabilidades locais, não probabilidade calibrada de que a extração esteja juridicamente correta. Em produção, calibre limiares por classe em dados do domínio-alvo, valide janelas nas bordas, mantenha revisão humana e monitore mudança de linguagem e de fontes.

Privacidade, uso jurídico e limites

Dados pessoais. Peças processuais podem conter nomes, endereços, saúde, finanças, filiação e fatos íntimos. NER não anonimiza: ele pode deixar passar dados, marcar texto inocente e expor o próprio conteúdo ao serviço de inferência. A LGPD define tratamento de forma ampla e exige finalidade, necessidade, segurança, prevenção, não discriminação e prestação de contas; dados publicamente acessíveis não perdem automaticamente essas salvaguardas [12]. Prefira processamento local, criptografia, controle de acesso, retenção mínima e testes de vazamento. Avalie também segredo de justiça e regras específicas do órgão.

Automação jurídica. Uma extração errada pode omitir parte, confundir precedente com norma ou truncar qualificador decisivo. O modelo deve apoiar indexação e revisão, não decidir admissibilidade, risco, prioridade, direitos ou resultado processual. Meça desempenho por órgão, gênero, época e grupo afetado; registre falsos positivos e negativos; disponibilize contestação e revisão humana quando a saída influenciar pessoas.

Generalização. A proveniência declarada concentra-se no STF e em documentos associados. Contratos, tribunais locais, atos administrativos, doutrina, linguagem informal e documentos recentes podem ter distribuição diferente. O limite de 512 tokens e possíveis ruídos de OCR agravam a transferência. F1 médio não substitui validação prospectiva no fluxo de destino.

Reprodutibilidade e licenças

A inferência pode ser reproduzida registrando a versão do modelo, do tokenizer, de Transformers, PyTorch e Python, além do hardware. Para uma avaliação verificável, versione também os textos e registre offsets, estratégia de agregação, tamanho e sobreposição das janelas, limiares e versão da métrica.

A reprodução pública do treinamento é deliberadamente limitada pelo Termo de Compromisso. Não posso fornecer o corpus, a unidade individual dos exemplos, o guia e a ferramenta vinculados à anotação, a composição dos splits, scripts, predições ou artefatos intermediários capazes de expor a base [14]. Pesquisadores com autorização própria ainda precisariam reconstruir dependências, hardware e alinhamento WordPiece; a semente 42 e training_args.bin são insuficientes. A troca posterior do modelo-base reforça a necessidade de controlar a versão de cada dependência permitida.

Os pesos NER são declarados CC BY 4.0, que permite compartilhar e adaptar, inclusive comercialmente, desde que haja atribuição, link para a licença e indicação de mudanças [13]. Isso não concede acesso ao corpus nem afasta o Termo de Compromisso, que proíbe o uso comercial da base e dos conhecimentos indiretos gerados a partir dela [14]. O espelho Hugging Face do LeNER-Br marca sua licença como desconhecida, enquanto o repositório GitHub declara MIT [6]. Licença dos pesos, código, dataset, documentos judiciais, saídas e obrigações contratuais são camadas diferentes. Nenhuma delas implica endosso do STF.

Conclusão

Com o ajuste fino, produzi e disponibilizei um checkpoint capaz de localizar seis classes de entidades em textos jurídicos para integração e comparação. Aprendi que métricas de teste precisam permanecer separadas de interpretação jurídica e de validação no domínio de implantação.

Referências

1. Domingues, M. legal-bert-ner-base-cased-ptbr: cartão, configuração e argumentos. Hugging Face, 2022. Modelo; configuração.
2. Devlin, J. et al. BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding. NAACL-HLT, 2019. ACL Anthology.
3. Souza, F.; Nogueira, R.; Lotufo, R. BERTimbau: Pretrained BERT Models for Brazilian Portuguese. BRACIS, 2020. DOI; modelo.
4. Domingues, M. legal-bert-base-cased-ptbr: cartão e configuração. Hugging Face, 2022. Modelo.
5. Luz de Araujo, P. H. et al. LeNER-Br: A Dataset for Named Entity Recognition in Brazilian Legal Text. PROPOR, 2018. DOI.
6. Luz de Araujo, P. H. et al. LeNER-Br dataset e conversão Hugging Face. Repositório; dataset card.
7. Luz de Araujo, P. H. et al. VICTOR: a Dataset for Brazilian Legal Documents Classification. LREC, 2020. ACL Anthology.
8. Ramshaw, L. A.; Marcus, M. P. Text Chunking using Transformation-Based Learning. Third Workshop on Very Large Corpora, 1995. arXiv.
9. Tjong Kim Sang, E. F.; De Meulder, F. Introduction to the CoNLL-2003 Shared Task: Language-Independent Named Entity Recognition. CoNLL, 2003. ACL Anthology.
10. Hugging Face. Token classification e TokenClassificationPipeline. Alinhamento; pipeline.
11. Nakayama, H. seqeval: A Python framework for sequence labeling evaluation. 2018. Metric card.
12. Brasil. Lei nº 13.709, de 14 de agosto de 2018: Lei Geral de Proteção de Dados Pessoais. Planalto.
13. Creative Commons. Attribution 4.0 International. Licença.
14. AI.Lab, Universidade de Brasília. Termo de Compromisso diante da cessão de bases de dados do Supremo Tribunal Federal. Documento de acesso às bases do projeto VICTOR.

BibTeX

@inproceedings{devlin2019bert,
  title     = {BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding},
  author    = {Devlin, Jacob and Chang, Ming-Wei and Lee, Kenton and Toutanova, Kristina},
  booktitle = {Proceedings of NAACL-HLT},
  pages     = {4171--4186},
  year      = {2019},
  doi       = {10.18653/v1/N19-1423}
}
 
@inproceedings{souza2020bertimbau,
  title     = {BERTimbau: Pretrained BERT Models for Brazilian Portuguese},
  author    = {Souza, F{\'a}bio and Nogueira, Rodrigo and Lotufo, Roberto},
  booktitle = {Intelligent Systems (BRACIS 2020)},
  pages     = {403--417},
  year      = {2020},
  doi       = {10.1007/978-3-030-61377-8_28}
}
 
@inproceedings{luzdearaujo2018lener,
  title     = {LeNER-Br: A Dataset for Named Entity Recognition in Brazilian Legal Text},
  author    = {Luz de Araujo, Pedro H. and de Campos, Te{\'o}filo E. and de Oliveira, Renato R. R. and Stauffer, Matheus and Couto, Samuel and Bermejo, Paulo},
  booktitle = {Computational Processing of the Portuguese Language (PROPOR)},
  pages     = {313--323},
  year      = {2018},
  doi       = {10.1007/978-3-319-99722-3_32}
}
 
@inproceedings{ramshaw1995text,
  title     = {Text Chunking using Transformation-Based Learning},
  author    = {Ramshaw, Lance A. and Marcus, Mitchell P.},
  booktitle = {Third Workshop on Very Large Corpora},
  pages     = {82--94},
  year      = {1995},
  url       = {https://aclanthology.org/W95-0107/}
}
 
@inproceedings{tjongkimsang2003conll,
  title     = {Introduction to the CoNLL-2003 Shared Task: Language-Independent Named Entity Recognition},
  author    = {Tjong Kim Sang, Erik F. and De Meulder, Fien},
  booktitle = {Proceedings of the Seventh Conference on Natural Language Learning},
  pages     = {142--147},
  year      = {2003},
  url       = {https://aclanthology.org/W03-0419/}
}
 
@inproceedings{luzdearaujo2020victor,
  title     = {VICTOR: a Dataset for Brazilian Legal Documents Classification},
  author    = {Luz de Araujo, Pedro Henrique and de Campos, Te{\'o}filo Em{\'i}dio and Ataides Braz, Fabricio and Correia da Silva, Nilton},
  booktitle = {Proceedings of the Twelfth Language Resources and Evaluation Conference},
  pages     = {1449--1458},
  year      = {2020},
  url       = {https://aclanthology.org/2020.lrec-1.181/}
}