自定义文本库允许您将已知的风险或安全文本内容添加到黑名单或白名单，并在您调用内容检测API进行图片广告检测（ad）、文本反垃圾（antispam）、语音反垃圾（antispam）时，自动匹配文本库中的内容，满足突发性或个性化的管控需求，达到紧急止血的目的。本文介绍了使用自定义文本库的具体操作。

背景信息

自定义文本库支持两种文本类型：关键词和相似文本。您可以创建关键词文本库，用来管理关键词黑名单、忽略名单；或者创建相似文本文本库，用来管理相似文本黑名单、白名单及疑似名单。调用检测服务中，系统会根据黑名单、忽略名单、白名单及疑似名单的命中情况，返回相应的suggestion。

说明 如果您不清楚如何使用该功能，请通过工单咨询我们。不建议您随意添加关键词，因为可能导致误抓，使检测效果无法得到保障。

进行具体操作前，请先熟悉以下概念：

  • 关键词

    关键词是针对短小词语进行防控的一种方式。您可以将其理解为：一句话或者一段文本里面是否包含某个既定词语；当包含该词语时，则表明命中该关键词。不同的业务场景支持配置不同的关键词。

    在内容安全的识别中，关键词技术可以被应用到图片广告、文本反垃圾、语音反垃圾场景中，具体配置见对应场景中的使用描述（配置参数可能略有出入）。

  • 相似文本

    相似文本是针对句子或者段落式文本进行相似性判断的一种方式。您可以将其理解为：两句话或者两段文本，从句意上具有非常强的相似性，但又不是百分百一样；局部可能有变化，但是整体却具有相同的意思或者在描述同一件事情。通过既定或者参照的文本样本，可以判断要识别的文本是否与样本具有强相似性。当相似性的概率在一定程度上时，则表明命中样本。

    相似文本文本库适用于文本反垃圾的检测场景。通过定义自己业务的相似文本库黑名单、白名单、疑似名单（疑似名单是指业务上需要识别出来，且需要人工审核），并在相似文本库里面维护与您业务相关的文本样本，从而指导文本反垃圾识别去过滤命中相似文本样本的内容。

使用限制

类型 项目 限制
文本库 库个数 不超过10个。
文本库 库名长度 不超过20个字符。
关键词 关键词类型 仅支持中文关键词，支持用字母和数字作为关键词；暂不支持英文关键词。
说明 检测时，字母和数字会被当作整体进行分词。
关键词 单个文本库中关键词个数 不超过10000个。
关键词 关键词最大长度 50个字符（包括符号）。
关键词 中文关键词编码类型 UTF-8
关键词 关键词格式 不允许包含以下特殊字符（包括全角）：@ # $ % ^ * ( ) < > / ?, . ; _ + - = ‘ “ 空格 tab键
相似文本 相似文本长度 10~4000个字符。
说明 如果添加的文本过长，容易引起文本误抓。建议文本长度不要超过200个字符，具体情况可提工单咨询。
相似文本 单个文本库中相似文本个数 不超过10000个。
相似文本 文本编码格式 UTF-8
相似文本 相似文本内容 文本样本需要包含明确的可提取的中文语义特征。如果经过引擎分析特征数太少，该文本样本将不会生效，引擎将其直接忽略。
说明 如果一段样本都是无意义的字母数字，或各种表情符等，则可能被忽略。

关键词高级特性

中文关键词支持“与（&）”、“非（~）”的逻辑判断属性。例如：
  • 定义“你&我”，则只有在句子中同时出现“你”和“我”时，才会命中。
  • 定义“你~我”，则只有在句子中只出现“你”且不出现“我”时才会命中，同时出现“你”和“我”则不会命中。
说明 与（&）必须在非（~）之前。例如，您可以设置“你好&再见~他们”作为关键词，但不能设置“你好~他们&再见”作为关键词。

操作步骤

  1. 登录云盾内容安全控制台。
  2. 前往内容检测API > 风险库管理页面。
  3. 打开自定义文本库页签，并单击创建文本库。
    创建文本库
  4. 在创建自定义文本库对话框中，完成文本库配置，并单击确认。文本库的配置描述见下表。
    配置项 描述
    名称 为文本库命名。文本库名称允许重复，但建议您在业务中将其设置为唯一。
    使用场景 选择文本库的使用场景，取值：
    • 文本反垃圾
    • 语音反垃圾
    • 图片广告
    说明 该场景参数对应于API调用时通过scenes传入的参数。例如，假如该文本库适用于文本反垃圾，则使用场景选择文本反垃圾；那么，在您调用文本反垃圾或文件反垃圾检测时，都会默认匹配该文本库。 文本库支持启用/停用操作，如果文本库被停用，则文本库在检测时不会被使用。
    文本类型 选择文本库的文本类型，取值：
    • 关键词：使用关键词匹配，只要包含关键词就会命中，覆盖面大。
    • 相似文本：使用文本相似度匹配，只有整段文本相似才会命中，精确度高。
    匹配方式 文本类型为关键词时，选择文本库的匹配方式，取值：
    • 精确匹配：待检测文本中包括与库中的词完全一样的内容时才命中。
    • 模糊匹配：待检测文本以及关键词都会经过预处理，预处理后进行匹配。预处理的逻辑如下：
      • 字母大写统一转换为小写。例如，输入检测文本“bitCoin”，会命中关键词“bitcoin”。
      • 繁体中文统一转换为简体。例如，输入检测文本“中國”，会命中关键词“中国”。
      • 相似字转换。例如，输入检测文本“②”，会命中关键词“2”。
    识别结果 选择命中后的处理方式。
    • 文本类型为关键词时，取值：
      • 黑名单：当检测文本命中黑名单中的样本时，API检测请求返回的suggestion为block（拒绝）。
      • 忽略名单：当检测文本中包含了忽略名单中的样本时，该关键词即会被替换为空字符串，然后再进行检测（并非直接返回suggestion为pass）。
    • 文本类型为相似文本时，取值：
      • 黑名单：当检测文本与黑名单中的文本内容相似时，API检测请求返回的suggestion为block（拒绝）。
      • 疑似名单：当检测文本与疑似名单中的文本内容相似时，API检测请求返回的suggestion为review（审核）。
      • 白名单：当检测的文本与白名单中的文本内容相似时，API检测请求返回的suggestion为pass（通过）。
    BizType BizType属于高级功能，目的是能够根据不同的业务需求配置不同的文本库，请根据需要进行设置（建议通过工单联系我们指导配置）。BizType生效逻辑如下：
    • 文本库设置BizType为“A”，且API检测请求中传递了biztype为“A”，则检测文本只会使用biztype为“A”的文本库（前提是库已开启）。
    • 其他情况下，检测文本均会使用所有已开启的文本库。

    创建自定义文本库
    成功创建文本库。您可以在文本库列表中看到新建的文本库。
  5. 可选： 若新建的文本库的文本类型是关键词，参照以下步骤管理关键词。
    1. 定位到目标（关键词）文本库，单击其操作列下的管理。
    2. 在文本库管理页面，维护文本库内的关键词：
      • 单击新增关键词或导入，按照页面提示在文本库中增加关键词。
        说明 已添加的关键词，您可以查看其最近7天命中次数（不包括当天的命中数据）。
      • 勾选不需要的关键词，单击批量删除，删除关键词；也可以单击不需要的关键词下的删除，单独将其删除。

      在文本库新增、删除关键词后，系统大约在10分钟左右生效。

  6. 可选： 若新建的文本库的文本类型是相似文本，参照以下步骤管理相似文本。
    1. 定位到目标（相似文本）文本库，单击其操作列下的管理。
    2. 在文本库管理页面，维护文本库内的相似文本：
      • 单击新增文本或导入，按照页面提示在文本库中增加相似文本。
        说明 已添加的相似文本，您可以查看其最近7天命中次数（不包括当天的命中数据）。
      • 勾选不需要的相似文本，单击批量删除，删除相似文本；也可以单击不需要的相似文本下的删除，单独将其删除。

      在文本库新增、删除相似文本后，系统大约在1分钟左右生效。

  7. 启用与停用文本库。回到文本库列表，选择对应文本库，单击其操作列下的启用或停用，可以根据实际需求启用或者停用文本库。
  8. 删除与修改文本库。回到文本库列表，选择对应文本库，单击其操作列下的删除和修改，可以分别删除目标文本库和修改目标文本库的配置。

自定义文本库API与SDK

我们同时提供了操作自定义词库（关键词库/相似文本库）的API接口与部分语言的SDK，供您直接将文本库管理功能集成到自己的业务平台中。具体包含以下接口：