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

Configurar barreras de seguridad en Python

Lección 3 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. De la teoría al código
  2. El parámetro guardrails en detalle
  3. Ejemplo completo: chatbot con barreras de seguridad
  4. Gestionar los errores de bloqueo correctamente
  5. Mejores prácticas de configuración
  6. Puntos clave

Lección reescrita el 3 de noviembre de 2026. La versión anterior configuraba las barreras de seguridad mediante un diccionario inventado (enabled), categorías inexistentes (hate, violence, unpredictable), afirmaba que las categorías no listadas mantenían «umbrales predeterminados» y probaba e.status_code == 3201, a pesar de que 3201 es un código de error en el cuerpo de la respuesta, no un estado HTTP. La configuración sigue ahora el formato oficial y el código se ha verificado frente a los tipos del SDK mistralai 3.7.0. Fuentes: Moderación y barreras de seguridad · SDK de Python para mistralai.

De la teoría al código

Ya sabes cómo funcionan las barreras de seguridad. En esta lección, las configurarás con precisión: seleccionarás tus categorías, definirás tus umbrales y gestionarás los bloqueos en tu código Python.

Comienza con el SDK de Mistral instalado (las barreras de seguridad requieren la versión 2 o posterior) y una clave de API cargada desde el entorno en lugar de estar hardcodeada.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

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

El parámetro guardrails en detalle

El parámetro guardrails es una lista. Cada elemento empareja la opción block_on_error con una configuración moderation_llm_v2, la cual contiene a su vez los umbrales, la opción ignore_other_categories y la acción:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Bloquear si la propia evaluación falla
        "block_on_error": True,
        "moderation_llm_v2": {
            # Umbrales por categoría, de 0 a 1 (1 desactiva la categoría)
            "custom_category_thresholds": {
                "sexual": 0.2,
                "hate_and_discrimination": 0.1,
                "violence_and_threats": 0.3,
                "dangerous": 0.2,
                "criminal": 0.1,
                "selfharm": 0.1,
                "health": 0.5,
                "financial": 0.5,
                "law": 0.5,
                "pii": 0.2,
                "jailbreaking": 0.1,
            },
            "ignore_other_categories": False,
            # Acción al superar el umbral
            "action": "block",
        },
    }
]

El modelo de moderación predeterminado es mistral-moderation-2603; la clave opcional model_name te permite especificar otro diferente.

La anotación list[GuardrailConfigTypedDict] no es obligatoria, pero merece la pena usarla: el SDK describe cada clave permitida, de modo que un comprobador de tipos como pyright o mypy señalará una categoría mal escrita (violence en lugar de violence_and_threats) que la propia API no detectaría.

custom_category_thresholds

Este es el núcleo de la configuración. Cada categoría recibe un umbral entre 0 y 1, que se compara con la puntuación que el clasificador asigna al prompt. Cuanto más bajo sea el umbral, más bloqueará el filtro, con el riesgo de rechazar solicitudes legítimas. Un umbral de 1 desactiva explícitamente la categoría. Mistral no publica una cuadrícula de valores recomendados: debes calibrarlos con tus propios ejemplos (lección 7).

Los valores solo tienen sentido en el contexto de tu aplicación. Un chatbot de cara al público bloquea las categorías sensibles con la configuración más estricta, mientras que una herramienta interna para profesionales de la salud debe permitir preguntas médicas manteniendo la rigurosidad con los datos personales.

# Chatbot público: umbrales muy bajos
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Herramienta médica interna: health desactivada, PII aún monitorizada
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # desactiva la categoría: las preguntas médicas son la función principal de la herramienta
    "pii": 0.1,
}

Categorías que no listas

¿Qué ocurre con las categorías que faltan en custom_category_thresholds? La documentación no lo indica explícitamente, pero su ejemplo de bloqueo es revelador: las categorías no listadas aparecen allí con un umbral de 1.0, mencionadas pero ineficaces. No confíes en un umbral predeterminado: lista cada categoría que deba poder bloquear.

La opción ignore_other_categories controla únicamente qué se evalúa y se devuelve. Cuando se establece en False, todas las categorías evaluadas aparecen en el resultado; cuando es True, solo se evalúan las que has listado.

TARGETED_GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        "block_on_error": True,
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "hate_and_discrimination": 0.1,
                "violence_and_threats": 0.2,
            },
            "ignore_other_categories": True,  # evalúa solo estas dos categorías
            "action": "block",
        },
    }
]

Advertencia: con esta configuración, un intento de jailbreak o una solicitud de datos personales pasarían sin control. Restringe la lista solo por una razón específica.

Ejemplo completo: chatbot con barreras de seguridad

Aquí tienes una función mínima: envía el mensaje con la configuración completa y convierte un bloqueo en una respuesta legible para el usuario.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Envía un mensaje protegido por barreras de seguridad."""
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[
                {"role": "system", "content": "You are a professional assistant."},
                {"role": "user", "content": message_utilisateur},
            ],
            guardrails=GUARDRAILS,
        )
    except errors.SDKError as e:
        if e.status_code == 403:
            return "Lo sentimos, esta solicitud no puede ser procesada."
        raise

    contenu = response.choices[0].message.content
    return contenu if isinstance(contenu, str) else ""


print(chat_securise("Explain machine learning to me"))

Dos notas. message.content puede ser una cadena o una lista de partes dependiendo del modelo, de ahí la comprobación isinstance. Y la respuesta de chat.complete() no expone las puntuaciones de las barreras de seguridad en el SDK 3.7.0: para registrarlas, usa la API de Conversaciones, cuya respuesta las incluye en guardrails.

Gestionar los errores de bloqueo correctamente

Debes distinguir dos fallos que requieren ni el mismo mensaje ni la misma alerta: un bloqueo por política de contenido, que devuelve el estado HTTP 403, y un fallo en la evaluación de moderación con block_on_error activado, que el cuerpo de la respuesta señala con el código 3201. Ambos llegan como errors.SDKError, cuyo body contiene el JSON devuelto por la API:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Chat que distingue los bloqueos por política de los fallos de moderación."""
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[{"role": "user", "content": message_utilisateur}],
            guardrails=GUARDRAILS,
        )
    except errors.SDKError as e:
        try:
            corps = json.loads(e.body)
        except json.JSONDecodeError:
            raise e

        if corps.get("code") == 3201:
            return {
                "status": "error",
                "content": "Servicio de moderación no disponible. Solicitud bloqueada por precaución.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Tu mensaje ha sido bloqueado por nuestra política de seguridad.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

    return {"status": "ok", "content": response.choices[0].message.content}

Comprueba primero el código 3201, porque la documentación no especifica el estado HTTP para este error. Las categorías violadas provienen de decisions, donde cada entrada ofrece threshold, score y violated: esto es lo que registrarás para explicar un bloqueo.

Mejores prácticas de configuración

Comienza siendo restrictivo y luego relaja la configuración. Los umbrales bajos al lanzamiento te ayudan a descubrir falsos positivos mientras el volumen aún es manejable, y cada aumento se decide basándose en casos observados en lugar de en la intuición:

# Fase 1: lanzamiento (muy restrictivo)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# Fase 2: tras analizar falsos positivos
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# Fase 3: producción estable
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Estos valores ilustran el enfoque; los tuyos provendrán de tus propias mediciones. Mantén block_on_error establecido en True en producción: su valor predeterminado en el SDK es False, y un fallo de moderación dejaría pasar entonces contenido no verificado. Por último, la documentación advierte que el modelo de moderación evoluciona: las políticas basadas en puntuaciones pueden requerir recalibración.

Puntos clave

  • guardrails es una lista de objetos {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Dentro de moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action y, opcionalmente, model_name
  • Umbrales de 0 a 1; cuanto más bajo, más estricto; 1 desactiva una categoría. Lista cada categoría que deba bloquear
  • Un bloqueo lanza errors.SDKError con status_code == 403; un fallo con block_on_error lleva el código 3201 en el cuerpo
  • Mantén block_on_error=True en producción, ya que el valor predeterminado es False