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

API de Moderação da OpenAI

Aula 5 de 14 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Uma Ferramenta de Moderação Integrada
  2. O Que a API Devolve
  3. Categorias Detetadas
  4. Moderar Ambas as Extremidades do Pipeline
  5. O Que Esta API Não Faz
  6. Pontos-chave

Atualizado a 3 de novembro de 2026 com base no guia Moderation da OpenAI: adicionada a categoria illicit (e illicit/violent), que faltava na tabela, juntamente com as categorias aplicáveis a imagens. Fonte: Moderation.

Uma Ferramenta de Moderação Integrada

A OpenAI disponibiliza uma API de Moderação gratuita que analisa texto para detetar conteúdos potencialmente nocivos. Esta é a primeira linha de defesa a integrar em qualquer aplicação que utilize modelos da OpenAI, e não está limitado apenas a esse caso de uso: como aceita texto bruto como entrada, pode também utilizá-la para filtrar inputs destinados a outros modelos. O facto de ser gratuita altera a forma como encara o problema. As compensações habituais — devemos moderar todos os pedidos ou apenas os suspeitos? — perdem peso, uma vez que o único custo remanescente é a latência.

O Que a API Devolve

A chamada básica cabe numa única linha; é a resposta que exige atenção. A API devolve três elementos distintos: um booleano flagged que reflete a decisão da OpenAI, a lista de categorias efetivamente acionadas e, mais importante, pontuações contínuas por categoria. São estas pontuações que fazem a diferença em produção, pois permitem-lhe decidir onde traçar a linha, em vez de herdar um limiar desenhado para um uso genérico.

from openai import OpenAI

client = OpenAI()

def moderate_content(text: str) -> dict:
    """Analisa texto através da API de Moderação da OpenAI."""
    response = client.moderations.create(input=text)
    result = response.results[0]

    return {
        "blocked": result.flagged,
        "categories": {
            cat: flagged
            for cat, flagged in result.categories.__dict__.items()
            if flagged
        },
        "scores": {
            cat: round(score, 4)
            for cat, score in result.category_scores.__dict__.items()
            if score > 0.01
        },
    }

# Testar com diferentes tipos de conteúdo
examples = [
    "How do I bake a chocolate cake?",
    "I will kill you if you don't answer me",
    "Explain how AES encryption works",
]

for text in examples:
    result = moderate_content(text)
    status = "BLOCKED" if result["blocked"] else "OK"
    print(f"{status} : {text[:50]}...")
    if result["categories"]:
        print(f"  Categories : {list(result['categories'].keys())}")

Os três exemplos de teste não são aleatórios: o primeiro deve passar, o segundo deve ser bloqueado e o terceiro — uma pergunta técnica perfeitamente legítima — mostra-lhe como o seu pipeline se comporta quando confrontado com vocabulário de segurança. Este é exatamente o tipo de pedido que uma equipa de cibersegurança trata diariamente.

Categorias Detetadas

A API classifica conteúdos problemáticos ao longo de vários eixos, cada um correspondendo a um tipo distinto de dano.

Categoria Descrição
harassment Assédio, ameaças, intimidação
hate Discurso de ódio baseado na identidade
illicit Conselhos ou instruções para cometer atos ilícitos
self-harm Automutilação, suicídio
sexual Conteúdo sexual explícito
violence Violência gráfica, ameaças

Cada categoria possui também subcategorias (por exemplo, harassment/threatening, illicit/violent, violence/graphic) para uma filtragem mais fina. Com o modelo omni-moderation-latest, apenas self-harm e as suas variantes, sexual e violence (com violence/graphic) se aplicam também a imagens; as outras categorias aplicam-se apenas a texto. Esta granularidade poupa-o de fazer compensações grosseiras: uma plataforma de moderação de fóruns pode querer bloquear harassment/threatening enquanto tolera simples harassment, o que abrange muitas disputas comuns.

Quando necessita de processar volume — análise retrospetiva de um histórico de conversas, por exemplo — a API aceita uma lista e devolve um resultado para cada elemento, evitando múltiplas idas e voltas à rede.

def moderate_batch(messages: list[str]) -> list[dict]:
    """Modera múltiplas mensagens numa única chamada."""
    response = client.moderations.create(input=messages)
    results = []
    for i, result in enumerate(response.results):
        results.append({
            "index": i,
            "text": messages[i][:50],
            "blocked": result.flagged,
            "max_score": max(
                score
                for score in result.category_scores.__dict__.values()
            ),
        })
    return results

Moderar Ambas as Extremidades do Pipeline

Um erro comum é moderar apenas os inputs. Isto baseia-se numa intuição falsa: se a mensagem recebida for aceitável, a resposta também o será. No entanto, um modelo pode produzir conteúdo problemático a partir de um pedido neutro, especialmente quando recorre a documentos recuperados cujo conteúdo ninguém verificou. A classe abaixo aplica, portanto, o mesmo tratamento em ambas as direções, adicionando um limiar personalizado que aperta a decisão padrão da API.

class ModerationPipeline:
    """Pipeline de moderação de input + output para uma aplicação LLM."""

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

    def moderate_input(self, message: str) -> tuple[bool, dict]:
        """Modera a mensagem ANTES de enviar para o modelo."""
        result = self.client.moderations.create(input=message).results[0]
        scores = result.category_scores.__dict__
        high_categories = {
            cat: score for cat, score in scores.items() if score > self.threshold
        }
        blocked = result.flagged or bool(high_categories)
        return blocked, {"flagged_api": result.flagged, "custom_categories": high_categories}

    def moderate_output(self, response: str) -> tuple[bool, dict]:
        """Modera a resposta do modelo ANTES de enviar para o utilizador."""
        return self.moderate_input(response)

    def process_message(self, user_message: str, system_prompt: str) -> str:
        """Pipeline completo: moderação de input, LLM, moderação de output."""
        # Passo 1: moderar input
        input_blocked, details = self.moderate_input(user_message)
        if input_blocked:
            return "A sua mensagem não pode ser processada. Por favor, reformule-a."

        # Passo 2: chamar o modelo
        response = self.client.chat.completions.create(
            model="gpt-5.6-sol",
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_message},
            ],
        )
        model_response = response.choices[0].message.content

        # Passo 3: moderar output
        output_blocked, _ = self.moderate_output(model_response)
        if output_blocked:
            return "A resposta foi filtrada por não conformidade."

        return model_response

# Utilização
pipeline = ModerationPipeline(custom_threshold=0.5)
response = pipeline.process_message(
    "How do I protect my application against SQL injections?",
    "You are an expert in defensive cybersecurity."
)
print(response)

O Que Esta API Não Faz

A sua limitação mais importante é também a mais mal compreendida: não deteta injeção de prompts. Uma mensagem educada, perfeitamente inócua do ponto de vista do conteúdo, mas que pede ao modelo para ignorar as suas instruções, passará sem acionar qualquer categoria. Esperar que proteja contra manipulação é como instalar um detetor de fumo e esperar que impeça assaltos.

Os falsos positivos são a segunda limitação, particularmente sensível em contextos de segurança ou médicos, onde descrever uma ameaça faz parte do trabalho. Uma chamada de rede adicional é adicionada a cada pedido, o que importa quando visa respostas em tempo real. A deteção permanece mais fiável em inglês do que noutras línguas, um ponto cego que os atacantes conhecem perfeitamente. Por fim, as categorias e limiares evoluem com as atualizações: um conjunto de calibração definido há seis meses merece reverificação.

Estes limites ditam como utilizar a ferramenta. Modere em ambas as direções, ajuste os limiares categoria por categoria em vez de globalmente e combine-a sistematicamente com outras camadas — deteção de injeção, filtragem de lógica de negócio — que as lições seguintes detalham. Registe os resultados, porque observar os seus próprios falsos positivos é a forma de aprender onde mover os controlos. E planeie o caso em que a API esteja indisponível: decida agora, enquanto as coisas estão calmas, se a sua aplicação deve bloquear por defeito ou deixar o tráfego passar, em vez de descobrir esse comportamento durante um incidente.

Pontos-chave

  • A API de Moderação é gratuita, rápida e simples de integrar
  • Deteta conteúdo ofensivo, mas não injeções ou jailbreaks
  • O pipeline input-modelo-output deve ser moderado em ambas as extremidades
  • Os limiares padrão raramente se adequam — adapte-os ao seu contexto
  • É uma camada entre outras, nunca a única linha de defesa