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

Moderação de conteúdo em escala

Aula 19 de 20 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Proteger os seus utilizadores em produção
  2. A primeira camada: a API de Moderações
  3. Gerir a carga
  4. Manter um registo defensável
  5. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por padrão (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (API de Respostas) ou reasoning_effort="none" (Chat Completions). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.

Proteger os seus utilizadores em produção

Assim que a sua aplicação entra no ar, tem de lidar com conteúdo inadequado — tanto na entrada (prompts maliciosos) como na saída (respostas problemáticas). Este requisito bidirecional apanha muitas equipas de surpresa. A maioria pensa primeiro em filtrar o que os utilizadores enviam, mas o risco reputacional concentra-se no que a sua aplicação publica em seu nome. Um modelo bem alinhado raramente gera conteúdo chocante por si só, mas pode fazê-lo quando pressionado — e a sua marca aparece no topo da captura de ecrã.

Vamos evoluir de uma única chamada à API para um pipeline assíncrono de alto débito, escalando passo a passo.

A primeira camada: a API de Moderações

A API de Moderações classifica texto em várias categorias de risco e devolve tanto um veredito binário como pontuações detalhadas. É rápida e gratuita, tornando-se o primeiro filtro natural para qualquer aplicação pública. A função abaixo apenas expõe categorias com pontuações acima de 0,3 — um limiar deliberadamente baixo. Nesta fase, quer ver o que se aproxima da linha, não apenas o que a atravessa.

import openai

client = openai.OpenAI()

def moderate_content(text: str) -> dict:
    """Verificar se o texto contém conteúdo inadequado."""
    response = client.moderations.create(
        model="omni-moderation-latest",
        input=text,
    )

    result = response.results[0]
    return {
        "flagged": result.flagged,
        "categories": {
            cat: score
            for cat, score in result.category_scores.__dict__.items()
            if score > 0.3
        },
    }

# Exemplo
result = moderate_content("How do I bake a chocolate cake?")
print(f"Flagged: {result['flagged']}")

Em produção, um veredito binário não é suficiente. Dependendo do conteúdo e do contexto, poderá querer permiti-lo, reescrevê-lo, bloqueá-lo ou escalá-lo para um humano — quatro decisões distintas que deve nomear explicitamente no código em vez de improvisar com booleanos. O pipeline abaixo formaliza estas ações, aplica limiares por categoria e adiciona uma segunda camada para deteção de injeção de prompts.

from enum import Enum
from dataclasses import dataclass

class ModerationAction(Enum):
    ALLOW = "allow"
    MODIFY = "modify"
    BLOCK = "block"
    ESCALATE = "escalate"

@dataclass
class ModerationResult:
    action: ModerationAction
    reason: str | None = None
    modified_content: str | None = None

class ModerationPipeline:
    """Pipeline de moderação multicamada."""

    def __init__(self, thresholds: dict | None = None):
        self.thresholds = thresholds or {
            "harassment": 0.7,
            "hate": 0.7,
            "self-harm": 0.5,
            "sexual": 0.7,
            "violence": 0.7,
        }

    def moderate_input(self, text: str) -> ModerationResult:
        """Moderar conteúdo de entrada (prompt do utilizador)."""
        moderation = client.moderations.create(
            model="omni-moderation-latest",
            input=text,
        )

        result = moderation.results[0]
        if result.flagged:
            problematic_categories = [
                cat for cat, flagged in result.categories.__dict__.items()
                if flagged
            ]
            return ModerationResult(
                action=ModerationAction.BLOCK,
                reason=f"Conteúdo inadequado: {', '.join(problematic_categories)}",
            )

        # Deteção de injeção de prompts
        if self._detect_injection(text):
            return ModerationResult(
                action=ModerationAction.BLOCK,
                reason="Tentativa de injeção de prompt detetada",
            )

        return ModerationResult(action=ModerationAction.ALLOW)

    def moderate_output(self, response: str) -> ModerationResult:
        """Moderar conteúdo de saída (resposta do LLM)."""
        moderation = client.moderations.create(
            model="omni-moderation-latest",
            input=response,
        )

        if moderation.results[0].flagged:
            return ModerationResult(
                action=ModerationAction.BLOCK,
                reason="A resposta gerada contém conteúdo inadequado",
            )

        return ModerationResult(action=ModerationAction.ALLOW)

    def _detect_injection(self, text: str) -> bool:
        """Detetar tentativas de injeção de prompts."""
        markers = [
            "ignore previous instructions",
            "ignore your instructions",
            "forget your guidelines",
            "you are now",
            "new role",
            "system prompt",
            "jailbreak",
        ]
        text_lower = text.lower()
        return any(m in text_lower for m in markers)

O limiar de 0,5 para self-harm — mais rigoroso que o 0,7 usado para outras categorias — ilustra o raciocínio que deve aplicar a cada limiar. Aqui, o custo de um falso positivo está longe do custo de um falso negativo, pelo que baixa a fasquia. Faça esta compensação categoria por categoria, com base no seu público, em vez de aplicar um valor uniforme.

A deteção de injeção baseada em marcadores tem uma ressalva. Deteta tentativas ingénuas, que representam a maior parte do volume, e nada mais: uma formulação ligeiramente diferente ou uma versão traduzida passa ao lado. Trate-a como um filtro de ruído, não como uma defesa. A proteção real contra injeção é arquitetónica — nunca dê ao modelo capacidades que um prompt sequestrado possa explorar.

Gerir a carga

Numa aplicação de alto tráfego, a moderação síncrona torna-se um gargalo: cada mensagem espera pelo seu veredito antes de ser processada. Um moderador assíncrono desacopla estes passos, colocando o conteúdo numa fila para consumo por múltiplos trabalhadores, enquanto rastreia estatísticas úteis ao longo do caminho.

import asyncio

class AsyncModerator:
    """Moderar conteúdo assincronamente para alto débito."""

    def __init__(self, num_workers: int = 10):
        self.pipeline = ModerationPipeline()
        self.queue: asyncio.Queue = asyncio.Queue()
        self.num_workers = num_workers
        self.stats = {"allowed": 0, "blocked": 0, "escalated": 0}

    async def worker(self):
        while True:
            task = await self.queue.get()
            try:
                result = self.pipeline.moderate_input(task["text"])
                task["callback"](result)

                match result.action:
                    case ModerationAction.ALLOW:
                        self.stats["allowed"] += 1
                    case ModerationAction.BLOCK:
                        self.stats["blocked"] += 1
                    case ModerationAction.ESCALATE:
                        self.stats["escalated"] += 1
            finally:
                self.queue.task_done()

    async def start(self):
        for _ in range(self.num_workers):
            asyncio.create_task(self.worker())

    def report(self) -> str:
        total = sum(self.stats.values())
        if total == 0:
            return "Nenhum conteúdo moderado."
        return (
            f"Total: {total} | "
            f"Permitidos: {self.stats['allowed']} ({self.stats['allowed']/total:.1%}) | "
            f"Bloqueados: {self.stats['blocked']} ({self.stats['blocked']/total:.1%})"
        )

A taxa de bloqueio produzida por report é a sua métrica principal de calibração. Se saltar subitamente para 15% após operar a 0,5%, só existem duas explicações: está sob um ataque coordenado ou acabou de quebrar os seus limiares. Em qualquer caso, quer saber disso dentro da hora, não na próxima revisão mensal.

Uma limitação final merece menção: a API de Moderações nada sabe sobre o seu negócio. Uma mensagem perfeitamente aceitável em geral pode violar as suas próprias regras — pedir conselhos médicos a um assistente bancário, tentar obter uma tarifa fora da rede ou contornar um procedimento. A moderação contextual adiciona esta camada ao submeter a mensagem a um modelo com as suas regras explícitas, mas apenas depois de o filtro padrão a ter deixado passar.

def contextual_moderation(
    text: str,
    app_context: str,
    business_rules: list[str],
) -> ModerationResult:
    """Moderação consciente do contexto, adaptada à aplicação."""
    pipeline = ModerationPipeline()
    standard_result = pipeline.moderate_input(text)

    if standard_result.action == ModerationAction.BLOCK:
        return standard_result

    verification_prompt = (
        f"Contexto da aplicação: {app_context}\n\n"
        f"Regras de negócio a verificar:\n"
        + "\n".join(f"- {r}" for r in business_rules)
        + f"\n\nMensagem do utilizador: {text}\n\n"
        "A mensagem cumpre todas as regras? "
        "Responda sim ou não com uma breve justificação."
    )

    response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=verification_prompt,
        max_output_tokens=100,
        temperature=0.0,
    )

    if "no" in response.output_text.lower()[:10]:
        return ModerationResult(
            action=ModerationAction.BLOCK,
            reason=response.output_text,
        )

    return ModerationResult(action=ModerationAction.ALLOW)

A ordem destas duas verificações importa. O filtro gratuito e rápido executa primeiro, e a chamada ao modelo pago ocorre apenas para mensagens que o ultrapassam. No tráfego real, isto cobre quase todas as mensagens. Fazer o inverso — pagar por uma chamada de modelo para conteúdo que a API de Moderações teria rejeitado em milissegundos — seria um desperdício.

Manter um registo defensável

Uma decisão de moderação é uma decisão pela qual será responsabilizado, de uma forma ou de outra. Precisa de um registo — mas um que não se torne ele próprio um problema. O comentário no código destaca a linha mais importante do ficheiro: registe a ação, o motivo e o comprimento, nunca o texto bruto. Armazenar mensagens de utilizadores num ficheiro de registo expõe-no a obrigações de proteção de dados muito mais pesadas do que o serviço prestado.

import json
import time
from pathlib import Path

class ModerationLog:
    """Registar todas as decisões de moderação para fins de auditoria."""

    def __init__(self, log_path: str = "logs/moderation.jsonl"):
        self.path = Path(log_path)
        self.path.parent.mkdir(parents=True, exist_ok=True)

    def record(
        self,
        text: str,
        result: ModerationResult,
        source: str = "input",
    ):
        entry = {
            "timestamp": time.time(),
            "source": source,
            "action": result.action.value,
            "reason": result.reason,
            "text_length": len(text),
            # NÃO registe texto bruto por questões de privacidade
        }

        with open(self.path, "a") as f:
            f.write(json.dumps(entry) + "\n")

Se ainda precisar de poder recuperar uma mensagem específica durante uma disputa, registe um hash do texto em vez do próprio texto. Isto permite-lhe confirmar que um determinado conteúdo corresponde a uma decisão registada sem reter o conteúdo do seu lado.

Pontos-chave

  • Modere tanto as entradas (prompts) como as saídas (respostas)
  • Utilize a API de Moderações como a sua primeira camada, rápida e gratuita
  • Ajuste os limiares categoria por categoria com base no custo real de um falso negativo
  • Adicione deteção de injeção sabendo que só apanha tentativas ingénuas
  • Registe todas as decisões para auditoria sem armazenar conteúdo bruto