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

Arquitetura de Segurança Completa

Aula 12 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Reunir Todas as Peças
  2. Visão Geral da Arquitetura
  3. Implementação Completa
  4. Utilização em Produção
  5. Monitorização e Alertas
  6. Resumo do Curso
  7. Pontos-chave
  8. Teste os Seus Conhecimentos

Atualizado a 3 de novembro de 2026. A camada de geração utilizava anteriormente um formato de guardrails inventado (enabled), e a política de produção recorria a categorias inexistentes (hate, violence, unpredictable). O código segue agora o formato oficial moderation_llm_v2 e as onze chaves de mistral-moderation-2603. As pontuações, opcionais no SDK, são lidas com um valor de reserva. Código verificado face aos tipos do SDK mistralai versão 3.7.0. Fontes: Moderation & Guardrailing · Python SDK mistralai.

Reunir Todas as Peças

Ao longo deste curso, explorou os guardrails, a API de Moderação, as 11 categorias, os limiares, a deteção de jailbreak, a conformidade com o RGPD e as políticas de conteúdo. Esta última lição reúne todos estes blocos de construção numa arquitetura de segurança completa, pronta para produção.

Visão Geral da Arquitetura

Existem cinco camadas, regidas por um princípio: nenhuma delas é fiável isoladamente. Um guardrail pode ser contornado por uma formulação inesperada, um modelo de moderação produz falsos negativos e uma política de conteúdo nunca cobre todos os casos. A sobreposição funciona porque as lacunas não se sobrepõem — o que escapa à primeira camada tem boas hipóteses de ser detido pela segunda.

A consequência prática é uma ordem estrita: cada camada deve ser o mais económica possível antes de a seguinte ser executada. Valida o formato antes de chamar um guardrail e invoca o guardrail antes da geração — porque o conteúdo rejeitado na etapa 1 consome zero tokens.

User
    ↓
[1. Input Validation] → Regex, patterns, rate limiting
    ↓
[2. Mistral Guardrails]  → Pre-generation blocking (403)
    ↓
[3. LLM Generation]      → safe_prompt + secure instructions
    ↓
[4. Output Moderation]   → Moderation API post-generation
    ↓
[5. Logging & Audit]     → Scores, decisions, GDPR audit trail
    ↓
User Response

Implementação Completa

from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import os
import re
import json
import logging
from datetime import datetime, timezone
from enum import Enum

# Configuration
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("moderation")


class Decision(Enum):
    ALLOWED = "allowed"
    BLOCKED_INPUT = "blocked_input"
    BLOCKED_GUARDRAIL = "blocked_guardrail"
    BLOCKED_OUTPUT = "blocked_output"
    ERROR = "error"


class SecureArchitecture:
    """Complete security architecture for AI applications."""

    def __init__(self, policy: dict, model: str = "mistral-large-latest"):
        self.policy = policy
        self.model = model
        self.stats = {d.value: 0 for d in Decision}

    # --- Layer 1: Input Validation ---

    def validate_input(self, text: str) -> dict:
        """Fast validation before any API call."""
        # Maximum length
        if len(text) > 10000:
            return {"valid": False, "reason": "Message too long"}

        # Suspicious characters (Unicode injections)
        if re.search(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", text):
            return {"valid": False, "reason": "Invalid characters"}

        # Obvious jailbreak patterns
        patterns = [
            r"ignore\s+(all\s+)?(previous|prior|above)",
            r"you\s+are\s+now\s+(DAN|unfiltered)",
            r"oublie\s+(toutes?\s+)?(tes|vos)\s+instructions",
            r"system\s*prompt",
        ]
        for pattern in patterns:
            if re.search(pattern, text, re.IGNORECASE):
                return {
                    "valid": False,
                    "reason": "Injection pattern detected"
                }

        return {"valid": True}

    # --- Layer 2: Input Moderation ---

    def moderate_input(self, text: str) -> dict:
        """Prompt moderation via API."""
        response = client.classifiers.moderate(
            model="mistral-moderation-2603",
            inputs=[text]
        )
        scores = response.results[0].category_scores or {}
        violations = self._check_thresholds(scores)

        return {
            "allowed": len(violations) == 0,
            "scores": scores,
            "violations": violations
        }

    # --- Layer 3: Secure Generation ---

    def generate(self, messages: list) -> str:
        """Generation with guardrails and safe_prompt."""
        response = client.chat.complete(
            model=self.model,
            messages=messages,
            safe_prompt=True,
            guardrails=[
                {
                    "block_on_error": True,
                    "moderation_llm_v2": {
                        "custom_category_thresholds": self.policy["thresholds"],
                        "action": "block",
                    },
                }
            ],
        )
        content = response.choices[0].message.content
        return content if isinstance(content, str) else ""

    # --- Layer 4: Output Moderation ---

    def moderate_output(self, prompt: str, response_text: str) -> dict:
        """Response moderation in context."""
        response = client.classifiers.moderate_chat(
            model="mistral-moderation-2603",
            inputs=[[
                {"role": "user", "content": prompt},
                {"role": "assistant", "content": response_text}
            ]]
        )
        scores = response.results[0].category_scores or {}
        violations = self._check_thresholds(scores)

        return {
            "allowed": len(violations) == 0,
            "scores": scores,
            "violations": violations
        }

    # --- Layer 5: Logging ---

    def log_decision(self, decision: Decision, data: dict):
        """Records the decision for auditing."""
        self.stats[decision.value] += 1
        entry = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "decision": decision.value,
            "policy": self.policy["name"],
            **data
        }
        logger.info(json.dumps(entry, ensure_ascii=False))

    # --- Main Pipeline ---

    def process(self, user_message: str,
                system_prompt: str | None = None) -> dict:
        """Complete secure processing pipeline."""

        # Layer 1: Validation
        validation = self.validate_input(user_message)
        if not validation["valid"]:
            self.log_decision(Decision.BLOCKED_INPUT, {
                "reason": validation["reason"]
            })
            return {
                "status": Decision.BLOCKED_INPUT.value,
                "message": "Your message cannot be processed."
            }

        # Layer 2: Input Moderation
        check_input = self.moderate_input(user_message)
        if not check_input["allowed"]:
            self.log_decision(Decision.BLOCKED_INPUT, {
                "violations": check_input["violations"]
            })
            return {
                "status": Decision.BLOCKED_INPUT.value,
                "message": "This content violates our policy."
            }

        # Layer 3: Generation
        messages = []
        if system_prompt:
            messages.append({"role": "system",
                           "content": system_prompt})
        messages.append({"role": "user",
                        "content": user_message})

        try:
            response_text = self.generate(messages)
        except SDKError as e:
            if e.status_code == 403:
                self.log_decision(Decision.BLOCKED_GUARDRAIL, {})
                return {
                    "status": Decision.BLOCKED_GUARDRAIL.value,
                    "message": "Request blocked by guardrails."
                }
            raise

        # Layer 4: Output Moderation
        check_output = self.moderate_output(user_message, response_text)
        if not check_output["allowed"]:
            self.log_decision(Decision.BLOCKED_OUTPUT, {
                "violations": check_output["violations"]
            })
            return {
                "status": Decision.BLOCKED_OUTPUT.value,
                "message": "The response was filtered."
            }

        # Success
        self.log_decision(Decision.ALLOWED, {
            "input_max_score": max(check_input["scores"].values(), default=0.0),
            "output_max_score": max(check_output["scores"].values(), default=0.0),
        })

        return {
            "status": Decision.ALLOWED.value,
            "content": response_text,
            "moderation": {
                "input": check_input["scores"],
                "output": check_output["scores"]
            }
        }

    # --- Utilities ---

    def _check_thresholds(self, scores: dict) -> list:
        """Checks scores against policy thresholds."""
        violations = []
        for cat, threshold in self.policy["thresholds"].items():
            score = scores.get(cat, 0)
            if score > threshold:
                violations.append({
                    "category": cat,
                    "score": round(score, 3),
                    "threshold": threshold
                })
        return violations

    def report(self) -> dict:
        """Generates a statistics report."""
        total = sum(self.stats.values())
        return {
            "policy": self.policy["name"],
            "total_requests": total,
            "decisions": self.stats,
            "block_rate": round(
                (self.stats["blocked_input"] +
                 self.stats["blocked_guardrail"] +
                 self.stats["blocked_output"]) / max(total, 1),
                3
            )
        }

Utilização em Produção

# Define the policy
prod_policy = {
    "name": "Production v1.2",
    "thresholds": {
        "sexual": 0.15, "hate_and_discrimination": 0.1, "violence_and_threats": 0.2,
        "dangerous": 0.1, "criminal": 0.1, "selfharm": 0.1, "health": 0.4,
        "financial": 0.4, "law": 0.4, "pii": 0.15,
        "jailbreaking": 0.1
    }
}

# Instantiate the architecture
arch = SecureArchitecture(prod_policy)

# Process requests
result = arch.process(
    "Explain how transformers work",
    system_prompt="You are an AI instructor."
)
print(result["status"])   # expected: "allowed"
print(result["content"])

# Consult statistics
print(arch.report())

Monitorização e Alertas

Duas métricas bastam para orientar um sistema de moderação, e deve observá-las em direções opostas. A taxa de bloqueio deve permanecer estável: um pico súbito sinaliza quer um ataque, quer um limiar demasiado estrito que começa a prejudicar utilizadores legítimos. A distribuição de pontuações é igualmente importante — se o seu conteúdo se agrupar logo abaixo do limiar, este está mal posicionado e o próximo ajuste por parte dos seus utilizadores fará com que falhe.

def configure_alerts(arch: SecureArchitecture):
    """Configures alerts for monitoring."""
    report = arch.report()

    # Alert if block rate is abnormal
    if report["block_rate"] > 0.15:
        logger.warning(
            f"High block rate: "
            f"{report['block_rate']:.1%}"
        )

    # Alert if jailbreak spikes occur
    # Integrate with Prometheus, Grafana, Datadog, etc.

Resumo do Curso

No final deste curso, dominou:

  • Guardrails Personalizados: Bloquear pedidos perigosos antes da geração, configurar limiares por categoria, aplicar a agentes
  • API de Moderação: Classificar conteúdo com o Mistral Moderation 2, interpretar pontuações nas 11 categorias, tomar decisões automatizadas
  • Segurança em Produção: Definir políticas de conteúdo, detetar injeções de prompts, garantir a conformidade com o RGPD
  • Arquitetura Completa: Reunir guardrails + moderação + monitorização num pipeline robusto

Dispõe agora de todo o código necessário para implementar um sistema completo de moderação de IA com a API da Mistral.

Pontos-chave

  • A arquitetura de segurança inclui 5 camadas: validação, guardrails, geração, moderação, registo
  • Cada camada compensa as fraquezas das outras — isto é defesa em profundidade
  • Monitore a taxa de bloqueio e as pontuações em produção
  • Mantenha a sua política atualizada com revisões regulares
  • O código completo nesta lição é um ponto de partida — adapte-o ao seu contexto

Teste os Seus Conhecimentos

Guardrails, moderação, injeção: a arquitetura defensiva está clara?

1. Onde intervêm os guardrails personalizados?

Resposta: Antes do modelo: filtram as entradas de acordo com as suas regras (tópicos proibidos, formatos) — a primeira camada, que evita sequer fazer a chamada quando o pedido está fora do âmbito.

2. O que abrange a API de Moderação da Mistral?

Resposta: Onze categorias de conteúdo de risco, com uma pontuação por categoria: os seus limiares decidem se bloqueia, assinala ou permite — transformando a política de conteúdo em código.

3. Como se define uma boa política de conteúdo?

Resposta: Por caso de uso: o que é aceitável para a aplicação, limiares por categoria, ações associadas (bloqueio, reescrita, escalonamento) — documentado e testado, não implícito.

4. Como deteta tentativas de injeção de prompts?

Resposta: Tratando todo o conteúdo externo como suspeito: detetando padrões de instrução nos dados, isolando instruções de dados, validando saídas — e executando testes ofensivos regulares.

5. Qual é o aspeto da arquitetura de segurança completa?

Resposta: Camadas: guardrails de entrada, moderação de conteúdo, controlos de saída, conformidade com o RGPD (minimização, direitos) e rastreabilidade — nenhuma camada é perfeita isoladamente, mas a sua sobreposição compensa.

A defesa em profundidade não é um slogan: cada camada neste curso detém o que a anterior deixou passar.