Skip to content

NLP Folha de referência

Técnicas e ferramentas de Processamento de Linguagem Natural para análise de texto.

01

Primeiros Passos

Setup NLTK e spaCy

NLTK é ótimo para educação e pesquisa; spaCy é pronto para produção e rápido. Os modelos do spaCy retornam objetos Doc com texto tokenizado, tags POS, dependências e mais. Instale modelos de linguagem com 'python -m spacy download <modelo>' — en_core_web_sm é o modelo pequeno de inglês.

nlp
# install NLTK and spaCy
pip install nltk spacy
python -m spacy download en_core_web_sm

import nltk
import spacy

# download NLTK data
nltk.download('punkt')
nltk.download('stopwords')

# load a spaCy model
nlp = spacy.load("en_core_web_sm")
doc = nlp("Apple is looking at buying a U.K. startup.")
for token in doc:
    print(token.text, token.pos_, token.dep_)

Básico do Pipeline do spaCy

O pipeline do spaCy é modular: o tokenizer sempre roda primeiro, depois componentes opcionais como tagger, parser, ner. Desativar componentes não usados dá grandes acelerações (ex.: para embeddings você só precisa do tok2vec). Use nlp.pipe() para lotes — muito mais rápido que chamar nlp() num loop.

nlp
import spacy

# blank pipeline (no pretrained components)
nlp_blank = spacy.blank("en")

# full pipeline: tokenizer -> tagger -> parser -> ner -> ...
nlp = spacy.load("en_core_web_sm")
print(nlp.pipe_names)   # ['tok2vec', 'tagger', 'parser', 'ner', ...]

# disable components you don't need (faster)
nlp_fast = spacy.load("en_core_web_sm", disable=["parser", "ner"])

# process many texts efficiently
docs = list(nlp.pipe(["Hello world.", "SpaCy is fast."]))
# stream from file with nlp.pipe(texts, batch_size=1000)

Corpora e Dados do NLTK

O NLTK traz wrappers para muitos corpora clássicos — Gutenberg (livros), Brown (texto categorizado), Reuters (notícias), WordNet (léxico). Os downloads são únicos e cacheados. Útil para tutoriais e benchmarks, mas para produção prefira datasets modernos do Hugging Face 'datasets'.

nlp
import nltk

# one-time downloads (cached in ~/nltk_data)
nltk.download('gutenberg')     # Project Gutenberg books
nltk.download('reuters')       # Reuters news corpus
nltk.download('brown')         # Brown corpus (categorized)
nltk.download('wordnet')       # lexical database
nltk.download('averaged_perceptron_tagger')

from nltk.corpus import gutenberg, brown

# first sentences of Moby Dick
print(gutenberg.sents('melville-moby_dick.txt')[0][:8])

# Brown corpus categories
print(brown.categories())      # ['news', 'editorial', 'reviews', ...]
news_words = brown.words(categories='news')

Primeiro Script de NLP (Estatísticas de Texto)

Uma forma rápida de perfilar texto: contagem de tokens, contagem de frases, lemas únicos e frequência de palavras de conteúdo (após remover stopwords). O Doc do spaCy é iterável e expõe frases via doc.sents. Counter, de collections, é a ferramenta de frequência mais simples.

nlp
import spacy

nlp = spacy.load("en_core_web_sm")
text = "The quick brown fox jumps over the lazy dog. The dog barks."
doc = nlp(text)

# basic stats
print("Tokens:", len(doc))
print("Sentences:", len(list(doc.sents)))
print("Unique words:", len({t.lemma_.lower() for t in doc if t.is_alpha}))

# word frequency
from collections import Counter
words = [t.text.lower() for t in doc if not t.is_stop and t.is_alpha]
print(Counter(words).most_common(5))

Lendo e Limpando Arquivos de Texto

Texto real é bagunçado: codificações inconsistentes, HTML, aspas curvas, travessões. Sempre leia com utf-8 explícito. Normalize espaços em branco e remova HTML antes de tokenizar. Converter para minúsculas perde informação (EUA vs eua) — faça só para tarefas estilo bag-of-words, não para NER ou POS tagging.

nlp
import re
from pathlib import Path

# read with proper encoding
raw = Path("doc.txt").read_text(encoding="utf-8")

# normalize whitespace
text = re.sub(r"\s+", " ", raw).strip()

# remove HTML tags
text = re.sub(r"<[^>]+>", " ", text)

# fix curly quotes / dashes to ASCII
text = text.replace("\u2019", "'").replace("\u201c", '"')
text = text.replace("\u2013", "-").replace("\u2014", "-")

# lowercase only if case-insensitive task
clean = text.lower()
02

Tokenização

Tokenização de Palavras e Frases no NLTK

O tokenizer punkt do NLTK divide frases usando um modelo treinado que trata abreviações como 'Mr.'. word_tokenize usa a convenção Treebank, que separa contrações ('don't' -> 'do' + "n't"). Escolha um tokenizer que case com o treinamento do seu modelo downstream — tokenização desalinhada prejudica o desempenho silenciosamente.

nlp
from nltk.tokenize import word_tokenize, sent_tokenize

text = "Hello there! How are you? I'm fine, thanks."

# sentence split (handles abbreviations)
sents = sent_tokenize(text)
# ['Hello there!', 'How are you?', "I'm fine, thanks."]

# word split (handles contractions, punctuation)
tokens = word_tokenize(text)
# ['Hello', 'there', '!', 'How', 'are', 'you', '?',
#  'I', "'m", 'fine', ',', 'thanks', '.']

# treebank tokenizer: 'don't' -> ['do', "n't"]
from nltk.tokenize import TreebankWordTokenizer
print(TreebankWordTokenizer().tokenize("don't stop"))

Tokenização do spaCy

O tokenizer do spaCy é não destrutivo: nunca perde o alinhamento entre tokens e o texto original (tok.idx dá o offset de caractere). Isso importa para NER e destaque. Regras personalizadas de infix/exception permitem ajustar a divisão sem reescrever o pipeline inteiro.

nlp
import spacy

nlp = spacy.load("en_core_web_sm")
doc = nlp("Let's go to N.Y.C. on 03/14/2023 for $5.50!")

# tokens keep their position in the original text
for tok in doc:
    print(f"{tok.text!r:12} start={tok.idx} end={tok.idx + len(tok.text)}")

# spans: contiguous slices of the Doc
span = doc[2:5]   # 'go to N.Y.C.'
print(span.text)

# spaCy never loses alignment to the original string
print(doc.text == "".join(t.text_with_ws for t in doc))  # True

Tokenizer por Regex

Tokenizers por regex são rápidos e determinísticos — bons quando você controla o formato do texto. \w+ descarta pontuação e números-como-palavras; pareie com cuidado à sua tarefa. WhitespaceTokenizer é a divisão mais barata, mas deixa pontuação colada às palavras, o que geralmente exige uma segunda passada de limpeza.

nlp
from nltk.tokenize import RegexpTokenizer

# words only (drop punctuation)
tok = RegexpTokenizer(r"\w+")
print(tok.tokenize("Hello, world! 123"))   # ['Hello', 'world', '123']

# keep contractions: \w+|'\w+
tok2 = RegexpTokenizer(r"\w+|'\w+")
print(tok2.tokenize("don't stop"))          # ['do', "n't", 'stop']

# whitespace tokenizer (keeps punctuation attached)
from nltk.tokenize import WhitespaceTokenizer
print(WhitespaceTokenizer().tokenize("Hi! Bye."))   # ['Hi!', 'Bye.']

Tokenização por Subpalavras (BPE / WordPiece)

Tokenizers de subpalavras (BPE, WordPiece, Unigram, SentencePiece) dividem palavras raras em pedaços comuns, equilibrando tamanho de vocabulário e cobertura. São o padrão dos transformers modernos — BERT usa WordPiece, GPT-2 usa BPE, T5 usa SentencePiece. Treine no seu próprio corpus para casar com o domínio alvo.

nlp
from tokenizers import Tokenizer
from tokenizers.models import BPE
from tokenizers.trainers import BpeTrainer
from tokenizers.pre_tokenizers import Whitespace

# train a Byte-Pair-Encoding tokenizer
tokenizer = Tokenizer(BPE(unk_token="[UNK]"))
tokenizer.pre_tokenizer = Whitespace()
trainer = BpeTrainer(
    special_tokens=["[UNK]", "[PAD]", "[CLS]", "[SEP]"],
    vocab_size=8000,
)
tokenizer.train(files=["corpus.txt"], trainer=trainer)

enc = tokenizer.encode("Tokenization is fun.")
print(enc.tokens)        # ['Tok', 'eni', 'zer', ...]
print(enc.ids)           # [34, 912, ...]

Regras Personalizadas do Tokenizer do spaCy

Use add_special_case para termos de domínio (URLs, hashtags, nomes de medicamentos) que o tokenizer padrão trata mal. Modificar padrões infix/prefix/suffix muda o comportamento global de divisão — teste numa amostra. Prefira casos especiais a reescritas completas; eles se compõem limpo com o resto do pipeline.

nlp
import spacy
from spacy.tokenizer import Tokenizer
from spacy.util import compile_infix_regex, compile_prefix_regex

nlp = spacy.load("en_core_web_sm")

# add a special-case rule
specials = {"gimme": [{ORTH: "gim"}, {ORTH: "me"}]}
for text, pattern in specials.items():
    nlp.tokenizer.add_special_case(text, pattern)

print([t.text for t in nlp("gimme that")])   # ['gim', 'me', 'that']

# customize infixes (e.g. split on hyphens)
infixes = compile_infix_regex([r"-"])
nlp.tokenizer.infix_finditer = infixes.finditer
print([t.text for t in nlp("state-of-the-art")])

Tokenizers de Transformer (Hugging Face)

Sempre pareie um modelo com o tokenizer exato dele — vocabulários desalinhados quebram tudo silenciosamente. AutoTokenizer.from_pretrained seleciona automaticamente a classe certa (BertTokenizer, GPT2Tokenizer etc.). bert-base-uncased converte para minúsculas e adiciona [CLS]/[SEP]; variantes cased preservam a caixa. Defina truncation/max_length para evitar erros em entradas longas.

nlp
from transformers import AutoTokenizer

# load the tokenizer matching a pretrained model
tok = AutoTokenizer.from_pretrained("bert-base-uncased")

enc = tok("Tokenization with BERT.", return_tensors="pt")
print(enc.keys())         # dict_keys(['input_ids', 'token_type_ids', 'attention_mask'])
print(enc["input_ids"])   # tensor([[101, 19204, 3989, 102]])
print(tok.convert_ids_to_tokens(enc["input_ids"][0]))
# ['[CLS]', 'tokenization', 'with', 'bert', '.', '[SEP]']

# handle long inputs with sliding window
print(tok("Very long text", truncation=True, max_length=512))
03

POS Tagging

POS Tagging no NLTK

O tagger perceptron padrão usa o conjunto de tags Penn Treebank (NN=substantivo, VB=verbo, JJ=adjetivo, PRP=pronome...). É sensível ao contexto — 'permit' como verbo (VB) vs substantivo (NN) é desambiguado pelas palavras ao redor. Tags POS são uma feature barata que melhora NER, chunking e extração baseada em regras.

nlp
import nltk
from nltk.tokenize import word_tokenize

nltk.download('averaged_perceptron_tagger_eng')

tokens = word_tokenize("They refuse to permit us to obtain the permit.")
tags = nltk.pos_tag(tokens)
# [('They', 'PRP'), ('refuse', 'VBP'), ('to', 'TO'),
#  ('permit', 'VB'), ..., ('permit', 'NN'), ('.', '.')]

# note: the two 'permit' tokens get different tags (VB verb vs NN noun)
for word, tag in tags:
    print(f"{word:10} {tag}")

POS e Morfologia no spaCy

O spaCy dá tanto o POS Universal grosso (pos_, agnóstico de linguagem) quanto tags Treebank finas (tag_). O objeto morph carrega traços como tempo, número, pessoa. Tags universais são melhores para trabalho multilíngue; tags Treebank carregam mais detalhe para regras específicas do inglês.

nlp
import spacy
nlp = spacy.load("en_core_web_sm")

doc = nlp("The children were playing happily.")
for tok in doc:
    print(f"{tok.text:12} POS={tok.pos_:6} TAG={tok.tag_:5} "
          f"lemma={tok.lemma_:10} morph={tok.morph}")

# tok.pos_  -> coarse Universal POS (NOUN, VERB, ADJ, ...)
# tok.tag_  -> fine-grained Treebank tag (NN, VBD, JJ, ...)
# tok.morph -> morphological features (Tense=Past, Number=Plur, ...)

Tags POS Universais

Tags POS universais (da Universal Dependencies) usam as mesmas 17 etiquetas em todas as linguagens — inestimável para pipelines multilíngues. PROPN (nomes próprios) vs NOUN importa para NER. Contar proporções de POS (densidade lexical = NOUN+VERB+ADJ / total) é uma feature simples de estilo de texto.

nlp
# Universal Dependencies tagset (17 tags, same across languages)
# ADJ   - adjective       | ADP   - adposition (prep/post)
# ADV   - adverb          | AUX   - auxiliary (is, has)
# CCONJ - coordinating conj | DET  - determiner (the, a)
# INTJ  - interjection    | NOUN  - noun
# NUM   - numeral         | PART  - particle ('s, not)
# PRON  - pronoun         | PROPN - proper noun
# PUNCT - punctuation     | SCONJ - subordinating conj
# SYM   - symbol          | VERB  - verb
# X     - other

import spacy
nlp = spacy.load("en_core_web_sm")
doc = nlp("She quickly ran to the store.")
nouns = [t.text for t in doc if t.pos_ in ("NOUN", "PROPN")]
verbs = [t.text for t in doc if t.pos_ == "VERB"]

Lendo Corpora Marcados

Corpora marcados são ouro para treinar ou avaliar taggers e para análise linguística. Brown usa um conjunto de tags rico (com sufixos como -TL para títulos, -NC para citações). Comparar distribuições de tags entre categorias do Brown (notícias vs ficção) revela diferenças estilísticas no uso das classes de palavras.

nlp
import nltk
from nltk.corpus import brown, treebank

# Brown: each word pre-tagged
sent = brown.tagged_sents(categories='news')[0]
print(sent)   # [('The', 'AT'), ('Fulton', 'NP-TL'), ...]

# Penn Treebank ( Wall Street Journal)
for s in treebank.tagged_sents()[:1]:
    print(s)

# count tag distribution
from collections import Counter
tags = [tag for w, tag in brown.tagged_words(categories='news')]
print(Counter(tags).most_common(5))

Marcação Baseada em Regras e Lookup

Para dados pequenos ou específicos de domínio, taggers simples com cadeias de backoff funcionam surpreendentemente bem: tente o tagger mais específico primeiro, recuando para um mais amplo com palavras desconhecidas. UnigramTagger aprende a tag mais comum por palavra; DefaultTagger ('NN') trata palavras não vistas. RegexTagger captura números, datas e padrões de capitalização.

nlp
from nltk.tag import UnigramTagger, DefaultTagger
from nltk.corpus import brown

# fallback: tag everything as NN
default = DefaultTagger('NN')

# unigram: most-likely tag per word (from training data)
train = brown.tagged_sents(categories='news')[:3000]
uni = UnigramTagger(train, backoff=default)

# backoff chain: unigram -> default
test = brown.tagged_sents(categories='news')[3000:3100]
print(f"Accuracy: {uni.evaluate(test):.3f}")

# regex tagger for patterns
from nltk.tag import RegexpTagger
regex = RegexpTagger([(r'^-?[0-9]+(\.[0-9]+)?$', 'CD')], backoff=default)
04

Reconhecimento de Entidades Nomeadas

NER do spaCy

O NER pré-treinado do spaCy reconhece ORG, PERSON, GPE (geopolítico), DATE, MONEY etc. doc.ents são spans alinhados ao tokenizer. displacy.render/serve dá uma bonita visualização em HTML. A precisão em texto geral de notícias é boa; para domínios especializados (médico, jurídico) você precisará de fine-tuning.

nlp
import spacy
nlp = spacy.load("en_core_web_sm")

doc = nlp("Apple is buying a U.K. startup for $1 billion in New York.")

for ent in doc.ents:
    print(f"{ent.text:20} {ent.label_:10} {spacy.explain(ent.label_)}")
# Apple              ORG        Companies, agencies, institutions
# U.K.               GPE        Countries, cities, states
# $1 billion         MONEY      Monetary values
# New York           GPE        Countries, cities, states

# visualize
from spacy import displacy
displacy.serve(doc, style="ent")  # opens a browser

NE Chunking do NLTK

O ne_chunk do NLTK combina POS tagging com um chunker baseado em gramática. A saída é uma árvore em que entidades nomeadas são subárvores rotuladas PERSON, ORGANIZATION, GPE etc. É mais lento e menos preciso que o spaCy, mas útil para aprender o conceito de chunking e para extensões baseadas em regras.

nlp
import nltk
from nltk.tokenize import word_tokenize, sent_tokenize

text = "Barack Obama was born in Hawaii and led the USA."
sents = sent_tokenize(text)

for s in sents:
    tokens = word_tokenize(s)
    tags = nltk.pos_tag(tokens)
    # ne_chunk returns a nested tree of named entities
    tree = nltk.ne_chunk(tags)
    print(tree)
    # (S
    #   (PERSON Barack/NNP Obama/NNP)
    #   was/VBD born/VBN in/IN
    #   (GPE Hawaii/NNP) ...)

# extract just the named entities
for node in tree:
    if hasattr(node, 'label'):
        name = " ".join(w for w, t in node)
        print(node.label(), name)

Tipos e Rótulos de Entidades

O NER de inglês do spaCy usa o conjunto de rótulos OntoNotes — cobertura ampla de pessoa, organização, local, data, dinheiro, quantidade. Use spacy.explain(rótulo) para obter descrições legíveis. Para tipos mais finos (ex.: distinguir CEO de COMPANY), treine um modelo personalizado ou use uma base de conhecimento externa.

nlp
import spacy
nlp = spacy.load("en_core_web_sm")

# list all labels the model knows
for label in nlp.get_pipe("ner").labels:
    print(f"{label:12} {spacy.explain(label)}")
# PERSON       People, including fictional
# NORP         Nationalities or religious/political groups
# FAC          Buildings, airports, highways
# ORG          Companies, agencies, institutions
# GPE          Countries, cities, states
# LOC          Non-GPE locations: mountain ranges, bodies of water
# PRODUCT      Vehicles, food, clothing (not services)
# EVENT        Battles, wars, sports events
# DATE         Absolute or relative dates
# TIME         Times smaller than a day
# MONEY        Monetary values
# QUANTITY     Measurements (weight, distance)
# ORDINAL      First, second, ...
# CARDINAL     Numerals that are not dates or amounts

Treinando um Modelo NER Personalizado

Faça fine-tuning do NER quando os rótulos pré-treinados não servirem ao seu domínio. Forneça dados de treino como (texto, {entities: [(início, fim, rótulo)]}) usando offsets de caracteres — o spaCy precisa de spans exatos. Comece de en_core_web_sm em vez de blank, para aproveitar recursos existentes. 30-50 exemplos por tipo de entidade é um mínimo razoável; use_eval para parada antecipada.

nlp
import spacy
from spacy.training import Example

# start from a blank model (or fine-tune a pretrained one)
nlp = spacy.blank("en")
ner = nlp.add_pipe("ner")
ner.add_label("DRUG")

# training data: text + character offsets of entities
TRAIN = [
    ("Take aspirin daily.", {"entities": [(5, 11, "DRUG")]}),
    ("Ibuprofen reduces fever.", {"entities": [(0, 9, "DRUG")]}),
]

optimizer = nlp.initialize()
for epoch in range(30):
    for text, ann in TRAIN:
        doc = nlp.make_doc(text)
        nlp.update([Example.from_dict(doc, ann)], sgd=optimizer)

# save and use
nlp.to_disk("custom_ner")
doc = nlp("Give metformin 500mg.")
print([(e.text, e.label_) for e in doc.ents])  # [('metformin', 'DRUG')]

Entity Linking e Wikificação

NER acha menções; entity linking as desambigua para uma entrada de base de conhecimento (qual 'Apple'? empresa vs fruta). O linking completo precisa de uma KB mais um gerador de candidatos e um desambiguador. O EntityLinker embutido do spaCy exige que você construa a KB; para produção, considere REL, mGENRE ou APIs comerciais (Google KG, Bing Entity Search).

nlp
# Entity linking maps a mention to a unique ID in a knowledge base
# (e.g. "Apple" -> Apple Inc. the company, not the fruit)

import spacy
nlp = spacy.load("en_core_web_sm")

# spaCy's EntityLinker requires a knowledge base (KB).
# Building one from Wikipedia/Wikidata is involved; in practice use:

# Option 1: spaCy + Wikipedia-based KB (spacy-entity-linker)
# pip install spacy-entity-linker
# from spacy_entity_linker import EntityLinker
# linker = EntityLinker()
# nlp.add_pipe("entityLinker", last=True)

# Option 2: a dedicated library
# import entitylinking  # or use a Wikidata API directly

# Example query via Wikidata SPARQL
import requests
url = "https://www.wikidata.org/w/api.php"
params = {"action": "wbsearchentities", "search": "Apple",
          "language": "en", "format": "json"}
print(requests.get(url, params=params).json())
05

Stemming e Lematização

Porter Stemmer

PorterStemmer aplica uma sequência fixa de regras de remoção de sufixos. É rápido e determinístico, mas produz não-palavras ('easili', 'studi') e ignora o contexto — 'ran' continua 'ran' porque não tem sufixo a remover. Serve para buscadores e modelos de tópicos, onde consistência de stem importa mais que correção.

nlp
from nltk.stem import PorterStemmer

stemmer = PorterStemmer()
for w in ["running", "runs", "ran", "easily", "fairness", "studies"]:
    print(f"{w:10} -> {stemmer.stem(w)}")
# running    -> run
# runs       -> run
# ran        -> ran        (Porter doesn't handle irregulars)
# easily     -> easili     (sometimes ugly)
# fairness   -> fair
# studies    -> studi

# fast, rule-based, deterministic
print([stemmer.stem(t) for t in "the cats are running".split()])

Snowball Stemmer

SnowballStemmer é o Porter modernizado (versão 'English') e adiciona 15+ outras linguagens. É marginalmente mais preciso e suporta texto não inglês de fábrica. Se você precisa de stemming multilíngue sem dicionários, Snowball é o padrão prático; troque para um lemmatizer por resultados de maior qualidade.

nlp
from nltk.stem import SnowballStemmer

# Snowball = improved Porter, supports many languages
print(SnowballStemmer.languages)
# ['arabic', 'danish', 'dutch', 'english', 'finnish', 'french',
#  'german', 'hungarian', 'italian', 'norwegian', 'porter',
#  'portuguese', 'romanian', 'russian', 'spanish', 'swedish']

en = SnowballStemmer("english")
print(en.stem("running"), en.stem("fairly"), en.stem("studies"))
# run fair studi

# compare two languages
fr = SnowballStemmer("french")
print(fr.stem("mangerons"))   # mang

WordNet Lemmatizer

A lematização retorna palavras reais de dicionário ('better' -> 'good', 'mice' -> 'mouse') consultando o WordNet. Precisa do POS para desambiguar ('running' é substantivo vs verbo). O custo do POS tagging compensa quando as features downstream (BoW, TF-IDF) se beneficiam de formas canônicas. Mais lento que stemming, pelas consultas ao dicionário.

nlp
import nltk
from nltk.stem import WordNetLemmatizer
nltk.download('wordnet')

lem = WordNetLemmatizer()

# without POS, defaults to NOUN
print(lem.lemmatize("running"))            # running (treated as noun)
print(lem.lemmatize("running", pos='v'))   # run      (verb)
print(lem.lemmatize("better", pos='a'))    # good     (adjective)
print(lem.lemmatize("mice"))               # mouse    (irregular plural)

# pipeline: tokenize -> POS tag -> lemmatize with correct POS
from nltk.tokenize import word_tokenize
from nltk import pos_tag
words = word_tokenize("The cats were running quickly.")
treebank_to_wordnet = {'N': 'n', 'V': 'v', 'J': 'a', 'R': 'r'}
for w, t in pos_tag(words):
    wn_pos = treebank_to_wordnet.get(t[0], 'n')
    print(w, '->', lem.lemmatize(w, pos=wn_pos))

Lematização do spaCy

O spaCy lematiza dentro do pipeline — ciente de POS e trata irregulares ('ate'->'eat', 'were'->'be') sem código extra. Usar lemma_ em vez de text colapsa 'cat'/'cats' numa única feature, reduzindo o tamanho do vocabulário. Para modelos multilíngues, a qualidade da lematização varia; confira o relatório de precisão do modelo.

nlp
import spacy
nlp = spacy.load("en_core_web_sm")

doc = nlp("The cats were running faster. I ate two apples.")
for tok in doc:
    if tok.text.lower() != tok.lemma_:
        print(f"{tok.text:10} -> {tok.lemma_}")
# cats       -> cat
# were       -> be
# running    -> run
# faster     -> fast
# ate        -> eat
# apples     -> apple

# context-aware, handles irregulars automatically
# use lemma_ instead of text for bag-of-words features
docs_tokens = [[t.lemma_.lower() for t in nlp(d) if not t.is_stop]
               for d in ["Cats run.", "The cat ran."]]

Stemming vs Lematização

Stemming é mais rápido, mas produz não-palavras e confunde demais para alguns usos. A lematização retorna palavras válidas e respeita o POS, ao custo de consultas ao dicionário. Para features bag-of-words, ambos reduzem vocabulário; para saída voltada ao usuário (ex.: listas de palavras-chave), sempre lematize. Para busca em escala massiva, stemming é a escolha pragmática.

nlp
import spacy
from nltk.stem import PorterStemmer
nlp = spacy.load("en_core_web_sm")
stem = PorterStemmer()

words = ["studies", "studying", "better", "feet", "running", "happily"]

print(f"{'word':12}{'stem':12}{'lemma':12}")
for w in words:
    lemma = nlp(w)[0].lemma_
    print(f"{w:12}{stem.stem(w):12}{lemma:12}")
# studies     studi       study
# studying    studi       study
# better      better      good      <- lemma handles irregular
# feet        feet        foot
# running     run         run
# happily     happili     happily

# rule of thumb:
#   search/indexing/topic-models -> stemming (fast)
#   interpretation/visualization -> lemmatization (accurate)
06

Stopwords

Stopwords do NLTK

O NLTK traz listas compactas de stopwords por linguagem (~180 palavras para o inglês). Use um set para busca O(1). Sempre converta para minúsculas antes de checar, já que as listas estão em minúsculas. A filtragem encolhe o vocabulário e remove palavras de baixa informação — útil para modelos de tópicos e índices de busca, mas prejudicial para sentimento ("not good" perde a negação).

nlp
import nltk
from nltk.corpus import stopwords
nltk.download('stopwords')

# 18 languages available
print(stopwords.fileids())
# ['arabic', 'english', 'french', 'german', 'spanish', ...]

en = set(stopwords.words('english'))
print(len(en))                # 179
print("the" in en)            # True
print("python" in en)         # False

# remove from a token list
from nltk.tokenize import word_tokenize
text = "The quick brown fox is very lazy indeed"
tokens = [w for w in word_tokenize(text.lower()) if w.isalpha()]
filtered = [w for w in tokens if w not in en]
print(filtered)   # ['quick', 'brown', 'fox', 'lazy']

Stopwords do spaCy

O spaCy marca is_stop por token, incluindo contrações ('isn't'). A lista padrão é maior que a do NLTK (326 palavras). Use is_stop junto com is_punct e is_alpha para extração limpa de palavras de conteúdo. A lista vive em nlp.Defaults.stop_words e pode ser editada em runtime por pipeline.

nlp
import spacy
nlp = spacy.load("en_core_web_sm")

# access the stopword set
print(len(nlp.Defaults.stop_words))        # 326
print("the" in nlp.Defaults.stop_words)    # True

# tokens expose is_stop directly
doc = nlp("The quick fox isn't lazy")
for tok in doc:
    print(f"{tok.text:8} is_stop={tok.is_stop}")
# The      is_stop=True
# quick    is_stop=False
# isn't    is_stop=True   (contraction included)

# content words only
content = [t.text for t in doc if not t.is_stop and not t.is_punct]

Removendo Stopwords com Segurança

Remover stopwords às cegas pode destruir informação: negações ('not good' -> 'good'), entidades multiverso ('New York' vai bem, mas 'out of' pode importar) e estrutura de perguntas ('What is X?' -> 'X?'). Para sentimento, sempre mantenha negadores. Para NER, nunca remova stopwords antes da extração de entidades.

nlp
import spacy
nlp = spacy.load("en_core_web_sm")

def remove_stopwords(text, keep_negations=True):
    doc = nlp(text)
    out = []
    for tok in doc:
        if tok.is_stop or tok.is_punct:
            # keep negations for sentiment tasks
            if keep_negations and tok.lemma_ in ("not", "no", "never"):
                out.append(tok.text)
                continue
            continue
        out.append(tok.text)
    return " ".join(out)

print(remove_stopwords("I do not like green eggs and ham."))
# 'not like green eggs ham .'

# bigrams preserve phrases that stopwords broke:
# 'New York' should NOT lose its inner stopwords...

Listas de Stopwords Personalizadas

Listas genéricas ignoram ruído de domínio ('reuters', 'inc', 'said' em notícias). Mina seu corpus em busca de palavras de altíssima frequência e baixa informação e as adicione. Inversamente, remova palavras que sua tarefa se importa (negações, verbos modais para detecção de postura). Salve o pipeline modificado, para que a lista personalizada viaje com o modelo.

nlp
import spacy
nlp = spacy.load("en_core_web_sm")

# add domain-specific stopwords
domain_stops = {"said", "says", "say", "according", "reuters", "inc", "ltd"}
for w in domain_stops:
    nlp.Defaults.stop_words.add(w)
    # also set the lexeme attribute
    lex = nlp.vocab[w]
    lex.is_stop = True

# remove a word that you DO want to keep
nlp.Defaults.stop_words.discard("not")
nlp.vocab["not"].is_stop = False

# persist by saving the modified model
# nlp.to_disk("my_model_with_stops")

Quando Manter Stopwords

Modelos profundos (BERT, GPT) foram treinados com texto natural incluindo stopwords — removê-las antes degrada o desempenho, porque o modelo depende de palavras funcionais para a sintaxe. A remoção de stopwords é um truque de engenharia de features para modelos rasos; avalie dos dois jeitos e mantenha o que pontuar mais alto na sua métrica de validação.

nlp
# Stopword removal HELPS:
#   - bag-of-words / TF-IDF (smaller vocab, less noise)
#   - topic modeling (LDA wants content words)
#   - search indexing (precision up, index smaller)

# Stopword removal HURTS:
#   - sentiment analysis ("not good" != "good")
#   - NER / entity extraction (alignment breaks)
#   - syntax parsing (function words are syntactic glue)
#   - transformer models (they were pretrained WITH stopwords)

from transformers import AutoTokenizer
tok = AutoTokenizer.from_pretrained("bert-base-uncased")
# NEVER strip stopwords before feeding BERT — the model
# expects natural text and uses function words syntactically.

# rule: only remove stopwords for shallow features (BoW/TF-IDF),
# and only if you've checked it doesn't hurt your metric.
07

Bag of Words e Vetorização

Básico do CountVectorizer

CountVectorizer transforma uma lista de strings numa matriz esparsa documento-termo. fit_transform aprende o vocabulário e transforma num único passo; transform reutiliza o vocabulário aprendido em dados novos (crítico — nunca re-fite em dados de teste). A matriz é esparsa para tratar vocabulários grandes com eficiência. O padrão de token padrão \b\w\w+\b descarta tokens de um caractere.

nlp
from sklearn.feature_extraction.text import CountVectorizer

docs = ["The cat sat on the mat.", "The dog sat on the log."]

# default: lowercase, word tokenizer (\b\w\w+\b), unigrams
vec = CountVectorizer()
X = vec.fit_transform(docs)
print(X.shape)            # (2, 6)  -> 2 docs, 6 unique words
print(vec.get_feature_names_out())
# ['cat' 'dog' 'log' 'mat' 'on' 'sat' 'the']

print(X.toarray())
# [[1 0 0 1 1 1 2]   'the' appears twice in doc 0
#  [0 1 1 0 1 1 2]]

# transform new text with the fitted vocabulary
new = vec.transform(["The cat and the dog."])

N-gramas

N-gramas capturam a ordem local de palavras que unigramas perdem — 'not good' vs 'good'. Bigramas aumentam o vocabulário drasticamente (quadrático), então combine com min_df (descarta raras) ou max_features (limita às top-K). Trigramas raramente compensam para bag-of-words; para contexto mais longo, troque para embeddings.

nlp
from sklearn.feature_extraction.text import CountVectorizer

docs = ["I love this movie", "I hate this movie"]

# unigrams + bigrams
vec = CountVectorizer(ngram_range=(1, 2))
X = vec.fit_transform(docs)
print(vec.get_feature_names_out())
# ['hate', 'hate this', 'love', 'love this', 'movie',
#  'this', 'this movie']

# bigrams capture phrases like "not good", "New York"
# but explode the vocabulary -> pair with min_df / max_features
vec2 = CountVectorizer(ngram_range=(2, 2), min_df=2)
# (2,2) = bigrams only; min_df=2 keeps bigrams seen >= 2 times

HashingVectorizer

HashingVectorizer é sem estado — faz hash de cada token para um índice de coluna, então não há vocabulário a guardar. Ótimo para streaming ou ambientes com pouca memória. A troca: você não pode inspecionar qual palavra uma coluna representa, e colisões mesclam features. Defina alternate_sign=False para evitar inversões de sinal que cancelam contagens em modelos lineares.

nlp
from sklearn.feature_extraction.text import HashingVectorizer

# stateless: no vocabulary kept, uses feature hashing
vec = HashingVectorizer(n_features=2**18, alternate_sign=False)
X = vec.transform(["doc one", "doc two"])
print(X.shape)   # (2, 262144)

# pros: no memory for vocabulary, streamable, fit_transform = transform
# cons: hashes are not interpretable, possible collisions,
#       no inverse_transform (can't map feature -> word)

# use for: very large / streaming corpora where you don't need
# to know which word a column corresponds to

Controle de Vocabulário

min_df e max_df são os controles mais úteis: descartam, respectivamente, erros de digitação raros e stopwords do corpus inteiro, encolhendo a matriz e reduzindo ruído. max_features limita o vocabulário por memória. Um token_pattern personalizado filtra por comprimento ou classe de caracteres. Um vocabulário fixo é prático quando você precisa manter as colunas estáveis entre execuções.

nlp
from sklearn.feature_extraction.text import CountVectorizer

docs = ["a a a b b c rareword commontoken"] * 5

vec = CountVectorizer(
    min_df=2,          # ignore terms in <2 docs
    max_df=0.9,        # ignore terms in >90% of docs (corpus-specific stops)
    max_features=1000, # keep only top-1000 by frequency
    stop_words='english',
    token_pattern=r"\b[a-z]{2,}\b",  # only 2+ letter words
)
X = vec.fit_transform(docs)
print(vec.get_feature_names_out())

# fix a custom vocabulary (only these words are counted)
vec_fixed = CountVectorizer(vocabulary=["cat", "dog", "fish"])
print(vec_fixed.get_feature_names_out())

Operações com Matrizes Esparsas

Matrizes documento-termo são esparsas (majoritariamente zeros) — mantenha-as esparsas para não explodir a memória (uma matriz densa float64 de 100k×50k precisaria de 40GB). Use .sum(axis=0), .multiply(), slicing sobre o objeto esparso. Só chame .toarray() em fatias pequenas. O formato CSR é otimizado para fatiamento de linhas; converta para CSC para fatiar colunas.

nlp
from sklearn.feature_extraction.text import CountVectorizer
import numpy as np
from scipy.sparse import csr_matrix

docs = ["the cat sat", "the dog ran", "the cat ran"]
vec = CountVectorizer()
X = vec.fit_transform(docs)   # CSR sparse matrix

print(type(X))                # <class 'scipy.sparse.csr_matrix'>
print(X.shape, X.nnz)         # (3, 5) 9 non-zero entries

# NEVER call .toarray() on huge matrices — they explode in memory.
# operate on sparse directly:
col_sums = np.asarray(X.sum(axis=0)).ravel()   # document frequency
print(dict(zip(vec.get_feature_names_out(), col_sums)))

# find docs containing a word
word_idx = vec.vocabulary_["cat"]
rows_with_cat = X[:, word_idx].nonzero()[0]
print("docs with 'cat':", rows_with_cat)   # [0, 2]
08

TF-IDF

Básico do TfidfVectorizer

TF-IDF reduz o peso de palavras que aparecem em muitos documentos (baixo poder discriminativo) e aumenta o de palavras raras e informativas. TfidfVectorizer combina CountVectorizer + TfidfTransformer e normaliza as linhas em L2, para que o comprimento do documento não domine. É a feature padrão para classificação de texto com modelos lineares.

nlp
from sklearn.feature_extraction.text import TfidfVectorizer

docs = ["the cat sat on the mat",
        "the dog sat on the log",
        "cats and dogs are pets"]

vec = TfidfVectorizer()        # default: L2-normalized rows
X = vec.fit_transform(docs)
print(vec.get_feature_names_out())

# tf-idf = term_freq * log(N / df) * (variations exist)
# down-weights words common across all docs ('the', 'sat')
print(X.toarray().round(3))

# each row is L2-normalized to length 1
import numpy as np
print(np.linalg.norm(X.toarray(), axis=1))   # [1. 1. 1.]

TfidfTransformer e Fórmula

smooth_idf adiciona +1 para evitar divisão por zero em termos não vistos. sublinear_tf troca contagens cruas por 1+log(contagem), limitando a influência de palavras muito frequentes dentro de um documento — útil para documentos longos, em que um termo pode repetir dezenas de vezes. norm='l2' é o padrão; use None se quiser magnitudes cruas.

nlp
from sklearn.feature_extraction.text import CountVectorizer, TfidfTransformer
from sklearn.pipeline import Pipeline

# equivalent to TfidfVectorizer but in two steps
pipe = Pipeline([
    ("counts", CountVectorizer()),
    ("tfidf", TfidfTransformer(
        norm='l2',
        use_idf=True,
        smooth_idf=True,        # idf = ln((1+N)/(1+df)) + 1  (avoids div-by-zero)
        sublinear_tf=False,     # if True: tf = 1 + log(count)
    )),
])

# sublinear_tf compresses high counts:
#   count 5 -> tf 5 (linear) vs tf 1+log(5)≈2.6 (sublinear)
# useful when a word repeating 100x isn't 100x more important
pipe2 = Pipeline([
    ("counts", CountVectorizer()),
    ("tfidf", TfidfTransformer(sublinear_tf=True)),
])

Interpretando Pesos TF-IDF

As features TF-IDF de topo por documento são um resumo rápido do seu conteúdo distintivo. Palavras presentes em cada um dos documentos têm idf≈1 (peso baixo); palavras num só documento têm o idf mais alto. Inspecione vec.idf_ para ver os pesos globais aprendidos. É uma ótima checagem de sanidade antes de treinar um classificador.

nlp
from sklearn.feature_extraction.text import TfidfVectorizer
import numpy as np

docs = ["machine learning models", "deep learning networks",
        "natural language processing"]

vec = TfidfVectorizer()
X = vec.fit_transform(docs)
names = vec.get_feature_names_out()

# top features per document
for i, doc in enumerate(docs):
    row = X[i].toarray().ravel()
    top = np.argsort(row)[::-1][:3]
    print(f"doc {i}: {[(names[j], round(row[j], 3)) for j in top]}")
# doc 0: [('machine', 0.58), ('models', 0.58), ('learning', 0.41)]
# doc 1: [('deep', 0.5), ('networks', 0.5), ...]
# doc 2: [('natural', 0.41), ('processing', 0.41), ('language', 0.41)]

# inspect the learned idf weights
idf = dict(zip(names, vec.idf_))
print(sorted(idf.items(), key=lambda x: x[1])[:3])   # lowest idf = most common

TF-IDF com N-gramas e Stopwords

Parear TF-IDF com bigramas preserva a negação ('not good') que unigramas perdem. stop_words='english' mais min_df encolhe o vocabulário. Esta combinação TfidfVectorizer + LinearSVC/LogisticRegression é uma baseline surpreendentemente forte — só a supere com BERT se tiver dados rotulados suficientes.

nlp
from sklearn.feature_extraction.text import TfidfVectorizer

docs = ["not good at all", "very good indeed", "not bad actually"]

vec = TfidfVectorizer(
    stop_words='english',
    ngram_range=(1, 2),        # unigrams + bigrams
    min_df=1,
    sublinear_tf=True,
    max_features=5000,
)
X = vec.fit_transform(docs)
print(vec.get_feature_names_out())
# bigrams like 'not good', 'not bad' preserve negation

# this combination is a strong baseline for text classification
# with LogisticRegression or LinearSVC

TF-IDF para Similaridade e Busca

Similaridade de cosseno sobre vetores TF-IDF é uma baseline clássica de busca por palavras-chave: consulta e documentos viram vetores, ranqueados pelo ângulo de cosseno. Funciona sem nenhum dado de treino, mas só casa vocabulário compartilhado — texto semanticamente parecido, mas lexicalmente diferente ('ML' vs 'machine learning') não casa. Use embeddings (sentence-transformers) para busca semântica.

nlp
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity

corpus = [
    "Machine learning is fun",
    "Python is great for ML",
    "I love cooking pasta",
]
query = ["learning machine"]

vec = TfidfVectorizer()
X = vec.fit_transform(corpus)
q = vec.transform(query)

# cosine similarity between query and each doc
sims = cosine_similarity(q, X).ravel()
for doc, score in sorted(zip(corpus, sims), key=lambda x: -x[1]):
    print(f"{score:.3f}  {doc}")
# 0.580  Machine learning is fun
# 0.000  I love cooking pasta

# this is essentially a tiny search engine
09

Word Embeddings (Word2Vec / GloVe / FastText)

Word2Vec do gensim

Word2Vec aprende vetores densos prevendo o contexto (skip-gram) ou uma palavra a partir do contexto (CBOW). skip-gram (sg=1) funciona melhor com dados pequenos e palavras raras; CBOW é mais rápido. min_count filtra palavras raras. Modelos reais precisam de milhões de tokens — treine na Wikipédia ou use vetores pré-treinados para a maioria das aplicações.

nlp
from gensim.models import Word2Vec
from gensim.utils import simple_preprocess

sentences = [
    "the cat sat on the mat".split(),
    "the dog sat on the log".split(),
    "cats and dogs are pets".split(),
]
# simple_preprocess lowercases and tokenizes
sents = [simple_preprocess(" ".join(s)) for s in sentences]

model = Word2Vec(
    sentences=sents,
    vector_size=100,    # embedding dimension
    window=5,           # context window size
    min_count=1,        # ignore words with freq < min_count
    workers=4,
    sg=1,               # 1 = skip-gram, 0 = CBOW
    epochs=10,
)

print(model.wv["cat"].shape)            # (100,)
print(model.wv.most_similar("cat", topn=3))

Treinando Embeddings Personalizados

Use um gerador (SentenceIterator) para que o corpus seja transmitido do disco — o gensim é construído para streaming e nunca segura tudo na RAM. min_count=5 remove erros de digitação e palavras raras. negative=10 é o padrão para skip-gram. Salve e retome o treino quando chegarem mais dados. Avalie com tarefas de analogia e similaridade antes de implantar.

nlp
from gensim.models import Word2Vec
from gensim.utils import simple_preprocess
from pathlib import Path

# read a large corpus line by line (don't load all into memory)
class SentenceIterator:
    def __init__(self, path):
        self.path = Path(path)
    def __iter__(self):
        for line in self.path.open(encoding="utf-8"):
            yield simple_preprocess(line)

sentences = SentenceIterator("corpus.txt")

model = Word2Vec(
    sentences,
    vector_size=200,
    window=8,
    min_count=5,         # drop very rare words
    workers=8,
    epochs=5,
    negative=10,         # negative samples per positive (skip-gram)
)
model.save("w2v.model")

# resume training later
# model = Word2Vec.load("w2v.model")
# model.train(more_sentences, total_examples=len(more), epochs=5)

Similaridade e Analogia

O word2vec captura famosa relações de analogia (king - man + woman ≈ queen), porque contextos similares produzem vetores similares. similarity retorna cosseno em [-1, 1]. doesnt_match é um detector divertido de outliers. Os vetores pré-treinados do Google News cobrem 3M de palavras, mas têm 3GB; GloVe ou fastText costumam ser mais práticos.

nlp
from gensim.models import KeyedVectors

# load pretrained Google News vectors (3GB, 3M words)
# Download: https://code.google.com/archive/p/word2vec/
model = KeyedVectors.load_word2vec_format("GoogleNews-vectors-negative300.bin",
                                          binary=True)

# similarity
print(model.similarity("cat", "dog"))        # ~0.86
print(model.similarity("cat", "car"))        # ~0.28

# analogy: king - man + woman = queen
print(model.most_similar(positive=["king", "woman"],
                         negative=["man"], topn=1))
# [('queen', 0.71)]

# odd one out
print(model.doesnt_match("cat dog car horse".split()))   # 'car'

# which word doesn't fit
print(model.most_similar("python", topn=5))

FastText

FastText estende o Word2Vec aprendendo vetores para n-gramas de caracteres (subpalavras), então consegue embutir palavras não vistas ('catting' a partir de 'cat'+'ing'). Isso ajuda muito para linguagens morfologicamente ricas e erros de digitação. Um pouco mais lento que Word2Vec pela consulta de subpalavras, mas o tratamento de OOV compensa na maioria dos textos reais.

nlp
from gensim.models import FastText

sentences = [
    "the cat sat on the mat".split(),
    "dogs and cats are friends".split(),
]

# FastText learns subword (character n-gram) embeddings
model = FastText(
    sentences,
    vector_size=100,
    window=5,
    min_count=1,
    min_n=3,            # min char n-gram
    max_n=6,            # max char n-gram
    epochs=10,
)

# KEY advantage: handles out-of-vocabulary words
print("catting" in model.wv)            # False (not seen in training)
print(model.wv["catting"].shape)        # (100,)  -> still gets a vector!
# vector is averaged from subword n-grams of 'catting'

print(model.wv.most_similar("cat", topn=3))

Carregando Vetores GloVe

GloVe (Global Vectors) é treinado em contagens de co-ocorrência, não em previsões, produzindo vetores comparáveis ao Word2Vec. Stanford distribui versões de 50/100/200/300 dimensões treinadas em 6B tokens. Converta para o formato gensim para reutilizar a API Word2Vec. Para vetores de 300d, espere ~1.5GB em memória.

nlp
# GloVe: pretrained on Wikipedia+Gigaword
# Download: https://nlp.stanford.edu/projects/glove/
# Files: glove.6B.50d.txt, glove.6B.100d.txt, glove.6B.200d.txt, glove.6B.300d.txt

from gensim.scripts.glove2word2vec import glove2word2vec
from gensim.models import KeyedVectors

# convert GloVe format to word2vec format (one-time)
glove2word2vec("glove.6B.100d.txt", "glove.6B.100d.w2v.txt")

# load
glove = KeyedVectors.load_word2vec_format("glove.6B.100d.w2v.txt")
print(glove["king"].shape)        # (100,)
print(glove.most_similar("king", topn=3))

# fast alternative: load directly into a dict
import numpy as np
def load_glove(path, dim=100):
    embeddings = {}
    with open(path, encoding="utf-8") as f:
        for line in f:
            parts = line.split()
            embeddings[parts[0]] = np.asarray(parts[1:], dtype="float32")
    return embeddings

Visualizando Embeddings com t-SNE

t-SNE projeta vetores de alta dimensão em 2D para visualização — pontos próximos no gráfico são similares no espaço de embedding. Use perplexity entre 5 e 50, conforme a contagem de pontos. Nota: t-SNE distorce distâncias globais, então use para exploração, não para medição. UMAP costuma preservar a estrutura melhor que t-SNE.

nlp
import numpy as np
import matplotlib.pyplot as plt
from sklearn.manifold import TSNE
from gensim.models import KeyedVectors

model = KeyedVectors.load_word2vec_format("glove.6B.100d.w2v.txt")

# pick a small set of related words
words = ["king", "queen", "man", "woman", "paris", "france",
         "london", "england", "dog", "cat", "horse", "cow"]
vectors = np.array([model[w] for w in words])

# reduce 100d -> 2d with t-SNE
tsne = TSNE(n_components=2, random_state=42, perplexity=5)
coords = tsne.fit_transform(vectors)

plt.figure(figsize=(8, 6))
for w, (x, y) in zip(words, coords):
    plt.scatter(x, y)
    plt.annotate(w, (x, y), xytext=(5, 5), textcoords="offset points")
plt.savefig("embeddings_tsne.png", dpi=120)
plt.show()
10

Embeddings Contextuais (BERT)

Básico do Transformers do Hugging Face

AutoTokenizer/AutoModel selecionam automaticamente a classe certa a partir de um nome de modelo no Hugging Face Hub — sem precisar saber se é BERT, RoBERTa ou DistilBERT. last_hidden_state tem um vetor de 768-d por token; pooler_output é a representação do [CLS]. Para embeddings de frases, [CLS] sozinho costuma ser fraco — use um sentence-transformer.

nlp
from transformers import AutoTokenizer, AutoModel
import torch

# load any pretrained model by name from the Hub
model_name = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)

inputs = tokenizer("Hello, BERT!", return_tensors="pt")
print(inputs.keys())   # input_ids, token_type_ids, attention_mask

with torch.no_grad():
    outputs = model(**inputs)

# last hidden state: (batch, seq_len, hidden_size)
print(outputs.last_hidden_state.shape)   # torch.Size([1, 6, 768])

# pooled output: [CLS] token passed through a linear+tanh
print(outputs.pooler_output.shape)        # torch.Size([1, 768])

Embeddings de Tokens do BERT

O traço definidor do BERT: o vetor de 'bank' difere em 'river bank' vs 'bank account', porque a atenção incorpora contexto. Isso resolve a polissemia, a maior fraqueza do Word2Vec/GloVe. O vetor de cada token é uma representação contextualizada de 768-d construída da sequência inteira.

nlp
from transformers import AutoTokenizer, AutoModel
import torch

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased")

# contextual: 'bank' embeds differently in river vs money context
texts = ["I sat by the river bank.", "I deposited cash at the bank."]
for t in texts:
    inputs = tokenizer(t, return_tensors="pt")
    with torch.no_grad():
        out = model(**inputs)
    # find the index of 'bank'
    idx = (inputs["input_ids"][0] == tokenizer.convert_tokens_to_ids("bank")).nonzero()[0]
    vec = out.last_hidden_state[0, idx[0]]
    print(f"{t[:25]:25} bank-vec[:3] = {vec[:3].tolist()}")

# the two 'bank' vectors DIFFER -> this is the whole point of BERT
# (static embeddings like Word2Vec would give the same vector both times)

Sentence Transformers

O [CLS] do BERT puro é um embedding de frase fraco (pontuações de similaridade não são confiáveis). sentence-transformers faz fine-tuning com perdas contrastivas, para que a similaridade de cosseno reflita a proximidade semântica. all-MiniLM-L6-v2 é a escolha padrão: 384-d, rápido e competitivo com modelos muito maiores. Ideal para busca semântica, clustering e deduplicação.

nlp
# pip install sentence-transformers
from sentence_transformers import SentenceTransformer, util

# models tuned to produce good sentence-level embeddings
model = SentenceTransformer("all-MiniLM-L6-v2")   # 384d, fast & strong

sentences = [
    "The cat sits on the mat.",
    "A feline is resting on a rug.",
    "Machine learning is fascinating.",
]
emb = model.encode(sentences, convert_to_tensor=True, normalize_embeddings=True)

# semantic similarity via cosine
print(util.cos_sim(emb, emb).round(3))
# [[1.    0.678 0.089]
#  [0.678 1.    0.107]
#  [0.089 0.107 1.   ]]

# semantic search: rank corpus by similarity to a query
query = model.encode("where is the cat?", convert_to_tensor=True)
hits = util.semantic_search(query, emb)[0]
print(hits)   # ranks 'cat sits on the mat' highest

Embeddings Pooled vs por Token

Camadas diferentes codificam informação diferente: camadas baixas são sintáticas, altas são semânticas. [CLS] funciona para classificação (com fine-tuning), mas mean-pooling é geralmente um melhor vetor de frase gratuito. Concatenar as últimas 4 camadas era a receita original de extração de features do BERT e ainda funciona bem para tarefas no nível de token, como NER.

nlp
from transformers import AutoTokenizer, AutoModel
import torch

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased", output_hidden_states=True)

inputs = tokenizer("I love NLP", return_tensors="pt")
with torch.no_grad():
    out = model(**inputs)

# all 13 layers (embedding + 12 transformer layers)
hidden = out.hidden_states          # tuple of (1, seq, 768), len 13
print(len(hidden), hidden[0].shape)

# common pooling strategies for a sentence vector:
# 1. [CLS] token of the last layer
cls = hidden[-1][:, 0, :]
# 2. mean-pool over tokens (often better than [CLS])
mask = inputs["attention_mask"].unsqueeze(-1).float()
mean = (hidden[-1] * mask).sum(1) / mask.sum(1)
# 3. concat last 4 layers (rich feature, used in early BERT papers)
cat = torch.cat([hidden[-i][:, 0, :] for i in range(1, 5)], dim=-1)
print(cls.shape, mean.shape, cat.shape)   # all (1, 768) except cat (1, 3072)

Comparação Estático vs Contextual

Embeddings estáticos são 100-300x menores e mais rápidos que BERT, mas não distinguem sentidos de palavras. Para tarefas em que o contexto importa (sentimento, NER, QA), embeddings contextuais vencem. Para similaridade pura de palavras, clustering de um vocabulário grande ou execução em CPU em escala, embeddings estáticos ainda são competitivos — escolha pela tarefa e pelo orçamento.

nlp
import numpy as np
from gensim.models import KeyedVectors
from sentence_transformers import SentenceTransformer

# STATIC (Word2Vec/GloVe): same vector regardless of context
w2v = KeyedVectors.load_word2vec_format("glove.6B.100d.w2v.txt")
v1 = w2v["bank"]
v2 = w2v["bank"]
print("static cosine (always 1.0):", np.dot(v1, v2) / (np.linalg.norm(v1)*np.linalg.norm(v2)))

# CONTEXTUAL (BERT): vector depends on surrounding text
bert = SentenceTransformer("all-MiniLM-L6-v2")
from sklearn.metrics.pairwise import cosine_similarity
e_river = bert.encode("sat by the river bank")
e_money = bert.encode("deposited at the bank")
print("contextual cosine of two sentences:", cosine_similarity([e_river], [e_money])[0, 0].round(3))

# trade-offs:
#   static:   small, fast, fixed vocabulary, OOV-friendly only with FastText
#   contextual: large, slower, handles polysemy, needs GPU for speed
11

Classificação de Texto

Pipeline sklearn para Texto

Este pipeline TfidfVectorizer + LogisticRegression é a baseline canônica de classificação de texto — rápida, interpretável e difícil de bater sem deep learning. Pipeline embrulha pré-processamento + modelo, para que as mesmas transformações se apliquem na previsão. class_weight='balanced' ajuda com classes desbalanceadas. Sempre reporte precisão/recall por classe, não só acurácia.

nlp
from sklearn.pipeline import Pipeline
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.metrics import classification_report

# X: list of strings, y: labels
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2,
                                                    stratify=y, random_state=42)

clf = Pipeline([
    ("tfidf", TfidfVectorizer(ngram_range=(1, 2), min_df=2,
                              sublinear_tf=True, stop_words="english")),
    ("clf", LogisticRegression(max_iter=1000, class_weight="balanced")),
])

clf.fit(X_train, y_train)
print(classification_report(y_test, clf.predict(X_test)))

# predict on new text
print(clf.predict(["this is a great movie"]))   # ['positive']

Naive Bayes para Texto

Naive Bayes é o classificador de texto mais simples — rápido, funciona em datasets minúsculos, e a suposição 'ingênua' de independência entre palavras é violada, mas ainda funciona bem na prática. MultinomialNB recebe contagens (ou TF-IDF); BernoulliNB recebe presença binária. ComplementNB é projetado especificamente para classes desbalanceadas e frequentemente supera o Multinomial em texto.

nlp
from sklearn.feature_extraction.text import CountVectorizer
from sklearn.naive_bayes import MultinomialNB
from sklearn.pipeline import Pipeline

clf = Pipeline([
    ("vec", CountVectorizer()),
    ("clf", MultinomialNB(alpha=1.0)),    # alpha = Laplace smoothing
])
clf.fit(X_train, y_train)

# MultinomialNB assumes word counts -> use CountVectorizer (not TF-IDF)
# alpha=1 (default) adds one to every count -> avoids zero probabilities
# lower alpha (0.1) for less smoothing when you have lots of data

# variants:
#   MultinomialNB - counts/TF-IDF (most common for text)
#   BernoulliNB   - binary features (word present/absent)
#   ComplementNB  - better on imbalanced text classes

SVM Linear para Texto

LinearSVC é frequentemente o melhor classificador raso de texto — rápido, amigável a dados esparsos e de alta precisão em features TF-IDF. O lado ruim: não tem predict_proba nativo. Envolva com CalibratedClassifierCV se precisar de pontuações de probabilidade (ex.: para ajuste de limiar). Ajuste C com grid search; valores em torno de 0.1-10 costumam funcionar.

nlp
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.svm import LinearSVC
from sklearn.pipeline import Pipeline
from sklearn.calibration import CalibratedClassifierCV

# LinearSVC is much faster than SVC(kernel='linear') on sparse text
clf = Pipeline([
    ("tfidf", TfidfVectorizer(sublinear_tf=True)),
    ("clf", LinearSVC(C=1.0)),     # C = inverse regularization
])

# LinearSVC has no predict_proba by default; wrap if you need probabilities
calibrated = CalibratedClassifierCV(LinearSVC(), cv=3)
clf_prob = Pipeline([("tfidf", TfidfVectorizer()),
                     ("clf", calibrated)])

# tune C: smaller C = more regularization (helps with noisy text)
# LinearSVC is often the strongest shallow text classifier

Fine-tuning do BERT para Classificação

Fazer fine-tuning de um BERT/DistilBERT pré-treinado numa cabeça de classificação dá resultados de ponta quando você tem alguns milhares de exemplos rotulados. DistilBERT é ~40% menor e mais rápido que BERT com ~95% da qualidade — um ótimo padrão. Use uma taxa de aprendizado baixa (2e-5) e 2-4 épocas; mais épocas causam overfitting. O Trainer cuida de batching, precisão mista e logging.

nlp
from transformers import (AutoTokenizer, AutoModelForSequenceClassification,
                          TrainingArguments, Trainer)
import torch

model_name = "distilbert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(
    model_name, num_labels=3
)

# tokenize the dataset
def tokenize(batch):
    return tokenizer(batch["text"], padding="max_length",
                     truncation=True, max_length=128)

train_ds = dataset["train"].map(tokenize, batched=True)
train_ds.set_format("torch", columns=["input_ids", "attention_mask", "label"])

args = TrainingArguments(
    output_dir="./clf",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    learning_rate=2e-5,
    eval_strategy="epoch",
)
trainer = Trainer(model=model, args=args,
                  train_dataset=train_ds, eval_dataset=dataset["test"])
trainer.train()

Classificação Multi-Rótulo

Multi-rótulo difere de multi-classe: cada instância pode ter zero, um ou muitos rótulos. OneVsRestClassifier treina um classificador binário por rótulo. Use F1 micro/macro (não acurácia) — acurácia num espaço de 100 rótulos induz a erro. Para BERT, troque softmax por um sigmoid por rótulo e use BCEWithLogitsLoss.

nlp
# multi-label: each document can have MULTIPLE tags
# (e.g. a news article is both 'politics' AND 'economy')

from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.multiclass import OneVsRestClassifier
from sklearn.pipeline import Pipeline
from sklearn.metrics import f1_score

# y is a (n_samples, n_labels) binary matrix, NOT a 1-d array
clf = Pipeline([
    ("tfidf", TfidfVectorizer()),
    ("clf", OneVsRestClassifier(LogisticRegression(max_iter=1000))),
])
clf.fit(X_train, Y_train)         # Y_train: 2D binary array

# predict returns a 2D matrix
pred = clf.predict(X_test)
print(f1_score(Y_test, pred, average="micro"))

# alternatives:
#   MultiLabelBinarizer to convert list-of-labels -> 2D matrix
#   BinaryRelevance / ClassifierChains from scikit-multilearn
#   BERT with sigmoid + BCEWithLogitsLoss (one head per label)

Métricas de Avaliação

A acurácia mente em dados desbalanceados — um detector de spam 99%-negativo pontua 99% prevendo 'não spam' sempre. F1 macro trata todas as classes igualmente (melhor para desbalanceado), F1 micro é dominado pela classe majoritária, F1 weighted é um meio-termo. Sempre olhe precisão/recall por classe para achar classes fracas antes de implantar.

nlp
from sklearn.metrics import (classification_report, confusion_matrix,
                              f1_score, precision_recall_fscore_support)

y_true = [0, 0, 1, 1, 2, 2]
y_pred = [0, 1, 1, 1, 2, 0]

# per-class precision / recall / F1
print(classification_report(y_true, y_pred, digits=3))

# F1 averaging strategies (multi-class):
#   macro  : average F1 over classes (treats all classes equally)
#   micro  : aggregate then compute (dominated by majority class)
#   weighted: average weighted by class support
print("macro F1:", f1_score(y_true, y_pred, average="macro"))
print("micro F1:", f1_score(y_true, y_pred, average="micro"))

# confusion matrix
print(confusion_matrix(y_true, y_pred))

# ROC-AUC needs probabilities; for multi-class use roc_auc_score with multi_class='ovr'
12

Análise de Sentimento

VADER (Baseado em Léxico)

VADER é baseado em regras, sem necessidade de dados de treino — perfeito para redes sociais (trata emoticons, caixa, 'kinda', '!'). compound é a pontuação unidimensional recomendada. Ele sofre com sarcasmo e sentimento dependente de contexto. VADER é só inglês; para outras linguagens, use um modelo transformer ou traduza primeiro.

nlp
import nltk
from nltk.sentiment.vader import SentimentIntensityAnalyzer
nltk.download('vader_lexicon')

sia = SentimentIntensityAnalyzer()

for text in ["I love this!", "This is terrible :(",
             "It's okay, not great."]:
    scores = sia.polarity_scores(text)
    print(f"{text:25} {scores}")
# {'neg': 0.0, 'neu': 0.308, 'pos': 0.692, 'compound': 0.636}
# {'neg': 0.679, 'neu': 0.321, 'pos': 0.0, 'compound': -0.476}
# {'neg': 0.323, 'neu': 0.677, 'pos': 0.0, 'compound': -0.226}

# compound: normalized score in [-1, 1]
# common thresholds: >0.05 positive, <-0.05 negative, else neutral

Sentimento do TextBlob

TextBlob embrulha um léxico baseado em Pattern e dá polaridade e subjetividade numa única chamada. A subjetividade é útil para filtrar texto factual de opinativo. TextBlob é menos robusto em redes sociais que VADER (sem tratamento de emoticons), mas mais simples. Ambos são baselines — um transformer com fine-tuning os supera sempre que você tiver dados rotulados.

nlp
from textblob import TextBlob   # pip install textblob

for text in ["I love NLP.", "This is the worst experience.",
             "The movie was okay."]:
    blob = TextBlob(text)
    print(f"{text:30} polarity={blob.sentiment.polarity:.2f} "
          f"subjectivity={blob.sentiment.subjectivity:.2f}")
# I love NLP.                    polarity=0.50 subjectivity=0.60
# This is the worst experience.  polarity=-0.60 subjectivity=0.75
# The movie was okay.            polarity=0.00 subjectivity=0.00

# polarity:     [-1, 1]  negative to positive
# subjectivity: [0, 1]   objective (fact) to subjective (opinion)

# also gives noun phrases, translation, etc.
print(blob.noun_phrases)

Sentimento Baseado em Transformer

Um modelo de sentimento pré-treinado do Hub dá resultados de qualidade de produção com zero dados de treino. O pipeline zero-shot é mágico para prototipagem rápida: passe quaisquer rótulos candidatos e ele os ranqueia via NLI. Zero-shot é menos preciso que um modelo com fine-tuning, mas inestimável quando os rótulos são desconhecidos ou mudam com frequência.

nlp
from transformers import pipeline

# zero-shot: pick any labels you want, no fine-tuning
clf = pipeline("sentiment-analysis",
               model="distilbert-base-uncased-finetuned-sst-2-english")
print(clf(["I love this product!", "Worst purchase ever."]))
# [{'label': 'POSITIVE', 'score': 0.9998}, {'label': 'POSITIVE'...}]

# zero-shot classification: works on ANY label set
zero = pipeline("zero-shot-classification",
                model="facebook/bart-large-mnli")
print(zero("The battery lasts only an hour.",
           candidate_labels=["positive", "negative", "neutral"]))
# {'labels': ['negative', 'neutral', 'positive'], 'scores': [0.95, ...]}

Modelo de Sentimento com Fine-Tuning

Fine-tuning com seus próprios dados rotulados supera qualquer modelo de sentimento pronto, porque as definições de rótulo diferem (5 estrelas vs 3 classes vs por aspecto). Use uma taxa de aprendizado pequena (2e-5), 2-4 épocas, e acompanhe a perda de validação para overfitting. A biblioteca 'evaluate' reúne métricas padrão. Salve o modelo com trainer.save_model().

nlp
from transformers import (AutoTokenizer, AutoModelForSequenceClassification,
                          Trainer, TrainingArguments)
import evaluate

model_name = "distilbert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)

def tokenize(batch):
    return tokenizer(batch["text"], truncation=True, padding="max_length")

train_ds = dataset["train"].map(tokenize, batched=True)
train_ds = train_ds.rename_column("label", "labels")
train_ds.set_format("torch")

accuracy = evaluate.load("accuracy")

def compute_metrics(eval_pred):
    logits, labels = eval_pred
    preds = logits.argmax(axis=-1)
    return accuracy.compute(predictions=preds, references=labels)

args = TrainingArguments("sentiment", num_train_epochs=3,
                         per_device_train_batch_size=16,
                         eval_strategy="epoch", learning_rate=2e-5)
trainer = Trainer(model=model, args=args, train_dataset=train_ds,
                  eval_dataset=dataset["test"], compute_metrics=compute_metrics)
trainer.train()

Sentimento Baseado em Aspecto

A análise de sentimento por aspecto (ABSA) decompõe uma avaliação em opiniões por aspecto — muito mais útil que uma única pontuação no nível do documento para feedback de produtos. Zero-shot com NLI serve como protótipo rápido; para produção, faça fine-tuning de um classificador de par de sequência (aspecto, texto) -> sentimento, ou use bibliotecas especializadas como pyabsa. LLMs com prompts estruturados também são competitivos.

nlp
# Aspect-based sentiment: sentiment TOWARD a specific aspect
# "The food was great but the service was slow."
#   food -> positive, service -> negative

from transformers import pipeline

# approach 1: zero-shot on each aspect
zero = pipeline("zero-shot-classification", model="facebook/bart-large-mnli")
text = "The food was great but the service was slow."
for aspect in ["food", "service"]:
    result = zero(text, candidate_labels=["positive", "negative", "neutral"])
    print(f"{aspect}: {result['labels'][0]} ({result['scores'][0]:.2f})")

# approach 2: pyabsa library (specialized for ABSA)
# pip install pyabsa
# from pyabsa import AspectTermExtraction as ATE
# analyzer = ATE.AspectExtractor('english', auto_device=True)
# print(analyzer.predict(text))

# approach 3: prompt an LLM with aspect + text -> label
13

Modelagem de Tópicos

LDA com gensim

LDA (Latent Dirichlet Allocation) modela cada documento como uma mistura de tópicos e cada tópico como uma distribuição sobre palavras. O LdaModel do gensim é a implementação padrão. O pré-processamento importa: remova stopwords, lematize e filtre extremos (palavras muito comuns/raras) antes de ajustar. num_topics é o hiperparâmetro-chave — use coerência para escolhê-lo.

nlp
from gensim.corpora import Dictionary
from gensim.models import LdaModel

docs = [["cat", "dog", "pet"],
        ["dog", "bark", "pet"],
        ["python", "code", "program"],
        ["code", "bug", "python"]]

dictionary = Dictionary(docs)
corpus = [dictionary.doc2bow(d) for d in docs]   # bag-of-words

lda = LdaModel(
    corpus=corpus,
    id2word=dictionary,
    num_topics=2,
    passes=10,             # iterations over the corpus
    random_state=42,
    alpha="auto",          # document-topic prior
    eta="auto",            # topic-word prior
)

# top words per topic
for topic_id, words in lda.print_topics(num_words=4):
    print(f"Topic {topic_id}: {words}")

LDA com sklearn

O LDA do sklearn se integra ao pipeline CountVectorizer, mas é mais lento e usa mais memória que o gensim em corpora grandes. Use learning_method='online' para streaming. components_ dá as distribuições tópico-palavra; transform(X) dá as distribuições documento-tópico. Defina random_state por reprodutibilidade — LDA é sensível à inicialização.

nlp
from sklearn.feature_extraction.text import CountVectorizer
from sklearn.decomposition import LatentDirichletAllocation

docs = ["cat dog pet", "dog bark pet", "python code program", "code bug python"]
vec = CountVectorizer(max_df=0.9, min_df=2, stop_words="english")
X = vec.fit_transform(docs)

lda = LatentDirichletAllocation(
    n_components=3,
    learning_method="batch",   # 'online' for large corpora
    max_iter=20,
    random_state=42,
)
lda.fit(X)

# top words per topic
words = vec.get_feature_names_out()
for i, topic in enumerate(lda.components_):
    top = [words[j] for j in topic.argsort()[:-6:-1]]
    print(f"Topic {i}: {top}")

NMF (Fatoração de Matriz Não Negativa)

NMF fatora a matriz TF-IDF em W (doc-tópico) e H (tópico-palavra) não negativas. É mais rápida que LDA e frequentemente produz tópicos mais coerentes em textos curtos, porque não faz as suposições probabilísticas da LDA. LDA precisa de dados de contagem (TF-IDF quebra sua suposição generativa); NMF funciona com TF-IDF e se beneficia disso.

nlp
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.decomposition import NMF

docs = ["machine learning models", "deep learning networks",
        "natural language processing", "cooking recipes food"]

vec = TfidfVectorizer(max_features=1000, stop_words="english")
X = vec.fit_transform(docs)

nmf = NMF(n_components=2, random_state=42, l1_ratio=0.5, alpha_W=0.1)
W = nmf.fit_transform(X)   # document-topic
H = nmf.components_         # topic-word

words = vec.get_feature_names_out()
for i, topic in enumerate(H):
    print(f"Topic {i}: {[words[j] for j in topic.argsort()[:-6:-1]]}")
# NMF works with TF-IDF (LDA needs counts); topics are often cleaner
# on short documents

Coerência e Escolha de K

Coerência mede quão semanticamente relacionadas estão as palavras de topo de cada tópico — quanto maior, melhor. c_v é a métrica mais confiável. Plote coerência vs k e procure o 'cotovelo' ou pico. Não existe K de verdade absoluta, então inspecione os tópicos manualmente também: se dois tópicos são quase duplicados, reduza K. Tópicos com palavras genéricas ('get', 'make') sinalizam K grande demais.

nlp
from gensim.models import CoherenceModel, LdaModel
from gensim.corpora import Dictionary

# compare LDA models with different numbers of topics
dictionary = Dictionary(docs)
corpus = [dictionary.doc2bow(d) for d in docs]

scores = []
for k in range(2, 11):
    lda = LdaModel(corpus=corpus, id2word=dictionary,
                   num_topics=k, passes=10, random_state=42)
    cm = CoherenceModel(model=lda, texts=docs,
                        dictionary=dictionary, coherence="c_v")
    score = cm.get_coherence()
    scores.append((k, score))
    print(f"k={k}: coherence={score:.3f}")

# pick the k with highest coherence (or where scores plateau)
# c_v in [0,1]; >0.5 is usually interpretable

Visualização com pyLDAvis

pyLDAvis é a visualização de fato para modelos de tópicos: cada bolha é um tópico, dimensionada pela prevalência e posicionada pela distância aos outros (sobreposição = tópicos similares). O painel direito mostra as palavras mais relevantes por tópico com um slider de lambda — lambda menor destaca palavras distintivas sobre meramente frequentes. Ótimo para explicar tópicos a partes interessadas.

nlp
# pip install pyldavis
import pyLDAvis
import pyLDAvis.gensim_models as gensimvis

# (assuming lda, corpus, dictionary from above)
vis = gensimvis.prepare(lda, corpus, dictionary)

# save as standalone HTML
pyLDAvis.save_html(vis, "lda_vis.html")
# open in a browser: bubbles = topics, sized by prevalence,
# positioned by inter-topic distance (PCoA on topic-word distances)

#pyLDAvis.enable_notebook()   # inline in Jupyter
#vis

# lambda slider: 1 = pure relevance by frequency,
# 0.6 = lift (rare-but-distinctive words rise)

BERTopic (Modelagem Neural de Tópicos)

BERTopic é um pipeline neural moderno: embeddings de frases (padrão = um transformer) -> UMAP para redução de dimensionalidade -> HDBSCAN para clustering -> c-TF-IDF para representação de tópicos. Não precisa de num_topics (HDBSCAN os acha) e trata textos curtos muito melhor que LDA. Mais lento que LDA, mas produz tópicos mais coerentes; ajuste o modelo de embedding ao seu domínio.

nlp
# pip install bertopic
from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

docs = fetch_20newsgroups(subset="all")["data"][:1000]

# BERTopic: embeddings -> dimensionality reduction -> clustering
topic_model = BERTopic(
    language="english",
    calculate_probabilities=True,
    verbose=True,
)
topics, probs = topic_model.fit_transform(docs)

print(topic_model.get_topic_info().head())
print(topic_model.get_topic(0))   # top words for topic 0

# visualize
# topic_model.visualize_topics()
# topic_model.visualize_barchart()

# BERTopic finds the number of topics automatically (via HDBSCAN clusters)
14

Geração de Texto

Modelo de Linguagem por N-gramas

Um modelo de linguagem por n-gramas conta com que frequência cada palavra segue as n-1 anteriores e prevê a próxima palavra amostrando dessa distribuição. Bigramas são simples, mas com contexto limitado; trigramas/4-gramas melhoram a coerência, mas precisam de mais dados. Suavização (add-k, Kneser-Ney) trata contextos não vistos. Baseline útil para autocomplete e geração de texto simples.

nlp
import nltk
from nltk.util import ngrams
from collections import defaultdict, Counter

text = "the cat sat on the mat the dog sat on the log".split()
n = 2   # bigram model

# count bigram occurrences
model = defaultdict(Counter)
for w1, w2 in ngrams(text, n):
    model[w1][w2] += 1

# convert counts to probabilities
for w1 in model:
    total = sum(model[w1].values())
    for w2 in model[w1]:
        model[w1][w2] /= total

# generate next word given a context
import random
context = ("the",)
candidates = model[context[0]]
print(candidates)   # Counter({'cat': 0.25, 'dog': 0.25, 'mat': 0.25, 'log': 0.25})
print(random.choices(list(candidates), weights=candidates.values())[0])

Gerador de Texto por Cadeia de Markov

Uma cadeia de Markov é o modelo generativo mais simples: estado = últimas N palavras, próxima palavra amostrada das transições observadas. Captura o estilo local (frases comuns), mas nenhuma coerência de longo alcance — a saída se desvia após algumas palavras. Aumentar a ordem melhora a coerência, mas precisa exponencialmente de mais dados. Divertido para paródias estilizadas; não para geração de produção.

nlp
import random
from collections import defaultdict

def build_chain(text, order=2):
    chain = defaultdict(list)
    words = text.split()
    for i in range(len(words) - order):
        state = tuple(words[i:i + order])
        chain[state].append(words[i + order])
    return chain

def generate(chain, length=30, seed=None):
    start = seed or random.choice(list(chain))
    out = list(start)
    state = start
    for _ in range(length):
        nxt = chain.get(state)
        if not nxt:
            break
        word = random.choice(nxt)
        out.append(word)
        state = tuple(out[-len(state):])
    return " ".join(out)

text = "the cat sat on the mat the cat ran the dog barked"
chain = build_chain(text, order=2)
print(generate(chain, length=20))

Geração de Texto com GPT-2

GPT-2 (e sucessores) prevê o próximo token autorregressivamente, gerando parágrafos coerentes. A função generate() unifica estratégias de decodificação: do_sample=True habilita geração estocástica (criativa), False dá greedy/beam (determinístico). Para geração moderna, prefira modelos ajustados por instrução (GPT-NeoX, Llama, Mistral) ao GPT-2 base.

nlp
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "gpt2"   # 'gpt2-medium', 'gpt2-large' for bigger
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

prompt = "In a world where machines could think,"
input_ids = tokenizer.encode(prompt, return_tensors="pt")

# greedy / beam / sampling all live in generate()
output = model.generate(
    input_ids,
    max_new_tokens=80,
    do_sample=True,
    top_k=50,
    top_p=0.95,
    temperature=0.9,
    repetition_penalty=1.2,
    pad_token_id=tokenizer.eos_token_id,
)
print(tokenizer.decode(output[0], skip_special_tokens=True))

Estratégias de Decodificação (temperatura / top-k / top-p)

A estratégia de decodificação controla criatividade vs coerência. Greedy/beam são seguros, mas monótonos. Temperatura escala os logits antes do softmax (<1 mais afiado, >1 mais achatado). Top-k restringe aos k tokens mais prováveis; top-p (núcleo) restringe ao menor conjunto que cobre a probabilidade p — mais adaptativo. Receita comum: temperatura=0.7, top_p=0.9, repetition_penalty=1.1.

nlp
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

tokenizer = AutoTokenizer.from_pretrained("gpt2")
model = AutoModelForCausalLM.from_pretrained("gpt2")
input_ids = tokenizer.encode("Once upon a time", return_tensors="pt")

# 1. GREEDY: always pick the argmax token. Deterministic, repetitive.
# 2. BEAM SEARCH: keep top-k sequences; deterministic, more coherent
#    but still bland.
beam = model.generate(input_ids, num_beams=5, max_new_tokens=50)

# 3. TEMPERATURE: sharpen (<1) or flatten (>1) the distribution.
#    temp=0.1 = nearly greedy; temp=1.5 = chaotic
sampler = model.generate(input_ids, do_sample=True, temperature=0.7,
                         top_k=0, max_new_tokens=50)

# 4. TOP-K: sample only from the k most likely tokens (k=50 typical)
topk = model.generate(input_ids, do_sample=True, top_k=50, max_new_tokens=50)

# 5. TOP-P (nucleus): sample from the smallest set whose cumulative
#    probability >= p (p=0.9 typical). Adapts to the distribution shape.
topp = model.generate(input_ids, do_sample=True, top_p=0.9, max_new_tokens=50)

Engenharia de Prompt

Modelos base precisam de prompts cuidadosos: zero-shot para tarefas simples, few-shot (3-5 exemplos) para aprendizado de padrões, e instruções de formato explícitas. Modelos ajustados por instrução (InstructGPT, Llama-2-Chat, Mistral-Instruct) seguem instruções em linguagem natural muito melhor e precisam de menos exemplos. Chain-of-thought ('pense passo a passo') impulsiona o raciocínio em matemática e lógica. Itere nos prompts de forma sistemática.

nlp
from transformers import pipeline

generator = pipeline("text-generation", model="gpt2")

# zero-shot: just ask
zero = generator("Translate English to French: cheese ->", max_new_tokens=5)

# few-shot: show examples in the prompt, then ask for the next
prompt = """Translate English to French:
cheese -> fromage
bread -> pain
water ->"""
few = generator(prompt, max_new_tokens=3)

# instruction prompt (works best with instruction-tuned models)
instruction = """Summarize the following text in one sentence:
Text: The cat sat on the mat. It was a lazy afternoon...
Summary:"""
summary = generator(instruction, max_new_tokens=30)

# tips:
#   - be specific about format ("Output JSON", "Answer in one word")
#   - provide examples for non-obvious tasks
#   - chain-of-thought: "Let's think step by step."
15

Tradução Automática

Tradução com googletrans

googletrans embrulha o endpoint gratuito de tradução web do Google — rápido para protótipos, mas não oficial e com limite de taxa. Para produção, use APIs oficiais (Google Cloud Translation, DeepL, Azure Translator) ou hospede MarianMT/NLLB você mesmo via Hugging Face. DeepL geralmente dá as traduções mais fluentes para linguagens europeias.

nlp
# pip install googletrans==4.0.0-rc1
from googletrans import Translator

translator = Translator()

# single sentence
result = translator.translate("Hello, world!", src="en", dest="fr")
print(result.text)        # Bonjour le monde !
print(result.pronunciation)

# batch
results = translator.translate(
    ["Good morning", "Thank you"], src="en", dest="es")
for r in results:
    print(r.text)         # Buenos días / Gracias

# auto-detect source language
detected = translator.translate("Guten Tag")
print(detected.src)       # 'de'

# caveat: googletrans uses the free web API and may rate-limit / break.
# For production, use official Google / DeepL / Azure APIs.

MarianMT (Hugging Face)

MarianMT (modelos opus do Helsinki-NLP) dá tradução gratuita, offline e de qualidade decente para ~100 pares de linguagens. Cada par é um modelo separado — escolha exatamente o que precisa. Para tradução multilíngue, o NLLB-200 da Meta cobre 200 linguagens num único modelo. A qualidade fica atrás das APIs comerciais (Google/DeepL), mas basta para muitos casos e roda numa única GPU.

nlp
from transformers import MarianTokenizer, MarianMTModel

# many language pairs available: 'Helsinki-NLP/opus-mt-{src}-{tgt}'
model_name = "Helsinki-NLP/opus-mt-en-fr"
tokenizer = MarianTokenizer.from_pretrained(model_name)
model = MarianMTModel.from_pretrained(model_name)

texts = ["Hello, how are you?", "I love natural language processing."]

batch = tokenizer(texts, return_tensors="pt", padding=True, truncation=True)
generated = model.generate(**batch, max_length=128, num_beams=4)
print(tokenizer.batch_decode(generated, skip_special_tokens=True))
# ['Bonjour, comment allez-vous ?', "J'aime le traitement du langage naturel."]

# Helsinki-NLP shipped hundreds of language pairs; for many-to-many use
# 'facebook/nllb-200-distilled-600M' (200 languages, one model)

Pontuação BLEU

BLEU compara a sobreposição de n-gramas entre a saída do sistema e as traduções de referência, com penalidade de brevidade para saídas curtas. Pontuações vão de 0-100; 30+ é razoável, 60+ é alta qualidade. BLEU é barato e padrão, mas imperfeito — ignora sinonímia e reordenação. Sempre avalie com múltiplas referências e complemente com chrF ou COMET para melhor correlação humana.

nlp
from sacrebleu import corpus_bleu   # pip install sacrebleu

refs = [["The cat is on the mat."]]   # list of reference(s) per sentence
hyp = ["The cat is on the mat."]      # system output

bleu = corpus_bleu(hyp, refs)
print(bleu.score)    # 0-100 (0=worst, 100=perfect match)

# multiple references for one sentence
refs = [["The cat is on the mat.", "There is a cat on the mat."]]
hyp = ["A cat is on the mat."]
print(corpus_bleu(hyp, refs).score)

# BLEU = geometric mean of modified n-gram precision * brevity penalty
#   - precision: how many n-grams in hyp appear in references
#   - brevity penalty: penalizes too-short outputs

# caveats: BLEU ignores semantics, struggles on short sentences,
# correlates only moderately with human judgment

Tokenização para Tradução

Modelos de tradução usam tokenizers SentencePiece ou BPE que tratam qualquer Unicode (incluindo €, —, emoji) sem token desconhecido. O marcador ▁ denota fronteiras de palavra no SentencePiece — remova-o para reconstruir o texto de superfície. Nunca alimente texto tokenizado por espaço bruto a um modelo MarianMT/NLLB; sempre passe pelo tokenizer dele para obter IDs de entrada compatíveis.

nlp
from transformers import AutoTokenizer

# translation models often use SentencePiece (BPE/unigram) tokenizers
tok = AutoTokenizer.from_pretrained("Helsinki-NLP/opus-mt-en-de")

text = "Don't go there — it's 5€!"
enc = tok(text)
print(tok.convert_ids_to_tokens(enc["input_ids"]))
# ['▁Don', "'", 't', '▁go', '▁there', '▁—', '▁it', "'", 's', '▁5', '€', '!', '</s>']

# the leading '▁' (U+2581) marks a word start in SentencePiece.
# Strip it when reconstructing words:
pieces = [p.replace("▁", " ") for p in tok.convert_ids_to_tokens(enc["input_ids"])]
print("".join(pieces).strip())

# always use the model's own tokenizer, never a generic one —
# vocabulary and subword rules differ across translation models

Back-Translation (Aumento de Dados)

Back-translation cria dados paralelos sintéticos: traduz texto monolíngue do alvo para a fonte e o pareia com o alvo original. É assim que sistemas massivos de NMT (Google, Facebook) são treinados quando corpora paralelos são escassos. O texto retrotraduzido é mais ruidoso que dados paralelos reais, mas adiciona variedade e melhora a robustez, especialmente para pares de linguagens de poucos recursos.

nlp
from transformers import MarianMTModel, MarianTokenizer

# augment monolingual source data with back-translated paraphrases
src_model_name = "Helsinki-NLP/opus-mt-en-de"   # EN -> DE
bt_model_name = "Helsinki-NLP/opus-mt-de-en"     # DE -> EN (back)

mono_en = ["The weather is nice today.", "I am learning NLP."]

# forward: EN -> DE
fwd_tok = MarianTokenizer.from_pretrained(src_model_name)
fwd_model = MarianMTModel.from_pretrained(src_model_name)
de = fwd_model.generate(**fwd_tok(mono_en, return_tensors="pt", padding=True))

# back: DE -> EN (paraphrase of the original)
bt_tok = MarianTokenizer.from_pretrained(bt_model_name)
bt_model = MarianMTModel.from_pretrained(bt_model_name)
en_bt = bt_model.generate(**bt_tok(
    bt_tok.batch_decode(de, skip_special_tokens=True),
    return_tensors="pt", padding=True))

paraphrases = bt_tok.batch_decode(en_bt, skip_special_tokens=True)
print(paraphrases)   # ~same meaning, different wording
16

Sequence-to-Sequence

Básico de Encoder-Decoder

Seq2Seq mapeia uma sequência de entrada de comprimento variável para uma saída de comprimento variável — a fundação da tradução, resumização e muitas outras tarefas. O clássico encoder-decoder com RNNs comprime toda a entrada num vetor de contexto fixo, que vira gargalo para sequências longas. Atenção (próxima seção) foi inventada exatamente para corrigir isso.

nlp
# Seq2Seq: an encoder maps the input sequence to a context vector,
# a decoder generates the output sequence from that context.
#
#   input -> [Encoder] -> context -> [Decoder] -> output
#
# Classic architecture (Sutskever et al. 2014):
#   - Encoder: RNN/LSTM/GRU processes input tokens, final hidden state
#     becomes the context vector.
#   - Decoder: another RNN initialized with the context, generates
#     output tokens one at a time.
#
# Used for: translation, summarization, QA, parsing, code generation.

import torch
import torch.nn as nn

class Encoder(nn.Module):
    def __init__(self, vocab_size, emb_dim, hid_dim):
        super().__init__()
        self.emb = nn.Embedding(vocab_size, emb_dim)
        self.rnn = nn.LSTM(emb_dim, hid_dim)
    def forward(self, src):
        embedded = self.emb(src)
        outputs, (hidden, cell) = self.rnn(embedded)
        return hidden, cell   # context

Seq2Seq com RNN/LSTM

O decodificador gera um token por vez, alimentando a própria saída anterior como próxima entrada (autorregressivo). Inicialize o estado oculto do decodificador com o contexto do encoder. Decodificação greedy (argmax a cada passo) é simples, mas pode travar em loops; beam search mantém as top-k hipóteses. O vetor de contexto fixo sofre com entradas longas — atenção resolve.

nlp
import torch
import torch.nn as nn

class Decoder(nn.Module):
    def __init__(self, vocab_size, emb_dim, hid_dim):
        super().__init__()
        self.emb = nn.Embedding(vocab_size, emb_dim)
        self.rnn = nn.LSTM(emb_dim, hid_dim)
        self.fc = nn.Linear(hid_dim, vocab_size)

    def forward(self, input_token, hidden, cell):
        # input_token: (1,) the previous output token
        emb = self.emb(input_token).unsqueeze(0)   # (1, 1, emb_dim)
        out, (hidden, cell) = self.rnn(emb, (hidden, cell))
        logits = self.fc(out.squeeze(0))            # (1, vocab_size)
        return logits, hidden, cell

# full generation loop (greedy decoding)
def generate(decoder, context_hidden, context_cell, sos_idx, eos_idx, max_len=20):
    hidden, cell = context_hidden, context_cell
    token = torch.tensor([sos_idx])
    output = []
    for _ in range(max_len):
        logits, hidden, cell = decoder(token, hidden, cell)
        token = logits.argmax(dim=-1)
        if token.item() == eos_idx:
            break
        output.append(token.item())
    return output

Teacher Forcing

Teacher forcing acelera dramaticamente o treino ao alimentar o token anterior verdadeiro em vez da previsão (frequentemente errada) do próprio modelo. Teacher forcing puro causa 'viés de exposição' — na inferência o modelo nunca viu os próprios erros durante o treino. Scheduled sampling (mistura de teacher-forced e previsões próprias) mitiga, mas adiciona complexidade; transformers modernos dependem de treino paralelo teacher-forced.

nlp
import torch
import torch.nn as nn

# During training, feed the GROUND TRUTH previous token (not the model's
# prediction) as the next input. This is 'teacher forcing'.

def train_step(encoder, decoder, src, trg, criterion, teacher_ratio=0.5):
    # src: (src_len, batch), trg: (trg_len, batch)
    hidden, cell = encoder(src)
    batch_size = src.size(1)
    trg_len = trg.size(0)
    vocab_size = decoder.fc.out_features

    outputs = torch.zeros(trg_len, batch_size, vocab_size)

    input_token = trg[0, :]   # <sos> token
    for t in range(1, trg_len):
        logits, hidden, cell = decoder(input_token, hidden, cell)
        outputs[t] = logits
        # teacher forcing: use real target as next input
        teacher_force = torch.rand(1).item() < teacher_ratio
        input_token = trg[t, :] if teacher_force else logits.argmax(dim=-1)

    return criterion(outputs[1:].reshape(-1, vocab_size),
                     trg[1:].reshape(-1))

Mecanismo de Atenção

A atenção liberta o decodificador de um único vetor de contexto fixo: a cada passo computa uma média ponderada de todas as saídas do encoder, aprendendo quais palavras da fonte importam agora. Isso corrige o gargalo de sequências longas e melhora drasticamente a qualidade. Bahdanau (aditiva) e Luong (multiplicativa) são as duas variantes clássicas; ambas foram precursoras da self-attention do Transformer.

nlp
import torch
import torch.nn as nn
import torch.nn.functional as F

# Bahdanau-style additive attention:
# the decoder looks at ALL encoder outputs (not just the final state)
# and learns which to focus on at each step.

class Attention(nn.Module):
    def __init__(self, hid_dim):
        super().__init__()
        self.attn = nn.Linear(hid_dim * 2, hid_dim)
        self.v = nn.Linear(hid_dim, 1, bias=False)

    def forward(self, hidden, encoder_outputs):
        # hidden: (1, batch, hid), encoder_outputs: (src_len, batch, hid)
        src_len = encoder_outputs.size(0)
        hidden_exp = hidden.repeat(src_len, 1, 1)
        energy = torch.tanh(self.attn(
            torch.cat((hidden_exp, encoder_outputs), dim=2)))
        attention = self.v(energy).squeeze(2)        # (src_len, batch)
        return F.softmax(attention, dim=0)           # weights over src

# context = sum(attention_weights * encoder_outputs)
# then concat context with decoder input embedding

Beam Search

Beam search mantém k sequências candidatas e expande as mais promissoras, equilibrando exploração e exploração (aproveitamento). Largura 4-8 é típica. Beam search produz saídas mais fluentes que greedy, mas pode preferir traduções genéricas — length_penalty e no_repeat_ngram_size contrapõem isso. Para geração aberta, amostragem costuma vencer beam search; para tradução/resumização, beam search geralmente vence.

nlp
# Greedy decoding picks the single most likely token each step.
# Beam search keeps the top-k candidate SEQUENCES, expanding each.

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

model = AutoModelForSeq2SeqLM.from_pretrained("Helsinki-NLP/opus-mt-en-fr")
tokenizer = AutoTokenizer.from_pretrained("Helsinki-NLP/opus-mt-en-fr")

input_ids = tokenizer("Hello, how are you?", return_tensors="pt").input_ids

# beam search: explore k hypotheses in parallel
output = model.generate(
    input_ids,
    num_beams=5,            # beam width
    max_length=50,
    length_penalty=0.6,     # <1 prefers shorter, >1 prefers longer
    early_stopping=True,
)
print(tokenizer.decode(output[0], skip_special_tokens=True))

# trade-off: larger beam = better quality but slower (O(k * steps))
# and a tendency toward generic / shorter outputs (length penalty helps)
17

Atenção e Transformer

Intuição da Self-Attention

Self-attention é o núcleo do Transformer: cada token atenta a cada um dos tokens (incluindo a si mesmo) e agrega seus valores ponderados pela similaridade query-key. Isso dá contexto global numa única operação, sem recorrência, permitindo paralelismo massivo. O escalonamento 1/sqrt(d_k) mantém os gradientes do softmax estáveis. Este único mecanismo substitui RNNs e convoluções.

nlp
# Self-attention lets each token look at every other token in the
# sequence to build a context-aware representation.
#
# For token i:  context_i = sum_j  attention(i, j) * value_j
#
# attention(i, j) = softmax( q_i . k_j / sqrt(d) )
#   q_i = query of token i  (what am I looking for?)
#   k_j = key of token j    (what do I contain?)
#   v_j = value of token j  (what info do I pass on?)
#
# Each token is projected to Q, K, V by learned weight matrices.

import torch
import torch.nn.functional as F
import math

def self_attention(x, W_q, W_k, W_v):
    # x: (seq_len, d_model)
    Q, K, V = x @ W_q, x @ W_k, x @ W_v
    d_k = K.size(-1)
    scores = Q @ K.transpose(-2, -1) / math.sqrt(d_k)
    weights = F.softmax(scores, dim=-1)
    return weights @ V   # (seq_len, d_model)

Multi-Head Attention

Multi-head attention roda várias camadas de atenção em paralelo sobre projeções diferentes da entrada e depois concatena. Cada cabeça aprende uma relação diferente (sintática, coreferência, semântica...). 8-16 cabeças é típico. Mais cabeças = mais capacidade, mas retornos decrescentes. O parâmetro mask é como máscaras causais (decodificador) e de preenchimento são aplicadas.

nlp
import torch
import torch.nn as nn
import math
import torch.nn.functional as F

class MultiHeadAttention(nn.Module):
    def __init__(self, d_model, n_heads):
        super().__init__()
        assert d_model % n_heads == 0
        self.d_k = d_model // n_heads
        self.n_heads = n_heads
        self.q = nn.Linear(d_model, d_model)
        self.k = nn.Linear(d_model, d_model)
        self.v = nn.Linear(d_model, d_model)
        self.out = nn.Linear(d_model, d_model)

    def forward(self, x, mask=None):
        B, L, D = x.shape
        # project to (B, n_heads, L, d_k)
        Q = self.q(x).view(B, L, self.n_heads, self.d_k).transpose(1, 2)
        K = self.k(x).view(B, L, self.n_heads, self.d_k).transpose(1, 2)
        V = self.v(x).view(B, L, self.n_heads, self.d_k).transpose(1, 2)
        scores = (Q @ K.transpose(-2, -1)) / math.sqrt(self.d_k)
        if mask is not None:
            scores = scores.masked_fill(mask == 0, float("-inf"))
        attn = F.softmax(scores, dim=-1)
        ctx = attn @ V                          # (B, h, L, d_k)
        ctx = ctx.transpose(1, 2).contiguous().view(B, L, D)
        return self.out(ctx)

Arquitetura Transformer

Um bloco Transformer = multi-head attention + feed-forward por posição, cada um com uma conexão residual e LayerNorm. Residuais deixam os gradientes fluir por pilhas profundas; LayerNorm estabiliza o treino. O feed-forward (geralmente 4x mais largo que d_model) é onde vivem a maioria dos parâmetros. Empilhe 6-24 blocos para um modelo completo. A memória é O(L^2) no comprimento da sequência — a origem dos desafios de contexto longo.

nlp
# The full Transformer block (Vaswani et al. 2017):
#
#   x -> MultiHeadAttention -> Add & LayerNorm -> FeedForward -> Add & LayerNorm
#   (Add = residual connection: out = x + Sublayer(x))
#
# Encoder: stacks N of these blocks (N=6 in base, 12 in BERT-base).
# Decoder: same but with masked self-attention + cross-attention
#          to the encoder output.
#
# Properties:
#   - no recurrence -> fully parallelizable, trains much faster than RNNs
#   - global receptive field from layer 1
#   - position-agnostic -> needs positional encoding
#   - quadratic memory in seq_len (O(L^2)) due to full attention

import torch.nn as nn

class TransformerBlock(nn.Module):
    def __init__(self, d_model=512, n_heads=8, d_ff=2048, dropout=0.1):
        super().__init__()
        self.attn = nn.MultiheadAttention(d_model, n_heads, dropout=dropout,
                                          batch_first=True)
        self.ff = nn.Sequential(
            nn.Linear(d_model, d_ff), nn.GELU(), nn.Linear(d_ff, d_model))
        self.norm1 = nn.LayerNorm(d_model)
        self.norm2 = nn.LayerNorm(d_model)
        self.drop = nn.Dropout(dropout)

    def forward(self, x, mask=None):
        a, _ = self.attn(x, x, x, attn_mask=mask, need_weights=False)
        x = self.norm1(x + self.drop(a))
        f = self.ff(x)
        x = self.norm2(x + self.drop(f))
        return x

Positional Encoding

Como a atenção trata a entrada como um conjunto, Transformers precisam de sinais explícitos de posição. O artigo original usava sinusoides fixas (extrapolam além do comprimento de treino). BERT/GPT usam embeddings aprendidos (mais simples, levemente melhor, mas não extrapola). LLMs modernos favorecem RoPE (rotativo) ou ALiBi, que generalizam para contextos mais longos que os vistos no treino — crítico para tarefas de documentos longos.

nlp
import torch
import math
import torch.nn as nn

# Self-attention is permutation-invariant, so we ADD positional info
# to the embeddings so the model knows token order.

class SinusoidalPositionalEncoding(nn.Module):
    def __init__(self, d_model, max_len=5000):
        super().__init__()
        pe = torch.zeros(max_len, d_model)
        position = torch.arange(0, max_len).unsqueeze(1).float()
        div_term = torch.exp(
            torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model))
        pe[:, 0::2] = torch.sin(position * div_term)
        pe[:, 1::2] = torch.cos(position * div_term)
        self.register_buffer("pe", pe.unsqueeze(0))   # (1, max_len, d_model)

    def forward(self, x):
        # x: (batch, seq_len, d_model)
        return x + self.pe[:, :x.size(1)]

# alternatives:
#   - learned positional embeddings (BERT, GPT): nn.Embedding(max_len, d_model)
#   - relative positional encoding (T5, Transformer-XL)
#   - RoPE (Rotary Position Embedding, used in LLaMA) -> handles long context

BERT vs GPT vs T5

BERT (encoder) lê texto nas duas direções — melhor para tarefas de compreensão. GPT (decodificador) lê da esquerda para a direita — melhor para geração. T5/BART (encoder-decoder) — melhor para tarefas sequência-para-sequência como tradução e resumização. LLMs modernos só decodificador (LLaMA, Mistral) fecham a lacuna em compreensão via ajuste por instrução, mas um BERT pequeno ainda vence em classificação simples com dados limitados.

nlp
# Three Transformer families, three pretraining objectives:
#
# BERT (encoder-only, bidirectional):
#   - Masked Language Modeling (predict [MASK] tokens)
#   - Great for: classification, NER, QA (extractive), embeddings
#   - example: bert-base-uncased, RoBERTa, DistilBERT, DeBERTa
#
# GPT (decoder-only, autoregressive):
#   - Causal Language Modeling (predict next token)
#   - Great for: generation, chat, few-shot, code
#   - example: gpt2, gpt-neo, LLaMA, Mistral, Qwen
#
# T5 (encoder-decoder, text-to-text):
#   - Span corruption (mask spans, predict them)
#   - One model for EVERY task by framing as text->text
#   - example: t5-base, flan-t5, BART (similar, denoising autoencoder)

from transformers import AutoModel
bert = AutoModel.from_pretrained("bert-base-uncased")   # encoder
print(bert.config.model_type)   # bert

# pick the family that matches your task:
#   classification/NER -> encoder (BERT)
#   generation         -> decoder (GPT)
#   translation/summarization -> encoder-decoder (T5/BART)
18

Perguntas e Respostas (QA)

QA Extrativo com BERT

QA extrativo enquadra perguntas e respostas como previsão de span: o modelo produz as posições de token inicial e final no contexto. DistilBERT com fine-tuning em SQuAD é um padrão rápido e preciso. Funciona melhor quando a resposta literalmente aparece no contexto. Para respostas abstratas (parafraseadas, sintetizadas), use um modelo seq2seq como T5 ou um LLM com recuperação.

nlp
from transformers import pipeline

# Extractive QA: pick a SPAN of the context as the answer.
qa = pipeline("question-answering",
              model="distilbert-base-cased-distilled-squad")

context = "Transformers were introduced in 2017. The model uses self-attention."
question = "When were transformers introduced?"

result = qa(question=question, context=context)
print(result)
# {'score': 0.97, 'start': 32, 'end': 36, 'answer': '2017'}

# start/end are character offsets into the context —
# you can highlight the answer in the original text:
print(context[:result['start']] + '[' + result['answer'] + ']' + context[result['end']:])

QA Generativo (LLM)

QA generativo produz respostas livres (não spans), podendo sintetizar, parafrasear ou dizer 'não sei'. FLAN-T5 é um modelo pequeno, gratuito e ajustado por instrução que segue bem prompts de QA. Para perguntas de domínio aberto sem contexto fornecido, você precisa de um LLM muito grande com conhecimento interno ou de geração aumentada por recuperação (RAG) para fornecer fatos frescos.

nlp
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "google/flan-t5-base"   # instruction-tuned seq2seq
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSeq2SeqLM.from_pretrained(model_name)

prompt = """context: The Eiffel Tower is located in Paris and was built in 1889.
question: Where is the Eiffel Tower?
answer:"""

input_ids = tokenizer(prompt, return_tensors="pt").input_ids
out = model.generate(input_ids, max_new_tokens=20)
print(tokenizer.decode(out[0], skip_special_tokens=True))
# 'Paris'

# for open-ended QA without a fixed context, use a large LLM
# (Llama-2-Chat, Mistral-Instruct) and prompt with the question directly

Geração Aumentada por Recuperação (RAG)

RAG mantém as respostas do LLM ancoradas em evidências recuperadas — crucial para dados frescos ou privados que o LLM nunca viu. Passos: embuta documentos, ache os top-k por similaridade de cosseno, coloque-os no prompt e deixe o modelo gerar. Para produção, use um banco de vetores (FAISS, Chroma, Qdrant) e divida documentos longos em chunks. RAG reduz alucinação e permite citar fontes.

nlp
# RAG: retrieve relevant documents, then let an LLM answer
# using those documents as context. Combines search + generation.

from sentence_transformers import SentenceTransformer, util

# 1. Build a vector index of your documents
docs = ["Paris is the capital of France.",
        "Python is a programming language.",
        "The Eiffel Tower was built in 1889."]
encoder = SentenceTransformer("all-MiniLM-L6-v2")
doc_emb = encoder.encode(docs, convert_to_tensor=True, normalize_embeddings=True)

# 2. Retrieve top-k for a query
query = encoder.encode("What is the capital of France?",
                       convert_to_tensor=True, normalize_embeddings=True)
hits = util.semantic_search(query, doc_emb, top_k=2)[0]
context = "\n".join(docs[h['corpus_id']] for h in hits)

# 3. Generate answer conditioned on retrieved context
prompt = f"Context:\n{context}\n\nQuestion: What is the capital of France?\nAnswer:"
# -> feed to an LLM; it reads the context and answers 'Paris'
print(prompt)

Dataset SQuAD

SQuAD é O benchmark de QA extrativo — cada modelo de QA reporta F1 no SQuAD. As respostas são spans, então os modelos produzem posições inicial/final. SQuAD v2 adiciona perguntas sem resposta para testar abstenção. Modelos modernos pontuam >90 F1 (super-humanos na métrica), mas SQuAD é de um salto e inglês — para casos mais difíceis use Natural Questions, HotpotQA (multi-salto) ou TyDiQA (multilíngue).

nlp
# SQuAD (Stanford Question Answering Dataset):
#   - 100k+ questions on Wikipedia paragraphs
#   - each answer is a SPAN in the paragraph
#   - the standard benchmark for extractive QA
#
# Load with Hugging Face datasets:
from datasets import load_dataset
squad = load_dataset("squad")
print(squad)
# DatasetDict({ train: 87599 rows, validation: 10570 rows })

ex = squad["train"][0]
print(ex.keys())
# dict_keys(['id', 'title', 'context', 'question', 'answers'])
print(ex["question"])      # 'Which NFL team represented the AFC...'
print(ex["answers"]["text"])   # ['Denver Broncos']  (sometimes multiple)

# SQuAD v2 adds unanswerable questions (model must abstain)
squad_v2 = load_dataset("squad_v2")

Avaliação de QA (F1 / EM)

A pontuação SQuAD normaliza ambas as respostas (minúsculas, remover artigos/pontuação/espaços extras) antes de comparar. EM é binário; F1 é no nível de token e mais tolerante a parafrasear. Ambos ignoram semântica — 'canino' vs 'cão' pontua 0. Para QA abstrato, use métricas semânticas (BERTScore, BARTScore) ou avaliação humana. Reporte EM e F1, com média sobre todas as perguntas, incluindo as sem resposta.

nlp
# Two standard metrics for extractive QA:
#   Exact Match (EM): 1 if prediction == gold answer exactly, else 0
#   F1: token-level F1 between prediction and gold (after normalization)

import re
from collections import Counter

def normalize(text):
    # SQuAD normalization: lowercase, remove articles/punct/extra space
    text = text.lower()
    text = re.sub(r"\b(a|an|the)\b", " ", text)
    text = " ".join(text.split())
    return re.sub(r"[^\w\s]", "", text)

def f1_score(pred, gold):
    p, g = normalize(pred).split(), normalize(gold).split()
    common = Counter(p) & Counter(g)
    n_common = sum(common.values())
    if n_common == 0:
        return 0.0
    precision = n_common / len(p)
    recall = n_common / len(g)
    return 2 * precision * recall / (precision + recall)

def exact_match(pred, gold):
    return float(normalize(pred) == normalize(gold))

print(f1_score("the cat", "a cat"))      # 1.0 (articles removed)
print(exact_match("Paris.", "paris"))    # 1.0 (case/punct normalized)
19

Resumização de Texto

Resumização Extrativa (TextRank)

TextRank constrói um grafo de similaridade de frases e roda PageRank para achar as frases mais centrais (representativas). Abordagens extrativas são rápidas, fiéis (sem alucinação) e bons para notícias. Fraqueza: não conseguem parafrasear ou mesclar informação entre frases. Use sumy, o summarize do gensim ou pytextrank para implementações prontas para produção.

nlp
# Extractive: pick the most important SENTENCES from the source
# (no new text generated). TextRank ranks sentences by graph centrality.

import numpy as np
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity

def textrank_summary(text, n=3):
    sentences = text.split(". ")   # naive sentence split
    if len(sentences) <= n:
        return text
    # similarity graph: sentence vs sentence
    tfidf = TfidfVectorizer(stop_words="english").fit_transform(sentences)
    sim = cosine_similarity(tfidf)
    np.fill_diagonal(sim, 0)
    # PageRank-style power iteration
    scores = np.ones(len(sentences)) / len(sentences)
    for _ in range(50):
        scores = 0.85 * sim.dot(scores) / sim.sum(axis=0) + 0.15 / len(sentences)
    top = np.argsort(scores)[-n:]
    return ". ".join(sentences[i] for i in sorted(top))

text = "Sentence one. Sentence two is longer. Third sentence here. Fourth."
print(textrank_summary(text, n=2))

Summarize do gensim

gensim 4 removeu seu módulo summarize; use a biblioteca sumy para resumização extrativa. sumy oferece múltiplos algoritmos (TextRank, LexRank, LSA, Luhn) — LexRank frequentemente supera TextRank em notícias. As abordagens extrativas compartilham a mesma limitação: não reformulam. Para resumos de maior qualidade, troque para um modelo abstrativo como BART ou T5.

nlp
from gensim.summarization import summarize  # older gensim
# (removed in gensim 4.x; use 'sumy' or 'pytextrank' instead)

# modern alternative: sumy
# pip install sumy
from sumy.parsers.plaintext import PlaintextParser
from sumy.nlp.tokenizers import Tokenizer
from sumy.summarizers.text_rank import TextRankSummarizer

parser = PlaintextParser.from_string("Your long text here. Multiple "
    "sentences. The summarizer picks the most important ones.",
    Tokenizer("english"))
summarizer = TextRankSummarizer()
for sentence in summarizer(parser.document, sentences_count=2):
    print(sentence)

# sumy also offers: LuhnSummarizer, LsaSummarizer, LexRankSummarizer,
# EdmundsonSummarizer (heuristic-based)

Resumização Abstrativa (BART / T5)

BART-large-CNN é o resumizador pré-treinado padrão para notícias: treinado em CNN/DailyMail para produzir resumos de 3 frases. Resumos abstrativos leem melhor que extrativos (parafraseiam e condensam), mas podem alucinar fatos não presentes na fonte — sempre verifique no seu domínio. Pegasus é ajustado para resumos muito curtos; T5 é multitarefa e flexível.

nlp
from transformers import pipeline

# Abstractive: GENERATE a summary (may use words not in the source)
summarizer = pipeline("summarization",
                      model="facebook/bart-large-cnn")

article = """\
Scientists at CERN have announced the discovery of a new subatomic
particle. The finding, published in Nature, confirms a prediction made
decades ago and opens new avenues for research into dark matter. The
team analyzed data from the Large Hadron Collider over three years."""

summary = summarizer(article, max_length=50, min_length=20,
                     do_sample=False, truncation=True)
print(summary[0]["summary_text"])

# alternative models:
#   t5-base / flan-t5-base  (text-to-text, multitask)
#   google/pegasus-xsum     (very short, one-sentence summaries)

Avaliação ROUGE

ROUGE mede a sobreposição de n-gramas entre resumos gerados e de referência — orientado a recall (você cobriu a referência?). ROUGE-1 e ROUGE-2 F1 são os números de manchete; ROUGE-L usa a subsequência comum mais longa para capturar a ordem. Como BLEU, ROUGE ignora equivalência semântica ('canino' vs 'cão'). Complemente com BERTScore ou avaliação humana para checagens de qualidade de produção.

nlp
# ROUGE (Recall-Oriented Understudy for Gisting Evaluation):
# standard metric for summarization. Compares n-gram overlap.

# pip install rouge-score
from rouge_score import rouge_scorer

scorer = rouge_scorer.RougeScorer(["rouge1", "rouge2", "rougeL"],
                                  use_stemmer=True)
reference = "The cat sat on the mat."
hypothesis = "A cat is sitting on a mat."
scores = scorer.score(reference, hypothesis)
print(scores)
# rouge1: unigram overlap, rouge2: bigram, rougeL: longest common subsequence
# each gives (precision, recall, fmeasure)

# tips:
#   - ROUGE-1/ROUGE-2 F1 are the most reported
#   - ROUGE-L captures sentence-level order via LCS
#   - use multiple references for a fairer comparison
#   - ROUGE correlates with human judgment but ignores semantics

Resumização de Documentos Longos

BART/T5 padrão limitam as entradas a 512-1024 tokens. Para documentos longos, use um modelo de contexto longo (LongT5, Longformer-Encoder-Decoder, BigBird) que escala a atenção quase linearmente. Chunking map-reduce (resumir cada chunk e depois resumir os resumos) é uma alternativa robusta e dá controle por seção. Resumização hierárquica preserva a estrutura para relatórios e reuniões.

nlp
from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
import torch

# Problem: most summarizers have a 512/1024-token input limit.
# Long documents (papers, meetings) need special handling.

model_name = "google/long-t5-tglobal-base"   # handles long inputs
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSeq2SeqLM.from_pretrained(model_name)

# option 1: use a long-context model (LongT5, LED, BigBird)
inputs = tokenizer(long_text, return_tensors="pt", truncation=True,
                   max_length=4096)
out = model.generate(**inputs, max_length=256)

# option 2: chunk + summarize + combine (map-reduce)
def chunk_text(text, max_tokens=512):
    # split into overlapping windows, summarize each, then summarize
    # the concatenation of partial summaries
    pass

# option 3: hierarchical attention (summarize sections, then summarize
# section summaries)
20

Transformers do Hugging Face

API Pipeline

pipeline() é o ponto de entrada mais fácil: escolha uma tarefa, receba um modelo, rode inferência numa linha. Ele cuida de tokenização, despacho de modelo e pós-processamento. Sobrescreva 'model' com qualquer nome do Hub para trocar arquiteturas. Ótimo para protótipos; para produção você vai querer controle explícito sobre batching, posicionamento de dispositivo e tokenização, pela velocidade.

nlp
from transformers import pipeline

# one-line inference for common tasks (downloads a default model)
clf = pipeline("sentiment-analysis")
print(clf("I love transformers!"))

qa = pipeline("question-answering")
print(qa(question="Who built BERT?", context="BERT was built by Google."))

ner = pipeline("ner", aggregation_strategy="simple")
print(ner("Barack Obama was born in Hawaii."))

summarizer = pipeline("summarization")
print(summarizer("Long text...", max_length=50))

generator = pipeline("text-generation", model="gpt2")
print(generator("Once upon a time", max_new_tokens=30))

# tasks available: sentiment-analysis, ner, question-answering,
# summarization, translation, text-generation, zero-shot-classification,
# fill-mask, feature-extraction, text2text-generation, image-classification...

AutoModel e AutoTokenizer

AutoModel carrega o encoder base (produz estados ocultos); as classes Auto específicas por tarefa adicionam a cabeça de previsão certa (classificação, NER, QA, geração). AutoTokenizer escolhe o tokenizer correspondente. Use-os para fine-tuning ou pipelines de inferência personalizados. Cada 'AutoModelFor*' tem a função de perda correta embutida — basta passar labels ao forward() e você recebe uma loss.

nlp
from transformers import AutoTokenizer, AutoModel, AutoModelForSequenceClassification
import torch

model_name = "bert-base-uncased"

# Auto* classes pick the right implementation from the model's config
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)   # base encoder
clf_model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)

inputs = tokenizer(["Hello", "World"], padding=True, return_tensors="pt")
with torch.no_grad():
    embeddings = model(**inputs).last_hidden_state   # (batch, seq, 768)

# task-specific Auto classes:
#   AutoModelForTokenClassification  (NER)
#   AutoModelForQuestionAnswering   (QA)
#   AutoModelForCausalLM             (GPT-style generation)
#   AutoModelForSeq2SeqLM            (T5/BART translation, summarization)
#   AutoModelForMaskedLM             (BERT-style MLM)

Fine-tuning com Trainer

Trainer cuida do loop de treino (batching, acumulação de gradiente, precisão mista, avaliação, checkpoints), para que você escreva o mínimo de boilerplate. Passe TrainingArguments para controlar LR, tamanho de lote, épocas, estratégia de eval/save. load_best_model_at_end=True mantém o melhor checkpoint. Para controle total (loss personalizado, multitarefa) você ainda pode escrever um loop PyTorch puro — Trainer é conveniência, não restrição.

nlp
from transformers import (AutoTokenizer, AutoModelForSequenceClassification,
                          TrainingArguments, Trainer)
from datasets import load_dataset
import evaluate

model_name = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)

dataset = load_dataset("imdb")

def tokenize(batch):
    return tokenizer(batch["text"], truncation=True, padding="max_length", max_length=256)

train_ds = dataset["train"].map(tokenize, batched=True).rename_column("label", "labels")
train_ds.set_format("torch", columns=["input_ids", "attention_mask", "labels"])

accuracy = evaluate.load("accuracy")
def compute_metrics(eval_pred):
    logits, labels = eval_pred
    return accuracy.compute(predictions=logits.argmax(-1), references=labels)

args = TrainingArguments(
    output_dir="imdb-bert",
    eval_strategy="epoch",
    save_strategy="epoch",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    num_train_epochs=3,
    load_best_model_at_end=True,
)
trainer = Trainer(model=model, args=args,
                  train_dataset=train_ds,
                  eval_dataset=dataset["test"].map(tokenize, batched=True),
                  compute_metrics=compute_metrics)
trainer.train()

Biblioteca Datasets

datasets dá uma API unificada a milhares de datasets de NLP, com cache inteligente, mapeamento de memória (sem OOM em dados enormes) e modo streaming. map(batched=True) aplica pré-processamento em paralelo com multiprocessing. Funções embutidas (filter, shuffle, train_test_split) espelham pandas/sklearn. O Hub também hospeda métricas via a biblioteca 'evaluate'.

nlp
from datasets import load_dataset, Dataset

# thousands of datasets, one API, streaming for huge ones
squad = load_dataset("squad", split="train[:1%]")
print(squad.column_names)   # ['id', 'title', 'context', 'question', 'answers']

# map over examples (batched for speed)
def preprocess(batch):
    return tokenizer(batch["context"], truncation=True)
squad = squad.map(preprocess, batched=True)

# filter / shuffle / select
squad = squad.filter(lambda ex: len(ex["context"]) > 100).shuffle(seed=42)

# create your own from a dict or CSV/JSON
ds = Dataset.from_dict({"text": ["a", "b"], "label": [0, 1]})
ds = Dataset.from_csv("data.csv")

# stream a huge dataset without downloading fully
wiki = load_dataset("wikipedia", "20220301.en", streaming=True)
for ex in wiki: break   # first example only

Biblioteca Tokenizers

A biblioteca tokenizers (núcleo Rust, bindings Python) permite treinar um tokenizer BPE/WordPiece/Unigram personalizado rápido — minutos vs horas para Python puro. Normalizadores tratam Unicode (NFD, minúsculas, remoção de acentos). Decoders reconstruem o texto de superfície a partir dos IDs. Envolva o resultado como PreTrainedTokenizerFast para plugá-lo ao Trainer do transformers. Espelhe a tokenização exata do seu modelo para evitar perda silenciosa de precisão.

nlp
from tokenizers import Tokenizer
from tokenizers.models import BPE
from tokenizers.trainers import BpeTrainer
from tokenizers.pre_tokenizers import Whitespace, Metaspace
from tokenizers.decoders import Metaspace as MetaspaceDecoder
from tokenizers.normalizers import NFD, Lowercase, StripAccents, Sequence

# build a tokenizer from scratch (fast, Rust-backed)
tokenizer = Tokenizer(BPE(unk_token="[UNK]"))
tokenizer.normalizer = Sequence([NFD(), Lowercase(), StripAccents()])
tokenizer.pre_tokenizer = Whitespace()

trainer = BpeTrainer(vocab_size=30000,
                     special_tokens=["[UNK]", "[PAD]", "[CLS]", "[SEP]", "[MASK]"])
tokenizer.train(files=["corpus.txt"], trainer=trainer)

# encode/decode
enc = tokenizer.encode("Hello, world!")
print(enc.ids, enc.tokens)
print(tokenizer.decode(enc.ids))

# save / load
tokenizer.save("my_tokenizer.json")
tok = Tokenizer.from_file("my_tokenizer.json")

# use with transformers: wrap as PreTrainedTokenizerFast

Model Hub e Compartilhamento

O Hub é o coração do ecossistema: modelos pré-treinados, datasets e demos num só lugar. Publique seu modelo com fine-tuning via trainer.push_to_hub() para que colegas (ou você do futuro) possam carregá-lo pelo nome. Adicione um model card descrevendo os dados de treino, o uso pretendido e as limitações — boa prática e cada vez mais exigida para IA responsável. Repos privados precisam de token; compartilhe via contas de organização.

nlp
# The Hugging Face Hub hosts 100k+ models and datasets.
# Browse: https://huggingface.co/models

# load any model by its repo id
from transformers import AutoModel, AutoTokenizer
model = AutoModel.from_pretrained("bert-base-uncased")
# private/org models need an access token:
# AutoModel.from_pretrained("org/private-model", token="hf_xxx")

# share your own fine-tuned model
from huggingface_hub import HfApi
# 1. huggingface-cli login  (one-time, paste a token)
# 2. push from a Trainer:
trainer.push_to_hub("my-imdb-bert")
# 3. or push manually:
# api = HfApi()
# api.create_repo(repo_id="my-imdb-bert", repo_type="model")
# api.upload_folder(folder_path="imdb-bert", repo_id="my-imdb-bert")

# now anyone (or your team) can load it:
# AutoModel.from_pretrained("your-username/my-imdb-bert")

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.