Configurar guardrails em Python
Nesta página
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 testavae.status_code == 3201, embora3201seja 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 SDKmistralai3.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,actione, opcionalmente,model_name - Limiares de
0a1; quanto mais baixo, mais restritivo;1desativa uma categoria. Liste todas as categorias que devem bloquear - Um bloqueio levanta
errors.SDKErrorcomstatus_code == 403; uma falha comblock_on_errortransporta o código3201no corpo - Mantenha
block_on_error=Trueem produção, pois o valor predefinido éFalse