How to use custom text libraries to manage content security - AI Guardrails

Content Moderation supports custom text libraries to align detection results more closely with your business needs. Custom text libraries apply to scenarios such as text violation detection in images, text anti-spam, file anti-spam, and voice anti-spam. You can use these libraries to manage text that you want to block, filter, or send for human review, helping you adapt to new moderation requirements.

Background

Important

Before using a custom text library, read this document carefully to understand how text libraries work. This helps prevent misconfigurations, such as adding improper keywords, which can lead to false positives and affect detection accuracy.

Custom text libraries include feedback-based text libraries and self-managed text libraries.

A feedback-based text library is automatically generated from your human review records and applies by default to all detection scenarios of the same type. You can manage the text in this library, but you cannot disable or delete the library itself. For more information about human review, see human review.
You create a self-managed text library to use for a specific detection or a category of detection scenarios. You can manage the text within it, as well as the library itself.

Note

You can create up to 10 self-managed text libraries. This limit does not include feedback-based text libraries.

This document describes how to manage custom text libraries in the Content Moderation console. In addition to using the console, you can also perform these operations by using APIs or SDKs. For more information, see the following documents:

Text types

A custom text library can contain two types of text: Text and similar text.

Text
A keyword is a specific short word or phrase used for content control. If a text contains a predefined keyword, it triggers a match. You can configure different keywords for different business scenarios.
In Content Moderation, you can use keywords in text violation detection in images and text anti-spam scenarios. Configurations may vary slightly across scenarios.
Chinese keywords support AND (&) and NOT (~) logical operators. For example:
- If you define "A&B", a match occurs only if the text contains both "A" and "B".
- If you define "A~B", a match occurs only if the text contains "A" but not "B". If the text contains both "A" and "B", a match is not triggered.
Note
The AND (&) operator must precede the NOT (~) operator. For example, you can set "A&B~C" as a keyword, but you cannot set "A~C&B".
Similar text
The similar text feature assesses the semantic similarity between sentences or paragraphs. Two pieces of text might have slight variations but convey the same overall meaning or describe the same event. The system checks if the scanned text is highly similar to predefined text samples. If the similarity score reaches a certain threshold, it triggers a match.
A similar text library is for the text anti-spam scenario. You can define a block list, trust list, and review list for your business. A review list contains text that requires human review. By maintaining relevant text samples in the library, you can guide the text anti-spam service to filter content that matches these samples.

Limitations

Type	Item	Limit
Text library	Number of libraries	Up to 10 self-managed text libraries.
Text library	Library name length	Up to 20 characters.
Keyword	Keyword type	You can use Chinese keywords. Letters and digits can be used as keywords. Note During detection, letters and digits are treated as a single token. English keywords are not supported.
Keyword	Number of keywords per library	Up to 10,000.
Keyword	Maximum keyword length	50 characters (including symbols).
Keyword	Chinese keyword encoding	UTF-8.
Keyword	Keyword format	Keywords cannot contain the following special characters in either full-width or half-width forms: `@ # $ % ^ * ( ) < > / ? , . ; _ + - = ' "`, space, and tab
Similar text	Similar text length	20 to 10,000 characters. Note To avoid false positives, we recommend keeping text to 200 characters or less.
Similar text	Number of similar text entries per library	Up to 10,000.
Similar text	Text encoding format	UTF-8.
Similar text	Similar text content	Text samples must contain distinct and extractable Chinese semantic features. If the analysis engine finds that a sample has too few features, the engine will ignore the sample. Note For example, a sample that consists only of meaningless letters, digits, or various emojis may be ignored.

Procedure

Log on to the Content Moderation console.
In the left-side navigation pane, choose Machine audit V1.0 > Risk Libraries.
On the Custom Text Library tab, click Create Text Library.

In the Create Custom Text Library dialog box, configure the parameters as described in Table 1, and then click OK.

Table 1. Parameters for creating a custom text library

Parameter	Description
Name	The name of the text library. Duplicate names are allowed, but we recommend using a unique name for your business.
Detection Scene	The use case for the text library. Valid values: Text Anti-spam: Applicable to text anti-spam (when the `scenes` parameter includes `antispam`). Texts or Objects on Image: Applicable to image moderation (when the `scenes` parameter includes `ad`).
Type	The type of text in the library. Valid values: Text: Uses keyword matching. Triggers a match if the content contains a keyword. This provides broad coverage. Similar Text: Uses text similarity matching. Triggers a match only if the entire segment of text is similar to a sample. This provides high precision. Note This option is available only when Detection Scene is set to Text Anti-spam.
Match Mode	When Type is set to Text, select the match mode for the library. Valid values: Precise: A match is triggered only if the scanned text contains content that is identical to a keyword in the library. Check after Preprocess Texts : Normalizes the scanned text and keywords before matching. The normalization logic is as follows: Uppercase letters are converted to lowercase. For example, if the input text is "bitCoin", it will match the keyword "bitcoin". Traditional Chinese characters are uniformly converted to Simplified Chinese characters. For example, if you enter the text "中國", it will match the keyword "中国". Visually similar characters are converted. For example, the input text "②" will match the keyword "2". Note For a similar text library, match after normalization is used by default.
Suggestion	The purpose of the text library. If Type is Text, valid values are: Block list: If a match is found, the automated review result is `suggestion=block`. Review List: If a match is found, the automated review result is `suggestion=review`. Filter List: Keywords in this list are ignored, but other content is still scanned. If Type is Similar Text, valid values are: Block list: If a match is found, the automated review result is `suggestion=block`. Review List: If a match is found, the automated review result is `suggestion=review`. Trust list: If a match is found, the automated review result is `suggestion=pass`.
BizType	The `BizType` parameter allows you to configure and apply different text libraries for different business requirements, such as specifying a text library for a specific detection. The logic is as follows: If you set `BizType` to "A" for a text library and also pass `BizType="A"` in your API request, the detection uses only enabled libraries with that `BizType`. Otherwise, the detection uses all enabled text libraries.

After you create the text library, it appears in the text library list.

Manage the content (keywords or similar text) in your text library.
The Custom Text Library list displays all your custom text libraries. A feedback-based text library is identified by a System tag and follows the naming format SCENE_FEEDBACK_WHITE/BLACK. For example, ANTISPAM_FEEDBACK_BLACK is a system-generated block list for the text anti-spam scenario.
1. Find the library you want to manage and click Modify in the Actions column.
2. On the Text Libraries page, manage the keywords in the library.
  The Text Libraries page displays all added keywords and the number of hits in the Detected in Last Seven Days column. This count excludes the current day.
  Note
  After you add or delete keywords, the changes take effect in about 15 minutes.
  - Click Add Keyword or Import and follow the on-screen instructions to add keywords to the library.
  - To remove keywords, select the ones you want to delete and click Batch Delete. You can also click Delete next to an individual keyword to remove it.

Related operations

For a self-managed text library, you can click Delete, Modify, or Disable in the Actions column on the Custom Text Library page to manage the library.