You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "Yilialinn (via GitHub)" <gi...@apache.org> on 2026/04/07 09:14:55 UTC
[PR] docs: update ai-aliyun-content-moderation plugin documentation [apisix]
Yilialinn opened a new pull request, #13167:
URL: https://github.com/apache/apisix/pull/13167
## Summary
- Update EN and ZH plugin docs for `ai-aliyun-content-moderation` based on API7 docs source
- Add canonical link to API7 docs
- Add comprehensive attribute table with all fields from plugin Lua schema, including `keepalive`, `keepalive_pool`, `keepalive_timeout` fields
- Add detailed descriptions and chunking behavior for length limits
- Add two rich examples: Moderate Request Content Toxicity and Adjust Risk Level Threshold
- Replace hardcoded `ADMIN_API_KEY` with `admin_key` variable and add the note block
- Fix attribute types and defaults to match plugin source code (e.g. `deny_message` type was wrong in API7 config, `ssl_verify` is optional not required)
- Follow APISIX doc conventions (`True`/`False` for Required, lowercase types)
Ref: https://github.com/api7/docs/issues/892
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update ai-aliyun-content-moderation plugin documentation [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn merged PR #13167:
URL: https://github.com/apache/apisix/pull/13167
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update ai-aliyun-content-moderation plugin documentation [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn commented on code in PR #13167:
URL: https://github.com/apache/apisix/pull/13167#discussion_r3116725559
##########
docs/en/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,646 @@ description: This document contains information about the Apache APISIX ai-aliyu
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
-The `ai-aliyun-content-moderation` plugin integrates with Aliyun's content moderation service to check both request and response content for inappropriate material when working with LLMs. It supports both real-time streaming checks and final packet moderation.
-
-This plugin must be used in routes that utilize the ai-proxy or ai-proxy-multi plugins.
-
-## Plugin Attributes
-
-| **Field** | **Required** | **Type** | **Description** |
-| ---------------------------- | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | Yes | String | Aliyun service endpoint URL |
-| region_id | Yes | String | Aliyun region identifier |
-| access_key_id | Yes | String | Aliyun access key ID |
-| access_key_secret | Yes | String | Aliyun access key secret |
-| check_request | No | Boolean | Enable request content moderation. Default: `true` |
-| check_response | No | Boolean | Enable response content moderation. Default: `false` |
-| stream_check_mode | No | String | Streaming moderation mode. Default: `"final_packet"`. Valid values: `["realtime", "final_packet"]` |
-| stream_check_cache_size | No | Integer | Max characters per moderation batch in realtime mode. Default: `128`. Must be `>= 1`. |
-| stream_check_interval | No | Number | Seconds between batch checks in realtime mode. Default: `3`. Must be `>= 0.1`. |
-| request_check_service | No | String | Aliyun service for request moderation. Default: `"llm_query_moderation"` |
-| request_check_length_limit | No | Number | Max characters per request moderation chunk. Default: `2000`. |
-| response_check_service | No | String | Aliyun service for response moderation. Default: `"llm_response_moderation"` |
-| response_check_length_limit | No | Number | Max characters per response moderation chunk. Default: `5000`. |
-| risk_level_bar | No | String | Threshold for content rejection. Default: `"high"`. Valid values: `["none", "low", "medium", "high", "max"]` |
-| deny_code | No | Number | HTTP status code for rejected content. Default: `200`. |
-| deny_message | No | String | Custom message for rejected content. Default: `-`. |
-| timeout | No | Integer | Request timeout in milliseconds. Default: `10000`. Must be `>= 1`. |
-| ssl_verify | No | Boolean | Enable SSL certificate verification. Default: `true`. |
-
-## Example usage
-
-First initialise these shell variables:
+The `ai-aliyun-content-moderation` Plugin integrates with [Aliyun Machine-Assisted Moderation Plus](https://help.aliyun.com/document_detail/2671445.html) to check request and response content for risk level when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold.
+
+Please ensure that the `access_key_secret` is correctly configured in the Plugin. If misconfigured, all requests will bypass the Plugin to be directly forwarded to the LLM Upstream, and you will see a `Specified signature is not matched with our calculation` error in the gateway's error log from the Plugin.
Review Comment:
Fixed — softened the wording to say the moderation check fails and the request may still be forwarded upstream, rather than implying it is an intentional bypass mode.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update ai-aliyun-content-moderation plugin documentation [apisix]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13167:
URL: https://github.com/apache/apisix/pull/13167#discussion_r3076973714
##########
docs/zh/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: 本文档包含有关 Apache APISIX ai-aliyun-content-moderation
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`ai-aliyun-content-moderation` 插件集成了阿里云的内容审核服务，用于在与大语言模型 (LLM) 交互时检查请求和响应内容是否包含不当材料。它支持实时流式检查和最终数据包审核两种模式。
-
-此插件必须在使用 `ai-proxy` 或 `ai-proxy-multi` 插件的路由中使用。
-
-## 插件属性
-
-| **字段** | **必选项** | **类型** | **描述** |
-| ---------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | 是 | String | 阿里云服务端点 URL |
-| region_id | 是 | String | 阿里云区域标识符 |
-| access_key_id | 是 | String | 阿里云访问密钥 ID |
-| access_key_secret | 是 | String | 阿里云访问密钥密码 |
-| check_request | 否 | Boolean | 启用请求内容审核。默认值：`true` |
-| check_response | 否 | Boolean | 启用响应内容审核。默认值：`false` |
-| stream_check_mode | 否 | String | 流式审核模式。默认值：`"final_packet"`。有效值：`["realtime", "final_packet"]` |
-| stream_check_cache_size | 否 | Integer | 实时模式下每次审核批次的最大字符数。默认值：`128`。必须 `>= 1` |
-| stream_check_interval | 否 | Number | 实时模式下批次检查之间的间隔秒数。默认值：`3`。必须 `>= 0.1` |
-| request_check_service | 否 | String | 用于请求审核的阿里云服务。默认值：`"llm_query_moderation"` |
-| request_check_length_limit | 否 | Number | 每个请求审核块的最大字符数。默认值：`2000` |
-| response_check_service | 否 | String | 用于响应审核的阿里云服务。默认值：`"llm_response_moderation"` |
-| response_check_length_limit | 否 | Number | 每个响应审核块的最大字符数。默认值：`5000` |
-| risk_level_bar | 否 | String | 内容拒绝的阈值。默认值：`"high"`。有效值：`["none", "low", "medium", "high", "max"]` |
-| deny_code | 否 | Number | 被拒绝内容的 HTTP 状态码。默认值：`200` |
-| deny_message | 否 | String | 被拒绝内容的自定义消息。默认值：`-` |
-| timeout | 否 | Integer | 请求超时时间（毫秒）。默认值：`10000`。必须 `>= 1` |
-| ssl_verify | 否 | Boolean | 启用 SSL 证书验证。默认值：`true` |
-
-## 使用示例
-
-首先初始化这些 shell 变量：
+`ai-aliyun-content-moderation` 插件集成了[阿里云机器辅助审核 Plus](https://help.aliyun.com/document_detail/2671445.html)，用于在代理 LLM 请求时检查请求和响应内容的风险等级，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，当评估结果超过配置的阈值时拒绝请求。
+
+请确保在插件中正确配置 `access_key_secret`。如果配置错误，所有请求将绕过插件直接转发到 LLM 上游，并且您将在网关的错误日志中看到来自插件的 `Specified signature is not matched with our calculation` 错误。
+
+`ai-aliyun-content-moderation` 插件应与 [`ai-proxy`](./ai-proxy.md) 或 [`ai-proxy-multi`](./ai-proxy-multi.md) 插件配合使用以代理 LLM 请求。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| access_key_id | string | True | | | 阿里云访问密钥 ID。 |
+| access_key_secret | string | True | | | 阿里云访问密钥。该值在存储到 etcd 之前会使用 AES 加密。 |
+| region_id | string | True | | | 阿里云区域 ID。 |
+| endpoint | string | True | | | 阿里云端点。 |
+| check_request | boolean | False | `true` | | 如果为 `true`，则审核请求内容。 |
+| check_response | boolean | False | `false` | | 如果为 `true`，则审核响应内容。 |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`、`final_packet` | 流式审核模式。`realtime`：流式传输期间批量检查。`final_packet`：在最后附加风险等级。 |
+| stream_check_cache_size | integer | False | `128` | >= 1 | `realtime` 模式下每次审核批次的最大字符数。 |
+| stream_check_interval | number | False | `3` | >= 0.1 | `realtime` 模式下批次检查之间的间隔秒数。 |
+| request_check_service | string | False | `"llm_query_moderation"` | | 用于请求审核的阿里云服务。 |
+| request_check_length_limit | number | False | `2000` | | 请求内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果请求内容有 250 个字符，且 `request_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| response_check_service | string | False | `"llm_response_moderation"` | | 用于响应审核的阿里云服务。 |
+| response_check_length_limit | number | False | `5000` | | 响应内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果响应内容有 250 个字符，且 `response_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| risk_level_bar | string | False | `"high"` | `none`、`low`、`medium`、`high`、`max` | 如果评估的风险等级低于 `risk_level_bar`，请求或响应将分别被放行到上游 LLM 或客户端。 |
+| deny_code | number | False | `200` | | 拒绝时的 HTTP 状态码。 |
+| deny_message | string | False | | | 拒绝时的消息。 |
+| timeout | integer | False | `10000` | >= 1 | 超时时间（毫秒）。 |
+| keepalive | boolean | False | `true` | | 如果为 `true`，启用到阿里云的 HTTP 连接保活。 |
+| keepalive_pool | integer | False | `30` | >= 1 | 连接保活池的最大连接数。 |
+| keepalive_timeout | integer | False | `60000` | >= 1000 | 连接保活超时时间（毫秒）。 |
+| ssl_verify | boolean | False | `true` | | 如果为 `true`，启用 SSL 证书验证。 |
+
+## 示例
+
+以下示例使用 OpenAI 作为上游服务提供商。在开始之前，请创建一个 [OpenAI 账号](https://openai.com) 并获取 [API 密钥](https://openai.com/blog/openai-api)。如果您使用其他 LLM 提供商，请参考相应提供商的文档获取 API 密钥。
+
+此外，创建一个[阿里云账号](https://www.aliyun.com)，开通机器辅助审核 Plus 服务，并获取端点、区域 ID、访问密钥 ID 和访问密钥。
+
+:::note
+
+您可以使用以下命令从 `config.yaml` 中获取 `admin_key` 并保存到环境变量中：
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+您可以选择将阿里云和 OpenAI 信息保存到环境变量：
```shell
-ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1
-ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
-ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
-ALIYUN_REGION=cn-hangzhou
-ALIYUN_ENDPOINT=https://green.cn-hangzhou.aliyuncs.com
-OPENAI_KEY=your-openai-api-key
+# 替换为您的数据
+export OPENAI_API_KEY=your-openai-api-key
+export ALIYUN_ENDPOINT=https://green-cip.cn-shanghai.aliyuncs.com
+export ALIYUN_REGION_ID=cn-shanghai
+export ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
+export ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
```
-创建一个带有 `ai-aliyun-content-moderation` 和 `ai-proxy` 插件的路由：
+### 审核请求内容毒性
+
+以下示例演示如何使用该插件审核请求中的内容毒性并自定义拒绝代码和消息。
+
+<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">
+
+创建一个路由到 LLM 聊天补全端点，使用 [`ai-proxy`](./ai-proxy.md) 插件，并在 `ai-aliyun-content-moderation` 插件中配置集成详情以及 `deny_code` 和 `deny_message`：
```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-aliyun-content-moderation-route",
+ "uri": "/anything",
"plugins": {
+ "ai-aliyun-content-moderation": {
+ "endpoint": "'"$ALIYUN_ENDPOINT"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
+ "access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
+ "access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
+ "deny_code": 400,
+ "deny_message": "Request contains forbidden content, such as hate speech or violence."
+ },
"ai-proxy": {
"provider": "openai",
"auth": {
"header": {
- "Authorization": "Bearer '"$OPENAI_KEY"'"
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
}
- },
- "override": {
- "endpoint": "http://localhost:6724/v1/chat/completions"
}
+ }
+ }
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+```
+
+将配置同步到网关：
+
+```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">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+向该路由发送一个 POST 请求，请求体中包含系统提示和一个含有不当用语的用户问题：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "gpt-4",
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+您应该收到 `HTTP/1.1 400 Bad Request` 响应并看到以下消息：
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
},
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+向该路由发送另一个包含正常问题的请求：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "What is 1+1?" }
+ ]
+ }'
+```
+
+您应该收到 `HTTP/1.1 200 OK` 响应和模型输出：
+
+```json
+{
+ "model": "gpt-4-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": "1+1 equals 2.",
+ "refusal": null
+ },
+ "logprobs": null,
+ "finish_reason": "stop"
+ }
+ ]
+}
+```
+
+### 调整风险等级阈值
+
+以下示例演示如何调整风险等级的阈值，该阈值用于控制请求或响应是否应被放行。
+
+<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">
+
+创建一个路由到 LLM 聊天补全端点，使用 [`ai-proxy`](./ai-proxy.md) 插件，并将 `ai-aliyun-content-moderation` 中的 `risk_level_bar` 配置为 `high`：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ai-aliyun-content-moderation-route",
+ "uri": "/anything",
+ "plugins": {
"ai-aliyun-content-moderation": {
"endpoint": "'"$ALIYUN_ENDPOINT"'",
- "region_id": "'"$ALIYUN_REGION"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
"access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
"access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
- "risk_level_bar": "high",
- "check_request": true,
- "check_response": true,
"deny_code": 400,
- "deny_message": "您的请求违反了内容政策"
+ "deny_message": "Request contains forbidden content, such as hate speech or violence.",
+ "risk_level_bar": "high"
+ },
+ "ai-proxy": {
+ "provider": "openai",
+ "auth": {
+ "header": {
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
+ }
+ },
+ "model": "gpt-4"
Review Comment:
In this Admin API example, `ai-proxy` is configured with a top-level `model` field, but the plugin schema uses `options.model` (as shown in the ADC example below and in `docs/zh/latest/plugins/ai-proxy.md`). With the current config, the model may be ignored and requests without a `model` in the body will fail upstream. Please move this to `options: { model: "gpt-4" }` (or keep `model` in every request body).
```suggestion
"options": {
"model": "gpt-4"
}
```
##########
docs/en/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: This document contains information about the Apache APISIX ai-aliyu
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
-The `ai-aliyun-content-moderation` plugin integrates with Aliyun's content moderation service to check both request and response content for inappropriate material when working with LLMs. It supports both real-time streaming checks and final packet moderation.
-
-This plugin must be used in routes that utilize the ai-proxy or ai-proxy-multi plugins.
-
-## Plugin Attributes
-
-| **Field** | **Required** | **Type** | **Description** |
-| ---------------------------- | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | Yes | String | Aliyun service endpoint URL |
-| region_id | Yes | String | Aliyun region identifier |
-| access_key_id | Yes | String | Aliyun access key ID |
-| access_key_secret | Yes | String | Aliyun access key secret |
-| check_request | No | Boolean | Enable request content moderation. Default: `true` |
-| check_response | No | Boolean | Enable response content moderation. Default: `false` |
-| stream_check_mode | No | String | Streaming moderation mode. Default: `"final_packet"`. Valid values: `["realtime", "final_packet"]` |
-| stream_check_cache_size | No | Integer | Max characters per moderation batch in realtime mode. Default: `128`. Must be `>= 1`. |
-| stream_check_interval | No | Number | Seconds between batch checks in realtime mode. Default: `3`. Must be `>= 0.1`. |
-| request_check_service | No | String | Aliyun service for request moderation. Default: `"llm_query_moderation"` |
-| request_check_length_limit | No | Number | Max characters per request moderation chunk. Default: `2000`. |
-| response_check_service | No | String | Aliyun service for response moderation. Default: `"llm_response_moderation"` |
-| response_check_length_limit | No | Number | Max characters per response moderation chunk. Default: `5000`. |
-| risk_level_bar | No | String | Threshold for content rejection. Default: `"high"`. Valid values: `["none", "low", "medium", "high", "max"]` |
-| deny_code | No | Number | HTTP status code for rejected content. Default: `200`. |
-| deny_message | No | String | Custom message for rejected content. Default: `-`. |
-| timeout | No | Integer | Request timeout in milliseconds. Default: `10000`. Must be `>= 1`. |
-| ssl_verify | No | Boolean | Enable SSL certificate verification. Default: `true`. |
-
-## Example usage
-
-First initialise these shell variables:
+The `ai-aliyun-content-moderation` Plugin integrates with [Aliyun Machine-Assisted Moderation Plus](https://help.aliyun.com/document_detail/2671445.html) to check request and response content for risk level when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold.
+
+Please ensure that the `access_key_secret` is correctly configured in the Plugin. If misconfigured, all requests will bypass the Plugin to be directly forwarded to the LLM Upstream, and you will see a `Specified signature is not matched with our calculation` error in the gateway's error log from the Plugin.
+
+The `ai-aliyun-content-moderation` Plugin should be used with either [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests.
+
+## Attributes
+
+| Name | Type | Required | Default | Valid Values | Description |
+|------|------|----------|---------|--------------|-------------|
+| access_key_id | string | True | | | Aliyun access key ID. |
+| access_key_secret | string | True | | | Aliyun secret access key. The value is encrypted with AES before being stored in etcd. |
+| region_id | string | True | | | Aliyun region ID. |
+| endpoint | string | True | | | Aliyun endpoint. |
+| check_request | boolean | False | `true` | | If `true`, moderate the request content. |
+| check_response | boolean | False | `false` | | If `true`, moderate the response content. |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`, `final_packet` | Streaming moderation mode. `realtime`: batched checks during streaming. `final_packet`: append risk level at the end. |
+| stream_check_cache_size | integer | False | `128` | >= 1 | Maximum characters per moderation batch in `realtime` mode. |
+| stream_check_interval | number | False | `3` | >= 0.1 | Seconds between batch checks in `realtime` mode. |
+| request_check_service | string | False | `"llm_query_moderation"` | | Aliyun service for request moderation. |
+| request_check_length_limit | number | False | `2000` | | Request content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the request content has 250 characters and the `request_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
+| response_check_service | string | False | `"llm_response_moderation"` | | Aliyun service for response moderation. |
+| response_check_length_limit | number | False | `5000` | | Response content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the response content has 250 characters and the `response_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
+| risk_level_bar | string | False | `"high"` | `none`, `low`, `medium`, `high`, `max` | If the evaluated risk level is lower than the `risk_level_bar`, the request or response will be passed through to Upstream LLM or client respectively. |
+| deny_code | number | False | `200` | | Rejection HTTP status code. |
+| deny_message | string | False | | | Rejection message. |
+| timeout | integer | False | `10000` | >= 1 | Timeout in milliseconds. |
+| keepalive | boolean | False | `true` | | If `true`, enable HTTP connection keepalive to Aliyun. |
+| keepalive_pool | integer | False | `30` | >= 1 | Maximum number of connections in the keepalive pool. |
+| keepalive_timeout | integer | False | `60000` | >= 1000 | Keepalive timeout in milliseconds. |
+| ssl_verify | boolean | False | `true` | | If `true`, enable SSL certificate verification. |
+
+## Examples
+
+The following examples use OpenAI as the Upstream service provider. Before proceeding, create an [OpenAI account](https://openai.com) and obtain an [API key](https://openai.com/blog/openai-api). If you are working with other LLM providers, please refer to the provider's documentation to obtain an API key.
+
+Additionally, create an [Aliyun account](https://www.aliyun.com), enable Machine-Assisted Moderation Plus, and obtain the endpoint, region ID, access key ID, and access key secret.
+
+:::note
+
+You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+You can optionally save the Aliyun and OpenAI information to environment variables:
```shell
-ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1
-ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
-ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
-ALIYUN_REGION=cn-hangzhou
-ALIYUN_ENDPOINT=https://green.cn-hangzhou.aliyuncs.com
-OPENAI_KEY=your-openai-api-key
+# Replace with your data
+export OPENAI_API_KEY=your-openai-api-key
+export ALIYUN_ENDPOINT=https://green-cip.cn-shanghai.aliyuncs.com
+export ALIYUN_REGION_ID=cn-shanghai
+export ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
+export ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
```
-Create a route with the `ai-aliyun-content-moderation` and `ai-proxy` plugin like so:
+### Moderate Request Content Toxicity
+
+The following example demonstrates how you can use the Plugin to moderate content toxicity in requests and customize the rejection code and message.
+
+<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 to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the integration details as well as the `deny_code` and `deny_message` in the `ai-aliyun-content-moderation` Plugin:
```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-aliyun-content-moderation-route",
+ "uri": "/anything",
"plugins": {
+ "ai-aliyun-content-moderation": {
+ "endpoint": "'"$ALIYUN_ENDPOINT"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
+ "access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
+ "access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
+ "deny_code": 400,
+ "deny_message": "Request contains forbidden content, such as hate speech or violence."
+ },
"ai-proxy": {
"provider": "openai",
"auth": {
"header": {
- "Authorization": "Bearer '"$OPENAI_KEY"'"
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
}
- },
- "override": {
- "endpoint": "http://localhost:6724/v1/chat/completions"
}
+ }
+ }
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+```
+
+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-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+Send a POST request to the Route with a system prompt and a user question with a profane word in the request body:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "gpt-4",
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
},
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+Send another request to the Route with a typical question in the request body:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "What is 1+1?" }
+ ]
+ }'
Review Comment:
This request body omits the `model` field. Unless the Route config sets `ai-proxy.options.model`, OpenAI-compatible chat completions will fail upstream because `model` is required by the provider API. Please either include `"model": ...` in this request, or configure `ai-proxy.options.model` in the Route examples.
##########
docs/en/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: This document contains information about the Apache APISIX ai-aliyu
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
-The `ai-aliyun-content-moderation` plugin integrates with Aliyun's content moderation service to check both request and response content for inappropriate material when working with LLMs. It supports both real-time streaming checks and final packet moderation.
-
-This plugin must be used in routes that utilize the ai-proxy or ai-proxy-multi plugins.
-
-## Plugin Attributes
-
-| **Field** | **Required** | **Type** | **Description** |
-| ---------------------------- | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | Yes | String | Aliyun service endpoint URL |
-| region_id | Yes | String | Aliyun region identifier |
-| access_key_id | Yes | String | Aliyun access key ID |
-| access_key_secret | Yes | String | Aliyun access key secret |
-| check_request | No | Boolean | Enable request content moderation. Default: `true` |
-| check_response | No | Boolean | Enable response content moderation. Default: `false` |
-| stream_check_mode | No | String | Streaming moderation mode. Default: `"final_packet"`. Valid values: `["realtime", "final_packet"]` |
-| stream_check_cache_size | No | Integer | Max characters per moderation batch in realtime mode. Default: `128`. Must be `>= 1`. |
-| stream_check_interval | No | Number | Seconds between batch checks in realtime mode. Default: `3`. Must be `>= 0.1`. |
-| request_check_service | No | String | Aliyun service for request moderation. Default: `"llm_query_moderation"` |
-| request_check_length_limit | No | Number | Max characters per request moderation chunk. Default: `2000`. |
-| response_check_service | No | String | Aliyun service for response moderation. Default: `"llm_response_moderation"` |
-| response_check_length_limit | No | Number | Max characters per response moderation chunk. Default: `5000`. |
-| risk_level_bar | No | String | Threshold for content rejection. Default: `"high"`. Valid values: `["none", "low", "medium", "high", "max"]` |
-| deny_code | No | Number | HTTP status code for rejected content. Default: `200`. |
-| deny_message | No | String | Custom message for rejected content. Default: `-`. |
-| timeout | No | Integer | Request timeout in milliseconds. Default: `10000`. Must be `>= 1`. |
-| ssl_verify | No | Boolean | Enable SSL certificate verification. Default: `true`. |
-
-## Example usage
-
-First initialise these shell variables:
+The `ai-aliyun-content-moderation` Plugin integrates with [Aliyun Machine-Assisted Moderation Plus](https://help.aliyun.com/document_detail/2671445.html) to check request and response content for risk level when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold.
+
+Please ensure that the `access_key_secret` is correctly configured in the Plugin. If misconfigured, all requests will bypass the Plugin to be directly forwarded to the LLM Upstream, and you will see a `Specified signature is not matched with our calculation` error in the gateway's error log from the Plugin.
+
+The `ai-aliyun-content-moderation` Plugin should be used with either [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests.
+
+## Attributes
+
+| Name | Type | Required | Default | Valid Values | Description |
+|------|------|----------|---------|--------------|-------------|
+| access_key_id | string | True | | | Aliyun access key ID. |
+| access_key_secret | string | True | | | Aliyun secret access key. The value is encrypted with AES before being stored in etcd. |
+| region_id | string | True | | | Aliyun region ID. |
+| endpoint | string | True | | | Aliyun endpoint. |
+| check_request | boolean | False | `true` | | If `true`, moderate the request content. |
+| check_response | boolean | False | `false` | | If `true`, moderate the response content. |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`, `final_packet` | Streaming moderation mode. `realtime`: batched checks during streaming. `final_packet`: append risk level at the end. |
+| stream_check_cache_size | integer | False | `128` | >= 1 | Maximum characters per moderation batch in `realtime` mode. |
+| stream_check_interval | number | False | `3` | >= 0.1 | Seconds between batch checks in `realtime` mode. |
+| request_check_service | string | False | `"llm_query_moderation"` | | Aliyun service for request moderation. |
+| request_check_length_limit | number | False | `2000` | | Request content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the request content has 250 characters and the `request_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
+| response_check_service | string | False | `"llm_response_moderation"` | | Aliyun service for response moderation. |
+| response_check_length_limit | number | False | `5000` | | Response content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the response content has 250 characters and the `response_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
+| risk_level_bar | string | False | `"high"` | `none`, `low`, `medium`, `high`, `max` | If the evaluated risk level is lower than the `risk_level_bar`, the request or response will be passed through to Upstream LLM or client respectively. |
+| deny_code | number | False | `200` | | Rejection HTTP status code. |
+| deny_message | string | False | | | Rejection message. |
+| timeout | integer | False | `10000` | >= 1 | Timeout in milliseconds. |
+| keepalive | boolean | False | `true` | | If `true`, enable HTTP connection keepalive to Aliyun. |
+| keepalive_pool | integer | False | `30` | >= 1 | Maximum number of connections in the keepalive pool. |
+| keepalive_timeout | integer | False | `60000` | >= 1000 | Keepalive timeout in milliseconds. |
+| ssl_verify | boolean | False | `true` | | If `true`, enable SSL certificate verification. |
+
+## Examples
+
+The following examples use OpenAI as the Upstream service provider. Before proceeding, create an [OpenAI account](https://openai.com) and obtain an [API key](https://openai.com/blog/openai-api). If you are working with other LLM providers, please refer to the provider's documentation to obtain an API key.
+
+Additionally, create an [Aliyun account](https://www.aliyun.com), enable Machine-Assisted Moderation Plus, and obtain the endpoint, region ID, access key ID, and access key secret.
+
+:::note
+
+You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+You can optionally save the Aliyun and OpenAI information to environment variables:
```shell
-ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1
-ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
-ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
-ALIYUN_REGION=cn-hangzhou
-ALIYUN_ENDPOINT=https://green.cn-hangzhou.aliyuncs.com
-OPENAI_KEY=your-openai-api-key
+# Replace with your data
+export OPENAI_API_KEY=your-openai-api-key
+export ALIYUN_ENDPOINT=https://green-cip.cn-shanghai.aliyuncs.com
+export ALIYUN_REGION_ID=cn-shanghai
+export ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
+export ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
```
-Create a route with the `ai-aliyun-content-moderation` and `ai-proxy` plugin like so:
+### Moderate Request Content Toxicity
+
+The following example demonstrates how you can use the Plugin to moderate content toxicity in requests and customize the rejection code and message.
+
+<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 to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the integration details as well as the `deny_code` and `deny_message` in the `ai-aliyun-content-moderation` Plugin:
```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-aliyun-content-moderation-route",
+ "uri": "/anything",
"plugins": {
+ "ai-aliyun-content-moderation": {
+ "endpoint": "'"$ALIYUN_ENDPOINT"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
+ "access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
+ "access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
+ "deny_code": 400,
+ "deny_message": "Request contains forbidden content, such as hate speech or violence."
+ },
"ai-proxy": {
"provider": "openai",
"auth": {
"header": {
- "Authorization": "Bearer '"$OPENAI_KEY"'"
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
}
- },
- "override": {
- "endpoint": "http://localhost:6724/v1/chat/completions"
}
+ }
+ }
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+```
+
+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-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+Send a POST request to the Route with a system prompt and a user question with a profane word in the request body:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "gpt-4",
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
},
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+Send another request to the Route with a typical question in the request body:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "What is 1+1?" }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 200 OK` response with the model output:
+
+```json
+{
+ "model": "gpt-4-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": "1+1 equals 2.",
+ "refusal": null
+ },
+ "logprobs": null,
+ "finish_reason": "stop"
+ }
+ ]
+}
+```
+
+### Adjust Risk Level Threshold
+
+The following example demonstrates how you can adjust the threshold of risk level, which regulates whether a request or response should be allowed through.
+
+<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 to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the `risk_level_bar` in `ai-aliyun-content-moderation` to be `high`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ai-aliyun-content-moderation-route",
+ "uri": "/anything",
+ "plugins": {
"ai-aliyun-content-moderation": {
"endpoint": "'"$ALIYUN_ENDPOINT"'",
- "region_id": "'"$ALIYUN_REGION"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
"access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
"access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
- "risk_level_bar": "high",
- "check_request": true,
- "check_response": true,
"deny_code": 400,
- "deny_message": "Your request violates content policy"
+ "deny_message": "Request contains forbidden content, such as hate speech or violence.",
+ "risk_level_bar": "high"
+ },
+ "ai-proxy": {
+ "provider": "openai",
+ "auth": {
+ "header": {
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
+ }
+ },
+ "model": "gpt-4"
Review Comment:
In this Admin API example, `ai-proxy` is configured with a top-level `model` field, but the plugin schema uses `options.model` (as shown in the ADC example below and in `docs/en/latest/plugins/ai-proxy.md`). With the current config, the model may be ignored and requests without a `model` in the body will fail upstream. Please move this to `options: { model: "gpt-4" }` (or keep `model` in every request body).
```suggestion
"options": {
"model": "gpt-4"
}
```
##########
docs/zh/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: 本文档包含有关 Apache APISIX ai-aliyun-content-moderation
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`ai-aliyun-content-moderation` 插件集成了阿里云的内容审核服务，用于在与大语言模型 (LLM) 交互时检查请求和响应内容是否包含不当材料。它支持实时流式检查和最终数据包审核两种模式。
-
-此插件必须在使用 `ai-proxy` 或 `ai-proxy-multi` 插件的路由中使用。
-
-## 插件属性
-
-| **字段** | **必选项** | **类型** | **描述** |
-| ---------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | 是 | String | 阿里云服务端点 URL |
-| region_id | 是 | String | 阿里云区域标识符 |
-| access_key_id | 是 | String | 阿里云访问密钥 ID |
-| access_key_secret | 是 | String | 阿里云访问密钥密码 |
-| check_request | 否 | Boolean | 启用请求内容审核。默认值：`true` |
-| check_response | 否 | Boolean | 启用响应内容审核。默认值：`false` |
-| stream_check_mode | 否 | String | 流式审核模式。默认值：`"final_packet"`。有效值：`["realtime", "final_packet"]` |
-| stream_check_cache_size | 否 | Integer | 实时模式下每次审核批次的最大字符数。默认值：`128`。必须 `>= 1` |
-| stream_check_interval | 否 | Number | 实时模式下批次检查之间的间隔秒数。默认值：`3`。必须 `>= 0.1` |
-| request_check_service | 否 | String | 用于请求审核的阿里云服务。默认值：`"llm_query_moderation"` |
-| request_check_length_limit | 否 | Number | 每个请求审核块的最大字符数。默认值：`2000` |
-| response_check_service | 否 | String | 用于响应审核的阿里云服务。默认值：`"llm_response_moderation"` |
-| response_check_length_limit | 否 | Number | 每个响应审核块的最大字符数。默认值：`5000` |
-| risk_level_bar | 否 | String | 内容拒绝的阈值。默认值：`"high"`。有效值：`["none", "low", "medium", "high", "max"]` |
-| deny_code | 否 | Number | 被拒绝内容的 HTTP 状态码。默认值：`200` |
-| deny_message | 否 | String | 被拒绝内容的自定义消息。默认值：`-` |
-| timeout | 否 | Integer | 请求超时时间（毫秒）。默认值：`10000`。必须 `>= 1` |
-| ssl_verify | 否 | Boolean | 启用 SSL 证书验证。默认值：`true` |
-
-## 使用示例
-
-首先初始化这些 shell 变量：
+`ai-aliyun-content-moderation` 插件集成了[阿里云机器辅助审核 Plus](https://help.aliyun.com/document_detail/2671445.html)，用于在代理 LLM 请求时检查请求和响应内容的风险等级，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，当评估结果超过配置的阈值时拒绝请求。
+
+请确保在插件中正确配置 `access_key_secret`。如果配置错误，所有请求将绕过插件直接转发到 LLM 上游，并且您将在网关的错误日志中看到来自插件的 `Specified signature is not matched with our calculation` 错误。
+
+`ai-aliyun-content-moderation` 插件应与 [`ai-proxy`](./ai-proxy.md) 或 [`ai-proxy-multi`](./ai-proxy-multi.md) 插件配合使用以代理 LLM 请求。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| access_key_id | string | True | | | 阿里云访问密钥 ID。 |
+| access_key_secret | string | True | | | 阿里云访问密钥。该值在存储到 etcd 之前会使用 AES 加密。 |
+| region_id | string | True | | | 阿里云区域 ID。 |
+| endpoint | string | True | | | 阿里云端点。 |
+| check_request | boolean | False | `true` | | 如果为 `true`，则审核请求内容。 |
+| check_response | boolean | False | `false` | | 如果为 `true`，则审核响应内容。 |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`、`final_packet` | 流式审核模式。`realtime`：流式传输期间批量检查。`final_packet`：在最后附加风险等级。 |
+| stream_check_cache_size | integer | False | `128` | >= 1 | `realtime` 模式下每次审核批次的最大字符数。 |
+| stream_check_interval | number | False | `3` | >= 0.1 | `realtime` 模式下批次检查之间的间隔秒数。 |
+| request_check_service | string | False | `"llm_query_moderation"` | | 用于请求审核的阿里云服务。 |
+| request_check_length_limit | number | False | `2000` | | 请求内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果请求内容有 250 个字符，且 `request_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| response_check_service | string | False | `"llm_response_moderation"` | | 用于响应审核的阿里云服务。 |
+| response_check_length_limit | number | False | `5000` | | 响应内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果响应内容有 250 个字符，且 `response_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
Review Comment:
These limits are documented as “字符数”, but the plugin implementation uses Lua string length (`#content` / `#ctx.content_moderation_cache`), which is byte-based for UTF-8. For non-ASCII content this will chunk earlier (and can cause extra empty chunks). Please update the wording to reflect byte-based length, or clarify the UTF-8/byte behavior.
```suggestion
| stream_check_cache_size | integer | False | `128` | >= 1 | `realtime` 模式下每次审核批次的最大字节数（按 UTF-8 编码后的字节长度计算）。 |
| stream_check_interval | number | False | `3` | >= 0.1 | `realtime` 模式下批次检查之间的间隔秒数。 |
| request_check_service | string | False | `"llm_query_moderation"` | | 用于请求审核的阿里云服务。 |
| request_check_length_limit | number | False | `2000` | | 请求内容字节数上限（按 UTF-8 编码后的字节长度计算）。如果超过该限制，内容将被分块发送。对于非 ASCII 内容，可能会比按字符数理解时更早触发分块。例如，如果请求内容按 UTF-8 编码后有 250 个字节，且 `request_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
| response_check_service | string | False | `"llm_response_moderation"` | | 用于响应审核的阿里云服务。 |
| response_check_length_limit | number | False | `5000` | | 响应内容字节数上限（按 UTF-8 编码后的字节长度计算）。如果超过该限制，内容将被分块发送。对于非 ASCII 内容，可能会比按字符数理解时更早触发分块。例如，如果响应内容按 UTF-8 编码后有 250 个字节，且 `response_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
```
##########
docs/en/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: This document contains information about the Apache APISIX ai-aliyu
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
-The `ai-aliyun-content-moderation` plugin integrates with Aliyun's content moderation service to check both request and response content for inappropriate material when working with LLMs. It supports both real-time streaming checks and final packet moderation.
-
-This plugin must be used in routes that utilize the ai-proxy or ai-proxy-multi plugins.
-
-## Plugin Attributes
-
-| **Field** | **Required** | **Type** | **Description** |
-| ---------------------------- | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | Yes | String | Aliyun service endpoint URL |
-| region_id | Yes | String | Aliyun region identifier |
-| access_key_id | Yes | String | Aliyun access key ID |
-| access_key_secret | Yes | String | Aliyun access key secret |
-| check_request | No | Boolean | Enable request content moderation. Default: `true` |
-| check_response | No | Boolean | Enable response content moderation. Default: `false` |
-| stream_check_mode | No | String | Streaming moderation mode. Default: `"final_packet"`. Valid values: `["realtime", "final_packet"]` |
-| stream_check_cache_size | No | Integer | Max characters per moderation batch in realtime mode. Default: `128`. Must be `>= 1`. |
-| stream_check_interval | No | Number | Seconds between batch checks in realtime mode. Default: `3`. Must be `>= 0.1`. |
-| request_check_service | No | String | Aliyun service for request moderation. Default: `"llm_query_moderation"` |
-| request_check_length_limit | No | Number | Max characters per request moderation chunk. Default: `2000`. |
-| response_check_service | No | String | Aliyun service for response moderation. Default: `"llm_response_moderation"` |
-| response_check_length_limit | No | Number | Max characters per response moderation chunk. Default: `5000`. |
-| risk_level_bar | No | String | Threshold for content rejection. Default: `"high"`. Valid values: `["none", "low", "medium", "high", "max"]` |
-| deny_code | No | Number | HTTP status code for rejected content. Default: `200`. |
-| deny_message | No | String | Custom message for rejected content. Default: `-`. |
-| timeout | No | Integer | Request timeout in milliseconds. Default: `10000`. Must be `>= 1`. |
-| ssl_verify | No | Boolean | Enable SSL certificate verification. Default: `true`. |
-
-## Example usage
-
-First initialise these shell variables:
+The `ai-aliyun-content-moderation` Plugin integrates with [Aliyun Machine-Assisted Moderation Plus](https://help.aliyun.com/document_detail/2671445.html) to check request and response content for risk level when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold.
+
+Please ensure that the `access_key_secret` is correctly configured in the Plugin. If misconfigured, all requests will bypass the Plugin to be directly forwarded to the LLM Upstream, and you will see a `Specified signature is not matched with our calculation` error in the gateway's error log from the Plugin.
+
+The `ai-aliyun-content-moderation` Plugin should be used with either [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests.
+
+## Attributes
+
+| Name | Type | Required | Default | Valid Values | Description |
+|------|------|----------|---------|--------------|-------------|
+| access_key_id | string | True | | | Aliyun access key ID. |
+| access_key_secret | string | True | | | Aliyun secret access key. The value is encrypted with AES before being stored in etcd. |
+| region_id | string | True | | | Aliyun region ID. |
+| endpoint | string | True | | | Aliyun endpoint. |
+| check_request | boolean | False | `true` | | If `true`, moderate the request content. |
+| check_response | boolean | False | `false` | | If `true`, moderate the response content. |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`, `final_packet` | Streaming moderation mode. `realtime`: batched checks during streaming. `final_packet`: append risk level at the end. |
+| stream_check_cache_size | integer | False | `128` | >= 1 | Maximum characters per moderation batch in `realtime` mode. |
+| stream_check_interval | number | False | `3` | >= 0.1 | Seconds between batch checks in `realtime` mode. |
+| request_check_service | string | False | `"llm_query_moderation"` | | Aliyun service for request moderation. |
+| request_check_length_limit | number | False | `2000` | | Request content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the request content has 250 characters and the `request_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
+| response_check_service | string | False | `"llm_response_moderation"` | | Aliyun service for response moderation. |
+| response_check_length_limit | number | False | `5000` | | Response content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the response content has 250 characters and the `response_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
+| risk_level_bar | string | False | `"high"` | `none`, `low`, `medium`, `high`, `max` | If the evaluated risk level is lower than the `risk_level_bar`, the request or response will be passed through to Upstream LLM or client respectively. |
+| deny_code | number | False | `200` | | Rejection HTTP status code. |
+| deny_message | string | False | | | Rejection message. |
+| timeout | integer | False | `10000` | >= 1 | Timeout in milliseconds. |
+| keepalive | boolean | False | `true` | | If `true`, enable HTTP connection keepalive to Aliyun. |
+| keepalive_pool | integer | False | `30` | >= 1 | Maximum number of connections in the keepalive pool. |
+| keepalive_timeout | integer | False | `60000` | >= 1000 | Keepalive timeout in milliseconds. |
+| ssl_verify | boolean | False | `true` | | If `true`, enable SSL certificate verification. |
+
+## Examples
+
+The following examples use OpenAI as the Upstream service provider. Before proceeding, create an [OpenAI account](https://openai.com) and obtain an [API key](https://openai.com/blog/openai-api). If you are working with other LLM providers, please refer to the provider's documentation to obtain an API key.
+
+Additionally, create an [Aliyun account](https://www.aliyun.com), enable Machine-Assisted Moderation Plus, and obtain the endpoint, region ID, access key ID, and access key secret.
+
+:::note
+
+You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+You can optionally save the Aliyun and OpenAI information to environment variables:
```shell
-ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1
-ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
-ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
-ALIYUN_REGION=cn-hangzhou
-ALIYUN_ENDPOINT=https://green.cn-hangzhou.aliyuncs.com
-OPENAI_KEY=your-openai-api-key
+# Replace with your data
+export OPENAI_API_KEY=your-openai-api-key
+export ALIYUN_ENDPOINT=https://green-cip.cn-shanghai.aliyuncs.com
+export ALIYUN_REGION_ID=cn-shanghai
+export ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
+export ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
```
-Create a route with the `ai-aliyun-content-moderation` and `ai-proxy` plugin like so:
+### Moderate Request Content Toxicity
+
+The following example demonstrates how you can use the Plugin to moderate content toxicity in requests and customize the rejection code and message.
+
+<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 to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the integration details as well as the `deny_code` and `deny_message` in the `ai-aliyun-content-moderation` Plugin:
```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-aliyun-content-moderation-route",
+ "uri": "/anything",
"plugins": {
+ "ai-aliyun-content-moderation": {
+ "endpoint": "'"$ALIYUN_ENDPOINT"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
+ "access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
+ "access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
+ "deny_code": 400,
+ "deny_message": "Request contains forbidden content, such as hate speech or violence."
+ },
"ai-proxy": {
"provider": "openai",
"auth": {
"header": {
- "Authorization": "Bearer '"$OPENAI_KEY"'"
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
}
- },
- "override": {
- "endpoint": "http://localhost:6724/v1/chat/completions"
}
+ }
+ }
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+```
+
+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-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+Send a POST request to the Route with a system prompt and a user question with a profane word in the request body:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "gpt-4",
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
},
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+Send another request to the Route with a typical question in the request body:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "What is 1+1?" }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 200 OK` response with the model output:
+
+```json
+{
+ "model": "gpt-4-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": "1+1 equals 2.",
+ "refusal": null
+ },
+ "logprobs": null,
+ "finish_reason": "stop"
+ }
+ ]
+}
+```
+
+### Adjust Risk Level Threshold
+
+The following example demonstrates how you can adjust the threshold of risk level, which regulates whether a request or response should be allowed through.
+
+<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 to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the `risk_level_bar` in `ai-aliyun-content-moderation` to be `high`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ai-aliyun-content-moderation-route",
+ "uri": "/anything",
+ "plugins": {
"ai-aliyun-content-moderation": {
"endpoint": "'"$ALIYUN_ENDPOINT"'",
- "region_id": "'"$ALIYUN_REGION"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
"access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
"access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
- "risk_level_bar": "high",
- "check_request": true,
- "check_response": true,
"deny_code": 400,
- "deny_message": "Your request violates content policy"
+ "deny_message": "Request contains forbidden content, such as hate speech or violence.",
+ "risk_level_bar": "high"
+ },
+ "ai-proxy": {
+ "provider": "openai",
+ "auth": {
+ "header": {
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
+ }
+ },
+ "model": "gpt-4"
}
}
}'
```
-The `ai-proxy` plugin is used here as it simplifies access to LLMs. However, you may configure the LLM in the upstream configuration as well.
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ risk_level_bar: high
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+ options:
+ model: gpt-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-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
-Now send a request:
+```yaml title="ai-aliyun-moderation-threshold-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ risk_level_bar: high
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+ options:
+ model: gpt-4
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+Apply the configuration to your cluster:
```shell
-curl http://127.0.0.1:9080/v1/chat/completions -i \
+kubectl apply -f ai-aliyun-moderation-threshold-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Route with the `ai-aliyun-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such:
+
+```yaml title="ai-aliyun-moderation-threshold-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ risk_level_bar: high
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+ options:
+ model: gpt-4
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f ai-aliyun-moderation-threshold-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+Send a POST request to the Route with a system prompt and a user question with a profane word in the request body:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
-H "Content-Type: application/json" \
-d '{
- "model": "gpt-3.5-turbo",
+ "model": "gpt-4",
"messages": [
- {"role": "user", "content": "I want to kill you"}
- ],
- "stream": false
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+You should receive an `HTTP/1.1 400 Bad Request` response and see the following message:
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
+ },
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+Update the `risk_level_bar` in the Plugin to `max`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/ai-aliyun-content-moderation-route" -X PATCH \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "plugins": {
+ "ai-aliyun-content-moderation": {
+ "risk_level_bar": "max"
+ }
+ }
}'
```
-Then the request will be blocked with error like this:
+Send the same request to the Route:
-```text
-HTTP/1.1 400 Bad Request
-Content-Type: application/json
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
Review Comment:
This “same request” example omits the `model` field. Unless the Route config sets `ai-proxy.options.model`, OpenAI-compatible chat completions will fail upstream because `model` is required by the provider API. Please either include `"model": ...` in this request, or configure `ai-proxy.options.model` in the Route examples.
##########
docs/zh/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: 本文档包含有关 Apache APISIX ai-aliyun-content-moderation
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`ai-aliyun-content-moderation` 插件集成了阿里云的内容审核服务，用于在与大语言模型 (LLM) 交互时检查请求和响应内容是否包含不当材料。它支持实时流式检查和最终数据包审核两种模式。
-
-此插件必须在使用 `ai-proxy` 或 `ai-proxy-multi` 插件的路由中使用。
-
-## 插件属性
-
-| **字段** | **必选项** | **类型** | **描述** |
-| ---------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | 是 | String | 阿里云服务端点 URL |
-| region_id | 是 | String | 阿里云区域标识符 |
-| access_key_id | 是 | String | 阿里云访问密钥 ID |
-| access_key_secret | 是 | String | 阿里云访问密钥密码 |
-| check_request | 否 | Boolean | 启用请求内容审核。默认值：`true` |
-| check_response | 否 | Boolean | 启用响应内容审核。默认值：`false` |
-| stream_check_mode | 否 | String | 流式审核模式。默认值：`"final_packet"`。有效值：`["realtime", "final_packet"]` |
-| stream_check_cache_size | 否 | Integer | 实时模式下每次审核批次的最大字符数。默认值：`128`。必须 `>= 1` |
-| stream_check_interval | 否 | Number | 实时模式下批次检查之间的间隔秒数。默认值：`3`。必须 `>= 0.1` |
-| request_check_service | 否 | String | 用于请求审核的阿里云服务。默认值：`"llm_query_moderation"` |
-| request_check_length_limit | 否 | Number | 每个请求审核块的最大字符数。默认值：`2000` |
-| response_check_service | 否 | String | 用于响应审核的阿里云服务。默认值：`"llm_response_moderation"` |
-| response_check_length_limit | 否 | Number | 每个响应审核块的最大字符数。默认值：`5000` |
-| risk_level_bar | 否 | String | 内容拒绝的阈值。默认值：`"high"`。有效值：`["none", "low", "medium", "high", "max"]` |
-| deny_code | 否 | Number | 被拒绝内容的 HTTP 状态码。默认值：`200` |
-| deny_message | 否 | String | 被拒绝内容的自定义消息。默认值：`-` |
-| timeout | 否 | Integer | 请求超时时间（毫秒）。默认值：`10000`。必须 `>= 1` |
-| ssl_verify | 否 | Boolean | 启用 SSL 证书验证。默认值：`true` |
-
-## 使用示例
-
-首先初始化这些 shell 变量：
+`ai-aliyun-content-moderation` 插件集成了[阿里云机器辅助审核 Plus](https://help.aliyun.com/document_detail/2671445.html)，用于在代理 LLM 请求时检查请求和响应内容的风险等级，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，当评估结果超过配置的阈值时拒绝请求。
+
+请确保在插件中正确配置 `access_key_secret`。如果配置错误，所有请求将绕过插件直接转发到 LLM 上游，并且您将在网关的错误日志中看到来自插件的 `Specified signature is not matched with our calculation` 错误。
+
+`ai-aliyun-content-moderation` 插件应与 [`ai-proxy`](./ai-proxy.md) 或 [`ai-proxy-multi`](./ai-proxy-multi.md) 插件配合使用以代理 LLM 请求。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| access_key_id | string | True | | | 阿里云访问密钥 ID。 |
+| access_key_secret | string | True | | | 阿里云访问密钥。该值在存储到 etcd 之前会使用 AES 加密。 |
+| region_id | string | True | | | 阿里云区域 ID。 |
+| endpoint | string | True | | | 阿里云端点。 |
+| check_request | boolean | False | `true` | | 如果为 `true`，则审核请求内容。 |
+| check_response | boolean | False | `false` | | 如果为 `true`，则审核响应内容。 |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`、`final_packet` | 流式审核模式。`realtime`：流式传输期间批量检查。`final_packet`：在最后附加风险等级。 |
+| stream_check_cache_size | integer | False | `128` | >= 1 | `realtime` 模式下每次审核批次的最大字符数。 |
+| stream_check_interval | number | False | `3` | >= 0.1 | `realtime` 模式下批次检查之间的间隔秒数。 |
+| request_check_service | string | False | `"llm_query_moderation"` | | 用于请求审核的阿里云服务。 |
+| request_check_length_limit | number | False | `2000` | | 请求内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果请求内容有 250 个字符，且 `request_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| response_check_service | string | False | `"llm_response_moderation"` | | 用于响应审核的阿里云服务。 |
+| response_check_length_limit | number | False | `5000` | | 响应内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果响应内容有 250 个字符，且 `response_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
Review Comment:
In the Chinese docs, the “必选项” column uses `True`/`False`, but other zh plugin docs use `是`/`否` (for example `docs/zh/latest/plugins/ai-proxy.md`). To match existing zh documentation conventions, please switch these values to `是`/`否`.
```suggestion
| access_key_id | string | 是 | | | 阿里云访问密钥 ID。 |
| access_key_secret | string | 是 | | | 阿里云访问密钥。该值在存储到 etcd 之前会使用 AES 加密。 |
| region_id | string | 是 | | | 阿里云区域 ID。 |
| endpoint | string | 是 | | | 阿里云端点。 |
| check_request | boolean | 否 | `true` | | 如果为 `true`，则审核请求内容。 |
| check_response | boolean | 否 | `false` | | 如果为 `true`，则审核响应内容。 |
| stream_check_mode | string | 否 | `"final_packet"` | `realtime`、`final_packet` | 流式审核模式。`realtime`：流式传输期间批量检查。`final_packet`：在最后附加风险等级。 |
| stream_check_cache_size | integer | 否 | `128` | >= 1 | `realtime` 模式下每次审核批次的最大字符数。 |
| stream_check_interval | number | 否 | `3` | >= 0.1 | `realtime` 模式下批次检查之间的间隔秒数。 |
| request_check_service | string | 否 | `"llm_query_moderation"` | | 用于请求审核的阿里云服务。 |
| request_check_length_limit | number | 否 | `2000` | | 请求内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果请求内容有 250 个字符，且 `request_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
| response_check_service | string | 否 | `"llm_response_moderation"` | | 用于响应审核的阿里云服务。 |
| response_check_length_limit | number | 否 | `5000` | | 响应内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果响应内容有 250 个字符，且 `response_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
```
##########
docs/en/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: This document contains information about the Apache APISIX ai-aliyu
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
-The `ai-aliyun-content-moderation` plugin integrates with Aliyun's content moderation service to check both request and response content for inappropriate material when working with LLMs. It supports both real-time streaming checks and final packet moderation.
-
-This plugin must be used in routes that utilize the ai-proxy or ai-proxy-multi plugins.
-
-## Plugin Attributes
-
-| **Field** | **Required** | **Type** | **Description** |
-| ---------------------------- | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | Yes | String | Aliyun service endpoint URL |
-| region_id | Yes | String | Aliyun region identifier |
-| access_key_id | Yes | String | Aliyun access key ID |
-| access_key_secret | Yes | String | Aliyun access key secret |
-| check_request | No | Boolean | Enable request content moderation. Default: `true` |
-| check_response | No | Boolean | Enable response content moderation. Default: `false` |
-| stream_check_mode | No | String | Streaming moderation mode. Default: `"final_packet"`. Valid values: `["realtime", "final_packet"]` |
-| stream_check_cache_size | No | Integer | Max characters per moderation batch in realtime mode. Default: `128`. Must be `>= 1`. |
-| stream_check_interval | No | Number | Seconds between batch checks in realtime mode. Default: `3`. Must be `>= 0.1`. |
-| request_check_service | No | String | Aliyun service for request moderation. Default: `"llm_query_moderation"` |
-| request_check_length_limit | No | Number | Max characters per request moderation chunk. Default: `2000`. |
-| response_check_service | No | String | Aliyun service for response moderation. Default: `"llm_response_moderation"` |
-| response_check_length_limit | No | Number | Max characters per response moderation chunk. Default: `5000`. |
-| risk_level_bar | No | String | Threshold for content rejection. Default: `"high"`. Valid values: `["none", "low", "medium", "high", "max"]` |
-| deny_code | No | Number | HTTP status code for rejected content. Default: `200`. |
-| deny_message | No | String | Custom message for rejected content. Default: `-`. |
-| timeout | No | Integer | Request timeout in milliseconds. Default: `10000`. Must be `>= 1`. |
-| ssl_verify | No | Boolean | Enable SSL certificate verification. Default: `true`. |
-
-## Example usage
-
-First initialise these shell variables:
+The `ai-aliyun-content-moderation` Plugin integrates with [Aliyun Machine-Assisted Moderation Plus](https://help.aliyun.com/document_detail/2671445.html) to check request and response content for risk level when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold.
+
+Please ensure that the `access_key_secret` is correctly configured in the Plugin. If misconfigured, all requests will bypass the Plugin to be directly forwarded to the LLM Upstream, and you will see a `Specified signature is not matched with our calculation` error in the gateway's error log from the Plugin.
+
+The `ai-aliyun-content-moderation` Plugin should be used with either [`ai-proxy`](./ai-proxy.md) or [`ai-proxy-multi`](./ai-proxy-multi.md) Plugin for proxying LLM requests.
+
+## Attributes
+
+| Name | Type | Required | Default | Valid Values | Description |
+|------|------|----------|---------|--------------|-------------|
+| access_key_id | string | True | | | Aliyun access key ID. |
+| access_key_secret | string | True | | | Aliyun secret access key. The value is encrypted with AES before being stored in etcd. |
+| region_id | string | True | | | Aliyun region ID. |
+| endpoint | string | True | | | Aliyun endpoint. |
+| check_request | boolean | False | `true` | | If `true`, moderate the request content. |
+| check_response | boolean | False | `false` | | If `true`, moderate the response content. |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`, `final_packet` | Streaming moderation mode. `realtime`: batched checks during streaming. `final_packet`: append risk level at the end. |
+| stream_check_cache_size | integer | False | `128` | >= 1 | Maximum characters per moderation batch in `realtime` mode. |
+| stream_check_interval | number | False | `3` | >= 0.1 | Seconds between batch checks in `realtime` mode. |
+| request_check_service | string | False | `"llm_query_moderation"` | | Aliyun service for request moderation. |
+| request_check_length_limit | number | False | `2000` | | Request content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the request content has 250 characters and the `request_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
+| response_check_service | string | False | `"llm_response_moderation"` | | Aliyun service for response moderation. |
+| response_check_length_limit | number | False | `5000` | | Response content length limit, in character count. If exceeded, the content will be sent in chunks. For instance, if the response content has 250 characters and the `response_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
Review Comment:
These limits are documented as “character count”, but the plugin implementation uses Lua string length (`#content` / `#ctx.content_moderation_cache`), which is byte-based for UTF-8. For non-ASCII content this will chunk earlier (and can cause extra empty chunks). Please update the wording to reflect byte-based length, or clarify the UTF-8/byte behavior.
```suggestion
| stream_check_cache_size | integer | False | `128` | >= 1 | Maximum bytes per moderation batch in `realtime` mode. Length is measured using Lua string length, so for UTF-8 text non-ASCII characters may consume multiple bytes. |
| stream_check_interval | number | False | `3` | >= 0.1 | Seconds between batch checks in `realtime` mode. |
| request_check_service | string | False | `"llm_query_moderation"` | | Aliyun service for request moderation. |
| request_check_length_limit | number | False | `2000` | | Request content length limit, in bytes. Length is measured using Lua string length, so for UTF-8 text non-ASCII characters may consume multiple bytes. If exceeded, the content will be sent in chunks. For instance, if the request content is 250 bytes and the `request_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
| response_check_service | string | False | `"llm_response_moderation"` | | Aliyun service for response moderation. |
| response_check_length_limit | number | False | `5000` | | Response content length limit, in bytes. Length is measured using Lua string length, so for UTF-8 text non-ASCII characters may consume multiple bytes. If exceeded, the content will be sent in chunks. For instance, if the response content is 250 bytes and the `response_check_length_limit` is set to `100`, then the content will be sent in 3 requests to Aliyun. |
```
##########
docs/zh/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: 本文档包含有关 Apache APISIX ai-aliyun-content-moderation
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`ai-aliyun-content-moderation` 插件集成了阿里云的内容审核服务，用于在与大语言模型 (LLM) 交互时检查请求和响应内容是否包含不当材料。它支持实时流式检查和最终数据包审核两种模式。
-
-此插件必须在使用 `ai-proxy` 或 `ai-proxy-multi` 插件的路由中使用。
-
-## 插件属性
-
-| **字段** | **必选项** | **类型** | **描述** |
-| ---------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | 是 | String | 阿里云服务端点 URL |
-| region_id | 是 | String | 阿里云区域标识符 |
-| access_key_id | 是 | String | 阿里云访问密钥 ID |
-| access_key_secret | 是 | String | 阿里云访问密钥密码 |
-| check_request | 否 | Boolean | 启用请求内容审核。默认值：`true` |
-| check_response | 否 | Boolean | 启用响应内容审核。默认值：`false` |
-| stream_check_mode | 否 | String | 流式审核模式。默认值：`"final_packet"`。有效值：`["realtime", "final_packet"]` |
-| stream_check_cache_size | 否 | Integer | 实时模式下每次审核批次的最大字符数。默认值：`128`。必须 `>= 1` |
-| stream_check_interval | 否 | Number | 实时模式下批次检查之间的间隔秒数。默认值：`3`。必须 `>= 0.1` |
-| request_check_service | 否 | String | 用于请求审核的阿里云服务。默认值：`"llm_query_moderation"` |
-| request_check_length_limit | 否 | Number | 每个请求审核块的最大字符数。默认值：`2000` |
-| response_check_service | 否 | String | 用于响应审核的阿里云服务。默认值：`"llm_response_moderation"` |
-| response_check_length_limit | 否 | Number | 每个响应审核块的最大字符数。默认值：`5000` |
-| risk_level_bar | 否 | String | 内容拒绝的阈值。默认值：`"high"`。有效值：`["none", "low", "medium", "high", "max"]` |
-| deny_code | 否 | Number | 被拒绝内容的 HTTP 状态码。默认值：`200` |
-| deny_message | 否 | String | 被拒绝内容的自定义消息。默认值：`-` |
-| timeout | 否 | Integer | 请求超时时间（毫秒）。默认值：`10000`。必须 `>= 1` |
-| ssl_verify | 否 | Boolean | 启用 SSL 证书验证。默认值：`true` |
-
-## 使用示例
-
-首先初始化这些 shell 变量：
+`ai-aliyun-content-moderation` 插件集成了[阿里云机器辅助审核 Plus](https://help.aliyun.com/document_detail/2671445.html)，用于在代理 LLM 请求时检查请求和响应内容的风险等级，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，当评估结果超过配置的阈值时拒绝请求。
+
+请确保在插件中正确配置 `access_key_secret`。如果配置错误，所有请求将绕过插件直接转发到 LLM 上游，并且您将在网关的错误日志中看到来自插件的 `Specified signature is not matched with our calculation` 错误。
+
+`ai-aliyun-content-moderation` 插件应与 [`ai-proxy`](./ai-proxy.md) 或 [`ai-proxy-multi`](./ai-proxy-multi.md) 插件配合使用以代理 LLM 请求。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| access_key_id | string | True | | | 阿里云访问密钥 ID。 |
+| access_key_secret | string | True | | | 阿里云访问密钥。该值在存储到 etcd 之前会使用 AES 加密。 |
+| region_id | string | True | | | 阿里云区域 ID。 |
+| endpoint | string | True | | | 阿里云端点。 |
+| check_request | boolean | False | `true` | | 如果为 `true`，则审核请求内容。 |
+| check_response | boolean | False | `false` | | 如果为 `true`，则审核响应内容。 |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`、`final_packet` | 流式审核模式。`realtime`：流式传输期间批量检查。`final_packet`：在最后附加风险等级。 |
+| stream_check_cache_size | integer | False | `128` | >= 1 | `realtime` 模式下每次审核批次的最大字符数。 |
+| stream_check_interval | number | False | `3` | >= 0.1 | `realtime` 模式下批次检查之间的间隔秒数。 |
+| request_check_service | string | False | `"llm_query_moderation"` | | 用于请求审核的阿里云服务。 |
+| request_check_length_limit | number | False | `2000` | | 请求内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果请求内容有 250 个字符，且 `request_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| response_check_service | string | False | `"llm_response_moderation"` | | 用于响应审核的阿里云服务。 |
+| response_check_length_limit | number | False | `5000` | | 响应内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果响应内容有 250 个字符，且 `response_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| risk_level_bar | string | False | `"high"` | `none`、`low`、`medium`、`high`、`max` | 如果评估的风险等级低于 `risk_level_bar`，请求或响应将分别被放行到上游 LLM 或客户端。 |
+| deny_code | number | False | `200` | | 拒绝时的 HTTP 状态码。 |
+| deny_message | string | False | | | 拒绝时的消息。 |
+| timeout | integer | False | `10000` | >= 1 | 超时时间（毫秒）。 |
+| keepalive | boolean | False | `true` | | 如果为 `true`，启用到阿里云的 HTTP 连接保活。 |
+| keepalive_pool | integer | False | `30` | >= 1 | 连接保活池的最大连接数。 |
+| keepalive_timeout | integer | False | `60000` | >= 1000 | 连接保活超时时间（毫秒）。 |
+| ssl_verify | boolean | False | `true` | | 如果为 `true`，启用 SSL 证书验证。 |
+
+## 示例
+
+以下示例使用 OpenAI 作为上游服务提供商。在开始之前，请创建一个 [OpenAI 账号](https://openai.com) 并获取 [API 密钥](https://openai.com/blog/openai-api)。如果您使用其他 LLM 提供商，请参考相应提供商的文档获取 API 密钥。
+
+此外，创建一个[阿里云账号](https://www.aliyun.com)，开通机器辅助审核 Plus 服务，并获取端点、区域 ID、访问密钥 ID 和访问密钥。
+
+:::note
+
+您可以使用以下命令从 `config.yaml` 中获取 `admin_key` 并保存到环境变量中：
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+您可以选择将阿里云和 OpenAI 信息保存到环境变量：
```shell
-ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1
-ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
-ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
-ALIYUN_REGION=cn-hangzhou
-ALIYUN_ENDPOINT=https://green.cn-hangzhou.aliyuncs.com
-OPENAI_KEY=your-openai-api-key
+# 替换为您的数据
+export OPENAI_API_KEY=your-openai-api-key
+export ALIYUN_ENDPOINT=https://green-cip.cn-shanghai.aliyuncs.com
+export ALIYUN_REGION_ID=cn-shanghai
+export ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
+export ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
```
-创建一个带有 `ai-aliyun-content-moderation` 和 `ai-proxy` 插件的路由：
+### 审核请求内容毒性
+
+以下示例演示如何使用该插件审核请求中的内容毒性并自定义拒绝代码和消息。
+
+<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">
+
+创建一个路由到 LLM 聊天补全端点，使用 [`ai-proxy`](./ai-proxy.md) 插件，并在 `ai-aliyun-content-moderation` 插件中配置集成详情以及 `deny_code` 和 `deny_message`：
```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-aliyun-content-moderation-route",
+ "uri": "/anything",
"plugins": {
+ "ai-aliyun-content-moderation": {
+ "endpoint": "'"$ALIYUN_ENDPOINT"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
+ "access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
+ "access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
+ "deny_code": 400,
+ "deny_message": "Request contains forbidden content, such as hate speech or violence."
+ },
"ai-proxy": {
"provider": "openai",
"auth": {
"header": {
- "Authorization": "Bearer '"$OPENAI_KEY"'"
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
}
- },
- "override": {
- "endpoint": "http://localhost:6724/v1/chat/completions"
}
+ }
+ }
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+```
+
+将配置同步到网关：
+
+```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">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+向该路由发送一个 POST 请求，请求体中包含系统提示和一个含有不当用语的用户问题：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "gpt-4",
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+您应该收到 `HTTP/1.1 400 Bad Request` 响应并看到以下消息：
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
},
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+向该路由发送另一个包含正常问题的请求：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "What is 1+1?" }
+ ]
+ }'
Review Comment:
该请求体缺少 `model` 字段。除非路由配置里设置了 `ai-proxy.options.model`，否则 OpenAI 兼容的聊天补全请求会因为缺少 `model` 而在上游失败。请在该请求中补充 `"model": ...`，或在路由示例里配置 `ai-proxy.options.model`。
##########
docs/zh/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,643 @@ description: 本文档包含有关 Apache APISIX ai-aliyun-content-moderation
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`ai-aliyun-content-moderation` 插件集成了阿里云的内容审核服务，用于在与大语言模型 (LLM) 交互时检查请求和响应内容是否包含不当材料。它支持实时流式检查和最终数据包审核两种模式。
-
-此插件必须在使用 `ai-proxy` 或 `ai-proxy-multi` 插件的路由中使用。
-
-## 插件属性
-
-| **字段** | **必选项** | **类型** | **描述** |
-| ---------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | 是 | String | 阿里云服务端点 URL |
-| region_id | 是 | String | 阿里云区域标识符 |
-| access_key_id | 是 | String | 阿里云访问密钥 ID |
-| access_key_secret | 是 | String | 阿里云访问密钥密码 |
-| check_request | 否 | Boolean | 启用请求内容审核。默认值：`true` |
-| check_response | 否 | Boolean | 启用响应内容审核。默认值：`false` |
-| stream_check_mode | 否 | String | 流式审核模式。默认值：`"final_packet"`。有效值：`["realtime", "final_packet"]` |
-| stream_check_cache_size | 否 | Integer | 实时模式下每次审核批次的最大字符数。默认值：`128`。必须 `>= 1` |
-| stream_check_interval | 否 | Number | 实时模式下批次检查之间的间隔秒数。默认值：`3`。必须 `>= 0.1` |
-| request_check_service | 否 | String | 用于请求审核的阿里云服务。默认值：`"llm_query_moderation"` |
-| request_check_length_limit | 否 | Number | 每个请求审核块的最大字符数。默认值：`2000` |
-| response_check_service | 否 | String | 用于响应审核的阿里云服务。默认值：`"llm_response_moderation"` |
-| response_check_length_limit | 否 | Number | 每个响应审核块的最大字符数。默认值：`5000` |
-| risk_level_bar | 否 | String | 内容拒绝的阈值。默认值：`"high"`。有效值：`["none", "low", "medium", "high", "max"]` |
-| deny_code | 否 | Number | 被拒绝内容的 HTTP 状态码。默认值：`200` |
-| deny_message | 否 | String | 被拒绝内容的自定义消息。默认值：`-` |
-| timeout | 否 | Integer | 请求超时时间（毫秒）。默认值：`10000`。必须 `>= 1` |
-| ssl_verify | 否 | Boolean | 启用 SSL 证书验证。默认值：`true` |
-
-## 使用示例
-
-首先初始化这些 shell 变量：
+`ai-aliyun-content-moderation` 插件集成了[阿里云机器辅助审核 Plus](https://help.aliyun.com/document_detail/2671445.html)，用于在代理 LLM 请求时检查请求和响应内容的风险等级，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，当评估结果超过配置的阈值时拒绝请求。
+
+请确保在插件中正确配置 `access_key_secret`。如果配置错误，所有请求将绕过插件直接转发到 LLM 上游，并且您将在网关的错误日志中看到来自插件的 `Specified signature is not matched with our calculation` 错误。
+
+`ai-aliyun-content-moderation` 插件应与 [`ai-proxy`](./ai-proxy.md) 或 [`ai-proxy-multi`](./ai-proxy-multi.md) 插件配合使用以代理 LLM 请求。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| access_key_id | string | True | | | 阿里云访问密钥 ID。 |
+| access_key_secret | string | True | | | 阿里云访问密钥。该值在存储到 etcd 之前会使用 AES 加密。 |
+| region_id | string | True | | | 阿里云区域 ID。 |
+| endpoint | string | True | | | 阿里云端点。 |
+| check_request | boolean | False | `true` | | 如果为 `true`，则审核请求内容。 |
+| check_response | boolean | False | `false` | | 如果为 `true`，则审核响应内容。 |
+| stream_check_mode | string | False | `"final_packet"` | `realtime`、`final_packet` | 流式审核模式。`realtime`：流式传输期间批量检查。`final_packet`：在最后附加风险等级。 |
+| stream_check_cache_size | integer | False | `128` | >= 1 | `realtime` 模式下每次审核批次的最大字符数。 |
+| stream_check_interval | number | False | `3` | >= 0.1 | `realtime` 模式下批次检查之间的间隔秒数。 |
+| request_check_service | string | False | `"llm_query_moderation"` | | 用于请求审核的阿里云服务。 |
+| request_check_length_limit | number | False | `2000` | | 请求内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果请求内容有 250 个字符，且 `request_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| response_check_service | string | False | `"llm_response_moderation"` | | 用于响应审核的阿里云服务。 |
+| response_check_length_limit | number | False | `5000` | | 响应内容字符数上限。如果超过该限制，内容将被分块发送。例如，如果响应内容有 250 个字符，且 `response_check_length_limit` 设置为 `100`，则内容将分 3 次请求发送到阿里云。 |
+| risk_level_bar | string | False | `"high"` | `none`、`low`、`medium`、`high`、`max` | 如果评估的风险等级低于 `risk_level_bar`，请求或响应将分别被放行到上游 LLM 或客户端。 |
+| deny_code | number | False | `200` | | 拒绝时的 HTTP 状态码。 |
+| deny_message | string | False | | | 拒绝时的消息。 |
+| timeout | integer | False | `10000` | >= 1 | 超时时间（毫秒）。 |
+| keepalive | boolean | False | `true` | | 如果为 `true`，启用到阿里云的 HTTP 连接保活。 |
+| keepalive_pool | integer | False | `30` | >= 1 | 连接保活池的最大连接数。 |
+| keepalive_timeout | integer | False | `60000` | >= 1000 | 连接保活超时时间（毫秒）。 |
+| ssl_verify | boolean | False | `true` | | 如果为 `true`，启用 SSL 证书验证。 |
+
+## 示例
+
+以下示例使用 OpenAI 作为上游服务提供商。在开始之前，请创建一个 [OpenAI 账号](https://openai.com) 并获取 [API 密钥](https://openai.com/blog/openai-api)。如果您使用其他 LLM 提供商，请参考相应提供商的文档获取 API 密钥。
+
+此外，创建一个[阿里云账号](https://www.aliyun.com)，开通机器辅助审核 Plus 服务，并获取端点、区域 ID、访问密钥 ID 和访问密钥。
+
+:::note
+
+您可以使用以下命令从 `config.yaml` 中获取 `admin_key` 并保存到环境变量中：
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+您可以选择将阿里云和 OpenAI 信息保存到环境变量：
```shell
-ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1
-ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
-ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
-ALIYUN_REGION=cn-hangzhou
-ALIYUN_ENDPOINT=https://green.cn-hangzhou.aliyuncs.com
-OPENAI_KEY=your-openai-api-key
+# 替换为您的数据
+export OPENAI_API_KEY=your-openai-api-key
+export ALIYUN_ENDPOINT=https://green-cip.cn-shanghai.aliyuncs.com
+export ALIYUN_REGION_ID=cn-shanghai
+export ALIYUN_ACCESS_KEY_ID=your-aliyun-access-key-id
+export ALIYUN_ACCESS_KEY_SECRET=your-aliyun-access-key-secret
```
-创建一个带有 `ai-aliyun-content-moderation` 和 `ai-proxy` 插件的路由：
+### 审核请求内容毒性
+
+以下示例演示如何使用该插件审核请求中的内容毒性并自定义拒绝代码和消息。
+
+<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">
+
+创建一个路由到 LLM 聊天补全端点，使用 [`ai-proxy`](./ai-proxy.md) 插件，并在 `ai-aliyun-content-moderation` 插件中配置集成详情以及 `deny_code` 和 `deny_message`：
```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-aliyun-content-moderation-route",
+ "uri": "/anything",
"plugins": {
+ "ai-aliyun-content-moderation": {
+ "endpoint": "'"$ALIYUN_ENDPOINT"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
+ "access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
+ "access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
+ "deny_code": 400,
+ "deny_message": "Request contains forbidden content, such as hate speech or violence."
+ },
"ai-proxy": {
"provider": "openai",
"auth": {
"header": {
- "Authorization": "Bearer '"$OPENAI_KEY"'"
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
}
- },
- "override": {
- "endpoint": "http://localhost:6724/v1/chat/completions"
}
+ }
+ }
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+```
+
+将配置同步到网关：
+
+```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">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="ai-aliyun-moderation-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f ai-aliyun-moderation-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+向该路由发送一个 POST 请求，请求体中包含系统提示和一个含有不当用语的用户问题：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "gpt-4",
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+您应该收到 `HTTP/1.1 400 Bad Request` 响应并看到以下消息：
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
},
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+向该路由发送另一个包含正常问题的请求：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "What is 1+1?" }
+ ]
+ }'
+```
+
+您应该收到 `HTTP/1.1 200 OK` 响应和模型输出：
+
+```json
+{
+ "model": "gpt-4-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": "1+1 equals 2.",
+ "refusal": null
+ },
+ "logprobs": null,
+ "finish_reason": "stop"
+ }
+ ]
+}
+```
+
+### 调整风险等级阈值
+
+以下示例演示如何调整风险等级的阈值，该阈值用于控制请求或响应是否应被放行。
+
+<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">
+
+创建一个路由到 LLM 聊天补全端点，使用 [`ai-proxy`](./ai-proxy.md) 插件，并将 `ai-aliyun-content-moderation` 中的 `risk_level_bar` 配置为 `high`：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "ai-aliyun-content-moderation-route",
+ "uri": "/anything",
+ "plugins": {
"ai-aliyun-content-moderation": {
"endpoint": "'"$ALIYUN_ENDPOINT"'",
- "region_id": "'"$ALIYUN_REGION"'",
+ "region_id": "'"$ALIYUN_REGION_ID"'",
"access_key_id": "'"$ALIYUN_ACCESS_KEY_ID"'",
"access_key_secret": "'"$ALIYUN_ACCESS_KEY_SECRET"'",
- "risk_level_bar": "high",
- "check_request": true,
- "check_response": true,
"deny_code": 400,
- "deny_message": "您的请求违反了内容政策"
+ "deny_message": "Request contains forbidden content, such as hate speech or violence.",
+ "risk_level_bar": "high"
+ },
+ "ai-proxy": {
+ "provider": "openai",
+ "auth": {
+ "header": {
+ "Authorization": "Bearer '"$OPENAI_API_KEY"'"
+ }
+ },
+ "model": "gpt-4"
}
}
}'
```
-这里使用 `ai-proxy` 插件是因为它简化了对 LLM 的访问。不过，您也可以在上游配置中配置 LLM。
+</TabItem>
+
+<TabItem value="adc">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="adc.yaml"
+services:
+ - name: aliyun-moderation-service
+ routes:
+ - name: aliyun-moderation-route
+ uris:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ ai-aliyun-content-moderation:
+ endpoint: "${ALIYUN_ENDPOINT}"
+ region_id: "${ALIYUN_REGION_ID}"
+ access_key_id: "${ALIYUN_ACCESS_KEY_ID}"
+ access_key_secret: "${ALIYUN_ACCESS_KEY_SECRET}"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ risk_level_bar: high
+ ai-proxy:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer ${OPENAI_API_KEY}"
+ options:
+ model: gpt-4
+```
+
+将配置同步到网关：
+
+```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">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
-现在发送一个请求：
+```yaml title="ai-aliyun-moderation-threshold-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: ai-aliyun-moderation-plugin-config
+spec:
+ plugins:
+ - name: ai-aliyun-content-moderation
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ risk_level_bar: high
+ - name: ai-proxy
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+ options:
+ model: gpt-4
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-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-aliyun-moderation-plugin-config
+```
+
+将配置应用到集群：
```shell
-curl http://127.0.0.1:9080/v1/chat/completions -i \
+kubectl apply -f ai-aliyun-moderation-threshold-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+创建一个配置了 `ai-aliyun-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由：
+
+```yaml title="ai-aliyun-moderation-threshold-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: aliyun-moderation-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: aliyun-moderation-route
+ match:
+ paths:
+ - /anything
+ methods:
+ - POST
+ plugins:
+ - name: ai-aliyun-content-moderation
+ enable: true
+ config:
+ endpoint: "https://green-cip.cn-shanghai.aliyuncs.com"
+ region_id: "cn-shanghai"
+ access_key_id: "your-aliyun-access-key-id"
+ access_key_secret: "your-aliyun-access-key-secret"
+ deny_code: 400
+ deny_message: "Request contains forbidden content, such as hate speech or violence."
+ risk_level_bar: high
+ - name: ai-proxy
+ enable: true
+ config:
+ provider: openai
+ auth:
+ header:
+ Authorization: "Bearer your-openai-api-key"
+ options:
+ model: gpt-4
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f ai-aliyun-moderation-threshold-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+向该路由发送一个 POST 请求，请求体中包含系统提示和一个含有不当用语的用户问题：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
-H "Content-Type: application/json" \
-d '{
- "model": "gpt-3.5-turbo",
+ "model": "gpt-4",
"messages": [
- {"role": "user", "content": "I want to kill you"}
- ],
- "stream": false
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
+```
+
+您应该收到 `HTTP/1.1 400 Bad Request` 响应并看到以下消息：
+
+```json
+{
+ "object": "chat.completion",
+ "usage": {
+ "completion_tokens": 0,
+ "prompt_tokens": 0,
+ "total_tokens": 0
+ },
+ "choices": [
+ {
+ "message": {
+ "role": "assistant",
+ "content": "Request contains forbidden content, such as hate speech or violence."
+ },
+ "finish_reason": "stop",
+ "index": 0
+ }
+ ],
+ "model": "gpt-4",
+ "id": "c9466bbf-e010-469d-949a-a10f25525964"
+}
+```
+
+将插件中的 `risk_level_bar` 更新为 `max`：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/ai-aliyun-content-moderation-route" -X PATCH \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "plugins": {
+ "ai-aliyun-content-moderation": {
+ "risk_level_bar": "max"
+ }
+ }
}'
```
-然后请求将被阻止，并返回如下错误：
+发送相同的请求到该路由：
-```text
-HTTP/1.1 400 Bad Request
-Content-Type: application/json
+```shell
+curl -i "http://127.0.0.1:9080/anything" -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ { "role": "system", "content": "You are a mathematician" },
+ { "role": "user", "content": "Stupid, what is 1+1?" }
+ ]
+ }'
Review Comment:
该“相同请求”示例缺少 `model` 字段。除非路由配置里设置了 `ai-proxy.options.model`，否则 OpenAI 兼容的聊天补全请求会因为缺少 `model` 而在上游失败。请在该请求中补充 `"model": ...`，或在路由示例里配置 `ai-proxy.options.model`。
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update ai-aliyun-content-moderation plugin documentation [apisix]
Posted by "kayx23 (via GitHub)" <gi...@apache.org>.
kayx23 commented on code in PR #13167:
URL: https://github.com/apache/apisix/pull/13167#discussion_r3109783148
##########
docs/en/latest/plugins/ai-aliyun-content-moderation.md:
##########
@@ -27,103 +30,646 @@ description: This document contains information about the Apache APISIX ai-aliyu
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/ai-aliyun-content-moderation" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
-The `ai-aliyun-content-moderation` plugin integrates with Aliyun's content moderation service to check both request and response content for inappropriate material when working with LLMs. It supports both real-time streaming checks and final packet moderation.
-
-This plugin must be used in routes that utilize the ai-proxy or ai-proxy-multi plugins.
-
-## Plugin Attributes
-
-| **Field** | **Required** | **Type** | **Description** |
-| ---------------------------- | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| endpoint | Yes | String | Aliyun service endpoint URL |
-| region_id | Yes | String | Aliyun region identifier |
-| access_key_id | Yes | String | Aliyun access key ID |
-| access_key_secret | Yes | String | Aliyun access key secret |
-| check_request | No | Boolean | Enable request content moderation. Default: `true` |
-| check_response | No | Boolean | Enable response content moderation. Default: `false` |
-| stream_check_mode | No | String | Streaming moderation mode. Default: `"final_packet"`. Valid values: `["realtime", "final_packet"]` |
-| stream_check_cache_size | No | Integer | Max characters per moderation batch in realtime mode. Default: `128`. Must be `>= 1`. |
-| stream_check_interval | No | Number | Seconds between batch checks in realtime mode. Default: `3`. Must be `>= 0.1`. |
-| request_check_service | No | String | Aliyun service for request moderation. Default: `"llm_query_moderation"` |
-| request_check_length_limit | No | Number | Max characters per request moderation chunk. Default: `2000`. |
-| response_check_service | No | String | Aliyun service for response moderation. Default: `"llm_response_moderation"` |
-| response_check_length_limit | No | Number | Max characters per response moderation chunk. Default: `5000`. |
-| risk_level_bar | No | String | Threshold for content rejection. Default: `"high"`. Valid values: `["none", "low", "medium", "high", "max"]` |
-| deny_code | No | Number | HTTP status code for rejected content. Default: `200`. |
-| deny_message | No | String | Custom message for rejected content. Default: `-`. |
-| timeout | No | Integer | Request timeout in milliseconds. Default: `10000`. Must be `>= 1`. |
-| ssl_verify | No | Boolean | Enable SSL certificate verification. Default: `true`. |
-
-## Example usage
-
-First initialise these shell variables:
+The `ai-aliyun-content-moderation` Plugin integrates with [Aliyun Machine-Assisted Moderation Plus](https://help.aliyun.com/document_detail/2671445.html) to check request and response content for risk level when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold.
+
+Please ensure that the `access_key_secret` is correctly configured in the Plugin. If misconfigured, all requests will bypass the Plugin to be directly forwarded to the LLM Upstream, and you will see a `Specified signature is not matched with our calculation` error in the gateway's error log from the Plugin.
Review Comment:
The implementation does log the Aliyun signature error and then allows the request to continue when moderation fails, but this wording feels stronger than what the code actually guarantees. It is not really an intentional “bypass” mode tied specifically to `access_key_secret`; it is a moderation-call failure path. Suggest softening this to say the moderation check fails and the request may still be forwarded upstream, rather than stating that all requests will bypass the plugin directly.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org