🏠 BERT Addresses Brazil
Modelo BERT fine-tuned para Named Entity Recognition (NER) de endereços brasileiros.
Este modelo é especializado em extrair entidades de endereços brasileiros a partir de texto não estruturado, incluindo:
- 📍 Ruas e logradouros
- 🔢 Números
- 🏘️ Bairros
- 🏙️ Cidades
- 🗺️ Estados
- 📮 CEPs
- 🏢 Complementos (apartamento, sala, bloco, torre)
- 📌 Pontos de referência
🚀 Como Usar
Com Transformers
from transformers import AutoTokenizer, AutoModelForTokenClassification
from transformers import pipeline
# Carrega modelo e tokenizer
tokenizer = AutoTokenizer.from_pretrained("ottema/bert-addresses-brazil")
model = AutoModelForTokenClassification.from_pretrained("ottema/bert-addresses-brazil")
# Cria pipeline de NER
ner = pipeline("ner", model=model, tokenizer=tokenizer, aggregation_strategy="simple")
# Extrai entidades
texto = "Rua das Flores, 123, Apto 45, Centro, São Paulo - SP, 01234-567"
resultados = ner(texto)
# Mostra resultados
for entidade in resultados:
print(f"{entidade['entity_group']}: {entidade['word']} (confiança: {entidade['score']:.2f})")
Saída Esperada
RUA: Rua das Flores (confiança: 0.92)
NUMERO: 123 (confiança: 0.92)
COMPLEMENTO: Apto 45 (confiança: 0.91)
BAIRRO: Centro (confiança: 0.91)
CIDADE: São Paulo (confiança: 0.91)
ESTADO: SP (confiança: 0.73)
CEP: 01234-567 (confiança: 0.92)
Com Inference API
from huggingface_hub import InferenceClient
client = InferenceClient()
data = client.post(
json={"inputs": "Av. Paulista, 1000, Sala 501, Bela Vista, São Paulo - SP"},
model="ottema/bert-addresses-brazil"
)
print(data)
📊 Casos de Uso
✅ Funciona Bem Com:
Endereços Completos:
Rua Augusta, 1500, Consolação, São Paulo - SP, 01305-100
Com Complementos:
Av. das Nações Unidas, 1000, Apto 42, Torre A, Pinheiros, São Paulo - SP
Com Referências:
Rua do Catete, 150, ao lado do metrô, Catete, Rio de Janeiro - RJ
Abreviações:
R. das Flores, 123, Centro
Av. Paulista, 1000, Bela Vista
Pça. da Liberdade, s/n
Brasília:
SQN 102 Bloco A, Apto 101, Asa Norte, Brasília - DF
CLN 105, 32, Asa Norte, Brasília - DF
Zonas Rurais:
Sítio Boa Vista, s/n, Zona Rural, Goiânia - GO
Fazenda Santa Rita, Km 5, Zona Rural, Uberlândia - MG
Rodovias:
Rodovia BR-101, Km 250, Palhoça - SC
🎯 Entidades Extraídas
| Entidade | Descrição | Exemplo |
|---|---|---|
RUA |
Logradouro (rua, avenida, praça, etc.) | Rua das Flores, Av. Paulista |
NUMERO |
Número do endereço | 123, 1000, s/n |
BAIRRO |
Bairro ou distrito | Centro, Bela Vista |
CIDADE |
Cidade ou município | São Paulo, Rio de Janeiro |
ESTADO |
Estado (UF) | SP, RJ, MG |
CEP |
Código postal | 01234-567 |
COMPLEMENTO |
Complemento (apto, sala, bloco) | Apto 45, Sala 101, Bloco B |
REFERENCIA |
Ponto de referência | ao lado da padaria, em frente ao banco |
📈 Métricas
Avaliado em dataset de teste com 3.027 samples:
| Entidade | Precision | Recall | F1-Score |
|---|---|---|---|
| RUA | 0.999 | 0.999 | 0.999 |
| NUMERO | 0.999 | 0.999 | 0.999 |
| BAIRRO | 0.999 | 0.999 | 0.999 |
| CIDADE | 0.999 | 0.999 | 0.999 |
| ESTADO | 0.999 | 0.999 | 0.999 |
| CEP | 0.999 | 0.999 | 0.999 |
| COMPLEMENTO | 0.999 | 0.999 | 0.999 |
| REFERENCIA | 0.999 | 0.999 | 0.999 |
Média Geral (F1-Score): 0.9999 (99.99%)
🏗️ Arquitetura
| Parâmetro | Valor |
|---|---|
| Base Model | neuralmind/bert-base-portuguese-cased |
| Tipo | BERT Base (12 layers, 768 hidden) |
| Parâmetros | ~110M |
| Tamanho | 414 MB |
| Framework | PyTorch |
| Task | Token Classification (NER) |
📚 Dataset de Treinamento
O modelo foi treinado com 30.256 samples:
| Fonte | Quantidade | % |
|---|---|---|
| Dados Reais (ViaCEP) | 2.512 | 8.3% |
| Variações de Escrita | 7.536 | 24.9% |
| Casos Especiais | 208 | 0.7% |
| Dados Sintéticos | 20.000 | 66.1% |
Casos Especiais Incluídos:
- ✅ Brasília (SQN, CLN, SQS, CLS)
- ✅ Estradas e Rodovias (BR-101, SP-330)
- ✅ Zonas Rurais (Sítios, Fazendas, Chácaras)
- ✅ Complementos variados (Apto, Sala, Bloco, Torre)
- ✅ Referências completas (100+ tipos)
- ✅ Abreviações comuns (R., Av., Pça.)
🛠️ Treinamento
| Hiperparâmetro | Valor |
|---|---|
| Epochs | 10 |
| Batch Size | 16 |
| Learning Rate | 2e-5 |
| Warmup Steps | 800 |
| Weight Decay | 0.03 |
| Label Smoothing | 0.15 |
| Max Length | 128 |
| Optimizer | AdamW |
| Training Samples | 24,204 |
| Test Samples | 3,027 |
Tempo de Treino: ~18 minutos (RTX 3060)
📦 Instalação
pip install transformers torch accelerate
⚠️ Limitações
- ESTADO: Pode confundir estado com cidade em alguns casos
- Vírgulas: Pode incluir vírgulas nas entidades
- Endereços muito curtos: Pode ter dificuldade com endereços incompletos
Exemplo de Limitação:
Entrada: "SP"
Saída: Pode não identificar como ESTADO sem contexto
📄 Licença
- Modelo: Apache License 2.0
- Dataset: CC-BY-4.0 (apenas dados sintéticos)
🙏 Agradecimentos
- NeuralMind pelo modelo base em português
- ViaCEP pela API pública de CEPs
- Hugging Face pela plataforma
📞 Contato
- Organização: Ottema
- Website: https://ottema.com.br
- Issues: https://huggingface.co/ottema/bert-addresses-brazil/discussions
🔗 Links Úteis
Desenvolvido com ❤️ pela Ottema
- Downloads last month
- -