---
license: apache-2.0
base_model: Qwen/Qwen3-Reranker-0.6B
language:
- pt
tags:
- text-classification
- community-notes
- portuguese
- reranker
- lora
- peft
- misinformation
pipeline_tag: text-generation
---

# Community Notes Reranker (PT-BR)

Cross-encoder fine-tunado para prever se uma nota da comunidade do X (antigo Twitter) será avaliada como útil em português brasileiro. Adapters LoRA sobre `Qwen/Qwen3-Reranker-0.6B`. Dado um par `(tweet, nota)`, devolve uma probabilidade no intervalo `[0, 1]`.

## Por que Qwen3-Reranker

A pergunta central do projeto é **"esta nota responde adequadamente a este tweet?"**. Isso exige um modelo que *compare termo a termo* o que o tweet afirma e o que a nota desmente ou contextualiza — não basta saber se os dois textos falam do mesmo assunto.

A família Qwen3 dedicada a recuperação tem dois ramos com arquiteturas diferentes:

- **Qwen3-Embedding** é um *bi-encoder*: codifica tweet e nota em vetores separados e mede similaridade vetorial. Captura "falam do mesmo assunto", mas perde nuance lógica — não percebe quando uma frase específica da nota desmente uma afirmação específica do tweet.
- **Qwen3-Reranker** é um *cross-encoder*: lê o par `(tweet, nota)` concatenado num único contexto, com atenção cruzada em todas as camadas. Cada token da nota pode atender a cada token do tweet ao longo de toda a rede.

| Aspecto | Bi-Encoder (Embedding) | Cross-Encoder (Reranker) |
|---|---|---|
| Entrada | tweet e nota processados **separadamente** | par `(tweet, nota)` **concatenado** |
| Encoder | um encoder por texto | um encoder único que vê os dois |
| Onde os textos se comparam | **depois** da codificação (similaridade vetorial) | **durante** a codificação (atenção cruzada em todas as camadas) |
| Saída | dois vetores + similaridade | logit conjunto |
| Captura bem | "falam do mesmo assunto" | "esta frase da nota desmente esta afirmação do tweet" |

O Qwen3-Reranker é treinado nativamente como julgador de pares: emite `yes` ou `no` em resposta a uma instrução. Aqui mantemos esse protocolo literal e re-orientamos o `yes` para significar *nota útil*, com loss binária `BCEWithLogitsLoss` sobre `logit("yes") − logit("no")`. O tamanho `0.6B` viabiliza fine-tune fold-a-fold sob `StratifiedGroupKFold(5)` no mesmo regime dos baselines lexicais e bi-encoder, mantendo a comparação justa.

## Como usar

```python
import json, torch
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel
from huggingface_hub import snapshot_download

REPO = "histlearn/community-notes-reranker-ptbr"
path = snapshot_download(REPO, allow_patterns=["manifesto.json", "adapter_fold_1/*"])
m    = json.load(open(f"{path}/manifesto.json"))

tok  = AutoTokenizer.from_pretrained(m["base_model"], padding_side="left")
base = AutoModelForCausalLM.from_pretrained(
    m["base_model"], torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32)
model = PeftModel.from_pretrained(base, f"{path}/adapter_fold_1")
if torch.cuda.is_available(): model.cuda()
model.eval()

def util_prob(tweet: str, nota: str) -> float:
    text = (m["prompt_prefixo"] + "<Instruct>: " + m["instrucao"] +
            "\n<Query>: " + tweet + "\n<Document>: " + nota + m["prompt_sufixo"])
    enc = tok(text, return_tensors="pt", truncation=True, max_length=m["max_length"]).to(model.device)
    with torch.no_grad():
        l = model(**enc).logits[:, -1, :]
    return float(torch.sigmoid(l[:, m["id_yes"]] - l[:, m["id_no"]]).item())
```

O ponto operacional ótimo medido sob CV (Platt scaling) é `prob >= 0.38` — o reranker emite logits não calibrados que tendem a ficar abaixo de 0.50. Para reproduzir o número reportado abaixo, use o ensemble dos 5 folds (`examples/inference_ensemble.py`); a média das 5 probabilidades dá o resultado de referência.

## Resultados

Avaliação *out-of-fold* sob `StratifiedGroupKFold(5)` agrupado por `tweetId`, em 13.525 notas em PT-BR (universo `CRH ∪ CRNH`, 71,7% positivos).

| Configuração | macro-F1 | ROC-AUC | MCC | PR-AUC (minoritária) |
|---|---|---|---|---|
| **Ensemble de 5 folds (média de probabilidades)** | **0.7920** | **0.8932** | **0.5905** | **0.8293** |

Comparado às demais configurações testadas no projeto sob o mesmo protocolo (ver notebook `02_pipeline_experimento.ipynb` no [Space](https://huggingface.co/spaces/histlearn/communitynotesbr)):

| Configuração de referência | macro-F1 | ROC-AUC | Usa tweet? |
|---|---|---|---|
| Baseline trivial (classe majoritária) | 0.4175 | 0.5000 | — |
| TF-IDF da nota + Logistic Regression | 0.7725 | 0.8622 | não |
| Embedding Qwen *frozen* da nota + LR | 0.7489 | 0.8488 | não |
| Embedding Qwen *frozen* nota+tweet + LR | 0.7193 | 0.8057 | sim (sem aprendizado) |
| **Qwen3-Reranker-0.6B + LoRA (este modelo)** | **0.7920** | **0.8932** | **sim (aprendido)** |
| Stacking dos baselines acima + este modelo | 0.8282 | 0.9081 | sim |

O ganho do cross-encoder fine-tunado sobre o melhor baseline lexical é de ~2 pp macro-F1 e ~3 pp ROC-AUC. Sob bootstrap de 300 reamostras, IC95 do stacking é [0.821, 0.835] contra [0.785, 0.800] deste modelo — intervalos não se sobrepõem, confirmando significância. Com representações *frozen*, somar o tweet degrada o desempenho (linha 4 da tabela); o ganho aparece quando o modelo aprende a interação entre os dois textos.

## Dados de treino

- **Notas:** [`histlearn/notas-comunidade-ptbr`](https://huggingface.co/datasets/histlearn/notas-comunidade-ptbr) — 142.448 notas em PT-BR (CC0). Universo estrito (`consenso ∈ {CRH, CRNH}`) após filtro: ~20k notas; após hidratação dos tweets: **13.525 notas usadas**.
- **Tweets:** hidratados via *X syndication*. Não redistribuídos (restrição da X).

## Detalhes de treinamento

| | |
|---|---|
| Base | `Qwen/Qwen3-Reranker-0.6B` |
| Método | LoRA (`r=16`, `α=32`, `dropout=0.1`) |
| Alvos LoRA | `q_proj`, `k_proj`, `v_proj`, `o_proj` |
| Loss | `BCEWithLogitsLoss` sobre `logit(yes) − logit(no)`, com `pos_weight = n_neg / n_pos` |
| Otimizador | AdamW, `lr = 1e-4` |
| Batch | 8 |
| Épocas | 2 por fold |
| `max_length` | 512 |
| Precisão | fp16 |
| Protocolo | `StratifiedGroupKFold(5)` agrupado por `tweetId` |
| Seed | 42 |

### Template do prompt

```
<|im_start|>system
Judge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>
<|im_start|>user
<Instruct>: A nota e uma Community Note util e bem avaliada para o tweet?
<Query>: <texto do tweet>
<Document>: <texto da nota><|im_end|>
<|im_start|>assistant
<think>

</think>


```

Score = `sigmoid(logits["yes"] − logits["no"])` na última posição.

## Escopo

O modelo prevê se a comunidade marcaria a nota como útil, não se o conteúdo é factualmente correto — útil ≠ verdadeiro. Os números refletem o universo `CRH ∪ CRNH` (notas que já receberam consenso) e o subconjunto cujos tweets foram hidratados via *X syndication* (~70% das notas elegíveis). Domínio: PT-BR, contexto político-social brasileiro 2024–2025. Sob deslocamento temporal (treino no passado, teste no futuro), o ensemble degrada cerca de 1 pp macro-F1; baselines lexicais sozinhos degradam cerca de 3 pp.

## Reprodutibilidade

O projeto está hospedado inteiramente no Hugging Face:

- **Demo e contexto:** [`histlearn/communitynotesbr`](https://huggingface.co/spaces/histlearn/communitynotesbr) — Space com a página *Anatomia do classificador*.
- **Dataset principal:** [`histlearn/notas-comunidade-ptbr`](https://huggingface.co/datasets/histlearn/notas-comunidade-ptbr).
- **Dump bruto da X:** [`histlearn/community-notes-br`](https://huggingface.co/datasets/histlearn/community-notes-br).

Os 5 adapters correspondem exatamente às dobras do `StratifiedGroupKFold(5)` agrupado por `tweetId` rodado no notebook 2 do projeto. O pacote completo de artefatos (~190 MB, com embeddings pré-computados, scores de reranker zero-shot, índices das dobras e OOFs de todos os modelos comparados) é distribuído junto com os notebooks da entrega.

## Citação

```bibtex
@misc{communitynotes_reranker_ptbr_2026,
  author    = {Rocha, Davi Machado},
  title     = {Community Notes Reranker (PT-BR) — Qwen3-Reranker-0.6B fine-tunado com LoRA},
  year      = {2026},
  publisher = {Hugging Face},
  url       = {https://huggingface.co/histlearn/community-notes-reranker-ptbr},
  note      = {Disciplina Introdução à IA, prof. Ricardo M. Marcacini, ICMC/USP}
}
```

## Licença

Apache 2.0.