Use a blocklist with Azure OpenAI

The configurable content filters available in Azure OpenAI are sufficient for most content moderation needs. However, you might need to filter terms specific to your use case. For this, you can use custom blocklists.

Prerequisites

• An Azure subscription. Create one for free.
• Once you have your Azure subscription, create an Azure OpenAI resource in the Azure portal to get your token, key and endpoint. Enter a unique name for your resource, select the subscription you entered on the application form, select a resource group, supported region, and supported pricing tier. Then select Create.
  • The resource takes a few minutes to deploy. After it finishes, select go to resource. In the left pane, under Resource Management, select Subscription Key and Endpoint. The endpoint and either of the keys are used to call APIs.
• Azure CLI installed
• cURL installed

Use blocklists

Azure OpenAI API

You can create blocklists with the Azure OpenAI API. The following steps help you get started.

Get your token

First, you need to get a token for accessing the APIs for creating, editing and deleting blocklists. You can get this token using the following Azure CLI command:

Bash

az account get-access-token 

Create or modify a blocklist

Copy the cURL command below to a text editor and make the following changes:

1. Replace {subscriptionId} with your subscription ID.
2. Replace {resourceGroupName} with your resource group name.
3. Replace {accountName} with your resource name.
4. Replace {raiBlocklistName} (in the URL) with a custom name for your list. Allowed characters: 0-9, A-Z, a-z, - . _ ~.
5. Replace {token} with the token you got from the "Get your token" step above.
6. Optionally replace the value of the "description" field with a custom description.

Bash

curl --location --request PUT 'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/raiBlocklists/{raiBlocklistName}?api-version=2024-04-01-preview' \ 
--header 'Authorization: Bearer {token}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
    "properties": { 
        "description": "This is a prompt blocklist"  
    } 
}' 

The response code should be 201 (created a new list) or 200 (updated an existing list).

Apply a blocklist to a content filter

If you haven't yet created a content filter, you can do so in Azure AI Foundry. See Content filtering.

To apply a completion blocklist to a content filter, use the following cURL command:

1. Replace {subscriptionId} with your sub ID.
2. Replace {resourceGroupName} with your resource group name.
3. Replace {accountName} with your resource name.
4. Replace {raiPolicyName} with the name of your Content Filter
5. Replace {token} with the token you got from the "Get your token" step above.
6. Optionally change the "completionBlocklists" title to "promptBlocklists" if you want the blocklist to apply to user prompts instead of AI model completions.
7. Replace "raiBlocklistName" in the body with a custom name for your list. Allowed characters: 0-9, A-Z, a-z, - . _ ~.

Bash

curl --location --request PUT 'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/raiPolicies/{raiPolicyName}?api-version=2024-04-01-preview' \ 
--header 'Authorization: Bearer {token}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
    "properties": { 
        "basePolicyName": "Microsoft.Default", 
        "completionBlocklists": [{ 
            "blocklistName": "raiBlocklistName", 
            "blocking": true 
        }], 
        "contentFilters": [ ] 
    } 
}' 

Add blockItems to the list

Märkus

There is a maximum limit of 10,000 terms allowed in one list.

Copy the cURL command below to a text editor and make the following changes:

1. Replace {subscriptionId} with your sub ID.
2. Replace {resourceGroupName} with your resource group name.
3. Replace {accountName} with your resource name.
4. Replace {raiBlocklistName} (in the URL) with a custom name for your list. Allowed characters: 0-9, A-Z, a-z, - . _ ~.
5. Replace {raiBlocklistItemName} with a custom name for your list item.
6. Replace {token} with the token you got from the "Get your token" step above.
7. Replace the value of the "blocking pattern" field with the item you'd like to add to your blocklist. The maximum length of a blockItem is 1000 characters. Also specify whether the pattern is regex or exact match.

Bash

curl --location --request PUT 'https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/raiBlocklists/{raiBlocklistName}/raiBlocklistItems/{raiBlocklistItemName}?api-version=2024-04-01-preview' \ 
--header 'Authorization: Bearer {token}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{  
    "properties": {  
        "pattern": "blocking pattern",  
        "isRegex": false  
    }  
}' 

Märkus

It can take around 5 minutes for a new term to be added to the blocklist. Please test after 5 minutes.

The response code should be 200.

JSON

{ 
  "name": "raiBlocklistItemName", 
  "id": "/subscriptions/subscriptionId/resourceGroups/resourceGroupName/providers/Microsoft.CognitiveServices/accounts/accountName/raiBlocklists/raiBlocklistName/raiBlocklistItems/raiBlocklistItemName", 
  "properties": { 
    "pattern": "blocking pattern", 
    "isRegex": false 
  } 
} 

Analyze text with a blocklist

Now you can test out your deployment that has the blocklist. For instructions on calling the Azure OpenAI endpoints, visit the Quickstart.

In the below example, a GPT-35-Turbo deployment with a blocklist is blocking the prompt. The response returns a 400 error.

JSON

{ 
    "error": { 
        "message": "The response was filtered due to the prompt triggering Azure OpenAI’s content management policy. Please modify your prompt and retry. To learn more about our content filtering policies please read our documentation: https://go.microsoft.com/fwlink/?linkid=2198766", 
        "type": null, 
        "param": "prompt", 
        "code": "content_filter", 
        "status": 400, 
        "innererror": { 
            "code": "ResponsibleAIPolicyViolation", 
            "content_filter_result": { 
                "custom_blocklists": [ 
                    { 
                        "filtered": true, 
                        "id": "raiBlocklistName" 
                    } 
                ], 
                "hate": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "self_harm": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "sexual": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "violence": { 
                    "filtered": false, 
                    "severity": "safe" 
                } 
            } 
        } 
    } 
} 

If the completion itself is blocked, the response returns 200, as the completion only cuts off when the blocklist content is matched. The annotations show that a blocklist item was matched.

JSON

{ 
    "id": "chatcmpl-85NkyY0AkeBMunOjyxivQSiTaxGAl", 
    "object": "chat.completion", 
    "created": 1696293652, 
    "model": "gpt-35-turbo", 
    "prompt_filter_results": [ 
        { 
            "prompt_index": 0, 
            "content_filter_results": { 
                "hate": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "self_harm": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "sexual": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "violence": { 
                    "filtered": false, 
                    "severity": "safe" 
                } 
            } 
        } 
    ], 
    "choices": [ 
        { 
            "index": 0, 
            "finish_reason": "content_filter", 
            "message": { 
                "role": "assistant" 
            }, 
            "content_filter_results": { 
                "custom_blocklists": [ 
                    { 
                        "filtered": true, 
                        "id": "myBlocklistName" 
                    } 
                ], 
                "hate": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "self_harm": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "sexual": { 
                    "filtered": false, 
                    "severity": "safe" 
                }, 
                "violence": { 
                    "filtered": false, 
                    "severity": "safe" 
                } 
            } 
        } 
    ], 
    "usage": { 
        "completion_tokens": 75, 
        "prompt_tokens": 27, 
        "total_tokens": 102 
    } 
} 

Azure AI Foundry

Create a blocklist

1. Go to Azure AI Foundry and navigate to your project/hub. Then select the Safety+ Security page on the left nav and select the Blocklists tab.

   

2. Select Create a blocklist. Enter a name for your blocklist, add a description, and select an Azure OpenAI resource to connect it to. Then select Create Blocklist.

3. Select your new blocklist once it's created. On the blocklist's page, select Add new term.

4. Enter the term that should be filtered and select Add term. You can also use a regex. You can delete each term in your blocklist.

Attach a blocklist to a content filter configuration

1. Once the blocklist is ready, go back to the Safety+ Security page and select the Content filters tab. Create a new content filter configuration. This opens a wizard with several AI content safety components.

   

2. On the Input filter and Output filter screens, toggle the Blocklist button on. You can then select a blocklist from the list. There are two types of blocklists: the custom blocklists you created, and prebuilt blocklists that Microsoft provides—in this case a Profanity blocklist (English).

3. You can now decide which of the available blocklists you want to include in your content filtering configuration. The last step is to review and finish the content filtering configuration by selecting Next. You can always go back and edit your configuration. Once it’s ready, select a Create content filter. The new configuration that includes your blocklists can now be applied to a deployment.

Related content

• Learn more about Responsible AI practices for Azure OpenAI: Overview of Responsible AI practices for Azure OpenAI models.

• Read more about content filtering categories and severity levels with Azure OpenAI Service.

• Learn more about red teaming from our: Introduction to red teaming large language models (LLMs) article.