Ir al contenido principal
Español— Elegir un idioma
Menú

Puntuaciones y umbrales de moderación

Lección 7 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Interpretación de las puntuaciones de moderación
  2. Definición de tus umbrales: la matriz de decisión
  3. Sistema de clasificación multinivel
  4. Ejemplo práctico: analizar y decidir
  5. Ajuste dinámico de los umbrales
  6. Errores que debes evitar
  7. Puntos clave

Actualizado el 3 de noviembre de 2026. Los perfiles de umbral hacían referencia anteriormente a categorías inexistentes (hate, violence, unpredictable); ahora se alinean con las once claves de mistral-moderation-2603, incluyendo dangerous. La guía de interpretación de puntuaciones se ofrece como referencia de formación, ya que Mistral no publica ninguna. El monitor lanzaba anteriormente un KeyError para cualquier categoría faltante en el perfil y utilizaba datetime.utcnow(), que está obsoleto desde Python 3.12. Fuentes: Moderation & Guardrailing · datetime.utcnow.

Interpretación de las puntuaciones de moderación

Cada categoría devuelve una puntuación entre 0,0 y 1,0. Pero, ¿qué significan realmente estos números? ¿Y cómo estableces los umbrales de decisión para tu aplicación? Esta lección te da las claves para convertir puntuaciones brutas en decisiones automatizadas, pasando de la medición a la política.

En primer lugar, debes entender que Mistral no presenta estas puntuaciones como probabilidades calibradas. Una puntuación de 0,6 no significa «una probabilidad de seis sobre diez de que este texto sea peligroso»; es una señal fuerte del clasificador. La documentación destaca dos puntos útiles. Los booleanos categories en la respuesta aplican umbrales que Mistral eligió para un rendimiento óptimo en su conjunto de pruebas interno; puedes usarlos o partir de las puntuaciones brutas y establecer los tuyos propios. En ese conjunto de pruebas, la precisión de la categoría oscila entre 0,8 y 1,0, y la exhaustividad entre 0,7 y 1,0: se producen tanto falsos positivos como contenido omitido, razón por la cual los umbrales ajustados manualmente son importantes.

La cuadrícula siguiente no la publica Mistral: es una referencia de partida para validarla frente a tus propias métricas.

RangoInterpretación
0,0 - 0,1Contenido claramente seguro, sin señal detectada
0,1 - 0,3Señal débil, posiblemente benigna pero ambigua
0,3 - 0,5Señal moderada, contenido potencialmente problemático
0,5 - 0,7Señal fuerte, contenido muy probablemente problemático
0,7 - 1,0Señal muy fuerte, contenido manifiestamente peligroso

Definición de tus umbrales: la matriz de decisión

Elegir un umbral es un equilibrio entre seguridad (bloquear tanto como sea posible) y usabilidad (minimizar los falsos positivos). Ninguna configuración gana en ambos frentes, y afirmar lo contrario conduce a un ida y vuelta interminable. El método de trabajo consiste en definir tres perfiles explícitos y asignar cada aplicación a uno de ellos.

El perfil estricto está dirigido a una aplicación de consumo donde pueden estar presentes menores; el perfil equilibrado se ajusta a una aplicación profesional B2B con usuarios identificados; el perfil permisivo está reservado para una herramienta interna gestionada por expertos que saben lo que solicitan.

# Tres perfiles de umbral
PROFILES = {
    "strict": {
        # Aplicación de consumo, posibles niños
        "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": {
        # Aplicación profesional 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": {
        # Herramienta interna para expertos
        "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,
    },
}

Compara la columna health en todos los perfiles: 0,2, luego 0,4 y finalmente 0,7. El mismo intercambio sobre la dosificación se bloqueará en el primer caso y se aceptará en el último. Decide el contexto de uso, no la naturaleza del texto.

Sistema de clasificación multinivel

Bloquear o aceptar es una visión simplificada de la realidad. Entre el contenido manifiestamente seguro y el contenido manifiestamente infractor existe una zona gris donde la decisión correcta es mostrar mientras se marca. La función siguiente introduce este tercer estado: por encima del umbral, bloquear; por encima del 60 % del umbral, advertir y registrar; por debajo de eso, dejar pasar.

from enum import Enum

class RiskLevel(Enum):
    SAFE = "safe"          # Verde: contenido seguro
    WARNING = "warning"    # Naranja: contenido a monitorizar
    BLOCKED = "blocked"    # Rojo: contenido bloqueado

def classify_content(scores: dict, thresholds: dict) -> dict:
    """Clasifica el contenido en 3 niveles de riesgo."""
    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 advertencia: 60 % del umbral
            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"
        }

El valor de la zona naranja es tanto operativo como educativo: te muestra qué está rozando tus umbrales. Si una categoría genera muchas advertencias sin cruzar nunca la línea, sabes que un ajuste de unas pocas centésimas desplazaría un volumen significativo de tráfico.

Ejemplo práctico: analizar y decidir

El ensamblaje se reduce a una función: llamar al clasificador, aplicar el perfil, tomar la decisión. La comparación siguiente sirve de demostración: una dosificación de paracetamol se bloquea en el perfil estricto bajo health y se acepta en el perfil permisivo, sin cambiar ni una sola línea 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 el texto y toma una decisión basada en el perfil."""
    # Llamada a la API de moderación
    response = client.classifiers.moderate(
        model="mistral-moderation-2603",
        inputs=[text]
    )
    scores = response.results[0].category_scores or {}

    # Aplicar umbrales del 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
    }

# Prueba con diferentes perfiles
text = "Take 2 paracetamol tablets every 6 hours"

# Perfil estricto: probablemente bloqueado (health)
result_strict = moderate_and_decide(text, "strict")

# Perfil permisivo: probablemente aceptado
result_permissive = moderate_and_decide(text, "permissive")

Ajuste dinámico de los umbrales

En producción, tus umbrales deben evolucionar, y diriges esa evolución con datos. El monitor siguiente escribe cada decisión en un archivo JSONL y mantiene contadores de bloqueos, advertencias y aprobaciones, categoría por categoría. El informe resultante te ofrece una tasa de bloqueo por categoría: la única métrica que te indica si un umbral es demasiado bajo.

import json
from datetime import datetime, timezone

class ModerationMonitor:
    """Recopila métricas de moderación para ajustar umbrales."""

    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):
        """Registra una decisión de moderación."""
        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")

        # Actualizar 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:
        """Genera un informe para ajustar umbrales."""
        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

Errores que debes evitar

El primer error es aplicar un único umbral a todas las categorías. Cada categoría tiene su propia distribución de puntuaciones: un umbral de 0,3 para hate_and_discrimination no significa lo mismo que 0,3 para health, donde el contenido legítimo vive naturalmente más alto en la escala. Ajusta cada categoría individualmente, aunque eso implique tomar once decisiones en lugar de una.

El segundo es ignorar los falsos positivos. Una tasa de bloqueo alta erosiona la confianza del usuario mucho más rápido que un incidente aislado, porque afecta a personas que actúan de buena fe. Rastrea la tasa de bloqueo por categoría y eleva los umbrales cuando los datos lo justifiquen.

El tercero, más insidioso, es no registrar las decisiones. Sin registros, no puedes ajustar tus umbrales de forma informada y vuelves a discusiones basadas en opiniones. Registra sistemáticamente las puntuaciones, los umbrales aplicados y las decisiones tomadas; este corpus es lo que hará que la siguiente revisión sea rápida e indiscutible.

Puntos clave

  • Las puntuaciones van de 0,0 a 1,0; no son probabilidades calibradas y Mistral recomienda establecer tus propios umbrales
  • Define perfiles de umbral adaptados a tu contexto (estricto, equilibrado, permisivo)
  • Implementa un sistema de 3 niveles: seguro, advertencia, bloqueado
  • Registra todas las decisiones para ajustar continuamente tus umbrales
  • Cada categoría requiere su propio umbral; ningún valor único sirve para todo