Filtrado de palabras prohibidas

El filtrado de palabras prohibidas detecta en el texto tu propia lista de palabras no permitidas. A diferencia del spam o el sentimiento —que usan modelos entrenados—, esta comprobación compara el texto con una lista de palabras personalizada que configuras para tu proyecto, de modo que tú decides exactamente qué términos están prohibidos. Actívalo con check_badwords en POST /api/v2/check.

¿Cuándo debería usar una lista de palabras personalizada?

Los modelos son excelentes para categorías difusas como la toxicidad, pero algunos términos son decisiones de política que solo tú puedes tomar: el nombre de un competidor, un producto prohibido, insultos específicos de una comunidad, patrones de credenciales filtradas o palabras que tu equipo legal exige bloquear. Una lista personalizada te ofrece una coincidencia exacta y predecible para esos casos.

¿Cómo funciona?

El filtrado de palabras prohibidas se ejecuta solo cuando se cumplen dos condiciones: check_badwords está activado y tu proyecto tiene configurada una lista de palabras personalizada. Después realiza una búsqueda de subcadenas sin distinguir entre mayúsculas y minúsculas de cada palabra de la lista en el texto del mensaje, y devuelve todas las palabras que haya encontrado.

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
    }
  }'

Respuesta

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

El objeto results.badwords tiene tres campos:

Campo	Tipo	Descripción
hit	boolean	Verdadero si se encontró alguna palabra de la lista
matched_words	string[]	Las palabras configuradas que coincidieron con el texto
apply_penalty	boolean	Si la coincidencia debe activar tu medida de aplicación (siempre true cuando hay una coincidencia)

¿Cómo configuro la lista de palabras?

La lista forma parte de la configuración de tu proyecto, no de la solicitud: la defines una vez y cada solicitud con check_badwords la utiliza. Adminístrala desde la configuración de tu proyecto (el mismo lugar donde defines las comprobaciones predeterminadas). Como la solicitud solo incluye el interruptor check_badwords, puedes mantener tu lista de palabras en privado y modificarla sin tocar el código del cliente.

Si check_badwords está activado pero tu proyecto no tiene palabras configuradas, la comprobación se omite y no se devuelve ningún resultado de badwords.

¿Qué tipo de coincidencia utiliza?

La coincidencia es una búsqueda de subcadenas sin distinguir entre mayúsculas y minúsculas: una palabra incluida en la lista como spam coincide con spam, SPAM y también con spammer. Elige las entradas de la lista teniendo esto en cuenta: añade frases completas cuando quieras evitar coincidencias dentro de palabras más largas, y recuerda que las entradas cortas pueden coincidir con subcadenas no deseadas.

Uso

El filtrado de palabras prohibidas no tiene su propia cuota: al igual que las comprobaciones de texto, se ejecuta como parte de una llamada a /api/v2/check, y cada llamada cuenta una vez para tu límite mensual de solicitudes de API. Consulta Autenticación y claves de API para saber cómo funcionan la cuota y los límites de frecuencia.

Buenas prácticas

Combínalo con comprobaciones basadas en modelos

Usa la lista personalizada para términos exactos definidos por tus políticas y deja que check_spam, check_sentiment y check_images se encarguen de las categorías difusas. Una sola llamada a /check puede ejecutarlas todas juntas; consulta Análisis de texto.

Actúa según las palabras coincidentes

matched_words te indica exactamente qué activó el filtro, lo que resulta útil para dar contexto a los moderadores y para ajustar tu lista:

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

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

Revisa la lista con regularidad

Una lista estática se queda obsoleta a medida que las comunidades y el lenguaje cambian. Revisa periódicamente qué entradas se activan realmente (a partir de matched_words en tus registros) y elimina las que solo generen falsos positivos.

Ejemplo de integración

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()

¿Listo para aplicar tu propia política de palabras? Empieza con Discuse.