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

Guardrails Personalizados: Bloquear Antes do Modelo

Aula 2 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O Princípio dos Guardrails Personalizados
  2. Como Funciona
  3. O Formato do Parâmetro guardrails
  4. As Onze Categorias
  5. Os Três Níveis de Aplicação
  6. O Que os Guardrails Devolvem
  7. Escolher o Nível Correto
  8. Pontos-chave

Lição reescrita em 3 de novembro de 2026. A versão anterior descrevia um parâmetro guardrails fictício (um dicionário com enabled), categorias inexistentes (hate, violence), um método conversation.send() em falta no SDK e respostas JSON imaginárias. O formato oficial é uma lista de configurações moderation_llm_v2, e as respostas abaixo correspondem à documentação. O código foi verificado face aos tipos do SDK mistralai versã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:

  1. A sua aplicação envia o pedido com o parâmetro guardrails.
  2. O classificador mistral-moderation-2603 atribui uma pontuação ao prompt em cada categoria.
  3. Se uma pontuação exceder o seu limiar, a API devolve um erro 403 e o modelo não é chamado.
  4. Caso contrário, o modelo processa o pedido normalmente.
  5. A resposta inclui um campo guardrails contendo 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",
        },
    }
]
ChaveLocalizaçãoFunção
custom_category_thresholdsdentro de moderation_llm_v2Limiar de 0 a 1 por categoria; 1 desativa a categoria
ignore_other_categoriesdentro de moderation_llm_v2True: apenas as categorias listadas são avaliadas
actiondentro de moderation_llm_v2"block" para rejeitar o pedido se um limiar for excedido
model_namedentro de moderation_llm_v2, opcionalModelo de moderação diferente do padrão mistral-moderation-2603
block_on_errorao lado de moderation_llm_v2True: 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:

ChaveO que deteta
sexualConteúdo sexual explícito
hate_and_discriminationÓdio ou discriminação baseada em características protegidas
violence_and_threatsViolência física descrita, glorificada ou ameaçada
dangerousComportamentos extremamente perigosos
criminalAtividades ilegais
selfharmAutomutilação, suicídio, distúrbios alimentares
healthPedidos de conselhos médicos detalhados ou personalizados
financialPedidos de conselhos financeiros detalhados ou personalizados
lawPedidos de conselhos jurídicos detalhados ou personalizados
piiDados pessoais solicitados ou partilhados
jailbreakingTentativas 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érioChat CompletionsConversaçãoAgente
Onde os guardrails são declaradosEm cada chamadaNo arranque (start)Na criação do agente
HerançaNenhumaNão documentado para voltas subsequentesTodas as conversações do agente
Substituível——Sim, por um pedido de conversação
Caso de usoTestes, ajuste de limiaresConversação pontualProduçã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 com enabled
  • Onze categorias com nomes fixos (hate_and_discrimination, violence_and_threats, …), cada uma com um limiar de 0 a 1; 1 desativa
  • 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=True garante um comportamento fail-safe (erro 3201)