Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Configurar guardrails em Python

Aula 3 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Da teoria ao código
  2. O parâmetro guardrails em detalhe
  3. Exemplo completo: chatbot com guardrails
  4. Tratar erros de bloqueio corretamente
  5. Melhores práticas de configuração
  6. Pontos-chave

Lição reescrita a 3 de novembro de 2026. A versão anterior configurava os guardrails utilizando um dicionário inventado (enabled), categorias inexistentes (hate, violence, unpredictable), afirmava que categorias não listadas mantinham “limiares predefinidos” e testava e.status_code == 3201, embora 3201 seja um código de erro no corpo da resposta e não um estado HTTP. A configuração segue agora o formato oficial e o código foi verificado face aos tipos do SDK mistralai 3.7.0. Fontes: Moderation & Guardrailing · mistralai Python SDK.

Da teoria ao código

Compreende agora como funcionam os guardrails. Nesta lição, irá configurá-los com precisão: selecione as suas categorias, defina os seus limiares e trate os bloqueios no seu código Python.

Comece por ter o SDK da Mistral instalado (os guardrails exigem a versão 2 ou posterior) e uma chave de API carregada a partir do ambiente, em vez de estar codificada diretamente.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

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

O parâmetro guardrails em detalhe

O parâmetro guardrails é uma lista. Cada item associa a opção block_on_error a uma configuração moderation_llm_v2, que por sua vez contém limiares, a opção ignore_other_categories e a ação:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Bloquear se a própria avaliação falhar
        "block_on_error": True,
        "moderation_llm_v2": {
            # Limiares por categoria, de 0 a 1 (1 desativa a categoria)
            "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,
            # Ação em caso de violação do limiar
            "action": "block",
        },
    }
]

O modelo de moderação predefinido é mistral-moderation-2603; a chave opcional model_name permite especificar um modelo diferente.

A anotação list[GuardrailConfigTypedDict] não é obrigatória, mas vale a pena utilizá-la: o SDK descreve todas as chaves permitidas, pelo que um verificador de tipos como o pyright ou o mypy assinalará uma categoria mal escrita (violence em vez de violence_and_threats) que a própria API não detetaria.

custom_category_thresholds

Este é o cerne da configuração. Cada categoria recebe um limiar entre 0 e 1, comparado com a pontuação atribuída pelo classificador ao prompt. Quanto mais baixo for o limiar, mais o filtro bloqueia, com o risco de rejeitar pedidos legítimos. Um limiar de 1 desativa explicitamente a categoria. A Mistral não publica uma grelha de valores recomendados: deve calibrar estes valores com os seus próprios exemplos (lição 7).

Os valores só fazem sentido no contexto da sua aplicação. Um chatbot virado para o público fecha as categorias sensíveis nas definições mais baixas, enquanto uma ferramenta interna para profissionais de saúde deve permitir questões médicas, mantendo-se rigorosa quanto aos dados pessoais.

# Chatbot público: limiares muito baixos
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Ferramenta médica interna: saúde desativada, PII ainda monitorizado
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # desativa a categoria: as questões médicas são a função central da ferramenta
    "pii": 0.1,
}

Categorias que não lista

O que acontece às categorias em falta em custom_category_thresholds? A documentação não o afirma explicitamente, mas o seu exemplo de bloqueio é elucidativo: as categorias não listadas aparecem aí com um limiar de 1.0, registadas mas ineficazes. Não confie num limiar predefinido: liste todas as categorias que devem poder bloquear.

A opção ignore_other_categories controla apenas o que é avaliado e devolvido. Quando definida como False, todas as categorias avaliadas aparecem no resultado; quando True, apenas as que listou são avaliadas.

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,  # avalia apenas estas duas categorias
            "action": "block",
        },
    }
]

Aviso: com esta configuração, uma tentativa de jailbreak ou um pedido de dados pessoais passaria sem verificação. Restrinja a lista apenas por um motivo específico.

Exemplo completo: chatbot com guardrails

Eis uma função mínima: envia a mensagem com a configuração completa e transforma um bloqueio numa resposta legível para o utilizador.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Envia uma mensagem protegida por guardrails."""
    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 "Desculpe, este pedido não pode ser processado."
        raise

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


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

Duas notas. message.content pode ser uma cadeia de caracteres ou uma lista de partes, dependendo do modelo, daí a verificação isinstance. E a resposta de chat.complete() não expõe as pontuações dos guardrails no SDK 3.7.0: para as registar, utilize a API de Conversas, cuja resposta as transporta em guardrails.

Tratar erros de bloqueio corretamente

Deve distinguir duas falhas que exigem nem a mesma mensagem nem o mesmo alerta: um bloqueio por política de conteúdo, que devolve o estado HTTP 403, e uma falha na avaliação da moderação com block_on_error ativado, que o corpo da resposta assinala com o código 3201. Ambos chegam como errors.SDKError, cujo body contém o JSON devolvido pela 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 bloqueios de política de falhas de moderação."""
    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": "Serviço de moderação indisponível. Pedido bloqueado por precaução.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "A sua mensagem foi bloqueada pela nossa política de segurança.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

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

Verifique primeiro o código 3201, porque a documentação não especifica o estado HTTP para este erro. As categorias violadas provêm de decisions, onde cada entrada fornece threshold, score e violated: é isto que irá registar para explicar um bloqueio.

Melhores práticas de configuração

Comece de forma restritiva e depois alivie. Limiares baixos no lançamento ajudam a detetar falsos positivos enquanto o volume ainda é gerível, e cada aumento é decidido com base em casos observados e não na intuição:

# Fase 1: lançamento (muito restritivo)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# Fase 2: após análise de falsos positivos
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# Fase 3: produção estável
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Estes valores ilustram a abordagem; os seus resultarão das suas próprias medições. Mantenha block_on_error definido como True em produção: o seu valor predefinido no SDK é False, e uma falha de moderação deixaria então passar conteúdo não verificado. Por fim, a documentação avisa que o modelo de moderação evolui: as políticas baseadas em pontuações podem exigir recalibração.

Pontos-chave

  • guardrails é uma lista de objetos {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Dentro de moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action e, opcionalmente, model_name
  • Limiares de 0 a 1; quanto mais baixo, mais restritivo; 1 desativa uma categoria. Liste todas as categorias que devem bloquear
  • Um bloqueio levanta errors.SDKError com status_code == 403; uma falha com block_on_error transporta o código 3201 no corpo
  • Mantenha block_on_error=True em produção, pois o valor predefinido é False