Barreras de seguridad personalizadas: bloqueo antes del modelo
En esta página
Lección reescrita el 3 de noviembre de 2026. La versión anterior describía un parámetro
guardrailsficticio (un diccionario conenabled), categorías inexistentes (hate,violence), un métodoconversation.send()ausente en el SDK y respuestas JSON imaginarias. El formato oficial es una lista de configuracionesmoderation_llm_v2, y las respuestas siguientes coinciden con la documentación. El código se ha verificado frente a los tipos del SDKmistralaiversión 3.7.0. Fuentes: Moderation & Guardrailing · mistralai Python SDK.
El principio de las barreras de seguridad personalizadas
Las barreras de seguridad personalizadas (Custom Guardrails) de Mistral actúan como un filtro de entrada: analizan el prompt del usuario antes de que llegue al modelo de generación. Si el contenido supera algún umbral que hayas configurado, la solicitud se bloquea con un error HTTP 403. El modelo nunca llega a ver el prompt problemático.
Ten presentes desde el inicio dos limitaciones. En primer lugar, las barreras moderan solo la entrada; no comprueban lo que genera el modelo. Esa es la función de la API de Moderación (lección 5). En segundo lugar, sustituyen trabajo que, de otro modo, tendrías que programar tú mismo: llamar a la API de Moderación, comparar las puntuaciones con tus umbrales y rechazar la solicitud.
Cómo funciona
Cuando añades barreras de seguridad a una solicitud, el flujo en el lado de Mistral es el siguiente:
- Tu aplicación envía la solicitud con el parámetro
guardrails. - El clasificador
mistral-moderation-2603puntúa el prompt en cada categoría. - Si una puntuación supera su umbral, la API devuelve un error
403y no se llama al modelo. - En caso contrario, el modelo procesa la solicitud con normalidad.
- La respuesta incluye un campo
guardrailsque contiene las puntuaciones evaluadas.
Flujo: prompt → [mistral-moderation-2603] → ¿puntuación > umbral? → 403 (bloqueado)
→ si no → [LLM] → respuesta + puntuaciones
La decisión se basa en una puntuación comparada con un umbral que estableces tú, categoría por categoría, entre 0 y 1. Un umbral bajo bloquea más contenido; un umbral de 1 desactiva explícitamente la categoría.
Formato del parámetro guardrails
El parámetro es una lista. Cada elemento es un objeto que contiene una configuración moderation_llm_v2 y, junto a ella, la opción block_on_error:
guardrails = [
{
"block_on_error": True, # bloquear si la propia moderación falla
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Clave | Ubicación | Función |
|---|---|---|
custom_category_thresholds | dentro de moderation_llm_v2 | Umbral de 0 a 1 por categoría; 1 desactiva la categoría |
ignore_other_categories | dentro de moderation_llm_v2 | True: solo se evalúan las categorías listadas |
action | dentro de moderation_llm_v2 | "block" para rechazar la solicitud si se supera un umbral |
model_name | dentro de moderation_llm_v2, opcional | Modelo de moderación distinto del predeterminado mistral-moderation-2603 |
block_on_error | junto a moderation_llm_v2 | True: la solicitud se bloquea si la evaluación falla |
Puedes colocar varios objetos en la lista: la solicitud se bloquea en cuanto cualquiera de ellos se activa. Cada objeto contiene una única configuración moderation_llm_v2. Existe aún una configuración antigua, moderation_llm_v1, en el SDK con categorías del modelo obsoleto mistral-moderation-2411 (obsoleto el 31 de marzo de 2026): no la uses en proyectos nuevos.
Las once categorías
Las claves en custom_category_thresholds son fijas; otra clave, como violence o hate, no corresponde a nada:
| Clave | Qué detecta |
|---|---|
sexual | Contenido sexual explícito |
hate_and_discrimination | Odio o discriminación basada en características protegidas |
violence_and_threats | Violencia física descrita, glorificada o amenazada |
dangerous | Comportamientos extremadamente peligrosos |
criminal | Actividades ilegales |
selfharm | Autolesiones, suicidio, trastornos alimentarios |
health | Solicitudes de consejos médicos detallados o personalizados |
financial | Solicitudes de consejos financieros detallados o personalizados |
law | Solicitudes de consejos legales detallados o personalizados |
pii | Datos personales solicitados o compartidos |
jailbreaking | Intentos de eludir las reglas del modelo |
La lección 6 retoma cada una de estas y analiza la selección de umbrales.
Los tres niveles de aplicación
El mismo parámetro se acepta en tres lugares. Tu elección determina dónde reside tu política de seguridad y quién podría olvidar aplicarla.
Nivel 1: Una solicitud de Chat Completions
Pasas guardrails en la llamada chat.complete(). Cada solicitud lleva sus propias reglas: práctico para la exploración, pero arriesgado a gran escala, ya que una única llamada sin el parámetro se cuela sin control.
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is the distance from the Earth to the Moon?"}],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"sexual": 0.1, "selfharm": 0.1},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
print(response.choices[0].message.content)
Caso de uso: Prototipado, llamadas puntuales, ajuste de umbrales.
Nivel 2: Una conversación
Con la API de Conversaciones, pasas guardrails al inicio, en client.beta.conversations.start():
conversation = client.beta.conversations.start(
model="mistral-large-latest",
inputs="Hello, can you help me prepare for an interview?",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"selfharm": 0.1,
},
"action": "block",
},
}
],
)
for entree in conversation.outputs:
if entree.type == "message.output":
print(entree.content)
Los mensajes posteriores se envían con client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Este método no acepta un parámetro guardrails en el SDK 3.7.0, y la documentación no especifica si las barreras de seguridad del inicio se aplican a los turnos siguientes. Para garantizar la protección en cada turno, adjunta las barreras de seguridad a un agente.
Caso de uso: Conversación puntual sin agente, o anulación de las barreras de seguridad de un agente para una solicitud concreta.
Nivel 3: Un agente
Las barreras de seguridad pasadas a client.beta.agents.create() pasan a formar parte de la definición del agente. Según la documentación, todas las conversaciones que usen este agente las heredan sin necesidad de repetirlas. Sin embargo, una solicitud de conversación puede anularlas pasando sus propias guardrails.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Secure Assistant",
instructions="You are a professional customer service assistant.",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"jailbreaking": 0.3,
},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
conversation = client.beta.conversations.start(agent_id=agent.id, inputs="Hello!")
Caso de uso: Producción, cuando varios equipos o servicios llaman al mismo asistente.
Qué devuelven las barreras de seguridad
Cuando la solicitud pasa, la respuesta de la API incluye, junto a los campos estándar, un campo guardrails: una lista con un resultado por barrera de seguridad. Aquí tienes ese campo del ejemplo de la documentación:
{
"guardrails": [
{
"moderation_llm_v2": {
"action": "pass",
"categories": {
"sexual": { "score": 0.03, "violated": false },
"selfharm": { "score": 0.05, "violated": false },
"violence_and_threats": { "score": 0.0, "violated": false },
"hate_and_discrimination": { "score": 0.0, "violated": false }
}
}
}
]
}
Con ignore_other_categories establecido en True, solo las categorías listadas en tus umbrales aparecen en este resultado. En el SDK de Python, una respuesta de conversación expone este campo (conversation.guardrails). La respuesta de chat.complete(), sin embargo, no tiene un campo designado para ello en el SDK 3.7.0: allí se pierde. Si quieres registrar las puntuaciones —y es útil saber más adelante si tus umbrales son demasiado laxos o estrictos—, usa conversaciones o lee la respuesta HTTP cruda.
Cuando se supera un umbral, la API devuelve un error 403 cuyo cuerpo detalla la decisión, categoría por categoría:
{
"error": { "message": "Content blocked by guardrail", "status": 403 },
"guardrails": {
"results": {
"moderation_llm_v2": {
"model_name": "mistral-moderation-2603",
"decisions": {
"sexual": { "threshold": 0.1, "score": 0.3, "violated": true },
"selfharm": { "threshold": 0.1, "score": 0.05, "violated": false }
},
"violated": true,
"action": "block"
}
}
}
}
El SDK lanza entonces errors.SDKError, donde status_code es 403 y body contiene este JSON:
import json
from mistralai.client import errors
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": user_message}],
guardrails=guardrails,
)
except errors.SDKError as e:
if e.status_code != 403:
raise
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
violated = [name for name, d in decisions.items() if d["violated"]]
print(f"Request blocked: {violated}")
Esta carga útil te permite explicar un bloqueo durante una apelación: qué categoría, qué puntuación, qué umbral.
Por último, está el caso degradado. Si la propia evaluación falla y block_on_error es True, la solicitud se rechaza con el código de error 3201 y el mensaje Request blocked due to error in guardrail evaluation and block_on_error is set to True. Este es el modo fail-safe (seguro ante fallos): ante la duda, bloquear. Con block_on_error establecido en False (su valor predeterminado en el SDK), la solicitud pasaría sin control.
Elección del nivel adecuado
| Criterio | Chat Completions | Conversación | Agente |
|---|---|---|---|
| Dónde se declaran las barreras | En cada llamada | Al inicio (start) | En la creación del agente |
| Herencia | Ninguna | No documentada para turnos siguientes | Todas las conversaciones del agente |
| Anulable | — | — | Sí, mediante una solicitud de conversación |
| Caso de uso | Pruebas, ajuste de umbrales | Conversación puntual | Producción |
En la práctica, ajusta tus umbrales en solicitudes de Chat Completions usando casos reales y, a continuación, traslada la política a un agente en cuanto el código salga de tu máquina: así no habrá más llamadas olvidadas.
Puntos clave
- Las barreras bloquean los prompts antes del modelo mediante un error
403; no comprueban la salida - El parámetro es una lista de objetos
{"block_on_error": ..., "moderation_llm_v2": {...}}, no un diccionario conenabled - Once categorías con nombres fijos (
hate_and_discrimination,violence_and_threats, …), cada una con un umbral de 0 a 1;1desactiva - Tres niveles:
chat.complete(),conversations.start(),agents.create(); los agentes pasan sus barreras a todas sus conversaciones block_on_error=Truegarantiza un comportamiento fail-safe (error3201)