feat: migrar para bge-m3 (568M params, mean pooling, fold 04→fold_01)

README.md

@@ -10,7 +10,7 @@ app_file: app.py
 pinned: false
 short_description: Classificador de utilidade para community notes em PT-BR.
 models:
-  - Qwen/Qwen3-Embedding-4B
+  - BAAI/bge-m3
 ---
 
 # Notinhas — endpoint de utilidade (FT-Solo)
@@ -20,8 +20,8 @@ note* em português, devolve a probabilidade de ela ser classificada como "útil
 (`label_binary_strict = 1`), junto com uma leitura opcional da contribuição de
 cada palavra.
 
-Arquitetura: **Qwen3-Embedding-4B + LoRA + cabeça linear**, idêntica ao
-`predict_from_text` do notebook `explicabilidade_qwen4b_redesign` em modo fiel
+Arquitetura: **bge-m3 (568M params) + LoRA + cabeça linear**, idêntica ao
+`predict_from_text` do notebook FT-Solo em modo fiel
 (fold 01).
 
 ## Estrutura do repositório
@@ -38,7 +38,7 @@ Arquitetura: **Qwen3-Embedding-4B + LoRA + cabeça linear**, idêntica ao
     ├── fold_01_adapter/   # Pasta do adapter LoRA
     │   ├── adapter_config.json
     │   └── adapter_model.safetensors
-    └── fold_01_head.pt    # State dict do nn.Linear(2560, 1)
+    └── fold_01_head.pt    # State dict do nn.Linear(1024, 1)
 ```
 
 ## Setup — do zero até o Space no ar
@@ -51,13 +51,13 @@ Na UI do Hugging Face:
 2. SDK: **Gradio**.
 3. Hardware: **T4 small** (recomendado — caber na memória em bf16 e inferência
    em ~0,5 s). **A10G small** dá latência ainda menor. **ZeroGPU** funciona mas
-   com cold-start mais longo. **CPU** roda, porém cada inferência leva 20–40 s.
+   com cold-start mais longo. **CPU** roda — inferência ~4–8 s com bge-m3 (vs 20–40 s do Qwen3).
 4. Visibility: **Private**.
 
 ### 2. Popular `artifacts/`
 
 Os pesos vêm do pipeline do projeto. O zip base do Drive (`artefatos_projeto.zip`)
-traz as pastas `qwen4b_adapters/` e `qwen4b_heads/`. Rode localmente:
+traz as pastas com adapters e heads bge-m3. Rode localmente:
 
 ```bash
 pip install gdown
@@ -91,7 +91,7 @@ git commit -m "feat: endpoint inicial FT-Solo"
 git push
 ```
 
-O adapter do Qwen3-Embedding-4B em LoRA costuma ficar entre **20 e 80 MB**
+O adapter bge-m3 em LoRA costuma ficar entre **20 e 60 MB**
 (dependendo do rank e dos módulos-alvo). A cabeça é ~20 KB. Tudo cabe
 confortavelmente sem apertar quota.
 
@@ -99,7 +99,7 @@ confortavelmente sem apertar quota.
 
 Em **Settings → Variables and secrets**:
 
-- `HF_TOKEN` — só necessário se `Qwen/Qwen3-Embedding-4B` virar gated no futuro.
+- `HF_TOKEN` — só necessário se `BAAI/bge-m3` virar gated no futuro.
   Hoje o modelo é público, então você pode ignorar.
 
 ### 5. Primeiro boot
@@ -107,7 +107,7 @@ Em **Settings → Variables and secrets**:
 Na primeira inicialização o Space:
 
 1. Instala `requirements.txt` (~1 min).
-2. Baixa `Qwen/Qwen3-Embedding-4B` da HF (~8 GB, ~2–3 min).
+2. Baixa `BAAI/bge-m3` da HF (~2 GB, ~30–60 s).
 3. Carrega adapter + head (~5 s).
 4. Fica pronto — e o warm-up do modelo já aconteceu, o primeiro request é rápido.
 

app.py

@@ -1,390 +1,386 @@
-"""Gradio app — endpoint de utilidade para community notes em PT-BR.
-
-Expõe:
-  - UI web com três abas: Prever / Explicar / Sobre.
-  - API HTTP em /gradio_api/call/predict e /gradio_api/call/explain (gerada
-    automaticamente pelo Gradio a partir dos api_name).
-
-Para clientes Python, use gradio_client:
-
-    from gradio_client import Client
-    c = Client("<user>/<space>", hf_token="hf_...")
-    score = c.predict("texto da nota...", api_name="/predict")
-"""
-from __future__ import annotations
-
-import html
-import logging
-import os
-import traceback
-from pathlib import Path
-
-import gradio as gr
-
-from config import (
-    CONFIDENCE_BOUNDS_ALTA,
-    CONFIDENCE_BOUNDS_MEDIA,
-    THRESHOLD_UTIL,
-)
-from inference import DEVICE, explain_occlusion, predict_one, warmup
-
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-)
-log = logging.getLogger("app")
-
-# ---------------------------------------------------------------------------
-# CSS do projeto
-# ---------------------------------------------------------------------------
-APP_DIR = Path(__file__).resolve().parent
-STYLE_PATH = APP_DIR / "styles.css"
-CUSTOM_CSS = STYLE_PATH.read_text(encoding="utf-8") if STYLE_PATH.exists() else ""
-
-
-
-# ---------------------------------------------------------------------------
-# Warm-up agressivo — queremos que o primeiro request não pague cold-start
-# ---------------------------------------------------------------------------
-MODEL_READY: bool
-MODEL_ERROR: str | None
-
-try:
-    warmup()
-    MODEL_READY = True
-    MODEL_ERROR = None
-    log.info("Modelo carregado no startup. Device=%s", DEVICE)
-except Exception as exc:  # noqa: BLE001 — queremos pegar qualquer falha de carregamento
-    MODEL_READY = False
-    MODEL_ERROR = f"{type(exc).__name__}: {exc}"
-    log.error("Falha ao carregar modelo no startup:\n%s", traceback.format_exc())
-
-
-# ---------------------------------------------------------------------------
-# Helpers de apresentação
-# ---------------------------------------------------------------------------
-def _confidence_band(p: float) -> str:
-    lo_a, hi_a = CONFIDENCE_BOUNDS_ALTA
-    lo_m, hi_m = CONFIDENCE_BOUNDS_MEDIA
-    if p <= lo_a or p >= hi_a:
-        return "Alta"
-    if p <= lo_m or p >= hi_m:
-        return "Média"
-    return "Baixa"
-
-
-def _label(p: float) -> str:
-    return "Útil" if p >= THRESHOLD_UTIL else "Não-útil"
-
-
-def _score_card_html(p: float) -> str:
-    """Card principal do resultado — usando classes CSS do projeto."""
-    lbl = _label(p)
-    band = _confidence_band(p)
-
-    lbl_class = "notinhas-badge-util" if lbl == "Útil" else "notinhas-badge-nao-util"
-
-    if band == "Alta":
-        band_class = lbl_class
-    elif band == "Média":
-        band_class = "notinhas-badge-media"
-    else:
-        band_class = "notinhas-badge-baixa"
-
-    return f"""
-    <div class="notinhas-card">
-      <div style="display:flex;justify-content:space-between;align-items:center;gap:12px;flex-wrap:wrap;">
-        <div style="display:flex;gap:8px;flex-wrap:wrap;">
-          <span class="notinhas-badge {lbl_class}">{lbl}</span>
-          <span class="notinhas-badge {band_class}">Confiança {band}</span>
-        </div>
-
-        <div style="text-align:right;">
-          <div class="notinhas-score-label">P(útil)</div>
-          <div class="notinhas-score-value">{p:.4f}</div>
-        </div>
-      </div>
-    </div>
-    """
-
-
-def _contrib_color(v: float, v_max: float) -> str:
-    if v_max <= 0:
-        return "transparent"
-    intensity = min(1.0, abs(v) / v_max)
-    alpha = 0.15 + 0.65 * intensity  # 0.15 .. 0.80
-    if v > 0:
-        return f"rgba(95, 168, 143, {alpha:.3f})"  # verde (PALETA['util'] do notebook)
-    return f"rgba(224, 123, 107, {alpha:.3f})"  # coral (PALETA['nao_util'])
-
-
-def _highlighted_text_html(tokens: list[str], contribs: list[float]) -> str:
-    if not tokens:
-        return "<em>(sem palavras para destacar)</em>"
-    v_max = max((abs(c) for c in contribs), default=1e-9) or 1e-9
-    spans = []
-    for tok, c in zip(tokens, contribs):
-        bg = _contrib_color(c, v_max)
-        spans.append(
-            f'<span style="background:{bg};padding:2px 4px;border-radius:4px;'
-            f'margin:0 1px;" title="Δ={c:+.6f}">{html.escape(tok)}</span>'
-        )
-    return (
-        '<div style="font-size:15px;line-height:2;color:#212529;'
-        'font-family:system-ui, -apple-system, sans-serif;padding:4px;">'
-        + " ".join(spans)
-        + "</div>"
-    )
-
-
-def _top_tokens_table_html(
-    tokens: list[str], contribs: list[float], k: int = 5
-) -> str:
-    pairs = list(zip(tokens, contribs))
-    pos = sorted([p for p in pairs if p[1] > 0], key=lambda x: -x[1])[:k]
-    neg = sorted([p for p in pairs if p[1] < 0], key=lambda x: x[1])[:k]
-
-    def _row(tok: str, v: float, side: str) -> str:
-        color = "#1b4332" if side == "pos" else "#9d0208"
-        return (
-            f'<tr><td style="padding:5px 8px;color:{color};">'
-            f"{html.escape(tok)}</td>"
-            f'<td style="padding:5px 8px;text-align:right;color:{color};'
-            f'font-variant-numeric:tabular-nums;">{v:+.6f}</td></tr>'
-        )
-
-    empty = '<tr><td colspan="2" style="padding:6px;color:#9aa1aa;"><em>—</em></td></tr>'
-    pos_rows = "".join(_row(t, v, "pos") for t, v in pos) or empty
-    neg_rows = "".join(_row(t, v, "neg") for t, v in neg) or empty
-
-    all_same_side = (not neg and pos) or (not pos and neg)
-    if not neg and pos:
-        side_warning = (
-            '<p style="font-size:12px;color:#6c757d;margin:10px 4px 0 4px;line-height:1.5;">'
-            '⚠️ <strong>Nenhuma palavra puxando para não-útil identificada.</strong> '
-            'O método leave-one-out compara a frase completa com cada ablação de uma palavra. '
-            'Quando todas as contribuições são positivas, a frase completa pontua '
-            'marginalmente <em>mais</em> do que qualquer subconjunto — comum em textos '
-            'muito curtos ou frases com sentido idiomático. '
-            'O texto permanece Não-útil porque P(útil) está longe do limiar (0.5); '
-            'o que o define é a <em>ausência</em> de características úteis '
-            '(fontes, dados, neutralidade), não palavras negativas específicas.'
-            '</p>'
-        )
-    elif not pos and neg:
-        side_warning = (
-            '<p style="font-size:12px;color:#6c757d;margin:10px 4px 0 4px;line-height:1.5;">'
-            '⚠️ <strong>Nenhuma palavra puxando para útil identificada.</strong> '
-            'Todas as palavras reduzem marginalmente P(útil) quando presentes.'
-            '</p>'
-        )
-    else:
-        side_warning = ""
-
-    return f"""
-    <div style="display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:12px;
-                font-family:system-ui, -apple-system, sans-serif;">
-      <div style="background:#fcfcfd;border:1px solid #eef2f7;border-radius:12px;padding:12px;">
-        <div style="font-size:13px;font-weight:700;color:#1b4332;margin-bottom:6px;">
-          Empurram para útil
-        </div>
-        <table style="width:100%;border-collapse:collapse;font-size:13px;">{pos_rows}</table>
-      </div>
-      <div style="background:#fcfcfd;border:1px solid #eef2f7;border-radius:12px;padding:12px;">
-        <div style="font-size:13px;font-weight:700;color:#9d0208;margin-bottom:6px;">
-          Empurram para não-útil
-        </div>
-        <table style="width:100%;border-collapse:collapse;font-size:13px;">{neg_rows}</table>
-      </div>
-    </div>
-    """ + side_warning
-
-
-# ---------------------------------------------------------------------------
-# Handlers — retornam HTML para a UI + JSON para a API
-# ---------------------------------------------------------------------------
-def handle_predict(text: str):
-    text = (text or "").strip()
-    if not text:
-        return "<em>Forneça um texto.</em>", {"error": "empty_input"}
-    if not MODEL_READY:
-        err = MODEL_ERROR or "modelo indisponível"
-        return (
-            f"<em>Modelo indisponível: {html.escape(err)}</em>",
-            {"error": "model_unavailable", "detail": err},
-        )
-
-    p = predict_one(text)
-    return (
-        _score_card_html(p),
-        {
-            "proba_util": p,
-            "label": _label(p),
-            "confidence_band": _confidence_band(p),
-        },
-    )
-
-
-def handle_explain(text: str):
-    text = (text or "").strip()
-    if not text:
-        return "<em>Forneça um texto.</em>", "", "", {"error": "empty_input"}
-    if not MODEL_READY:
-        err = MODEL_ERROR or "modelo indisponível"
-        return (
-            f"<em>Modelo indisponível: {html.escape(err)}</em>",
-            "",
-            "",
-            {"error": "model_unavailable", "detail": err},
-        )
-
-    result = explain_occlusion(text)
-    p = result["proba_full"]
-    tokens = result["tokens"]
-    contribs = result["contributions"]
-
-    return (
-        _score_card_html(p),
-        _highlighted_text_html(tokens, contribs),
-        _top_tokens_table_html(tokens, contribs),
-        {
-            "proba_util": p,
-            "label": _label(p),
-            "confidence_band": _confidence_band(p),
-            "tokens": tokens,
-            "contributions": contribs,
-        },
-    )
-
-
-# ---------------------------------------------------------------------------
-# UI
-# ---------------------------------------------------------------------------
-EXAMPLE_UTIL = (
-    "Segundo dados oficiais do Ministério da Saúde, o número citado no tweet é falso. "
-    "A fonte correta pode ser conferida no link: https://www.gov.br/saude/..."
-)
-EXAMPLE_NAO = "Essa nota é claramente desnecessária, é opinião pessoal do autor."
-
-INTRO_MD = """
-# Notinhas — endpoint de utilidade (FT-Solo)
-
-Classificador de utilidade para **community notes em português**, baseado em
-**Qwen3-Embedding-4B + LoRA + cabeça linear** (modo fiel do FT-Solo, fold 01).
-
-- **Prever** — score + label + faixa de confiança.
-- **Explicar** — o mesmo + contribuição de cada palavra via leave-one-out.
-- **Sobre** — detalhes técnicos e limitações.
-"""
-
-
-with gr.Blocks(
-    title="Notinhas — endpoint de utilidade (FT-Solo)",
-    theme=gr.themes.Base(),
-    css=CUSTOM_CSS,
-) as demo:
-    gr.Markdown(INTRO_MD)
-
-    if not MODEL_READY:
-        gr.Markdown(
-            f"""
-> ⚠️ **Modelo não carregou.** Detalhe: `{html.escape(MODEL_ERROR or '')}`
->
-> Verifique que `artifacts/fold_01_adapter/` e `artifacts/fold_01_head.pt` estão presentes
-> no repositório do Space. Se o modelo base exigir autenticação, configure `HF_TOKEN` em
-> **Settings → Variables and secrets**.
-"""
-        )
-
-    with gr.Tab("Prever"):
-        with gr.Row():
-            with gr.Column(scale=2):
-                inp_p = gr.Textbox(
-                    label="Texto da nota",
-                    placeholder="Cole aqui o texto em português...",
-                    lines=7,
-                    max_lines=25,
-                )
-                btn_p = gr.Button("Prever", variant="primary")
-                gr.Examples(examples=[[EXAMPLE_UTIL], [EXAMPLE_NAO]], inputs=[inp_p])
-            with gr.Column(scale=3):
-                out_card_p = gr.HTML(label="Resultado")
-                out_json_p = gr.JSON(label="Resposta da API")
-
-        btn_p.click(
-            handle_predict,
-            inputs=[inp_p],
-            outputs=[out_card_p, out_json_p],
-            api_name="predict",
-        )
-
-    with gr.Tab("Explicar"):
-        with gr.Row():
-            with gr.Column(scale=2):
-                inp_e = gr.Textbox(
-                    label="Texto da nota",
-                    placeholder="Cole aqui o texto em português...",
-                    lines=7,
-                    max_lines=25,
-                )
-                btn_e = gr.Button("Explicar", variant="primary")
-                gr.Examples(examples=[[EXAMPLE_UTIL], [EXAMPLE_NAO]], inputs=[inp_e])
-            with gr.Column(scale=3):
-                out_card_e = gr.HTML(label="Resultado")
-                out_hl = gr.HTML(label="Contribuição por palavra")
-                out_tbl = gr.HTML(label="Top tokens por lado")
-                out_json_e = gr.JSON(label="Resposta da API")
-
-        btn_e.click(
-            handle_explain,
-            inputs=[inp_e],
-            outputs=[out_card_e, out_hl, out_tbl, out_json_e],
-            api_name="explain",
-        )
-
-    with gr.Tab("Sobre"):
-        gr.Markdown(
-            f"""
-### Detalhes técnicos
-
-- **Modelo base**: `Qwen/Qwen3-Embedding-4B` (embedding, 2.560 dims, last-token pooling).
-- **Adaptação**: LoRA treinado com alvo `label_binary_strict` (recorte A do projeto).
-- **Cabeça**: `nn.Linear(2560, 1)` → sigmoid.
-- **Prompt de instrução** (idêntico ao treino):
-
-  > `Instruct: Represent the following Brazilian Portuguese community note for binary classification of helpfulness.`
-  > `Query: <texto>`
-
-- **max_length**: 256 tokens.
-- **Dispositivo atual**: `{DEVICE}`.
-- **Fold servido**: 01 (melhor fold segundo o manifesto do pipeline).
-
-### Método de explicação
-
-A aba **Explicar** usa **occlusion word-level** (leave-one-out): para cada palavra
-separada por espaço, calculamos `Δ = P(texto completo) − P(texto sem a palavra)`.
-
-- Δ positivo ⇒ palavra puxando para **útil** (verde).
-- Δ negativo ⇒ palavra puxando para **não-útil** (coral).
-
-É uma aproximação rápida do SHAP Partition usado no notebook de explicabilidade
-(~1–2 s vs ~12–15 s em GPU), com resultados visualmente comparáveis para notas curtas.
-
-### Limitações
-
-- O rótulo `helpful` mede **aceitabilidade bipartidária**, não qualidade editorial.
-  A galeria curada do notebook mostra casos onde vizinhos semânticos idênticos
-  recebem rótulos opostos por razões políticas.
-- Textos são truncados em 256 tokens.
-- Este endpoint serve um único fold. Para produção com ganho marginal de robustez,
-  subir para ensemble dos 5 folds (média de probabilidades).
-"""
-        )
-
-
-if __name__ == "__main__":
-    demo.queue(default_concurrency_limit=1).launch(
-        server_name="0.0.0.0",
-        server_port=int(os.environ.get("PORT", 7860)),
-        show_api=True,
-    )
+"""Gradio app — endpoint de utilidade para community notes em PT-BR.
+
+Expõe:
+  - UI web com três abas: Prever / Explicar / Sobre.
+  - API HTTP em /gradio_api/call/predict e /gradio_api/call/explain (gerada
+    automaticamente pelo Gradio a partir dos api_name).
+
+Para clientes Python, use gradio_client:
+
+    from gradio_client import Client
+    c = Client("<user>/<space>", hf_token="hf_...")
+    score = c.predict("texto da nota...", api_name="/predict")
+"""
+from __future__ import annotations
+
+import html
+import logging
+import os
+import traceback
+from pathlib import Path
+
+import gradio as gr
+
+from config import (
+    CONFIDENCE_BOUNDS_ALTA,
+    CONFIDENCE_BOUNDS_MEDIA,
+    THRESHOLD_UTIL,
+)
+from inference import DEVICE, explain_occlusion, predict_one, warmup
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+log = logging.getLogger("app")
+
+# ---------------------------------------------------------------------------
+# CSS do projeto
+# ---------------------------------------------------------------------------
+APP_DIR = Path(__file__).resolve().parent
+STYLE_PATH = APP_DIR / "styles.css"
+CUSTOM_CSS = STYLE_PATH.read_text(encoding="utf-8") if STYLE_PATH.exists() else ""
+
+
+
+# ---------------------------------------------------------------------------
+# Warm-up agressivo — queremos que o primeiro request não pague cold-start
+# ---------------------------------------------------------------------------
+MODEL_READY: bool
+MODEL_ERROR: str | None
+
+try:
+    warmup()
+    MODEL_READY = True
+    MODEL_ERROR = None
+    log.info("Modelo carregado no startup. Device=%s", DEVICE)
+except Exception as exc:  # noqa: BLE001 — queremos pegar qualquer falha de carregamento
+    MODEL_READY = False
+    MODEL_ERROR = f"{type(exc).__name__}: {exc}"
+    log.error("Falha ao carregar modelo no startup:\n%s", traceback.format_exc())
+
+
+# ---------------------------------------------------------------------------
+# Helpers de apresentação
+# ---------------------------------------------------------------------------
+def _confidence_band(p: float) -> str:
+    lo_a, hi_a = CONFIDENCE_BOUNDS_ALTA
+    lo_m, hi_m = CONFIDENCE_BOUNDS_MEDIA
+    if p <= lo_a or p >= hi_a:
+        return "Alta"
+    if p <= lo_m or p >= hi_m:
+        return "Média"
+    return "Baixa"
+
+
+def _label(p: float) -> str:
+    return "Útil" if p >= THRESHOLD_UTIL else "Não-útil"
+
+
+def _score_card_html(p: float) -> str:
+    """Card principal do resultado — usando classes CSS do projeto."""
+    lbl = _label(p)
+    band = _confidence_band(p)
+
+    lbl_class = "notinhas-badge-util" if lbl == "Útil" else "notinhas-badge-nao-util"
+
+    if band == "Alta":
+        band_class = lbl_class
+    elif band == "Média":
+        band_class = "notinhas-badge-media"
+    else:
+        band_class = "notinhas-badge-baixa"
+
+    return f"""
+    <div class="notinhas-card">
+      <div style="display:flex;justify-content:space-between;align-items:center;gap:12px;flex-wrap:wrap;">
+        <div style="display:flex;gap:8px;flex-wrap:wrap;">
+          <span class="notinhas-badge {lbl_class}">{lbl}</span>
+          <span class="notinhas-badge {band_class}">Confiança {band}</span>
+        </div>
+
+        <div style="text-align:right;">
+          <div class="notinhas-score-label">P(útil)</div>
+          <div class="notinhas-score-value">{p:.4f}</div>
+        </div>
+      </div>
+    </div>
+    """
+
+
+def _contrib_color(v: float, v_max: float) -> str:
+    if v_max <= 0:
+        return "transparent"
+    intensity = min(1.0, abs(v) / v_max)
+    alpha = 0.15 + 0.65 * intensity  # 0.15 .. 0.80
+    if v > 0:
+        return f"rgba(95, 168, 143, {alpha:.3f})"  # verde (PALETA['util'] do notebook)
+    return f"rgba(224, 123, 107, {alpha:.3f})"  # coral (PALETA['nao_util'])
+
+
+def _highlighted_text_html(tokens: list[str], contribs: list[float]) -> str:
+    if not tokens:
+        return "<em>(sem palavras para destacar)</em>"
+    v_max = max((abs(c) for c in contribs), default=1e-9) or 1e-9
+    spans = []
+    for tok, c in zip(tokens, contribs):
+        bg = _contrib_color(c, v_max)
+        spans.append(
+            f'<span style="background:{bg};padding:2px 4px;border-radius:4px;'
+            f'margin:0 1px;" title="Δ={c:+.6f}">{html.escape(tok)}</span>'
+        )
+    return (
+        '<div style="font-size:15px;line-height:2;color:#212529;'
+        'font-family:system-ui, -apple-system, sans-serif;padding:4px;">'
+        + " ".join(spans)
+        + "</div>"
+    )
+
+
+def _top_tokens_table_html(
+    tokens: list[str], contribs: list[float], k: int = 5
+) -> str:
+    pairs = list(zip(tokens, contribs))
+    pos = sorted([p for p in pairs if p[1] > 0], key=lambda x: -x[1])[:k]
+    neg = sorted([p for p in pairs if p[1] < 0], key=lambda x: x[1])[:k]
+
+    def _row(tok: str, v: float, side: str) -> str:
+        color = "#1b4332" if side == "pos" else "#9d0208"
+        return (
+            f'<tr><td style="padding:5px 8px;color:{color};">'
+            f"{html.escape(tok)}</td>"
+            f'<td style="padding:5px 8px;text-align:right;color:{color};'
+            f'font-variant-numeric:tabular-nums;">{v:+.6f}</td></tr>'
+        )
+
+    empty = '<tr><td colspan="2" style="padding:6px;color:#9aa1aa;"><em>—</em></td></tr>'
+    pos_rows = "".join(_row(t, v, "pos") for t, v in pos) or empty
+    neg_rows = "".join(_row(t, v, "neg") for t, v in neg) or empty
+
+    all_same_side = (not neg and pos) or (not pos and neg)
+    if not neg and pos:
+        side_warning = (
+            '<p style="font-size:12px;color:#6c757d;margin:10px 4px 0 4px;line-height:1.5;">'
+            '⚠️ <strong>Nenhuma palavra puxando para não-útil identificada.</strong> '
+            'O método leave-one-out compara a frase completa com cada ablação de uma palavra. '
+            'Quando todas as contribuições são positivas, a frase completa pontua '
+            'marginalmente <em>mais</em> do que qualquer subconjunto — comum em textos '
+            'muito curtos ou frases com sentido idiomático. '
+            'O texto permanece Não-útil porque P(útil) está longe do limiar (0.5); '
+            'o que o define é a <em>ausência</em> de características úteis '
+            '(fontes, dados, neutralidade), não palavras negativas específicas.'
+            '</p>'
+        )
+    elif not pos and neg:
+        side_warning = (
+            '<p style="font-size:12px;color:#6c757d;margin:10px 4px 0 4px;line-height:1.5;">'
+            '⚠️ <strong>Nenhuma palavra puxando para útil identificada.</strong> '
+            'Todas as palavras reduzem marginalmente P(útil) quando presentes.'
+            '</p>'
+        )
+    else:
+        side_warning = ""
+
+    return f"""
+    <div style="display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:12px;
+                font-family:system-ui, -apple-system, sans-serif;">
+      <div style="background:#fcfcfd;border:1px solid #eef2f7;border-radius:12px;padding:12px;">
+        <div style="font-size:13px;font-weight:700;color:#1b4332;margin-bottom:6px;">
+          Empurram para útil
+        </div>
+        <table style="width:100%;border-collapse:collapse;font-size:13px;">{pos_rows}</table>
+      </div>
+      <div style="background:#fcfcfd;border:1px solid #eef2f7;border-radius:12px;padding:12px;">
+        <div style="font-size:13px;font-weight:700;color:#9d0208;margin-bottom:6px;">
+          Empurram para não-útil
+        </div>
+        <table style="width:100%;border-collapse:collapse;font-size:13px;">{neg_rows}</table>
+      </div>
+    </div>
+    """ + side_warning
+
+
+# ---------------------------------------------------------------------------
+# Handlers — retornam HTML para a UI + JSON para a API
+# ---------------------------------------------------------------------------
+def handle_predict(text: str):
+    text = (text or "").strip()
+    if not text:
+        return "<em>Forneça um texto.</em>", {"error": "empty_input"}
+    if not MODEL_READY:
+        err = MODEL_ERROR or "modelo indisponível"
+        return (
+            f"<em>Modelo indisponível: {html.escape(err)}</em>",
+            {"error": "model_unavailable", "detail": err},
+        )
+
+    p = predict_one(text)
+    return (
+        _score_card_html(p),
+        {
+            "proba_util": p,
+            "label": _label(p),
+            "confidence_band": _confidence_band(p),
+        },
+    )
+
+
+def handle_explain(text: str):
+    text = (text or "").strip()
+    if not text:
+        return "<em>Forneça um texto.</em>", "", "", {"error": "empty_input"}
+    if not MODEL_READY:
+        err = MODEL_ERROR or "modelo indisponível"
+        return (
+            f"<em>Modelo indisponível: {html.escape(err)}</em>",
+            "",
+            "",
+            {"error": "model_unavailable", "detail": err},
+        )
+
+    result = explain_occlusion(text)
+    p = result["proba_full"]
+    tokens = result["tokens"]
+    contribs = result["contributions"]
+
+    return (
+        _score_card_html(p),
+        _highlighted_text_html(tokens, contribs),
+        _top_tokens_table_html(tokens, contribs),
+        {
+            "proba_util": p,
+            "label": _label(p),
+            "confidence_band": _confidence_band(p),
+            "tokens": tokens,
+            "contributions": contribs,
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# UI
+# ---------------------------------------------------------------------------
+EXAMPLE_UTIL = (
+    "Segundo dados oficiais do Ministério da Saúde, o número citado no tweet é falso. "
+    "A fonte correta pode ser conferida no link: https://www.gov.br/saude/..."
+)
+EXAMPLE_NAO = "Essa nota é claramente desnecessária, é opinião pessoal do autor."
+
+INTRO_MD = """
+# Notinhas — endpoint de utilidade (FT-Solo)
+
+Classificador de utilidade para **community notes em português**, baseado em
+**bge-m3 (568M params) + LoRA + cabeça linear** (modo fiel do FT-Solo, fold 01).
+
+- **Prever** — score + label + faixa de confiança.
+- **Explicar** — o mesmo + contribuição de cada palavra via leave-one-out.
+- **Sobre** — detalhes técnicos e limitações.
+"""
+
+
+with gr.Blocks(
+    title="Notinhas — endpoint de utilidade (FT-Solo)",
+    theme=gr.themes.Base(),
+    css=CUSTOM_CSS,
+) as demo:
+    gr.Markdown(INTRO_MD)
+
+    if not MODEL_READY:
+        gr.Markdown(
+            f"""
+> ⚠️ **Modelo não carregou.** Detalhe: `{html.escape(MODEL_ERROR or '')}`
+>
+> Verifique que `artifacts/fold_01_adapter/` e `artifacts/fold_01_head.pt` estão presentes
+> no repositório do Space. Se o modelo base exigir autenticação, configure `HF_TOKEN` em
+> **Settings → Variables and secrets**.
+"""
+        )
+
+    with gr.Tab("Prever"):
+        with gr.Row():
+            with gr.Column(scale=2):
+                inp_p = gr.Textbox(
+                    label="Texto da nota",
+                    placeholder="Cole aqui o texto em português...",
+                    lines=7,
+                    max_lines=25,
+                )
+                btn_p = gr.Button("Prever", variant="primary")
+                gr.Examples(examples=[[EXAMPLE_UTIL], [EXAMPLE_NAO]], inputs=[inp_p])
+            with gr.Column(scale=3):
+                out_card_p = gr.HTML(label="Resultado")
+                out_json_p = gr.JSON(label="Resposta da API")
+
+        btn_p.click(
+            handle_predict,
+            inputs=[inp_p],
+            outputs=[out_card_p, out_json_p],
+            api_name="predict",
+        )
+
+    with gr.Tab("Explicar"):
+        with gr.Row():
+            with gr.Column(scale=2):
+                inp_e = gr.Textbox(
+                    label="Texto da nota",
+                    placeholder="Cole aqui o texto em português...",
+                    lines=7,
+                    max_lines=25,
+                )
+                btn_e = gr.Button("Explicar", variant="primary")
+                gr.Examples(examples=[[EXAMPLE_UTIL], [EXAMPLE_NAO]], inputs=[inp_e])
+            with gr.Column(scale=3):
+                out_card_e = gr.HTML(label="Resultado")
+                out_hl = gr.HTML(label="Contribuição por palavra")
+                out_tbl = gr.HTML(label="Top tokens por lado")
+                out_json_e = gr.JSON(label="Resposta da API")
+
+        btn_e.click(
+            handle_explain,
+            inputs=[inp_e],
+            outputs=[out_card_e, out_hl, out_tbl, out_json_e],
+            api_name="explain",
+        )
+
+    with gr.Tab("Sobre"):
+        gr.Markdown(
+            f"""
+### Detalhes técnicos
+
+- **Modelo base**: `BAAI/bge-m3` (embedding, 1.024 dims, mean pooling, 568M params).
+- **Adaptação**: LoRA treinado com alvo `label_binary_strict` (recorte A do projeto).
+- **Cabeça**: `nn.Linear(1024, 1)` → sigmoid.
+- **Prompt de instrução**: nenhum — texto cru (bge-m3 não usa prefix de instrução).
+- **max_length**: 256 tokens.
+- **Dispositivo atual**: `{DEVICE}`.
+- **Fold servido**: 01 (melhor fold segundo o manifesto do pipeline).
+
+### Método de explicação
+
+A aba **Explicar** usa **occlusion word-level** (leave-one-out): para cada palavra
+separada por espaço, calculamos `Δ = P(texto completo) − P(texto sem a palavra)`.
+
+- Δ positivo ⇒ palavra puxando para **útil** (verde).
+- Δ negativo ⇒ palavra puxando para **não-útil** (coral).
+
+É uma aproximação rápida do SHAP Partition usado no notebook de explicabilidade
+(~1–2 s vs ~12–15 s em GPU), com resultados visualmente comparáveis para notas curtas.
+
+### Limitações
+
+- O rótulo `helpful` mede **aceitabilidade bipartidária**, não qualidade editorial.
+  A galeria curada do notebook mostra casos onde vizinhos semânticos idênticos
+  recebem rótulos opostos por razões políticas.
+- Textos são truncados em 256 tokens.
+- Este endpoint serve um único fold. Para produção com ganho marginal de robustez,
+  subir para ensemble dos 5 folds (média de probabilidades).
+"""
+        )
+
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=1).launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+        show_api=True,
+    )

artifacts/fold_01_adapter/README.md

@@ -1,8 +1,8 @@
 ---
-base_model: Qwen/Qwen3-Embedding-4B
+base_model: BAAI/bge-m3
 library_name: peft
 tags:
-- base_model:adapter:Qwen/Qwen3-Embedding-4B
+- base_model:adapter:BAAI/bge-m3
 - lora
 - transformers
 ---

artifacts/fold_01_adapter/adapter_config.json

@@ -3,10 +3,10 @@
   "alpha_pattern": {},
   "arrow_config": null,
   "auto_mapping": {
-    "base_model_class": "Qwen3Model",
-    "parent_library": "transformers.models.qwen3.modeling_qwen3"
+    "base_model_class": "XLMRobertaModel",
+    "parent_library": "transformers.models.xlm_roberta.modeling_xlm_roberta"
   },
-  "base_model_name_or_path": "Qwen/Qwen3-Embedding-4B",
+  "base_model_name_or_path": "BAAI/bge-m3",
   "bias": "none",
   "corda_config": null,
   "ensure_weight_tying": false,
@@ -21,7 +21,7 @@
   "loftq_config": {},
   "lora_alpha": 32,
   "lora_bias": false,
-  "lora_dropout": 0.05,
+  "lora_dropout": 0.1,
   "megatron_config": null,
   "megatron_core": "megatron.core",
   "modules_to_save": null,
@@ -32,13 +32,10 @@
   "rank_pattern": {},
   "revision": null,
   "target_modules": [
-    "down_proj",
-    "q_proj",
-    "up_proj",
-    "gate_proj",
-    "k_proj",
-    "o_proj",
-    "v_proj"
+    "key",
+    "query",
+    "value",
+    "dense"
   ],
   "target_parameters": null,
   "task_type": null,

artifacts/fold_01_adapter/adapter_model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:326493c0cc026b088e80be86dc28fe61e21db919e52b602250e11abb6bac59b5
-size 132184864
+oid sha256:93d21f9a247eb8ce530e04b1f85055f7e405f5d0875ef646d6914de0d2a234a5
+size 28482384

artifacts/fold_01_head.pt

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:7a66a6088bce2a00b93377ecc4f8243e061eccdc4679f4920fd691b35a0523ab
-size 12365
+oid sha256:67ae73baff19fd870815c742171fe57d174bd984ccfd7f58751a37b44bbbda9c
+size 6093

config.py

@@ -1,54 +1,29 @@
-"""Constantes compartilhadas pelo Space.
-
-Mantemos tudo em um único módulo para facilitar trocas (ex: substituir o fold
-selecionado, apontar para um tokenizer diferente em debug, etc.).
-"""
+"""Constantes compartilhadas pelo Space (bge-m3 FT-Solo)."""
 from __future__ import annotations
 
 import os
 from pathlib import Path
 
-# ---------------------------------------------------------------------------
-# Modelo base (baixado da Hugging Face no primeiro startup do Space)
-# ---------------------------------------------------------------------------
-MODEL_NAME = "Qwen/Qwen3-Embedding-4B"
+# Modelo base — bge-m3 (568M params, ~7x menor que Qwen3-4B)
+MODEL_NAME = "BAAI/bge-m3"
 
-# ---------------------------------------------------------------------------
-# Inferência — parâmetros IDÊNTICOS aos do notebook (seção 6, predict_from_text)
-# ---------------------------------------------------------------------------
+# Inferência
 MAX_LENGTH = 256
 BATCH_SIZE = 8
 
-# Este prompt é parte do contrato do modelo — foi usado no fine-tuning.
-# Mudá-lo quebra o alinhamento entre o que o adapter viu e o que recebe agora.
-TASK_PROMPT = (
-    "Represent the following Brazilian Portuguese community note "
-    "for binary classification of helpfulness."
-)
+# bge-m3 NÃO usa prompt de instrução. None mantém compatibilidade.
+TASK_PROMPT = None
 
-# ---------------------------------------------------------------------------
-# Paths dos artefatos (resolvidos a partir da raiz do repo do Space)
-# ---------------------------------------------------------------------------
+# Paths
 ROOT = Path(__file__).resolve().parent
 ARTIFACTS_DIR = ROOT / "artifacts"
-
-# Obrigatórios para servir predição.
 ADAPTER_PATH = ARTIFACTS_DIR / "fold_01_adapter"
-HEAD_PATH = ARTIFACTS_DIR / "fold_01_head.pt"
+HEAD_PATH    = ARTIFACTS_DIR / "fold_01_head.pt"
 
-# ---------------------------------------------------------------------------
-# Classificação (thresholds de apresentação — não afetam a probabilidade em si)
-# ---------------------------------------------------------------------------
+# Classificação
 THRESHOLD_UTIL = 0.5
+CONFIDENCE_BOUNDS_ALTA  = (0.10, 0.90)
+CONFIDENCE_BOUNDS_MEDIA = (0.30, 0.70)
 
-# Faixas de confiança em função de p diretamente (evita imprecisão float do |p-0.5|):
-#   Alta   → p ≤ 0.10 ou p ≥ 0.90
-#   Média  → p ≤ 0.30 ou p ≥ 0.70
-#   Baixa  → 0.30 < p < 0.70
-CONFIDENCE_BOUNDS_ALTA = (0.10, 0.90)   # fora desses limites = Alta
-CONFIDENCE_BOUNDS_MEDIA = (0.30, 0.70)  # fora desses limites = Média
-
-# ---------------------------------------------------------------------------
-# Secrets (opcionais — definir em Settings → Secrets no Space)
-# ---------------------------------------------------------------------------
-HF_TOKEN = os.environ.get("HF_TOKEN")  # só necessário se o modelo base virar gated
+# Secret opcional
+HF_TOKEN = os.environ.get("HF_TOKEN")

inference.py

@@ -1,11 +1,7 @@
 """Carregamento do modelo e inferência.
 
-Espelha o modo 'fiel' (faithful) do FT-Solo no notebook de explicabilidade:
-base Qwen3-Embedding-4B + LoRA do fold 01 + cabeça linear treinada no projeto.
-
-A função `predict_from_text` do notebook está reproduzida aqui com a mesma
-tokenização, mesmo pooling, mesmo dtype e mesmo prompt — para que as
-probabilidades retornadas sejam numericamente comparáveis às OOF salvas.
+Serve o FT-Solo com base BAAI/bge-m3 + LoRA do fold 01 + cabeça linear.
+Pooling: mean sobre tokens reais (attention_mask). Sem prompt de instrução.
 """
 from __future__ import annotations
 
@@ -27,7 +23,6 @@ from config import (
     HF_TOKEN,
     MAX_LENGTH,
     MODEL_NAME,
-    TASK_PROMPT,
 )
 
 logger = logging.getLogger(__name__)
@@ -40,42 +35,26 @@ DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
 if DEVICE == "cuda":
     AMP_DTYPE = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
 else:
-    # Em CPU usamos float16 nos pesos para caber em 16 GB de RAM (fp32 daria ~16 GB
-    # só nos pesos, sem sobrar para ativações). As operações em CPU rodam em fp32
-    # via upcast automático; o dtype aqui só controla o armazenamento.
+    # Em CPU usamos float16 nos pesos para caber em RAM. As operações em CPU
+    # rodam em fp32 via upcast automático; o dtype aqui só controla armazenamento.
     # O autocast fica desligado (enabled=False abaixo) — fp16 ativo em CPU é instável.
     AMP_DTYPE = torch.float16
 
 
 # ---------------------------------------------------------------------------
-# Utilitários — idênticos ao notebook (seção 6)
+# Utilitários
 # ---------------------------------------------------------------------------
 def build_instruction_text(text: str) -> str:
-    """Formata o texto no molde esperado pelo fine-tuning."""
-    if not isinstance(text, str):
-        text = ""
-    return f"Instruct: {TASK_PROMPT}\nQuery: {text}"
+    """bge-m3 não usa prompt de instrução — retorna o texto cru."""
+    return text if isinstance(text, str) else ""
 
 
-def last_token_pool(
+def mean_pool(
     last_hidden_states: torch.Tensor, attention_mask: torch.Tensor
 ) -> torch.Tensor:
-    """Extrai o embedding do último token real.
-
-    Com o tokenizer em padding_side='left', o último índice (-1) é sempre um
-    token real para todos os elementos do batch, então podemos usar o atalho.
-    Mantemos a branch de right-padding por paranoia.
-    """
-    left_padding = bool(
-        (attention_mask[:, -1].sum() == attention_mask.shape[0]).item()
-    )
-    if left_padding:
-        return last_hidden_states[:, -1]
-    sequence_lengths = attention_mask.sum(dim=1) - 1
-    return last_hidden_states[
-        torch.arange(last_hidden_states.shape[0], device=last_hidden_states.device),
-        sequence_lengths,
-    ]
+    """Mean pooling sobre os tokens reais (mascara padding)."""
+    mask = attention_mask.unsqueeze(-1).float()
+    return (last_hidden_states * mask).sum(dim=1) / mask.sum(dim=1).clamp(min=1e-9)
 
 
 # ---------------------------------------------------------------------------
@@ -97,7 +76,7 @@ def load_model():
 
     logger.info("Carregando tokenizer de %s", MODEL_NAME)
     tokenizer = AutoTokenizer.from_pretrained(
-        MODEL_NAME, padding_side="left", token=HF_TOKEN
+        MODEL_NAME, padding_side="right", token=HF_TOKEN
     )
     if tokenizer.pad_token is None:
         tokenizer.pad_token = tokenizer.eos_token
@@ -179,7 +158,7 @@ def predict_batch(
             enabled=(DEVICE == "cuda"),
         ):
             out = encoder(**toks)
-            emb = last_token_pool(out.last_hidden_state, toks["attention_mask"])
+            emb = mean_pool(out.last_hidden_state, toks["attention_mask"])
             emb = F.normalize(emb, p=2, dim=1)
             # Em CPU sem autocast, o encoder sai em fp16 e a head permanece em fp32 →
             # F.linear recusa. Igualar ao dtype da head resolve (inofensivo em GPU).