Defina a Sua Política de Conteúdo
Nesta página
Atualizado em 3 de novembro de 2026. As políticas anteriores utilizavam três categorias inexistentes (
hate,violence,unpredictable) e omitiamdangerous. Agora estão alinhadas com as onze chaves do modelomistral-moderation-2603. Foi introduzido um método que converte uma política no formato oficial do parâmetroguardrails, garantindo a aplicação consistente dos limiares antes da geração. Fontes: Moderation & Guardrailing · SDKmistralai3.7.0.
Por Que Precisa de uma Política de Conteúdo Formal
Os limiares de moderação não são escolhas técnicas arbitrárias. Refletem uma política de conteúdo — um conjunto de regras que define o que a sua aplicação permite e proíbe. Sem uma política formal, cada programador toma as suas próprias decisões, e o seu sistema de segurança perde consistência: dois serviços dentro da mesma empresa acabam por bloquear conteúdos diferentes, sem que ninguém saiba porquê.
Uma política escrita permite-lhe justificar decisões de moderação tanto aos utilizadores como aos reguladores, harmonizar limiares entre equipas e aplicações, auditar a conformidade do sistema e iterar de forma estruturada à medida que as necessidades mudam. No dia em que um utilizador contestar um bloqueio, a diferença entre «o limiar está definido em 0,1» e «a nossa Política Pública v1.2 define este limiar por esta razão» é enorme.
Adaptação dos Limiares ao Contexto da Aplicação
O mesmo conteúdo pode ser aceitável num contexto e perigoso noutro. A sua política deve refletir estas nuances. A melhor forma de o conseguir é descrever cada perfil como um objeto nomeado, datado e documentado, em vez de um dicionário anónimo perdido no código.
Para um chatbot virado para o público, a regra é simples: rigoroso em tudo, com a segurança como prioridade. Não sabe nada sobre a pessoa do outro lado e podem estar presentes menores.
# Política: Rigoroso em tudo, segurança em primeiro lugar
POLICY_PUBLIC = {
"name": "Public-Facing",
"description": "Chatbot acessível a todos, incluindo menores",
"thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"dangerous": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
"health": 0.2,
"financial": 0.2,
"law": 0.2,
"pii": 0.1,
"jailbreaking": 0.1,
},
"block_action": "generic_message",
"logging": "full"
}
Um assistente interno muda as regras num ponto: os utilizadores estão autenticados, o que significa que são identificáveis e responsáveis. Isso permite limiares mais flexíveis, particularmente em financial e law, definidos em 0,6, uma vez que um colaborador que consulta o assistente sobre a estrutura de um contrato está apenas a fazer o seu trabalho.
# Política: Equilibrada, utilizadores identificados
POLICY_INTERNAL = {
"name": "Internal B2B",
"description": "Assistente para colaboradores autenticados",
"thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.15,
"violence_and_threats": 0.3,
"dangerous": 0.2,
"criminal": 0.15,
"selfharm": 0.15,
"health": 0.5,
"financial": 0.6,
"law": 0.6,
"pii": 0.3,
"jailbreaking": 0.15,
},
"block_action": "detailed_message",
"logging": "full"
}
Uma ferramenta especializada — médica, jurídica ou financeira — leva esta lógica à sua conclusão: muito permissiva no seu domínio, rigorosa em todo o resto. No exemplo médico, health sobe para 0,85 porque discutir diagnósticos é exatamente a função da ferramenta, enquanto pii desce para 0,15 porque os dados dos pacientes nunca devem circular. São aqui adicionados dois elementos ausentes nas políticas anteriores: um modo de bloqueio com redirecionamento e um aviso legal explícito.
# Política: Permissiva no domínio, rigorosa no resto
POLICY_MEDICAL = {
"name": "Medical Assistant",
"description": "Ferramenta para profissionais de saúde",
"thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"dangerous": 0.1,
"criminal": 0.1,
"selfharm": 0.3,
"health": 0.85, # Muito permissiva: domínio legítimo
"financial": 0.3,
"law": 0.4,
"pii": 0.15, # Rigorosa: dados de pacientes
"jailbreaking": 0.1,
},
"block_action": "detailed_message_with_redirect",
"logging": "full_with_audit",
"disclaimer": "Esta ferramenta não substitui aconselhamento médico."
}
Formalização da Política como Documento
A sua política de conteúdo deve ser um documento versionado acessível a todas as equipas. Em Python, isto traduz-se numa classe que transporta o número da versão e a data de revisão juntamente com os limiares, e que pode tanto avaliar pontuações como gerar a mensagem de bloqueio correspondente ao modo declarado.
from mistralai.client.models import GuardrailConfigTypedDict
class ContentPolicy:
"""Representação estruturada de uma política de conteúdo."""
def __init__(self, config: dict):
self.name = config["name"]
self.description = config["description"]
self.thresholds = config["thresholds"]
self.block_action = config["block_action"]
self.logging = config["logging"]
self.version = config.get("version", "1.0.0")
self.revision_date = config.get("revision_date", "2026-04-01")
def evaluate(self, scores: dict) -> dict:
"""Avalia as pontuações face à política."""
violations = []
for cat, threshold in self.thresholds.items():
score = scores.get(cat, 0)
if score > threshold:
violations.append({
"category": cat,
"score": round(score, 3),
"threshold": threshold
})
return {
"policy": self.name,
"version": self.version,
"allowed": len(violations) == 0,
"violations": violations
}
def block_message(self, violations: list) -> str:
"""Gera uma mensagem de bloqueio adequada."""
if self.block_action == "generic_message":
return "Este conteúdo não pode ser processado."
elif self.block_action == "detailed_message":
cats = ", ".join(v["category"] for v in violations)
return (f"Conteúdo bloqueado pelas seguintes razões: "
f"{cats}. Por favor, reformule o seu pedido.")
return "Conteúdo bloqueado."
def to_guardrails(self) -> list[GuardrailConfigTypedDict]:
"""Traduz a política para o parâmetro guardrails da API Mistral."""
return [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": self.thresholds,
"ignore_other_categories": False,
"action": "block",
},
}
]
O método to_guardrails torna a política a única fonte de verdade para os guardrails: client.chat.complete(..., guardrails=policy.to_guardrails()) ou client.beta.agents.create(..., guardrails=policy.to_guardrails()). Os limiares aplicados antes e depois da geração já não podem divergir.
Note também que o resultado de evaluate inclui o nome e a versão da política aplicada. Este detalhe permite-lhe, seis meses depois, reproduzir uma decisão contestada sabendo exatamente sob qual regime foi tomada.
Gestão Multiaplicação
Se a sua empresa gere várias aplicações, centralize a gestão de políticas. O gestor abaixo faz duas coisas úteis: recusa-se explicitamente a servir uma aplicação sem uma política declarada, prevenindo implantações sem redes de segurança, e produz um relatório de conformidade que lista a versão e a data da última revisão de cada aplicação — exatamente o que um auditor lhe pedirá.
class PolicyManager:
"""Gere políticas de conteúdo para várias aplicações."""
def __init__(self):
self.policies = {}
def register(self, app_id: str, policy: ContentPolicy):
"""Regista uma política para uma aplicação."""
self.policies[app_id] = policy
def get(self, app_id: str) -> ContentPolicy:
"""Recupera a política para uma aplicação."""
if app_id not in self.policies:
raise ValueError(f"Sem política para {app_id}")
return self.policies[app_id]
def compliance_report(self) -> dict:
"""Gera um relatório global de conformidade."""
return {
app_id: {
"name": pol.name,
"version": pol.version,
"revision_date": pol.revision_date,
"categories_covered": len(pol.thresholds)
}
for app_id, pol in self.policies.items()
}
# Utilização
manager = PolicyManager()
manager.register("chatbot-public",
ContentPolicy(POLICY_PUBLIC))
manager.register("assistant-medical",
ContentPolicy(POLICY_MEDICAL))
Revisão e Atualizações
A sua política não está escrita em pedra. O erro mais comum é escrevê-la uma vez e depois esquecê-la. Estabeleça um ritmo: todas as semanas, analise os falsos positivos e falsos negativos reportados nos seus registos; todos os meses, ajuste os limiares com base nas métricas acumuladas; todos os trimestres, realize uma revisão completa com as partes interessadas de negócios, jurídicas e de produto. Acrescente a isto uma regra não negociável: após cada incidente, realize um post-mortem e implemente uma correção imediata, sem esperar pela próxima revisão agendada.
Pontos-chave
- Uma política de conteúdo traduz os seus limiares técnicos em regras de negócio
- Adapte os limiares ao contexto: público, interno, especializado
- Formalize a política num documento versionado
- Centralize a gestão se tiver várias aplicações
- Revise regularmente — a política deve evoluir com o seu produto