Guardrails Personalizados: Bloquear Antes do Modelo
Nesta página
Lição reescrita em 3 de novembro de 2026. A versão anterior descrevia um parâmetro
guardrailsfictício (um dicionário comenabled), categorias inexistentes (hate,violence), um métodoconversation.send()em falta no SDK e respostas JSON imaginárias. O formato oficial é uma lista de configuraçõesmoderation_llm_v2, e as respostas abaixo correspondem à documentação. O código foi verificado face aos tipos do SDKmistralaiversão 3.7.0. Fontes: Moderation & Guardrailing · mistralai Python SDK.
O Princípio dos Guardrails Personalizados
Os Guardrails Personalizados da Mistral atuam como um filtro de entrada: analisam o prompt do utilizador antes de este chegar ao modelo de geração. Se o conteúdo exceder algum limiar que tenha definido, o pedido é bloqueado com um erro HTTP 403. O modelo nunca vê o prompt problemático.
Tenha em mente duas limitações desde o início. Primeiro, os guardrails moderam apenas a entrada; não verificam o que o modelo gera. Essa é a função da API de Moderação (Lição 5). Segundo, substituem trabalho que teria de codificar manualmente: chamar a API de Moderação, comparar pontuações com os seus limiares e rejeitar o pedido.
Como Funciona
Quando adiciona guardrails a um pedido, o fluxo do lado da Mistral é o seguinte:
- A sua aplicação envia o pedido com o parâmetro
guardrails. - O classificador
mistral-moderation-2603atribui uma pontuação ao prompt em cada categoria. - Se uma pontuação exceder o seu limiar, a API devolve um erro
403e o modelo não é chamado. - Caso contrário, o modelo processa o pedido normalmente.
- A resposta inclui um campo
guardrailscontendo as pontuações avaliadas.
Fluxo: prompt → [mistral-moderation-2603] → pontuação > limiar? → 403 (bloqueado)
→ senão → [LLM] → resposta + pontuações
A decisão baseia-se numa pontuação comparada a um limiar definido por si, categoria por categoria, entre 0 e 1. Um limiar baixo bloqueia mais conteúdo; um limiar de 1 desativa explicitamente a categoria.
O Formato do Parâmetro guardrails
O parâmetro é uma lista. Cada elemento é um objeto contendo uma configuração moderation_llm_v2 e, ao lado, a opção block_on_error:
guardrails = [
{
"block_on_error": True, # bloquear se a própria moderação falhar
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Chave | Localização | Função |
|---|---|---|
custom_category_thresholds | dentro de moderation_llm_v2 | Limiar de 0 a 1 por categoria; 1 desativa a categoria |
ignore_other_categories | dentro de moderation_llm_v2 | True: apenas as categorias listadas são avaliadas |
action | dentro de moderation_llm_v2 | "block" para rejeitar o pedido se um limiar for excedido |
model_name | dentro de moderation_llm_v2, opcional | Modelo de moderação diferente do padrão mistral-moderation-2603 |
block_on_error | ao lado de moderation_llm_v2 | True: o pedido é bloqueado se a avaliação falhar |
Pode colocar múltiplos objetos na lista: o pedido é bloqueado assim que um deles for acionado. Cada objeto contém apenas uma configuração moderation_llm_v2. Uma configuração mais antiga, moderation_llm_v1, ainda existe no SDK com categorias do modelo obsoleto mistral-moderation-2411 (obsoleto desde 31 de março de 2026): não a utilize em novos projetos.
As Onze Categorias
As chaves em custom_category_thresholds são fixas; outra chave, como violence ou hate, não corresponde a nada:
| Chave | O que deteta |
|---|---|
sexual | Conteúdo sexual explícito |
hate_and_discrimination | Ódio ou discriminação baseada em características protegidas |
violence_and_threats | Violência física descrita, glorificada ou ameaçada |
dangerous | Comportamentos extremamente perigosos |
criminal | Atividades ilegais |
selfharm | Automutilação, suicídio, distúrbios alimentares |
health | Pedidos de conselhos médicos detalhados ou personalizados |
financial | Pedidos de conselhos financeiros detalhados ou personalizados |
law | Pedidos de conselhos jurídicos detalhados ou personalizados |
pii | Dados pessoais solicitados ou partilhados |
jailbreaking | Tentativas de contornar as regras do modelo |
A Lição 6 retoma cada uma destas categorias e discute a seleção de limiares.
Os Três Níveis de Aplicação
O mesmo parâmetro é aceite em três locais. A sua escolha determina onde reside a sua política de segurança e quem se pode esquecer de a aplicar.
Nível 1: Um Pedido de Chat Completions
Passa o guardrails na chamada chat.complete(). Cada pedido transporta as suas próprias regras: prático para exploração, mas arriscado à escala, pois uma única chamada sem o parâmetro passa sem verificação.
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: Prototipagem, chamadas pontuais, ajuste de limiares.
Nível 2: Uma Conversação
Com a API de Conversações, passa o guardrails no arranque, em 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)
As mensagens subsequentes são enviadas com client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Este método não aceita um parâmetro guardrails no SDK 3.7.0, e a documentação não especifica se os guardrails do arranque se aplicam às voltas subsequentes. Para uma proteção garantida em cada volta, anexe guardrails a um agente.
Caso de uso: Conversação pontual sem um agente, ou substituição dos guardrails de um agente para um pedido específico.
Nível 3: Um Agente
Os guardrails passados a client.beta.agents.create() tornam-se parte da definição do agente. Segundo a documentação, todas as conversações que utilizam este agente herdam-nos sem necessidade de os repetir. No entanto, um pedido de conversação pode substituí-los passando os seus próprios 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: Produção, quando várias equipas ou serviços chamam o mesmo assistente.
O Que os Guardrails Devolvem
Quando o pedido é aprovado, a resposta da API inclui, juntamente com os campos padrão, um campo guardrails: uma lista com um resultado por guardrail. Eis esse campo do exemplo da documentação:
{
"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 }
}
}
}
]
}
Com ignore_other_categories definido como True, apenas as categorias listadas nos seus limiares aparecem neste resultado. No SDK Python, uma resposta de conversação expõe este campo (conversation.guardrails). A resposta de chat.complete(), no entanto, não tem um campo designado para isso no SDK 3.7.0: perde-se aí. Se quiser registar as pontuações — e é útil saber mais tarde se os seus limiares são demasiado laxistas ou demasiado rigorosos — utilize conversações ou leia a resposta HTTP bruta.
Quando um limiar é excedido, a API devolve um erro 403 cujo corpo detalha a decisão, categoria por categoria:
{
"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"
}
}
}
}
O SDK lança então errors.SDKError, onde status_code é 403 e body contém 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 permite-lhe explicar um bloqueio durante um recurso: qual a categoria, qual a pontuação, qual o limiar.
Finalmente, existe o caso degradado. Se a própria avaliação falhar e block_on_error for True, o pedido é recusado com o código de erro 3201 e a mensagem Request blocked due to error in guardrail evaluation and block_on_error is set to True. Este é o modo fail-safe: na dúvida, bloqueia. Com block_on_error definido como False (o seu valor padrão no SDK), o pedido passaria sem verificação.
Escolher o Nível Correto
| Critério | Chat Completions | Conversação | Agente |
|---|---|---|---|
| Onde os guardrails são declarados | Em cada chamada | No arranque (start) | Na criação do agente |
| Herança | Nenhuma | Não documentado para voltas subsequentes | Todas as conversações do agente |
| Substituível | — | — | Sim, por um pedido de conversação |
| Caso de uso | Testes, ajuste de limiares | Conversação pontual | Produção |
Na prática, ajuste os seus limiares em pedidos de Chat Completions usando casos reais e, em seguida, mova a política para um agente assim que o código sair da sua máquina: não haverá mais chamadas esquecidas.
Pontos-chave
- Os guardrails bloqueiam prompts antes do modelo através de um erro
403; não verificam a saída - O parâmetro é uma lista de objetos
{"block_on_error": ..., "moderation_llm_v2": {...}}, não um dicionário comenabled - Onze categorias com nomes fixos (
hate_and_discrimination,violence_and_threats, …), cada uma com um limiar de 0 a 1;1desativa - Três níveis:
chat.complete(),conversations.start(),agents.create(); os agentes passam os seus guardrails para todas as suas conversações block_on_error=Truegarante um comportamento fail-safe (erro3201)