API de Moderação da Mistral
Nesta página
Atualizado em 3 de novembro de 2026. O exemplo de resposta incluía anteriormente chaves inexistentes (
hate,violence,unpredictable); reflete agora as onze categorias do modelomistral-moderation-2603. O pipeline final utilizava anteriormente um formato de guardrail inventado (enabled) e detetava bloqueios procurando por “403” na mensagem de erro: segue agora o formato oficial e verificae.status_code. A apresentação do modelo respeita a sua ficha técnica oficial, e a lição introduz o Shieldstral 1.0, o modelo de moderação em pré-visualização pública desde agosto de 2026. Código verificado face aos tipos do SDKmistralaiversão 3.7.0. Fontes: Moderation & Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.
Classificar conteúdo após a geração
Os guardrails filtram os prompts de entrada. Mas e quanto ao conteúdo gerado pelo modelo? Um prompt inocente pode produzir uma resposta problemática: uma pergunta de um aluno do ensino básico sobre a Segunda Guerra Mundial pode gerar uma descrição que não deseja exibir sem ressalvas. É esse o papel da API de Moderação: analisar o conteúdo a posteriori e atribuir pontuações de risco por categoria.
A API de Moderação é a sua segunda linha de defesa — complementa os guardrails para criar uma arquitetura de segurança completa, com uma diferença fundamental: não bloqueia nada por si só; apenas informa-o.
O modelo Mistral Moderation 2
O modelo dedicado à moderação chama-se mistral-moderation-2603 (Mistral Moderation 2, versão de março de 2026). É um classificador especializado, distinto dos modelos de geração: não escreve texto, atribui pontuações. A sua ficha técnica oficial destaca uma janela de contexto de 128 000 tokens, deteção de jailbreak e um desempenho robusto em conteúdo multilingue complexo, incluindo conversas longas. Substitui o mistral-moderation-2411, que foi descontinuado a 31 de março de 2026.
Este modelo pontua cada texto em 11 categorias, com uma pontuação de 0,0 a 1,0 por categoria. Aceita dois modos de entrada, texto simples ou conversacional, e a escolha entre eles afeta a qualidade dos resultados mais do que poderia esperar.
Existe um segundo modelo de moderação desde 4 de agosto de 2026, em pré-visualização pública: o Shieldstral 1.0. Funciona de forma diferente: compacto (3,8 mil milhões de parâmetros) e multimodal, classifica texto e imagens com base em questões de política formuladas em linguagem natural, respondendo sim ou não. Os seus pesos são publicados sob a licença Apache 2.0, permitindo a auto-hospedagem. Enquanto permanecer em pré-visualização, o mistral-moderation-2603 mantém-se como o modelo de produção e é o utilizado para os guardrails.
O endpoint /v1/moderations
O modo de texto simples é o mais básico: envia um ou mais textos para classificar, sem contexto adicional.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Moderar texto simples
response = client.classifiers.moderate(
model="mistral-moderation-2603",
inputs=["Text to analyze for moderation"]
)
# Aceder aos resultados
for result in response.results:
print(f"Categories: {result.categories}")
print(f"Scores: {result.category_scores}")
Para moderar trocas completas, prompt e resposta em conjunto, o modo conversacional fornece ao classificador o que lhe faltava: o fio condutor da discussão.
# Moderar uma conversa completa
response = client.classifiers.moderate_chat(
model="mistral-moderation-2603",
inputs=[
[
{"role": "user", "content": "How do I treat a headache?"},
{"role": "assistant", "content": "Take 1g of paracetamol..."}
]
]
)
# O classificador avalia o contexto completo
for result in response.results:
print(f"Health score: {(result.category_scores or {}).get('health', 0)}")
O modo conversacional, que invoca o endpoint /v1/chat/moderations, é o que a Mistral recomenda para uma troca: o modelo foi treinado para classificar a última intervenção da conversa à luz das anteriores. Para moderar a resposta do seu assistente, coloque-a por último. A lista de listas no exemplo permite enviar várias conversas de uma vez; uma lista simples de mensagens basta para uma única conversa. O mesmo texto pode, assim, receber uma pontuação diferente consoante responda a uma pergunta legítima ou maliciosa — uma dosagem citada em resposta a um pedido de informação não tem o mesmo estatuto que a mesma dosagem inserida numa troca sobre automedicação de risco.
Estrutura da resposta
Para cada texto analisado, a resposta contém dois blocos paralelos: categories, booleanos calculados com limiares definidos pela Mistral com base no seu conjunto de testes interno, e category_scores, as pontuações brutas de 0,0 a 1,0. O exemplo abaixo é ilustrativo, com valores arredondados; alguns exemplos da documentação ainda mostram as nove categorias do modelo antigo, onde dangerous_and_criminal_content combinava dangerous e criminal. Deverá utilizar estas últimas, pois permitem-lhe definir os seus próprios limites.
{
"id": "mod-abc123",
"model": "mistral-moderation-2603",
"results": [
{
"categories": {
"sexual": false,
"hate_and_discrimination": false,
"violence_and_threats": false,
"dangerous": false,
"criminal": false,
"selfharm": false,
"health": true,
"financial": false,
"law": false,
"pii": false,
"jailbreaking": false
},
"category_scores": {
"sexual": 0.01,
"hate_and_discrimination": 0.02,
"violence_and_threats": 0.03,
"dangerous": 0.02,
"criminal": 0.01,
"selfharm": 0.01,
"health": 0.72,
"financial": 0.05,
"law": 0.08,
"pii": 0.02,
"jailbreaking": 0.01
}
}
]
}
Neste exemplo, apenas health está marcado como true, com 0,72. Um assistente virado para o consumidor veria isto como um sinal de bloqueio; uma ferramenta destinada a farmacêuticos deixá-la-ia passar sem hesitação. A mesma pontuação, duas decisões opostas, e é exatamente por isso que trabalha com pontuações em vez de booleanos.
Moderar múltiplos textos em lote
A API aceita múltiplos textos num único pedido, o que muda tudo para o processamento em lote: analisar retroativamente um histórico de conversas ou uma base de dados de comentários torna-se uma operação razoável em termos de número de chamadas.
# Moderar múltiplos textos num único pedido
texts = [
"First text to analyze",
"Second text to analyze",
"Third text to analyze"
]
response = client.classifiers.moderate(
model="mistral-moderation-2603",
inputs=texts
)
# Cada texto tem o seu próprio resultado
for i, result in enumerate(response.results):
scores = result.category_scores or {}
max_cat = max(scores, key=lambda c: scores[c])
max_score = scores[max_cat]
print(f"Text {i+1}: max score = {max_score:.2f} ({max_cat})")
Guardrails vs API de Moderação: quando usar o quê
| Aspeto | Guardrails Personalizados | API de Moderação |
|---|---|---|
| Momento | ANTES da geração | DEPOIS da geração |
| Ação | Bloqueia automaticamente (403) | Devolve pontuações (você decide) |
| Controlo | Os seus limiares por categoria, aplicados pela Mistral | Pontuações brutas, lógica livre |
| Chamada | Parâmetro do pedido de geração | Chamada separada a /v1/moderations |
| Caso de uso | Filtrar prompts perigosos | Classificar respostas |
Exemplo: pipeline completo
O pipeline abaixo mostra a sequenciação dos dois mecanismos. A geração é protegida por um guardrail focado no jailbreaking; a resposta é depois classificada em conjunto com a pergunta que a produziu, e uma decisão personalizada intervém assim que uma pontuação excede 0,5. Note que os dois passos devolvem estados distintos — blocked_input e blocked_output — para que os seus registos indiquem claramente onde o pedido foi interrompido.
from mistralai.client import errors
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAIL_JAILBREAK: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.1},
"action": "block",
},
}
]
def secure_pipeline(user_message: str) -> dict:
"""Pipeline com guardrails (entrada) e moderação (saída)."""
# Passo 1: gerar com guardrails
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": user_message}],
guardrails=GUARDRAIL_JAILBREAK,
)
except errors.SDKError as e:
if e.status_code == 403:
return {"status": "blocked_input", "content": None}
raise
generated = response.choices[0].message.content
if not isinstance(generated, str):
return {"status": "error", "content": None}
# Passo 2: moderar a saída, no contexto da pergunta
moderation = client.classifiers.moderate_chat(
model="mistral-moderation-2603",
inputs=[
{"role": "user", "content": user_message},
{"role": "assistant", "content": generated},
],
)
scores = moderation.results[0].category_scores or {}
if max(scores.values(), default=0.0) > 0.5:
return {"status": "blocked_output", "scores": scores}
return {"status": "ok", "content": generated, "scores": scores}
Pontos-chave
- A API de Moderação utiliza o modelo
mistral-moderation-2603para classificar conteúdo - Dois modos disponíveis: texto simples e conversacional
- As pontuações variam de 0,0 a 1,0 — você define os seus próprios limiares de decisão
- O modo conversacional é mais preciso porque tem em conta o contexto
- Combine guardrails (entrada) + moderação (saída) para uma defesa em profundidade