API de moderación de Mistral
En esta página
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 demistral-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 compruebae.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 SDKmistralaiversió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
| Aspecto | Barreras de seguridad personalizadas | API de Moderación |
|---|---|---|
| Momento | ANTES de la generación | DESPUÉS de la generación |
| Acción | Bloquea automáticamente (403) | Devuelve puntuaciones (tú decides) |
| Control | Tus umbrales por categoría, aplicados por Mistral | Puntuaciones brutas, lógica libre |
| Llamada | Parámetro de la solicitud de generación | Llamada separada a /v1/moderations |
| Caso de uso | Filtrar prompts peligrosos | Clasificar 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-2603para 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