Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Pontuações e Limiares de Moderação

Aula 7 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Interpretação das Pontuações de Moderação
  2. Definição dos Seus Limiares: A Matriz de Decisão
  3. Sistema de Classificação Multinível
  4. Exemplo Prático: Analisar e Decidir
  5. Ajuste Dinâmico dos Limiares
  6. Armadilhas a Evitar
  7. Pontos-chave

Atualizado a 3 de novembro de 2026. Os perfis de limiar referiam anteriormente categorias inexistentes (hate, violence, unpredictable); agora estão alinhados com as onze chaves de mistral-moderation-2603, incluindo dangerous. O guia de interpretação de pontuações é fornecido como referência de formação, uma vez que a Mistral não publica nenhum. O monitor levantava anteriormente um KeyError para qualquer categoria em falta no perfil e utilizava datetime.utcnow(), que está obsoleto desde o Python 3.12. Fontes: Moderation & Guardrailing · datetime.utcnow.

Interpretação das Pontuações de Moderação

Cada categoria devolve uma pontuação entre 0,0 e 1,0. Mas o que significam realmente estes números? E como define limiares de decisão para a sua aplicação? Esta lição dá-lhe as chaves para transformar pontuações brutas em decisões automatizadas — passando da medição para a política.

Em primeiro lugar, compreenda que a Mistral não apresenta estas pontuações como probabilidades calibradas. Uma pontuação de 0,6 não significa “seis em dez hipóteses de este texto ser perigoso”; é um sinal forte do classificador. A documentação destaca dois pontos úteis. Os booleanos categories na resposta aplicam limiares escolhidos pela Mistral para um desempenho ótimo no seu conjunto de testes interno; pode utilizá-los ou partir das pontuações brutas e definir os seus próprios. Nesse conjunto de testes, a precisão por categoria varia de 0,8 a 1,0 e a revocação de 0,7 a 1,0: ocorrem tanto falsos positivos como conteúdos omitidos, razão pela qual os limiares ajustados manualmente são importantes.

A grelha abaixo não é publicada pela Mistral: é uma referência inicial para validar face às suas próprias métricas.

IntervaloInterpretação
0,0 - 0,1Conteúdo claramente seguro, nenhum sinal detetado
0,1 - 0,3Sinal fraco, possivelmente benigno mas ambíguo
0,3 - 0,5Sinal moderado, conteúdo potencialmente problemático
0,5 - 0,7Sinal forte, conteúdo muito provavelmente problemático
0,7 - 1,0Sinal muito forte, conteúdo manifestamente perigoso

Definição dos Seus Limiares: A Matriz de Decisão

Escolher um limiar é um compromisso entre segurança (bloquear o máximo possível) e usabilidade (minimizar falsos positivos). Nenhuma configuração ganha nas duas frentes, e afirmar o contrário leva a um vaivém interminável. O método de trabalho consiste em definir três perfis explícitos e mapear cada aplicação para um deles.

O perfil estrito visa uma aplicação de consumo onde podem estar presentes menores; o perfil equilibrado adequa-se a uma aplicação profissional B2B com utilizadores identificados; o perfil permissivo é reservado a uma ferramenta interna manuseada por especialistas que sabem o que estão a pedir.

# Três perfis de limiar
PROFILES = {
    "strict": {
        # Aplicação de consumo, crianças possíveis
        "sexual": 0.1,
        "hate_and_discrimination": 0.1,
        "violence_and_threats": 0.1,
        "dangerous": 0.1,
        "criminal": 0.1,
        "selfharm": 0.1,
        "health": 0.2,
        "financial": 0.2,
        "law": 0.2,
        "pii": 0.1,
        "jailbreaking": 0.1,
    },
    "balanced": {
        # Aplicação profissional B2B
        "sexual": 0.2,
        "hate_and_discrimination": 0.15,
        "violence_and_threats": 0.25,
        "dangerous": 0.15,
        "criminal": 0.15,
        "selfharm": 0.15,
        "health": 0.4,
        "financial": 0.4,
        "law": 0.4,
        "pii": 0.2,
        "jailbreaking": 0.15,
    },
    "permissive": {
        # Ferramenta interna para especialistas
        "sexual": 0.3,
        "hate_and_discrimination": 0.2,
        "violence_and_threats": 0.4,
        "dangerous": 0.2,
        "criminal": 0.2,
        "selfharm": 0.2,
        "health": 0.7,
        "financial": 0.7,
        "law": 0.7,
        "pii": 0.3,
        "jailbreaking": 0.2,
    },
}

Compare a coluna health entre os perfis: 0,2, depois 0,4, depois 0,7. A mesma troca sobre dosagem será bloqueada no primeiro caso e aceite no último. O contexto de uso decide, não a natureza do texto.

Sistema de Classificação Multinível

Bloquear ou aceitar é uma visão simplista da realidade. Entre o conteúdo manifestamente seguro e o conteúdo manifestamente violador existe uma zona cinzenta onde a decisão correta é exibir assinalando. A função abaixo introduz este terceiro estado: acima do limiar, bloquear; acima de 60% do limiar, avisar e registar; abaixo disso, deixar passar.

from enum import Enum

class RiskLevel(Enum):
    SAFE = "safe"          # Verde: conteúdo seguro
    WARNING = "warning"    # Laranja: conteúdo a monitorizar
    BLOCKED = "blocked"    # Vermelho: conteúdo bloqueado

def classify_content(scores: dict, thresholds: dict) -> dict:
    """Classifica o conteúdo em 3 níveis de risco."""
    blocking_violations = []
    warnings = []

    for category, threshold in thresholds.items():
        score = scores.get(category, 0)

        if score > threshold:
            blocking_violations.append({
                "category": category,
                "score": round(score, 3)
            })
        elif score > threshold * 0.6:
            # Zona de aviso: 60% do limiar
            warnings.append({
                "category": category,
                "score": round(score, 3)
            })

    if blocking_violations:
        return {
            "level": RiskLevel.BLOCKED,
            "violations": blocking_violations,
            "action": "block_and_log"
        }
    elif warnings:
        return {
            "level": RiskLevel.WARNING,
            "warnings": warnings,
            "action": "display_and_log"
        }
    else:
        return {
            "level": RiskLevel.SAFE,
            "action": "display"
        }

O valor da zona laranja é tanto operacional como educativo: mostra-lhe o que está a roçar os seus limiares. Se uma categoria gerar muitos avisos sem nunca cruzar a linha, sabe que um ajuste de algumas centésimas deslocaria um volume significativo de tráfego.

Exemplo Prático: Analisar e Decidir

A montagem resume-se a uma função: chamar o classificador, aplicar o perfil, tomar a decisão. A comparação abaixo serve de demonstração — uma dosagem de paracetamol é bloqueada no perfil estrito sob health e aceite no perfil permissivo, sem alterar uma única linha de texto.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

def moderate_and_decide(text: str, profile: str = "balanced") -> dict:
    """Modera o texto e toma uma decisão com base no perfil."""
    # Chamada à API de moderação
    response = client.classifiers.moderate(
        model="mistral-moderation-2603",
        inputs=[text]
    )
    scores = response.results[0].category_scores or {}

    # Aplicar limiares do perfil
    thresholds = PROFILES[profile]
    classification = classify_content(scores, thresholds)

    return {
        "text": text[:80],
        "profile": profile,
        "raw_scores": {k: round(v, 3) for k, v in scores.items()},
        "decision": classification
    }

# Testar com diferentes perfis
text = "Take 2 paracetamol tablets every 6 hours"

# Perfil estrito: provavelmente bloqueado (health)
result_strict = moderate_and_decide(text, "strict")

# Perfil permissivo: provavelmente aceite
result_permissive = moderate_and_decide(text, "permissive")

Ajuste Dinâmico dos Limiares

Em produção, os seus limiares devem evoluir, e você orienta essa evolução com dados. O monitor abaixo escreve cada decisão num ficheiro JSONL e mantém contadores para bloqueios, avisos e passagens, categoria por categoria. O relatório resultante dá-lhe uma taxa de bloqueio por categoria — a única métrica que lhe diz se um limiar é demasiado baixo.

import json
from datetime import datetime, timezone

class ModerationMonitor:
    """Recolhe métricas de moderação para ajustar limiares."""

    def __init__(self, log_file: str = "moderation_logs.jsonl"):
        self.log_file = log_file
        self.stats = {cat: {"blocked": 0, "warned": 0, "passed": 0}
                     for cat in PROFILES["balanced"].keys()}

    def log_decision(self, scores: dict, thresholds: dict, decision: str):
        """Regista uma decisão de moderação."""
        entry = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "scores": scores,
            "thresholds": thresholds,
            "decision": decision
        }
        with open(self.log_file, "a") as f:
            f.write(json.dumps(entry) + "\n")

        # Atualizar contadores
        for cat, threshold in thresholds.items():
            score = scores.get(cat, 0.0)
            self.stats.setdefault(cat, {"blocked": 0, "warned": 0, "passed": 0})
            if score > threshold:
                self.stats[cat]["blocked"] += 1
            elif score > threshold * 0.6:
                self.stats[cat]["warned"] += 1
            else:
                self.stats[cat]["passed"] += 1

    def report(self) -> dict:
        """Gera um relatório para ajustar limiares."""
        report = {}
        for cat, stats in self.stats.items():
            total = sum(stats.values())
            if total > 0:
                report[cat] = {
                    "block_rate": round(stats["blocked"] / total, 3),
                    "warning_rate": round(stats["warned"] / total, 3),
                    "total": total
                }
        return report

Armadilhas a Evitar

A primeira armadilha é um único limiar aplicado a todas as categorias. Cada categoria tem a sua própria distribuição de pontuações: um limiar de 0,3 para hate_and_discrimination não significa o mesmo que 0,3 para health, onde o conteúdo legítimo vive naturalmente mais alto na escala. Ajuste cada categoria individualmente, mesmo que isso signifique tomar onze decisões em vez de uma.

A segunda é ignorar os falsos positivos. Uma taxa de bloqueio elevada corrói a confiança do utilizador muito mais depressa do que um incidente isolado, porque afeta pessoas que agem de boa-fé. Acompanhe a taxa de bloqueio por categoria e aumente os limiares quando os dados o justificarem.

A terceira, mais insidiosa, é não registar as decisões. Sem registos, não pode ajustar os seus limiares de forma informada e reverte para discussões baseadas em opiniões. Registe sistematicamente as pontuações, os limiares aplicados e as decisões tomadas — este corpus é o que tornará a próxima revisão rápida e indiscutível.

Pontos-chave

  • As pontuações variam de 0,0 a 1,0; não são probabilidades calibradas e a Mistral incentiva a definição dos seus próprios limiares
  • Defina perfis de limiar adaptados ao seu contexto (estrito, equilibrado, permissivo)
  • Implemente um sistema de 3 níveis: seguro, aviso, bloqueado
  • Registe todas as decisões para ajustar continuamente os seus limiares
  • Cada categoria requer o seu próprio limiar — nenhum valor único serve para todos