You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by yi...@apache.org on 2026/03/24 09:29:32 UTC
(apisix) branch docs-improve-ai-prompt-guard updated: update
This is an automated email from the ASF dual-hosted git repository.
yilialin pushed a commit to branch docs-improve-ai-prompt-guard
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/docs-improve-ai-prompt-guard by this push:
new 398b487d8 update
398b487d8 is described below
commit 398b487d86e3e02f265b25c69d1ba3cf423e053a
Author: Yilia Lin <yi...@163.com>
AuthorDate: Tue Mar 24 17:29:21 2026 +0800
update
---
docs/en/latest/plugins/ai-prompt-guard.md | 660 ++++++++++++++++++++++++++++--
1 file changed, 627 insertions(+), 33 deletions(-)
diff --git a/docs/en/latest/plugins/ai-prompt-guard.md b/docs/en/latest/plugins/ai-prompt-guard.md
index 51ec3c524..032765d48 100644
--- a/docs/en/latest/plugins/ai-prompt-guard.md
+++ b/docs/en/latest/plugins/ai-prompt-guard.md
@@ -5,7 +5,7 @@ keywords:
- API Gateway
- Plugin
- ai-prompt-guard
-description: This document contains information about the Apache APISIX ai-prompt-guard Plugin.
+description: The `ai-prompt-guard` Plugin safeguards your AI endpoints by inspecting and validating incoming prompt messages.
---
<!--
@@ -27,63 +27,657 @@ description: This document contains information about the Apache APISIX ai-promp
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-prompt-guard" />
+</head>
+
## Description
-The `ai-prompt-guard` plugin safeguards your AI endpoints by inspecting and validating incoming prompt messages. It checks the content of requests against user-defined allowed and denied patterns to ensure that only approved inputs are processed. Based on its configuration, the plugin can either examine just the latest message or the entire conversation history, and it can be set to check prompts from all roles or only from end users.
+The `ai-prompt-guard` Plugin safeguards your AI endpoints by inspecting and validating incoming prompt messages. It checks the content of requests against user-defined allowed and denied patterns to ensure that only approved inputs are processed. Based on its configuration, the Plugin can either examine just the latest message or the entire conversation history, and it can be set to check prompts from all roles or only from end users.
-When both **allow** and **deny** patterns are configured, the plugin first ensures that at least one allowed pattern is matched. If none match, the request is rejected with a _"Request doesn't match allow patterns"_ error. If an allowed pattern is found, it then checks for any occurrences of denied patterns—rejecting the request with a _"Request contains prohibited content"_ error if any are detected.
+When both **allow** and **deny** patterns are configured, the Plugin first ensures that at least one allowed pattern is matched. If none match, the request is rejected with a _"Request doesn't match allow patterns"_ error. If an allowed pattern is found, it then checks for any occurrences of denied patterns—rejecting the request with a _"Request contains prohibited content"_ error if any are detected.
## Plugin Attributes
| **Field** | **Required** | **Type** | **Description** |
| ------------------------------ | ------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| match_all_roles | No | boolean | If set to `true`, the plugin will check prompt messages from all roles. Otherwise, it only validates when its role is `"user"`. Default is `false`. |
-| match_all_conversation_history | No | boolean | When enabled, all messages in the conversation history are concatenated and checked. If `false`, only the content of the last message is examined. Default is `false`. |
-| allow_patterns | No | array | A list of regex patterns. When provided, the prompt must match **at least one** pattern to be considered valid. |
-| deny_patterns | No | array | A list of regex patterns. If any of these patterns match the prompt content, the request is rejected. |
+| match_all_roles | No | boolean | If true, validate messages from all roles. If false, validate the message from `user` role only. Default is `false`. |
+| match_all_conversation_history | No | boolean | If true, concatenate and check all messages in the conversation history. If false, only check the content of the last message. Default is `false`. |
+| allow_patterns | No | array | An array of RegEx patterns that messages should match. When configured, messages must match at least one pattern to be considered valid. |
+| deny_patterns | No | array | An array of RegEx patterns that messages should not match. If messages match any of the patterns, the request should be rejected. If both `allow_patterns` and `deny_patterns` are configured, the Plugin first ensures that at least one `allow_patterns` is matched. |
+
+## Examples
+
+The following examples will be using OpenAI as the upstream service provider. Before proceeding, create an [OpenAI account](https://openai.com) and an [API key](https://openai.com/blog/openai-api). You can optionally save the key to an environment variable as such:
+
+```shell
+export OPENAI_API_KEY=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 # replace with your API key
+```
+
+If you are working with other LLM providers, please refer to the provider's documentation to obtain an API key.
+
+### Implement Allow and Deny Patterns
+
+The following example demonstrates how to use the `ai-prompt-guard` Plugin to validate user prompts by defining both allow and deny patterns and understand how the allow pattern takes precedence.
+
+Define the allow and deny patterns. You can optionally save them to environment variables for easier escape:
+
+```shell
+# allow US dollar amount
+export ALLOW_PATTERN_1='\\$?\\(?\\d{1,3}(,\\d{3})*(\\.\\d{1,2})?\\)?'
+# deny phone number in US number format
+export DENY_PATTERN_1='(\\([0-9]{3}\\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+```
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
-## Example usage
+<TabItem value="admin-api">
-Create a route with the `ai-prompt-guard` plugin like so:
+Create a Route that uses `ai-proxy` to proxy to OpenAI and `ai-prompt-guard` to inspect input prompts:
```shell
-curl "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT \
- -H "X-API-KEY: ${ADMIN_API_KEY}" \
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
-d '{
- "uri": "/v1/chat/completions",
+ "id": "ai-prompt-guard-route",
+ "uri": "/anything",
+ "methods": ["POST"],
"plugins": {
+ # highlight-start
+ "ai-proxy": {
+ "provider": "openai",
+ "auth": {
+ "header": {
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
+ }
+ },
+ "options":{
+ "model": "gpt-4"
+ }
+ },
"ai-prompt-guard": {
- "match_all_roles": true,
- "allow_patterns": [
- "goodword"
- ],
+ "allow_patterns": [
+ "'"$ALLOW_PATTERN_1"'"
+ ],
"deny_patterns": [
- "badword"
+ "'"$DENY_PATTERN_1"'"
]
- }
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "api.openai.com:443": 1
- },
- "pass_host": "node",
- "scheme": "https"
+ }
+ # highlight-end
}
}'
```
-Now send a request:
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Route with the `ai-prompt-guard` and [`ai-proxy`](/hub/ai-proxy) Plugins configured as such:
+
+```yaml title="adc.yaml"
+services:
+ - name: prompt-guard-service
+ routes:
+ - name: prompt-guard-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+ options:
+ // Annotate 3
+ model: gpt-4
+ ai-prompt-guard:
+ allow_patterns:
+ // Annotate 4
+ - '\$?\(?\d{1,3}(,\d{3})*(\.\d{1,2})?\)?'
+ deny_patterns:
+ // Annotate 5
+ - '(\([0-9]{3}\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+Create a Route with the `ai-prompt-guard` and [`ai-proxy`](/hub/ai-proxy) Plugins configured as such:
+
+```yaml title="ai-prompt-guard-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-prompt-guard-plugin-config
+spec:
+ plugins:
+ - name: ai-prompt-guard
+ config:
+ allow_patterns:
+ // Annotate 1
+ - '\$?\(?\d{1,3}(,\d{3})*(\.\d{1,2})?\)?'
+ deny_patterns:
+ // Annotate 2
+ - '(\([0-9]{3}\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ // Annotate 3
+ Authorization: "Bearer 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"
+ options:
+ // Annotate 4
+ model: gpt-4
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: prompt-guard-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ method: POST
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: ai-prompt-guard-plugin-config
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-prompt-guard-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Route with the `ai-prompt-guard` and [`ai-proxy`](/hub/ai-proxy) Plugins configured as such:
+
+```yaml title="ai-prompt-guard-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: prompt-guard-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: prompt-guard-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-prompt-guard
+ enable: true
+ config:
+ allow_patterns:
+ - '\$?\(?\d{1,3}(,\d{3})*(\.\d{1,2})?\)?'
+ deny_patterns:
+ - '(\([0-9]{3}\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer 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"
+ options:
+ model: gpt-4
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-prompt-guard-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+Send a request to the Route to rate the fairness of a purchase:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase is at a decent price in USD." },
+ { "role": "user", "content": "John paid $12.5 for a hot brewed coffee in El Paso." }
+ ]
+ }'
+```
+
+You should see receive an `HTTP/1.1 200 OK` response similar to the following:
+
+```json
+{
+ ...
+ "model": "gpt-4-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ # highlight-next-line
+ "content": "The purchase is not at a decent price. Typically, a hot brewed coffee costs anywhere from $1 to $3 in most places in the US, so $12.5 is quite expensive.",
+ "refusal": null
+ },
+ "logprobs": null,
+ "finish_reason": "stop"
+ }
+ ],
+ ...
+}
+```
+
+Send another request to the Route without any price in the message:
```shell
-curl http://127.0.0.1:9080/v1/chat/completions -i -XPOST -H 'Content-Type: application/json' -d '{
- "model": "gpt-4",
- "messages": [{ "role": "user", "content": "badword request" }]
-}' -H "Authorization: Bearer <your token here>"
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase is at a decent price in USD." },
+ { "role": "user", "content": "John paid a bit for a hot brewed coffee in El Paso." }
+ ]
+ }'
```
-The request will fail with 400 error and following response.
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
-```bash
+```text
{"message":"Request doesn't match allow patterns"}
```
+
+Send a third request to the Route with a phone number in the message:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase is at a decent price in USD." },
+ { "role": "user", "content": "John (647-200-9393) paid $12.5 for a hot brewed coffee in El Paso." }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
+
+```text
+{"message":"Request contains prohibited content"}
+```
+
+By default, the Plugin only inspect the input of `user` role and the last message. For instance, if you send a request including the prohibited content in the `system` prompt:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase from 647-200-9393 is at a decent price in USD." },
+ { "role": "user", "content": "John paid $12.5 for a hot brewed coffee in El Paso." }
+ ]
+ }'
+```
+
+You will receive an `HTTP/1.1 200 OK` response.
+
+If you send a request including the prohibited content in the second last message:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase is at a decent price in USD." },
+ { "role": "user", "content": "Customer John contact: 647-200-9393" },
+ { "role": "user", "content": "John paid $12.5 for a hot brewed coffee in El Paso." }
+ ]
+ }'
+```
+
+You will also receive an `HTTP/1.1 200 OK` response.
+
+See the [next example](#validate-messages-from-all-roles-and-conversation-history) to see how to inspect messages from all roles and all messages.
+
+### Validate Messages From All Roles and Conversation History
+
+The following example demonstrates how to use the `ai-prompt-guard` Plugin to validate prompts from all roles, such as `system` and `user`, and validate the entire conversation history instead of the last message.
+
+Define the allow and deny patterns. You can optionally save them to environment variables for easier escape:
+
+```shell
+export ALLOW_PATTERN_1='\\$?\\(?\\d{1,3}(,\\d{3})*(\\.\\d{1,2})?\\)?'
+export DENY_PATTERN_1='(\\([0-9]{3}\\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+```
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
+Create a Route that uses `ai-proxy` to proxy to OpenAI and `ai-prompt-guard` to inspect input prompts:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ai-prompt-guard-route",
+ "uri": "/anything",
+ "methods": ["POST"],
+ "plugins": {
+ "ai-proxy": {
+ "provider": "openai",
+ "auth": {
+ "header": {
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
+ }
+ },
+ "options":{
+ "model": "gpt-4"
+ }
+ },
+ "ai-prompt-guard": {
+ "match_all_roles": true,
+ "match_all_conversation_history": true,
+ "allow_patterns": [
+ "'"$ALLOW_PATTERN_1"'"
+ ],
+ "deny_patterns": [
+ "'"$DENY_PATTERN_1"'"
+ ]
+ }
+ }
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Route with the `ai-prompt-guard` and [`ai-proxy`](/hub/ai-proxy) Plugins configured as such:
+
+```yaml title="adc.yaml"
+services:
+ - name: prompt-guard-service
+ routes:
+ - name: prompt-guard-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+ options:
+ model: gpt-4
+ ai-prompt-guard:
+ match_all_roles: true
+ match_all_conversation_history: true
+ allow_patterns:
+ - '\$?\(?\d{1,3}(,\d{3})*(\.\d{1,2})?\)?'
+ deny_patterns:
+ - '(\([0-9]{3}\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+Create a Route with the `ai-prompt-guard` and [`ai-proxy`](/hub/ai-proxy) Plugins configured as such:
+
+```yaml title="ai-prompt-guard-history-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-prompt-guard-plugin-config
+spec:
+ plugins:
+ - name: ai-prompt-guard
+ config:
+ match_all_roles: true
+ match_all_conversation_history: true
+ allow_patterns:
+ - '\$?\(?\d{1,3}(,\d{3})*(\.\d{1,2})?\)?'
+ deny_patterns:
+ - '(\([0-9]{3}\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer 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"
+ options:
+ model: gpt-4
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: prompt-guard-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ method: POST
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: ai-prompt-guard-plugin-config
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-prompt-guard-history-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Route with the `ai-prompt-guard` and [`ai-proxy`](/hub/ai-proxy) Plugins configured as such:
+
+```yaml title="ai-prompt-guard-history-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: prompt-guard-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: prompt-guard-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-prompt-guard
+ enable: true
+ config:
+ match_all_roles: true
+ match_all_conversation_history: true
+ allow_patterns:
+ - '\$?\(?\d{1,3}(,\d{3})*(\.\d{1,2})?\)?'
+ deny_patterns:
+ - '(\([0-9]{3}\)|[0-9]{3}-)[0-9]{3}-[0-9]{4}'
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer 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"
+ options:
+ model: gpt-4
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-prompt-guard-history-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+Send a request including with prohibited content in the `system` prompt:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase from 647-200-9393 is at a decent price in USD." },
+ { "role": "user", "content": "John paid $12.5 for a hot brewed coffee in El Paso." }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
+
+```text
+{"message":"Request contains prohibited content"}
+```
+
+Send a request with multiple messages from the same role with prohibited content:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase is at a decent price in USD." },
+ { "role": "user", "content": "Customer John contact: 647-200-9393" },
+ { "role": "user", "content": "John paid $12.5 for a hot brewed coffee in El Paso." }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
+
+```text
+{"message":"Request contains prohibited content"}
+```
+
+Send a request that conforms to the patterns:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "Rate if the purchase is at a decent price in USD." },
+ { "role": "system", "content": "The puchase is made in El Paso." },
+ { "role": "user", "content": "Customer John contact: xxx-xxx-xxxx" },
+ { "role": "user", "content": "John paid $12.5 for a hot brewed coffee." }
+ ]
+ }'
+```
+
+You should see receive an `HTTP/1.1 200 OK` response similar to the following:
+
+```json
+{
+ ...,
+ "model": "gpt-4-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": "$12.5 is generally considered quite expensive for a cup of brew coffee.",
+ "refusal": null
+ },
+ "logprobs": null,
+ "finish_reason": "stop"
+ }
+ ],
+ ...
+}
+```