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

Moderação de Conteúdo com a API

Aula 19 de 22 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Moderação de Conteúdo com a API
  2. A API de Moderação
  3. Categorias de Moderação
  4. Pipeline de Moderação Completo
  5. Moderação em Lote
  6. Registo de Moderação
  7. Pontos-chave

Atualizado em 3 de novembro de 2026 com base no guia de Moderação da OpenAI: as categorias illicit e illicit/violent para o modelo omni-moderation-latest estavam em falta na lista e no código. Fonte: Moderation.

Moderação de Conteúdo com a API

A API de Moderação da OpenAI deteta automaticamente conteúdo inadequado. É uma ferramenta gratuita e essencial para qualquer aplicação que aceite conteúdo gerado por utilizadores. A lição anterior mostrou-lhe como escrever filtros personalizados; esta oferece-lhe um classificador treinado que deteta o que as expressões regulares nunca conseguirão apanhar — ameaças veladas, insultos indiretos e formulações implícitas.

A API de Moderação

A chamada é intencionalmente minimalista: um modelo, um texto e um resultado que se resume a um booleano. O campo flagged responde à questão binária: «Este conteúdo viola as políticas de utilização?», enquanto categories detalha quais foram violadas. Como este endpoint é gratuito, não existe qualquer razão económica para o ignorar, mesmo em grandes volumes.

from openai import OpenAI
client = OpenAI()

# A API de Moderação é GRATUITA
moderation = client.moderations.create(
    model="omni-moderation-latest",
    input="Hello, how are you?"
)

result = moderation.results[0]
print(f"Content flagged: {result.flagged}")
print(f"Categories: {result.categories}")

# Result:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)

Categorias de Moderação

Por detrás do booleano esconde-se uma grelha de granularidade fina. O modelo devolve uma decisão por categoria — assédio, assédio ameaçador, ódio, ódio ameaçador, instruções para atos ilícitos (com ou sem violência), automutilação com as suas variantes (instruções e intenção), conteúdo sexual, conteúdo sexual envolvendo menores, violência e violência gráfica — juntamente com uma pontuação de confiança entre 0,0 e 1,0 para cada uma.

Estas pontuações são mais importantes do que a decisão binária quando deseja calibrar a sua política. Uma plataforma de fóruns profissional poderá querer bloquear a partir de 0,3 para assédio, enquanto um serviço de ficção poderá aceitar 0,7 para violência. A função abaixo expõe ambos os níveis de insight: as categorias realmente acionadas e as pontuações brutas para os seus próprios limiares.

def analyze_moderation(text: str) -> dict:
    """Análise detalhada de moderação."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    # Categorias disponíveis
    categories = {
        "harassment": result.categories.harassment,
        "harassment_threatening": result.categories.harassment_threatening,
        "hate": result.categories.hate,
        "hate_threatening": result.categories.hate_threatening,
        "illicit": result.categories.illicit,
        "illicit_violent": result.categories.illicit_violent,
        "self_harm": result.categories.self_harm,
        "self_harm_instructions": result.categories.self_harm_instructions,
        "self_harm_intent": result.categories.self_harm_intent,
        "sexual": result.categories.sexual,
        "sexual_minors": result.categories.sexual_minors,
        "violence": result.categories.violence,
        "violence_graphic": result.categories.violence_graphic,
    }

    # Pontuações de confiança (0.0 a 1.0)
    scores = {
        "harassment": result.category_scores.harassment,
        "hate": result.category_scores.hate,
        "self_harm": result.category_scores.self_harm,
        "sexual": result.category_scores.sexual,
        "violence": result.category_scores.violence,
    }

    return {
        "flagged": result.flagged,
        "detected_categories": [k for k, v in categories.items() if v],
        "main_scores": {k: round(v, 4) for k, v in scores.items()},
    }

# Teste
result = analyze_moderation("Hello everyone!")
print(f"Flagged: {result['flagged']}")
print(f"Scores: {result['main_scores']}")

Pipeline de Moderação Completo

Moderação de Inputs do Utilizador

Vamos envolver esta chamada num componente reutilizável. O ContentModerator devolve um par explícito — aceitável ou não, com o motivo — em vez de um objeto bruto que cada chamador teria de reinterpretar. Traduzir as categorias numa linguagem clara é fundamental: este é o vocabulário que aparecerá na sua interface e nos registos, e deve ser compreensível pela equipa de moderação humana que assumirá o controlo.

class ContentModerator:
    """Moderador de conteúdo para aplicações."""

    def __init__(self, custom_threshold: float = 0.5):
        self.client = OpenAI()
        self.threshold = custom_threshold

    def moderate(self, text: str) -> tuple[bool, dict]:
        """Modera texto. Devolve (é_aceitável, detalhes)."""
        moderation = self.client.moderations.create(
            model="omni-moderation-latest",
            input=text
        )

        result = moderation.results[0]

        if result.flagged:
            categories = []
            if result.categories.harassment:
                categories.append("harassment")
            if result.categories.hate:
                categories.append("hate speech")
            if result.categories.sexual:
                categories.append("sexual content")
            if result.categories.violence:
                categories.append("violence")
            if result.categories.self_harm:
                categories.append("self-harm")

            return False, {
                "reason": "Inappropriate content detected",
                "categories": categories
            }

        return True, {"reason": "Content acceptable"}

    def moderate_conversation(self, messages: list[str]) -> list[dict]:
        """Modera uma lista de mensagens."""
        results = []
        for msg in messages:
            acceptable, details = self.moderate(msg)
            results.append({
                "message": msg[:50] + "..." if len(msg) > 50 else msg,
                "acceptable": acceptable,
                **details
            })
        return results

# Utilização
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")

Integração no Pipeline da API

A moderação enquadra a chamada em ambos os lados. Filtrar o input evita pagar pela geração de conteúdo que iria rejeitar de qualquer forma; filtrar o output protege contra casos em que o modelo, habilmente provocado, produz algo inaceitável por si só. Note a diferença no tratamento: para o input, pode dizer ao utilizador o que foi detetado, uma vez que foi ele o autor; para o output, a mensagem mantém-se vaga, porque detalhá-la significaria descrever aquilo que o modelo acabou de produzir.

def moderated_chatbot(user_input: str) -> str:
    """Chatbot com moderação de inputs E outputs."""
    moderator = ContentModerator()

    # 1. Moderar input
    input_ok, input_details = moderator.moderate(user_input)
    if not input_ok:
        return (f"Your message was blocked: "
                f"{', '.join(input_details['categories'])}")

    # 2. Gerar resposta
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Respond in a professional and safe manner.",
        input=user_input
    )

    # 3. Moderar output
    output_ok, output_details = moderator.moderate(response.output_text)
    if not output_ok:
        return "I am unable to provide that response."

    return response.output_text

# Teste
print(moderated_chatbot("What is the capital of France?"))

Moderação em Lote

Esta chamada dupla adiciona latência, o que é aceitável numa conversa, mas torna-se proibitivo quando precisa de processar dez mil avaliações de clientes importadas de um ficheiro. Para moderar grandes volumes com eficiência, passe um array diretamente: a API processa todos os textos num único pedido e devolve os resultados pela mesma ordem, permitindo-lhe reassociá-los por índice.

def moderate_batch(texts: list[str]) -> list[dict]:
    """Modera múltiplos textos num único pedido."""
    results = []

    # A API aceita um array de inputs
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=texts
    )

    for i, result in enumerate(moderation.results):
        results.append({
            "index": i,
            "text_preview": texts[i][:50],
            "flagged": result.flagged,
        })

    flagged_count = sum(1 for r in results if r["flagged"])
    print(f"Moderated {len(texts)} texts: {flagged_count} flagged")

    return results

# Utilização
texts = [
    "Hello, how are you?",
    "Great product, I recommend it!",
    "Customer service is excellent.",
]
results = moderate_batch(texts)

Registo de Moderação

Uma decisão de moderação afeta um utilizador e, mais cedo ou mais tarde, terá de a justificar — seja a um cliente que conteste um bloqueio, seja a um regulador. Portanto, registe sistematicamente o veredicto, o ID do utilizador, as pontuações e um excerto do texto. O nível de registo distingue os dois casos: warning para conteúdo assinalado, que merece revisão humana, e info para o restante, que alimenta as suas estatísticas.

import json
import logging
from datetime import datetime

logger = logging.getLogger("moderation")

def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
    """Modera e regista o resultado para auditoria."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "user_id": user_id,
        "flagged": result.flagged,
        "text_preview": text[:100],
        "scores": {
            "harassment": round(result.category_scores.harassment, 4),
            "hate": round(result.category_scores.hate, 4),
            "violence": round(result.category_scores.violence, 4),
        }
    }

    if result.flagged:
        logger.warning(json.dumps(log_entry))
    else:
        logger.info(json.dumps(log_entry))

    return not result.flagged

# Utilização
is_ok = moderate_with_log("Test message", user_id="user-123")

Um último aviso antes de avançar: a moderação classifica o conteúdo; não compreende a intenção. Uma mensagem perfeitamente educada que tente contornar as proteções do seu assistente passará por todos estes filtros sem ser assinalada uma única vez. Esse é o tema da próxima lição.

Pontos-chave

  • A API de Moderação é gratuita — utilize-a sistematicamente
  • Modere tanto os inputs (conteúdo do utilizador) COMO os outputs (respostas do modelo)
  • O modelo omni-moderation-latest cobre todas as categorias de conteúdo
  • Registe todas as decisões de moderação para auditoria
  • Utilize o processamento em lote para moderar grandes volumes com eficiência
  • A moderação complementa as instruções do sistema; não as substitui