禁用词过滤

禁用词过滤会在文本中检测你自己列出的不允许使用的词。它不同于垃圾内容或情感分析——后两者使用训练好的模型——这项检查会根据你为项目配置的自定义词表进行匹配，因此哪些词属于禁止范围完全由你决定。在 POST /api/v2/check 中通过 check_badwords 启用它。

什么时候应该使用自定义词表？

模型很擅长识别有害性这类模糊类别，但有些词属于只能由你来决定的策略问题：竞争对手名称、被禁产品、特定社区的歧视性称呼、泄露凭据的模式，或法务团队要求你屏蔽的词。自定义词表可以为这些内容提供精确且可预测的匹配。

它是如何工作的？

只有在同时满足两个条件时，禁用词过滤才会运行：已启用 check_badwords，并且你的项目配置了自定义词表。随后，它会对消息文本中的每个已列词进行不区分大小写的子字符串匹配，并返回找到的所有词。

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

响应

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

results.badwords 对象包含三个字段：

字段	类型	说明
`hit`	boolean	如果找到任何已列词，则为 True
`matched_words`	string[]	与文本匹配的已配置词
`apply_penalty`	boolean	该匹配是否应触发你的处置措施（匹配时始终为 `true`）

如何配置词表？

词表是项目设置的一部分，而不是请求的一部分——你只需设置一次，之后每个 check_badwords 请求都会使用它。请在项目设置中管理它（也就是设置默认检查的同一位置）。由于请求只携带 check_badwords 开关，你可以保持词表私密，并且无需修改客户端代码即可更新它。

如果开启了 check_badwords，但你的项目没有配置任何词，则会跳过该检查，并且不会返回 badwords 结果。

它使用哪种匹配方式？

匹配方式是不区分大小写的子字符串搜索：已列词 spam 会匹配 spam、SPAM，也会匹配 spammer。选择词表条目时请考虑这一点——如果你想避免匹配到较长单词内部的内容，可以添加完整短语；同时请记住，较短的条目可能会匹配到非预期的子字符串。

使用方式

禁用词过滤没有单独的配额——和文本检查一样，它作为 /api/v2/check 调用的一部分运行，每次调用都会计入你每月的 API 请求额度。请参阅身份验证和 API 密钥，了解配额和速率限制的工作方式。

最佳实践

与基于模型的检查结合使用

将自定义词表用于精确的、由策略驱动的术语，并让 check_spam、check_sentiment 和 check_images 处理模糊类别。一次 /check 调用可以同时运行它们——请参阅文本分析。

根据匹配到的词采取行动

matched_words 会告诉你具体是什么触发了过滤器，这对审核员了解上下文以及调整词表都很有用：

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

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

定期审查词表

随着社区和语言的变化，静态词表会逐渐过时。请定期审查哪些条目实际触发了过滤（来自日志中的 matched_words），并清理那些只会造成误报的条目。

集成示例

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