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

API de Moderação da Mistral

Aula 5 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Classificar conteúdo após a geração
  2. O modelo Mistral Moderation 2
  3. O endpoint /v1/moderations
  4. Estrutura da resposta
  5. Moderar múltiplos textos em lote
  6. Guardrails vs API de Moderação: quando usar o quê
  7. Exemplo: pipeline completo
  8. Pontos-chave

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 modelo mistral-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 verifica e.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 SDK mistralai versã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ê

AspetoGuardrails PersonalizadosAPI de Moderação
MomentoANTES da geraçãoDEPOIS da geração
AçãoBloqueia automaticamente (403)Devolve pontuações (você decide)
ControloOs seus limiares por categoria, aplicados pela MistralPontuações brutas, lógica livre
ChamadaParâmetro do pedido de geraçãoChamada separada a /v1/moderations
Caso de usoFiltrar prompts perigososClassificar 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-2603 para 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