Filtragem de palavras proibidas

A filtragem de palavras proibidas identifica, em textos, a sua própria lista de palavras não permitidas. Diferentemente de spam ou sentimento — que usam modelos treinados — essa verificação compara o texto com uma lista personalizada de palavras que você configura para o seu projeto, para que você decida exatamente quais termos estão fora dos limites. Ative-a com check_badwords em POST /api/v2/check.

Quando devo usar uma lista de palavras personalizada?

Modelos são ótimos para categorias mais difusas, como toxicidade, mas alguns termos são decisões de política que só você pode tomar: o nome de um concorrente, um produto proibido, ofensas específicas da comunidade, padrões de credenciais vazadas ou palavras que sua equipe jurídica exige que sejam bloqueadas. Uma lista personalizada oferece uma correspondência exata e previsível para esses casos.

Como funciona?

A filtragem de palavras proibidas é executada somente quando duas condições são verdadeiras: check_badwords está ativado e seu projeto tem uma lista personalizada de palavras configurada. Em seguida, ela faz uma correspondência de substring sem diferenciar maiúsculas de minúsculas para cada palavra listada no texto da mensagem e retorna todas as palavras encontradas.

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "text": "Check out CompetitorBrand for a better deal"
    },
    "settings": {
      "check_badwords": true
    }
  }'

Resposta

{
  "has_violations": true,
  "cached": false,
  "results": {
    "hits": true,
    "badwords": {
      "hit": true,
      "matched_words": ["CompetitorBrand"],
      "apply_penalty": true
    }
  }
}

O objeto results.badwords tem três campos:

Campo	Tipo	Descrição
hit	boolean	Verdadeiro se qualquer palavra listada foi encontrada
matched_words	string[]	As palavras configuradas que corresponderam ao texto
apply_penalty	boolean	Se a correspondência deve acionar sua aplicação de regras (sempre true para uma correspondência)

Como configuro a lista de palavras?

A lista faz parte das configurações do seu projeto, não da solicitação — você a define uma vez, e toda solicitação com check_badwords a utiliza. Gerencie-a nas configurações do projeto (no mesmo lugar em que você define as verificações padrão). Como a solicitação leva apenas o seletor check_badwords, você pode manter sua lista de palavras privada e alterá-la sem mexer no código do cliente.

Se check_badwords estiver ativado, mas seu projeto não tiver palavras configuradas, a verificação será ignorada e nenhum resultado de badwords será retornado.

Que tipo de correspondência ela usa?

A correspondência é uma busca de substring sem diferenciar maiúsculas de minúsculas: uma palavra listada como spam corresponde a spam, SPAM e também a spammer. Escolha as entradas da lista levando isso em conta — adicione frases inteiras quando quiser evitar correspondências dentro de palavras maiores e lembre-se de que entradas curtas podem corresponder a substrings indesejadas.

Uso

A filtragem de palavras proibidas não tem uma cota própria — assim como as verificações de texto, ela é executada como parte de uma chamada a /api/v2/check, e cada chamada conta uma vez no seu limite mensal de solicitações à API. Consulte Autenticação e chaves de API para saber como funcionam a cota e os limites de taxa.

Boas práticas

Combine com verificações baseadas em modelos

Use a lista personalizada para termos exatos, orientados por políticas, e deixe check_spam, check_sentiment e check_images lidarem com as categorias mais difusas. Uma única chamada a /check pode executar todas elas juntas — veja Análise de texto.

Aja com base nas palavras correspondentes

matched_words informa exatamente o que acionou o filtro, o que é útil para dar contexto aos moderadores e para ajustar sua lista:

const result = await check({ text }, { check_badwords: true });
const bad = result.results?.badwords;

if (bad?.hit) {
  await blockAndLog(text, bad.matched_words);
}

Revise a lista regularmente

Uma lista estática fica desatualizada conforme as comunidades e a linguagem mudam. Revise periodicamente quais entradas realmente disparam o filtro (a partir de matched_words nos seus logs) e remova aquelas que só geram falsos positivos.

Exemplo de integração

import os
import requests

def check_badwords(text):
    response = requests.post(
        'https://api.discuse.com/api/v2/check',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ['DISCUSE_API_KEY']
        },
        json={'content': {'text': text}, 'settings': {'check_badwords': True}}
    )
    return response.json()

Pronto para aplicar sua própria política de palavras? Comece com Discuse.