felipergcpqd/debertinha-500k-address-ner-pt

DeBERTinha NER para Endereços Brasileiros

Modelo de Named Entity Recognition (NER) para extração de componentes de endereços brasileiros, baseado no DeBERTinha e treinado com LoRA (Low-Rank Adaptation).

Descrição do Modelo

Este modelo foi fine-tuned para identificar e extrair componentes de endereços brasileiros, incluindo:

Entidade	Descrição	Exemplo
LOGRADOURO	Tipo e nome da via	Rua das Flores, Avenida Brasil
NUMERO	Número do imóvel	123, S/N
COMPLEMENTO	Complemento do endereço	Apto 101, Bloco A
BAIRRO	Bairro	Centro, Jardim América
CIDADE	Cidade/Município	São Paulo, Campinas
ESTADO	Estado (sigla ou nome)	SP, São Paulo
CEP	Código de Endereçamento Postal	01310-100
PAIS	País	Brasil

Como Usar

Instalação

pip install transformers peft torch

Código de Exemplo

from transformers import AutoTokenizer, AutoModelForTokenClassification
from peft import PeftModel
import torch

# Carregar o modelo base e o adapter
base_model_name = "sagui-nlp/debertinha-ptbr-xsmall-lenerbr"
adapter_name = "felipergcpqd/debertinha-500k-address-ner-pt"

# Carregar tokenizer
tokenizer = AutoTokenizer.from_pretrained(adapter_name)

# Carregar modelo base
base_model = AutoModelForTokenClassification.from_pretrained(
    base_model_name,
    num_labels=17,  # 8 entidades x 2 (B-/I-) + O
    ignore_mismatched_sizes=True
)

# Carregar adapter PEFT
model = PeftModel.from_pretrained(base_model, adapter_name)
model.eval()

# Labels do modelo
id2label = {
    0: "O",
    1: "B-LOGRADOURO", 2: "I-LOGRADOURO",
    3: "B-NUMERO", 4: "I-NUMERO",
    5: "B-COMPLEMENTO", 6: "I-COMPLEMENTO",
    7: "B-BAIRRO", 8: "I-BAIRRO",
    9: "B-CIDADE", 10: "I-CIDADE",
    11: "B-ESTADO", 12: "I-ESTADO",
    13: "B-CEP", 14: "I-CEP",
    15: "B-PAIS", 16: "I-PAIS"
}

# Fazer predição
def predict_ner(text):
    inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=512)
    
    with torch.no_grad():
        outputs = model(**inputs)
    
    predictions = torch.argmax(outputs.logits, dim=2)
    tokens = tokenizer.convert_ids_to_tokens(inputs["input_ids"][0])
    
    results = []
    for token, pred in zip(tokens, predictions[0]):
        if token not in ["[CLS]", "[SEP]", "[PAD]"]:
            label = id2label[pred.item()]
            results.append((token, label))
    
    return results

# Exemplo de uso
endereco = "Rua das Flores, 123, Apto 45, Centro, São Paulo, SP, 01310-100"
resultado = predict_ner(endereco)

for token, label in resultado:
    if label != "O":
        print(f"{token}: {label}")

Usando com Pipeline (após merge)

Se você quiser usar o modelo completo (merged), você pode fazer:

from transformers import pipeline
from peft import PeftModel, AutoPeftModelForTokenClassification

# Carregar e fazer merge do modelo
model = AutoPeftModelForTokenClassification.from_pretrained(
    "felipergcpqd/debertinha-500k-address-ner-pt"
)
merged_model = model.merge_and_unload()

# Criar pipeline
ner_pipeline = pipeline(
    "token-classification",
    model=merged_model,
    tokenizer=tokenizer,
    aggregation_strategy="simple"
)

resultado = ner_pipeline("Av. Paulista, 1000, Bela Vista, São Paulo - SP, 01310-100")
print(resultado)

Detalhes do Treinamento

• Modelo Base: sagui-nlp/debertinha-ptbr-xsmall-lenerbr
• Técnica de Fine-tuning: LoRA (Low-Rank Adaptation)
• Framework: PEFT 0.18.0
• Dataset: Dataset sintético de ~500k endereços brasileiros
• Tarefa: Token Classification / NER

Hyperparâmetros LoRA

LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["query_proj", "key_proj", "value_proj", "dense"],
    lora_dropout=0.1,
    bias="none",
    task_type="TOKEN_CLS"
)

Limitações

• O modelo foi treinado principalmente com endereços brasileiros
• Endereços muito mal formatados podem ter resultados menos precisos
• O modelo pode ter dificuldades com abreviações não convencionais

Citação

Se usar este modelo, por favor cite:

@misc{debertinha-address-ner,
  author = {Felipe R. G.},
  title = {DeBERTinha NER para Endereços Brasileiros},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/felipergcpqd/debertinha-500k-address-ner-pt}
}

Licença

Apache 2.0