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

Barreras de seguridad personalizadas: bloqueo antes del modelo

Lección 2 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. El principio de las barreras de seguridad personalizadas
  2. Cómo funciona
  3. Formato del parámetro guardrails
  4. Las once categorías
  5. Los tres niveles de aplicación
  6. Qué devuelven las barreras de seguridad
  7. Elección del nivel adecuado
  8. Puntos clave

Lección reescrita el 3 de noviembre de 2026. La versión anterior describía un parámetro guardrails ficticio (un diccionario con enabled), categorías inexistentes (hate, violence), un método conversation.send() ausente en el SDK y respuestas JSON imaginarias. El formato oficial es una lista de configuraciones moderation_llm_v2, y las respuestas siguientes coinciden con la documentación. El código se ha verificado frente a los tipos del SDK mistralai versió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:

  1. Tu aplicación envía la solicitud con el parámetro guardrails.
  2. El clasificador mistral-moderation-2603 puntúa el prompt en cada categoría.
  3. Si una puntuación supera su umbral, la API devuelve un error 403 y no se llama al modelo.
  4. En caso contrario, el modelo procesa la solicitud con normalidad.
  5. La respuesta incluye un campo guardrails que 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",
        },
    }
]
ClaveUbicaciónFunción
custom_category_thresholdsdentro de moderation_llm_v2Umbral de 0 a 1 por categoría; 1 desactiva la categoría
ignore_other_categoriesdentro de moderation_llm_v2True: solo se evalúan las categorías listadas
actiondentro de moderation_llm_v2"block" para rechazar la solicitud si se supera un umbral
model_namedentro de moderation_llm_v2, opcionalModelo de moderación distinto del predeterminado mistral-moderation-2603
block_on_errorjunto a moderation_llm_v2True: 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:

ClaveQué detecta
sexualContenido sexual explícito
hate_and_discriminationOdio o discriminación basada en características protegidas
violence_and_threatsViolencia física descrita, glorificada o amenazada
dangerousComportamientos extremadamente peligrosos
criminalActividades ilegales
selfharmAutolesiones, suicidio, trastornos alimentarios
healthSolicitudes de consejos médicos detallados o personalizados
financialSolicitudes de consejos financieros detallados o personalizados
lawSolicitudes de consejos legales detallados o personalizados
piiDatos personales solicitados o compartidos
jailbreakingIntentos 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

CriterioChat CompletionsConversaciónAgente
Dónde se declaran las barrerasEn cada llamadaAl inicio (start)En la creación del agente
HerenciaNingunaNo documentada para turnos siguientesTodas las conversaciones del agente
Anulable——Sí, mediante una solicitud de conversación
Caso de usoPruebas, ajuste de umbralesConversación puntualProducció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 con enabled
  • Once categorías con nombres fijos (hate_and_discrimination, violence_and_threats, …), cada una con un umbral de 0 a 1; 1 desactiva
  • Tres niveles: chat.complete(), conversations.start(), agents.create(); los agentes pasan sus barreras a todas sus conversaciones
  • block_on_error=True garantiza un comportamiento fail-safe (error 3201)