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

API de moderación de Mistral

Lección 5 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Clasificar el contenido tras la generación
  2. El modelo Mistral Moderation 2
  3. El punto de acceso /v1/moderations
  4. Estructura de la respuesta
  5. Moderar varios textos por lotes
  6. Barreras de seguridad frente a API de Moderación: cuándo usar cada una
  7. Ejemplo: canalización completa
  8. Puntos clave

Actualizado el 3 de noviembre de 2026. El ejemplo de respuesta incluía anteriormente claves inexistentes (hate, violence, unpredictable); ahora refleja las once categorías de mistral-moderation-2603. La canalización final utilizaba antes un formato de barrera de seguridad inventado (enabled) y detectaba los bloqueos buscando “403” en el mensaje de error: ahora sigue el formato oficial y comprueba e.status_code. La presentación del modelo se adhiere a su ficha técnica oficial, y la lección introduce Shieldstral 1.0, el modelo de moderación en vista previa pública desde agosto de 2026. Código verificado frente a los tipos del SDK mistralai versión 3.7.0. Fuentes: Moderation & Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.

Clasificar el contenido tras la generación

Las barreras de seguridad filtran los prompts de entrada. ¿Pero qué ocurre con el contenido generado por el modelo? Un prompt inocente puede producir una respuesta problemática: la pregunta de un estudiante de secundaria sobre la Segunda Guerra Mundial podría generar una descripción que no quieras mostrar sin advertencias. Ese es el papel de la API de Moderación: analizar el contenido a posteriori y asignar puntuaciones de riesgo por categoría.

La API de Moderación es tu segunda línea de defensa; complementa a las barreras de seguridad para crear una arquitectura de seguridad completa, con una diferencia fundamental: no bloquea nada por sí sola, solo te informa.

El modelo Mistral Moderation 2

El modelo de moderación dedicado se llama mistral-moderation-2603 (Mistral Moderation 2, versión de marzo de 2026). Es un clasificador especializado, distinto de los modelos de generación: no escribe texto, asigna puntuaciones. Su ficha técnica oficial destaca una ventana de contexto de 128.000 tokens, detección de jailbreak y un rendimiento sólido en contenido multilingüe complejo, incluidas conversaciones largas. Sustituye a mistral-moderation-2411, que quedó obsoleto el 31 de marzo de 2026.

Puntúa cada texto en 11 categorías, con una puntuación de 0,0 a 1,0 por categoría. Acepta dos modos de entrada, texto plano o conversacional, y elegir entre ellos afecta a la calidad de los resultados más de lo que podrías esperar.

Existe un segundo modelo de moderación desde el 4 de agosto de 2026, en vista previa pública: Shieldstral 1.0. Funciona de manera diferente: es compacto (3.800 millones de parámetros) y multimodal; clasifica texto e imágenes basándose en preguntas de políticas formuladas en lenguaje natural, respondiendo sí o no. Sus pesos se publican bajo la licencia Apache 2.0, lo que permite el autoalojamiento. Mientras permanezca en vista previa, mistral-moderation-2603 sigue siendo el modelo de producción y es el que se utiliza para las barreras de seguridad.

El punto de acceso /v1/moderations

El modo de texto plano es el más sencillo: envías uno o varios textos para clasificar, sin contexto adicional.

from mistralai.client import Mistral
import os

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

# Moderar texto simple
response = client.classifiers.moderate(
    model="mistral-moderation-2603",
    inputs=["Texto a analizar para moderación"]
)

# Acceder a los resultados
for result in response.results:
    print(f"Categorías: {result.categories}")
    print(f"Puntuaciones: {result.category_scores}")

Para moderar intercambios completos, el prompt y la respuesta juntos, el modo conversacional proporciona al clasificador lo que le faltaba: el hilo de la discusión.

# Moderar una conversación completa
response = client.classifiers.moderate_chat(
    model="mistral-moderation-2603",
    inputs=[
        [
            {"role": "user", "content": "¿Cómo trato un dolor de cabeza?"},
            {"role": "assistant", "content": "Tome 1 g de paracetamol..."}
        ]
    ]
)

# El clasificador evalúa el contexto completo
for result in response.results:
    print(f"Puntuación de salud: {(result.category_scores or {}).get('health', 0)}")

El modo conversacional, que llama al punto de acceso /v1/chat/moderations, es lo que Mistral recomienda para un intercambio: el modelo está entrenado para clasificar el último turno de la conversación a la luz de los anteriores. Para moderar la respuesta de tu asistente, colócala en último lugar. La lista de listas del ejemplo permite enviar varias conversaciones a la vez; una lista simple de mensajes basta para una sola. Así, el mismo texto puede recibir una puntuación diferente dependiendo de si responde a una pregunta legítima o maliciosa: una dosis citada en respuesta a una solicitud de información no tiene el mismo estatus que esa misma dosis deslizada en un intercambio sobre automedicación de riesgo.

Estructura de la respuesta

Para cada texto analizado, la respuesta contiene dos bloques paralelos: categories, booleanos calculados con umbrales establecidos por Mistral basándose en su conjunto de pruebas interno, y category_scores, las puntuaciones brutas de 0,0 a 1,0. El ejemplo siguiente es ilustrativo, con valores redondeados; algunos ejemplos de la documentación aún muestran las nueve categorías del modelo antiguo, donde dangerous_and_criminal_content combinaba dangerous y criminal. Tú usarás estas últimas porque te permiten establecer tus propios límites.

{
  "id": "mod-abc123",
  "model": "mistral-moderation-2603",
  "results": [
    {
      "categories": {
        "sexual": false,
        "hate_and_discrimination": false,
        "violence_and_threats": false,
        "dangerous": false,
        "criminal": false,
        "selfharm": false,
        "health": true,
        "financial": false,
        "law": false,
        "pii": false,
        "jailbreaking": false
      },
      "category_scores": {
        "sexual": 0.01,
        "hate_and_discrimination": 0.02,
        "violence_and_threats": 0.03,
        "dangerous": 0.02,
        "criminal": 0.01,
        "selfharm": 0.01,
        "health": 0.72,
        "financial": 0.05,
        "law": 0.08,
        "pii": 0.02,
        "jailbreaking": 0.01
      }
    }
  ]
}

En este ejemplo, solo health está marcado como true, con 0,72. Un asistente orientado al consumidor vería esto como una señal de bloqueo; una herramienta destinada a farmacéuticos la dejaría pasar sin dudarlo. La misma puntuación, dos decisiones opuestas, y esa es precisamente la razón por la que trabajas con puntuaciones en lugar de booleanos.

Moderar varios textos por lotes

La API acepta varios textos en una única solicitud, lo que lo cambia todo para el procesamiento por lotes: analizar retroactivamente un historial de conversaciones o una base de datos de comentarios se convierte en una operación razonable en términos de número de llamadas.

# Moderar varios textos en una única solicitud
texts = [
    "Primer texto a analizar",
    "Segundo texto a analizar",
    "Tercer texto a analizar"
]

response = client.classifiers.moderate(
    model="mistral-moderation-2603",
    inputs=texts
)

# Cada texto tiene su propio resultado
for i, result in enumerate(response.results):
    scores = result.category_scores or {}
    max_cat = max(scores, key=lambda c: scores[c])
    max_score = scores[max_cat]
    print(f"Texto {i+1}: puntuación máx. = {max_score:.2f} ({max_cat})")

Barreras de seguridad frente a API de Moderación: cuándo usar cada una

AspectoBarreras de seguridad personalizadasAPI de Moderación
MomentoANTES de la generaciónDESPUÉS de la generación
AcciónBloquea automáticamente (403)Devuelve puntuaciones (tú decides)
ControlTus umbrales por categoría, aplicados por MistralPuntuaciones brutas, lógica libre
LlamadaParámetro de la solicitud de generaciónLlamada separada a /v1/moderations
Caso de usoFiltrar prompts peligrososClasificar respuestas

Ejemplo: canalización completa

La siguiente canalización muestra la secuenciación de los dos mecanismos. La generación está protegida por una barrera de seguridad centrada en el jailbreaking; la respuesta se clasifica luego junto con la pregunta que la produjo, y una decisión personalizada interviene tan pronto como una puntuación supera 0,5. Ten en cuenta que los dos pasos devuelven estados distintos —blocked_input y blocked_output— para que tus registros indiquen claramente dónde se detuvo la solicitud.

from mistralai.client import errors
from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAIL_JAILBREAK: list[GuardrailConfigTypedDict] = [
    {
        "block_on_error": True,
        "moderation_llm_v2": {
            "custom_category_thresholds": {"jailbreaking": 0.1},
            "action": "block",
        },
    }
]


def secure_pipeline(user_message: str) -> dict:
    """Canalización con barreras de seguridad (entrada) y moderación (salida)."""
    # Paso 1: generar con barreras de seguridad
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[{"role": "user", "content": user_message}],
            guardrails=GUARDRAIL_JAILBREAK,
        )
    except errors.SDKError as e:
        if e.status_code == 403:
            return {"status": "blocked_input", "content": None}
        raise

    generated = response.choices[0].message.content
    if not isinstance(generated, str):
        return {"status": "error", "content": None}

    # Paso 2: moderar la salida, en el contexto de la pregunta
    moderation = client.classifiers.moderate_chat(
        model="mistral-moderation-2603",
        inputs=[
            {"role": "user", "content": user_message},
            {"role": "assistant", "content": generated},
        ],
    )

    scores = moderation.results[0].category_scores or {}
    if max(scores.values(), default=0.0) > 0.5:
        return {"status": "blocked_output", "scores": scores}

    return {"status": "ok", "content": generated, "scores": scores}

Puntos clave

  • La API de Moderación utiliza el modelo mistral-moderation-2603 para clasificar contenido
  • Dos modos disponibles: texto plano y conversacional
  • Las puntuaciones van de 0,0 a 1,0: tú defines tus propios umbrales de decisión
  • El modo conversacional es más preciso porque tiene en cuenta el contexto
  • Combina barreras de seguridad (entrada) + moderación (salida) para una defensa en profundidad