Pontuações e Limiares de Moderação
Nesta página
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 demistral-moderation-2603, incluindodangerous. 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 umKeyErrorpara qualquer categoria em falta no perfil e utilizavadatetime.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.
| Intervalo | Interpretação |
|---|---|
| 0,0 - 0,1 | Conteúdo claramente seguro, nenhum sinal detetado |
| 0,1 - 0,3 | Sinal fraco, possivelmente benigno mas ambíguo |
| 0,3 - 0,5 | Sinal moderado, conteúdo potencialmente problemático |
| 0,5 - 0,7 | Sinal forte, conteúdo muito provavelmente problemático |
| 0,7 - 1,0 | Sinal 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