Copilot commented on code in PR #13211: URL: https://github.com/apache/apisix/pull/13211#discussion_r3076950612
########## docs/zh/latest/plugins/ai-aws-content-moderation.md: ########## @@ -29,221 +29,532 @@ description: 本文档包含有关 Apache APISIX ai-aws-content-moderation 插 # --> -## 描述 +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ai-aws-content-moderation"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -`ai-aws-content-moderation` 插件处理请求体以检查毒性内容，如果超过配置的阈值则拒绝请求。 +## 描述 -**_此插件只能在代理请求到 LLM 的路由中使用。_** +`ai-aws-content-moderation` 插件集成了 [AWS Comprehend](https://aws.amazon.com/comprehend/)，用于在代理请求到 LLM 时检查请求体中的有害内容，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，如果评估结果超过配置的阈值则拒绝请求。 -**_目前，该插件仅支持与 [AWS Comprehend](https://aws.amazon.com/comprehend/) 的集成进行内容审核。欢迎提交 PR 以引入对其他服务提供商的支持。_** +此插件只能在代理请求到 LLM 的路由中使用。 ## 插件属性 -| **字段** | **必选项** | **类型** | **描述** | -| ---------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| comprehend.access_key_id | 是 | String | AWS 访问密钥 ID | -| comprehend.secret_access_key | 是 | String | AWS 秘密访问密钥 | -| comprehend.region | 是 | String | AWS 区域 | -| comprehend.endpoint | 否 | String | AWS Comprehend 服务端点。必须匹配模式 `^https?://` | -| comprehend.ssl_verify | 否 | String | 启用 SSL 证书验证 | -| moderation_categories | 否 | Object | 审核类别及其分数的键值对。在每个对中，键应该是 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；值应该在 0 和 1 之间（包含） | -| moderation_threshold | 否 | Number | 内容有害、冒犯或不当的程度。较高的值表示允许更多毒性内容。范围：0 - 1。默认值：0.5 | +| **字段** | **必选项** | **类型** | **描述** | +| --- | --- | --- | --- | +| `comprehend` | True | object | [AWS Comprehend](https://aws.amazon.com/comprehend/) 配置。 | +| `comprehend.access_key_id` | True | string | AWS 访问密钥 ID。 | +| `comprehend.secret_access_key` | True | string | AWS 秘密访问密钥。 | +| `comprehend.region` | True | string | AWS 区域。 | +| `comprehend.endpoint` | False | string | AWS Comprehend 服务端点。必须匹配模式 `^https?://`。 | Review Comment: `comprehend.endpoint` 的说明与英文版本不一致：英文写明未设置时默认 `https://comprehend.{region}.amazonaws.com`，但中文仅描述了 URL 匹配模式。建议补充默认端点（并在需要时保留匹配模式约束），避免读者误以为必须显式配置该字段。 ```suggestion | `comprehend.endpoint` | False | string | AWS Comprehend 服务端点。未设置时默认为 `https://comprehend.{region}.amazonaws.com`。如果设置，必须匹配模式 `^https?://`。 | ``` ########## docs/en/latest/plugins/ai-aws-content-moderation.md: ########## @@ -27,221 +27,532 @@ description: This document contains information about the Apache APISIX ai-aws-c # --> -## Description +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ai-aws-content-moderation"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -The `ai-aws-content-moderation` plugin processes the request body to check for toxicity and rejects the request if it exceeds the configured threshold. +## Description -**_This plugin must be used in routes that proxy requests to LLMs only._** +The `ai-aws-content-moderation` Plugin integrates with [AWS Comprehend](https://aws.amazon.com/comprehend/) to check request bodies for toxicity when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold. -**_As of now, the plugin only supports the integration with [AWS Comprehend](https://aws.amazon.com/comprehend/) for content moderation. PRs for introducing support for other service providers are welcomed._** +This Plugin must be used in Routes that proxy requests to LLMs only. ## Plugin Attributes -| **Field** | **Required** | **Type** | **Description** | -| ---------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| comprehend.access_key_id | Yes | String | AWS access key ID | -| comprehend.secret_access_key | Yes | String | AWS secret access key | -| comprehend.region | Yes | String | AWS region | -| comprehend.endpoint | No | String | AWS Comprehend service endpoint. Must match the pattern `^https?://` | -| comprehend.ssl_verify | No | String | Enables SSL certificate verification. | -| moderation_categories | No | Object | Key-value pairs of moderation category and their score. In each pair, the key should be one of the `PROFANITY`, `HATE_SPEECH`, `INSULT`, `HARASSMENT_OR_ABUSE`, `SEXUAL`, or `VIOLENCE_OR_THREAT`; and the value should be between 0 and 1 (inclusive). | -| moderation_threshold | No | Number | The degree to which content is harmful, offensive, or inappropriate. A higher value indicates more toxic content allowed. Range: 0 - 1. Default: 0.5 | +| **Field** | **Required** | **Type** | **Description** | +| --- | --- | --- | --- | +| `comprehend` | True | object | [AWS Comprehend](https://aws.amazon.com/comprehend/) configurations. | +| `comprehend.access_key_id` | True | string | AWS access key ID. | +| `comprehend.secret_access_key` | True | string | AWS secret access key. | +| `comprehend.region` | True | string | AWS region. | +| `comprehend.endpoint` | False | string | AWS Comprehend service endpoint. If not set, defaults to `https://comprehend.{region}.amazonaws.com`. | +| `comprehend.ssl_verify` | False | boolean | If true, enable TLS certificate verification. Default: `true`. | +| `moderation_categories` | False | object | Key-value pairs of moderation category and their corresponding threshold. In each pair, the key should be one of `PROFANITY`, `HATE_SPEECH`, `INSULT`, `HARASSMENT_OR_ABUSE`, `SEXUAL`, or `VIOLENCE_OR_THREAT`; and the threshold value should be between 0 and 1 (inclusive). | +| `moderation_threshold` | False | number | Overall toxicity threshold. A higher value means more toxic content allowed. This option differs from the individual category thresholds in `moderation_categories`. For example, if `moderation_categories` is set with a `PROFANITY` threshold of `0.5`, and a request has a `PROFANITY` score of `0.1`, the request will not exceed the category threshold. However, if the request has other categories like `SEXUAL` or `VIOLENCE_OR_THREAT` exceeding the `moderation_threshold`, the request will be rejected. Default: `0.5`. Range: 0 - 1. | + +## 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 [AWS IAM user access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for APISIX to access [AWS Comprehend](https://aws.amazon.com/comprehend/). -## Example usage +You can optionally save these keys to environment variables: -First initialise these shell variables: +```shell +export OPENAI_API_KEY=your-openai-api-key +export AWS_ACCESS_KEY=your-aws-access-key-id +export AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key +``` + +### Moderate Profanity + +The following example demonstrates how you can use the Plugin to moderate the level of profanity in prompts. The profanity threshold is set to a low value (`0.1`) to allow only a low degree of profanity. + +:::note + +You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```shell -ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1 -ACCESS_KEY_ID=aws-comprehend-access-key-id-here -SECRET_ACCESS_KEY=aws-comprehend-secret-access-key-here -OPENAI_KEY=open-ai-key-here +admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') ``` -Create a route with the `ai-aws-content-moderation` and `ai-proxy` plugin like so: +::: + +<Tabs groupId="api"> +<TabItem value="admin-api" label="Admin API"> + +Create a Route to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the allowed profanity level in `ai-aws-content-moderation`: ```shell curl "http://127.0.0.1:9180/apisix/admin/routes/1"; -X PUT \ - -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -H "X-API-KEY: ${admin_key}" \ -d '{ "uri": "/post", "plugins": { "ai-aws-content-moderation": { "comprehend": { - "access_key_id": "'"$ACCESS_KEY_ID"'", - "secret_access_key": "'"$SECRET_ACCESS_KEY"'", + "access_key_id": "'"$AWS_ACCESS_KEY"'", + "secret_access_key": "'"$AWS_SECRET_ACCESS_KEY"'", "region": "us-east-1" }, "moderation_categories": { - "PROFANITY": 0.5 + "PROFANITY": 0.1 } }, "ai-proxy": { + "provider": "openai", "auth": { "header": { - "api-key": "'"$OPENAI_KEY"'" + "Authorization": "Bearer '"$OPENAI_API_KEY"'" } }, - "model": { - "provider": "openai", - "name": "gpt-4", - "options": { - "max_tokens": 512, - "temperature": 1.0 - } - } - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "httpbin.org:80": 1 + "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" label="ADC"> + +Create a Route with the `ai-aws-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such: + +```yaml title="adc.yaml" +services: + - name: aws-moderation-service + routes: + - name: aws-moderation-route + uris: + - /post + methods: + - POST + plugins: + ai-aws-content-moderation: + comprehend: + access_key_id: "${AWS_ACCESS_KEY}" + secret_access_key: "${AWS_SECRET_ACCESS_KEY}" + region: us-east-1 + moderation_categories: + PROFANITY: 0.1 + ai-proxy: + provider: openai + auth: + header: + Authorization: "Bearer ${OPENAI_API_KEY}" + options: + model: gpt-4 +``` -Now send a request: +Synchronize the configuration to the gateway: ```shell -curl http://127.0.0.1:9080/post -i -XPOST -H 'Content-Type: application/json' -d '{ - "messages": [ - { - "role": "user", - "content": "<very profane message here>" - } - ] -}' +adc sync -f adc.yaml ``` -Then the request will be blocked with error like this: +</TabItem> +<TabItem value="ingress" label="Ingress Controller"> -```text -HTTP/1.1 400 Bad Request -Date: Thu, 03 Oct 2024 11:53:15 GMT -Content-Type: text/plain; charset=utf-8 -Transfer-Encoding: chunked -Connection: keep-alive -Server: APISIX/3.10.0 +<Tabs groupId="k8s-api"> +<TabItem value="gateway-api" label="Gateway API"> -request body exceeds PROFANITY threshold +Create a Route with the `ai-aws-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such: + +```yaml title="ai-aws-moderation-ic.yaml" +apiVersion: apisix.apache.org/v1alpha1 +kind: PluginConfig +metadata: + namespace: aic + name: ai-aws-moderation-plugin-config +spec: + plugins: + - name: ai-aws-content-moderation + config: + comprehend: + access_key_id: "your-aws-access-key-id" + secret_access_key: "your-aws-secret-access-key" + region: us-east-1 + moderation_categories: + PROFANITY: 0.1 + - name: ai-proxy + config: + provider: openai + auth: + header: + Authorization: "Bearer your-api-key" + options: + model: gpt-4 +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + namespace: aic + name: aws-moderation-route +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /post + method: POST + filters: + - type: ExtensionRef + extensionRef: + group: apisix.apache.org + kind: PluginConfig + name: ai-aws-moderation-plugin-config ``` -Send a request with compliant content in the request body: +</TabItem> +<TabItem value="ingress" label="APISIX Ingress Controller"> + +Create a Route with the `ai-aws-content-moderation` and [`ai-proxy`](./ai-proxy.md) Plugins configured as such: + +```yaml title="ai-aws-moderation-ic.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + namespace: aic + name: aws-moderation-route +spec: + ingressClassName: apisix + http: + - name: aws-moderation-route + match: + paths: + - /post + methods: + - POST + plugins: + - name: ai-aws-content-moderation + enable: true + config: + comprehend: + access_key_id: "your-aws-access-key-id" + secret_access_key: "your-aws-secret-access-key" + region: us-east-1 + moderation_categories: + PROFANITY: 0.1 + - name: ai-proxy + enable: true + config: + provider: openai + auth: + header: + Authorization: "Bearer your-api-key" + options: + model: gpt-4 +``` + +</TabItem> +</Tabs> + +Apply the configuration to your cluster: ```shell -curl http://127.0.0.1:9080/post -i -XPOST -H 'Content-Type: application/json' -d '{ - "messages": [ - { - "role": "system", - "content": "You are a mathematician" - }, - { "role": "user", "content": "What is 1+1?" } - ] -}' +kubectl apply -f ai-aws-moderation-ic.yaml +``` + +</TabItem> +</Tabs> + +Send a POST request to the Route with a system prompt and a user question with a mildly profane word in the request body: + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + { "role": "system", "content": "You are a mathematician" }, + { "role": "user", "content": "Stupid, what is 1+1?" } + ] + }' ``` -This request will be proxied normally to the configured LLM. +You should receive an `HTTP/1.1 400 Bad Request` response and see the following message: ```text -HTTP/1.1 200 OK -Date: Thu, 03 Oct 2024 11:53:00 GMT -Content-Type: text/plain; charset=utf-8 -Transfer-Encoding: chunked -Connection: keep-alive -Server: APISIX/3.10.0 +request body exceeds PROFANITY threshold +``` + +Send another request to the Route with a typical question in the request body: + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + { "role": "system", "content": "You are a mathematician" }, + { "role": "user", "content": "What is 1+1?" } + ] + }' +``` -{"choices":[{"finish_reason":"stop","index":0,"message":{"content":"1+1 equals 2.","role":"assistant"}}],"created":1727956380,"id":"chatcmpl-AEEg8Pe5BAW5Sw3C1gdwXnuyulIkY","model":"gpt-4o-2024-05-13","object":"chat.completion","system_fingerprint":"fp_67802d9a6d","usage":{"completion_tokens":7,"prompt_tokens":23,"total_tokens":30}} +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" + } + ], + ... +} ``` -You can also configure filters on other moderation categories like so: +### Moderate Overall Toxicity + +The following example demonstrates how you can use the Plugin to moderate the overall toxicity level in prompts, in addition to moderating individual categories. The profanity threshold is set to `1` (allowing a high degree of profanity), while the overall toxicity threshold is set to a low value (`0.2`). + +<Tabs groupId="api"> +<TabItem value="admin-api" label="Admin API"> + +Create a Route to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the allowed profanity and overall toxicity levels in `ai-aws-content-moderation`: ```shell curl "http://127.0.0.1:9180/apisix/admin/routes/1"; -X PUT \ - -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -H "X-API-KEY: ${admin_key}" \ -d '{ "uri": "/post", "plugins": { "ai-aws-content-moderation": { "comprehend": { - "access_key_id": "'"$ACCESS_KEY_ID"'", - "secret_access_key": "'"$SECRET_ACCESS_KEY"'", + "access_key_id": "'"$AWS_ACCESS_KEY"'", + "secret_access_key": "'"$AWS_SECRET_ACCESS_KEY"'", "region": "us-east-1" }, "moderation_categories": { - "PROFANITY": 0.5, - "HARASSMENT_OR_ABUSE": 0.7, - "SEXUAL": 0.2 - } + "PROFANITY": 1 + }, + "moderation_threshold": 0.2 }, "ai-proxy": { + "provider": "openai", "auth": { "header": { - "api-key": "'"$OPENAI_KEY"'" + "Authorization": "Bearer '"$OPENAI_API_KEY"'" } }, - "model": { - "provider": "openai", - "name": "gpt-4", - "options": { - "max_tokens": 512, - "temperature": 1.0 - } - } - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "httpbin.org:80": 1 + "model": "gpt-4" Review Comment: Same issue as above: this Admin API example sets `ai-proxy.model`, but the documented configuration is `ai-proxy.options.model`. Please move the model into `options` for consistency and to prevent a non-working example. ```suggestion "options": { "model": "gpt-4" } ``` ########## docs/zh/latest/plugins/ai-aws-content-moderation.md: ########## @@ -29,221 +29,532 @@ description: 本文档包含有关 Apache APISIX ai-aws-content-moderation 插 # --> -## 描述 +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ai-aws-content-moderation"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -`ai-aws-content-moderation` 插件处理请求体以检查毒性内容，如果超过配置的阈值则拒绝请求。 +## 描述 -**_此插件只能在代理请求到 LLM 的路由中使用。_** +`ai-aws-content-moderation` 插件集成了 [AWS Comprehend](https://aws.amazon.com/comprehend/)，用于在代理请求到 LLM 时检查请求体中的有害内容，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，如果评估结果超过配置的阈值则拒绝请求。 -**_目前，该插件仅支持与 [AWS Comprehend](https://aws.amazon.com/comprehend/) 的集成进行内容审核。欢迎提交 PR 以引入对其他服务提供商的支持。_** +此插件只能在代理请求到 LLM 的路由中使用。 ## 插件属性 -| **字段** | **必选项** | **类型** | **描述** | -| ---------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| comprehend.access_key_id | 是 | String | AWS 访问密钥 ID | -| comprehend.secret_access_key | 是 | String | AWS 秘密访问密钥 | -| comprehend.region | 是 | String | AWS 区域 | -| comprehend.endpoint | 否 | String | AWS Comprehend 服务端点。必须匹配模式 `^https?://` | -| comprehend.ssl_verify | 否 | String | 启用 SSL 证书验证 | -| moderation_categories | 否 | Object | 审核类别及其分数的键值对。在每个对中，键应该是 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；值应该在 0 和 1 之间（包含） | -| moderation_threshold | 否 | Number | 内容有害、冒犯或不当的程度。较高的值表示允许更多毒性内容。范围：0 - 1。默认值：0.5 | +| **字段** | **必选项** | **类型** | **描述** | +| --- | --- | --- | --- | +| `comprehend` | True | object | [AWS Comprehend](https://aws.amazon.com/comprehend/) 配置。 | +| `comprehend.access_key_id` | True | string | AWS 访问密钥 ID。 | +| `comprehend.secret_access_key` | True | string | AWS 秘密访问密钥。 | +| `comprehend.region` | True | string | AWS 区域。 | +| `comprehend.endpoint` | False | string | AWS Comprehend 服务端点。必须匹配模式 `^https?://`。 | +| `comprehend.ssl_verify` | False | boolean | 如果为 true，则启用 TLS 证书验证。默认值：`true`。 | +| `moderation_categories` | False | object | 审核类别及其对应阈值的键值对。在每个键值对中，键应为 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；阈值应在 0 到 1 之间（包含）。 | +| `moderation_threshold` | False | number | 整体毒性阈值。值越高，允许的有害内容越多。此选项与 `moderation_categories` 中的单独类别阈值不同。例如，如果 `moderation_categories` 中设置了 `PROFANITY` 阈值为 `0.5`，而请求的 `PROFANITY` 分数为 `0.1`，则请求不会超过类别阈值。但如果请求的其他类别（如 `SEXUAL` 或 `VIOLENCE_OR_THREAT`）超过了 `moderation_threshold`，则请求将被拒绝。默认值：`0.5`。范围：0 - 1。 | Review Comment: 中文插件文档的表格里通常使用“是/否”表示必选项，并且类型多用 `String`/`Boolean` 等（例如 `docs/zh/latest/plugins/ai-proxy.md`、`ai-rate-limiting.md`）。这里新增的 `True/False` + `string/boolean` 风格与同目录中文文档不一致，建议统一为中文文档现有格式，提升一致性与可读性。 ```suggestion | `comprehend` | 是 | Object | [AWS Comprehend](https://aws.amazon.com/comprehend/) 配置。 | | `comprehend.access_key_id` | 是 | String | AWS 访问密钥 ID。 | | `comprehend.secret_access_key` | 是 | String | AWS 秘密访问密钥。 | | `comprehend.region` | 是 | String | AWS 区域。 | | `comprehend.endpoint` | 否 | String | AWS Comprehend 服务端点。必须匹配模式 `^https?://`。 | | `comprehend.ssl_verify` | 否 | Boolean | 如果为 true，则启用 TLS 证书验证。默认值：`true`。 | | `moderation_categories` | 否 | Object | 审核类别及其对应阈值的键值对。在每个键值对中，键应为 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；阈值应在 0 到 1 之间（包含）。 | | `moderation_threshold` | 否 | Number | 整体毒性阈值。值越高，允许的有害内容越多。此选项与 `moderation_categories` 中的单独类别阈值不同。例如，如果 `moderation_categories` 中设置了 `PROFANITY` 阈值为 `0.5`，而请求的 `PROFANITY` 分数为 `0.1`，则请求不会超过类别阈值。但如果请求的其他类别（如 `SEXUAL` 或 `VIOLENCE_OR_THREAT`）超过了 `moderation_threshold`，则请求将被拒绝。默认值：`0.5`。范围：0 - 1。 | ``` ########## docs/en/latest/plugins/ai-aws-content-moderation.md: ########## @@ -27,221 +27,532 @@ description: This document contains information about the Apache APISIX ai-aws-c # --> -## Description +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ai-aws-content-moderation"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -The `ai-aws-content-moderation` plugin processes the request body to check for toxicity and rejects the request if it exceeds the configured threshold. +## Description -**_This plugin must be used in routes that proxy requests to LLMs only._** +The `ai-aws-content-moderation` Plugin integrates with [AWS Comprehend](https://aws.amazon.com/comprehend/) to check request bodies for toxicity when proxying to LLMs, such as profanity, hate speech, insult, harassment, violence, and more, rejecting requests if the evaluated outcome exceeds the configured threshold. -**_As of now, the plugin only supports the integration with [AWS Comprehend](https://aws.amazon.com/comprehend/) for content moderation. PRs for introducing support for other service providers are welcomed._** +This Plugin must be used in Routes that proxy requests to LLMs only. ## Plugin Attributes -| **Field** | **Required** | **Type** | **Description** | -| ---------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| comprehend.access_key_id | Yes | String | AWS access key ID | -| comprehend.secret_access_key | Yes | String | AWS secret access key | -| comprehend.region | Yes | String | AWS region | -| comprehend.endpoint | No | String | AWS Comprehend service endpoint. Must match the pattern `^https?://` | -| comprehend.ssl_verify | No | String | Enables SSL certificate verification. | -| moderation_categories | No | Object | Key-value pairs of moderation category and their score. In each pair, the key should be one of the `PROFANITY`, `HATE_SPEECH`, `INSULT`, `HARASSMENT_OR_ABUSE`, `SEXUAL`, or `VIOLENCE_OR_THREAT`; and the value should be between 0 and 1 (inclusive). | -| moderation_threshold | No | Number | The degree to which content is harmful, offensive, or inappropriate. A higher value indicates more toxic content allowed. Range: 0 - 1. Default: 0.5 | +| **Field** | **Required** | **Type** | **Description** | +| --- | --- | --- | --- | +| `comprehend` | True | object | [AWS Comprehend](https://aws.amazon.com/comprehend/) configurations. | +| `comprehend.access_key_id` | True | string | AWS access key ID. | +| `comprehend.secret_access_key` | True | string | AWS secret access key. | +| `comprehend.region` | True | string | AWS region. | +| `comprehend.endpoint` | False | string | AWS Comprehend service endpoint. If not set, defaults to `https://comprehend.{region}.amazonaws.com`. | +| `comprehend.ssl_verify` | False | boolean | If true, enable TLS certificate verification. Default: `true`. | +| `moderation_categories` | False | object | Key-value pairs of moderation category and their corresponding threshold. In each pair, the key should be one of `PROFANITY`, `HATE_SPEECH`, `INSULT`, `HARASSMENT_OR_ABUSE`, `SEXUAL`, or `VIOLENCE_OR_THREAT`; and the threshold value should be between 0 and 1 (inclusive). | +| `moderation_threshold` | False | number | Overall toxicity threshold. A higher value means more toxic content allowed. This option differs from the individual category thresholds in `moderation_categories`. For example, if `moderation_categories` is set with a `PROFANITY` threshold of `0.5`, and a request has a `PROFANITY` score of `0.1`, the request will not exceed the category threshold. However, if the request has other categories like `SEXUAL` or `VIOLENCE_OR_THREAT` exceeding the `moderation_threshold`, the request will be rejected. Default: `0.5`. Range: 0 - 1. | + +## 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 [AWS IAM user access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for APISIX to access [AWS Comprehend](https://aws.amazon.com/comprehend/). -## Example usage +You can optionally save these keys to environment variables: -First initialise these shell variables: +```shell +export OPENAI_API_KEY=your-openai-api-key +export AWS_ACCESS_KEY=your-aws-access-key-id +export AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key +``` + +### Moderate Profanity + +The following example demonstrates how you can use the Plugin to moderate the level of profanity in prompts. The profanity threshold is set to a low value (`0.1`) to allow only a low degree of profanity. + +:::note + +You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```shell -ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1 -ACCESS_KEY_ID=aws-comprehend-access-key-id-here -SECRET_ACCESS_KEY=aws-comprehend-secret-access-key-here -OPENAI_KEY=open-ai-key-here +admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') ``` -Create a route with the `ai-aws-content-moderation` and `ai-proxy` plugin like so: +::: + +<Tabs groupId="api"> +<TabItem value="admin-api" label="Admin API"> + +Create a Route to the LLM chat completion endpoint using the [`ai-proxy`](./ai-proxy.md) Plugin and configure the allowed profanity level in `ai-aws-content-moderation`: ```shell curl "http://127.0.0.1:9180/apisix/admin/routes/1"; -X PUT \ - -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -H "X-API-KEY: ${admin_key}" \ -d '{ "uri": "/post", "plugins": { "ai-aws-content-moderation": { "comprehend": { - "access_key_id": "'"$ACCESS_KEY_ID"'", - "secret_access_key": "'"$SECRET_ACCESS_KEY"'", + "access_key_id": "'"$AWS_ACCESS_KEY"'", + "secret_access_key": "'"$AWS_SECRET_ACCESS_KEY"'", "region": "us-east-1" }, "moderation_categories": { - "PROFANITY": 0.5 + "PROFANITY": 0.1 } }, "ai-proxy": { + "provider": "openai", "auth": { "header": { - "api-key": "'"$OPENAI_KEY"'" + "Authorization": "Bearer '"$OPENAI_API_KEY"'" } }, - "model": { - "provider": "openai", - "name": "gpt-4", - "options": { - "max_tokens": 512, - "temperature": 1.0 - } - } - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "httpbin.org:80": 1 + "model": "gpt-4" Review Comment: In the Admin API example, `ai-proxy` is configured with a top-level `model` field, but `ai-proxy` docs and other examples use `options.model` (there is no documented top-level `model`). Update this example to configure the model under `ai-proxy.options.model` to avoid users copying a config that APISIX won’t recognize. ```suggestion "options": { "model": "gpt-4" } ``` ########## docs/zh/latest/plugins/ai-aws-content-moderation.md: ########## @@ -29,221 +29,532 @@ description: 本文档包含有关 Apache APISIX ai-aws-content-moderation 插 # --> -## 描述 +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ai-aws-content-moderation"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -`ai-aws-content-moderation` 插件处理请求体以检查毒性内容，如果超过配置的阈值则拒绝请求。 +## 描述 -**_此插件只能在代理请求到 LLM 的路由中使用。_** +`ai-aws-content-moderation` 插件集成了 [AWS Comprehend](https://aws.amazon.com/comprehend/)，用于在代理请求到 LLM 时检查请求体中的有害内容，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，如果评估结果超过配置的阈值则拒绝请求。 -**_目前，该插件仅支持与 [AWS Comprehend](https://aws.amazon.com/comprehend/) 的集成进行内容审核。欢迎提交 PR 以引入对其他服务提供商的支持。_** +此插件只能在代理请求到 LLM 的路由中使用。 ## 插件属性 -| **字段** | **必选项** | **类型** | **描述** | -| ---------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| comprehend.access_key_id | 是 | String | AWS 访问密钥 ID | -| comprehend.secret_access_key | 是 | String | AWS 秘密访问密钥 | -| comprehend.region | 是 | String | AWS 区域 | -| comprehend.endpoint | 否 | String | AWS Comprehend 服务端点。必须匹配模式 `^https?://` | -| comprehend.ssl_verify | 否 | String | 启用 SSL 证书验证 | -| moderation_categories | 否 | Object | 审核类别及其分数的键值对。在每个对中，键应该是 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；值应该在 0 和 1 之间（包含） | -| moderation_threshold | 否 | Number | 内容有害、冒犯或不当的程度。较高的值表示允许更多毒性内容。范围：0 - 1。默认值：0.5 | +| **字段** | **必选项** | **类型** | **描述** | +| --- | --- | --- | --- | +| `comprehend` | True | object | [AWS Comprehend](https://aws.amazon.com/comprehend/) 配置。 | +| `comprehend.access_key_id` | True | string | AWS 访问密钥 ID。 | +| `comprehend.secret_access_key` | True | string | AWS 秘密访问密钥。 | +| `comprehend.region` | True | string | AWS 区域。 | +| `comprehend.endpoint` | False | string | AWS Comprehend 服务端点。必须匹配模式 `^https?://`。 | +| `comprehend.ssl_verify` | False | boolean | 如果为 true，则启用 TLS 证书验证。默认值：`true`。 | +| `moderation_categories` | False | object | 审核类别及其对应阈值的键值对。在每个键值对中，键应为 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；阈值应在 0 到 1 之间（包含）。 | +| `moderation_threshold` | False | number | 整体毒性阈值。值越高，允许的有害内容越多。此选项与 `moderation_categories` 中的单独类别阈值不同。例如，如果 `moderation_categories` 中设置了 `PROFANITY` 阈值为 `0.5`，而请求的 `PROFANITY` 分数为 `0.1`，则请求不会超过类别阈值。但如果请求的其他类别（如 `SEXUAL` 或 `VIOLENCE_OR_THREAT`）超过了 `moderation_threshold`，则请求将被拒绝。默认值：`0.5`。范围：0 - 1。 | ## 使用示例 -首先初始化这些 shell 变量： +以下示例使用 OpenAI 作为上游服务提供商。 + +开始之前，请创建一个 [OpenAI 账户](https://openai.com) 并获取 [API 密钥](https://openai.com/blog/openai-api)。如果您使用其他 LLM 提供商，请参阅该提供商的文档获取 API 密钥。 + +此外，创建 [AWS IAM 用户访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) 以便 APISIX 访问 [AWS Comprehend](https://aws.amazon.com/comprehend/)。 + +您可以选择将这些密钥保存到环境变量中： + +```shell +export OPENAI_API_KEY=your-openai-api-key +export AWS_ACCESS_KEY=your-aws-access-key-id +export AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key +``` + +### 审核亵渎内容 + +以下示例演示如何使用该插件审核提示中的亵渎程度。亵渎阈值设置为较低的值（`0.1`），以仅允许较低程度的亵渎。 + +:::note + +您可以使用以下命令从 `config.yaml` 中获取 `admin_key` 并保存到环境变量中： ```shell -ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1 -ACCESS_KEY_ID=aws-comprehend-access-key-id-here -SECRET_ACCESS_KEY=aws-comprehend-secret-access-key-here -OPENAI_KEY=open-ai-key-here +admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') ``` -创建一个带有 `ai-aws-content-moderation` 和 `ai-proxy` 插件的路由： +::: + +<Tabs groupId="api"> +<TabItem value="admin-api" label="Admin API"> + +使用 [`ai-proxy`](./ai-proxy.md) 插件创建一个到 LLM 聊天补全端点的路由，并在 `ai-aws-content-moderation` 中配置允许的亵渎级别： ```shell curl "http://127.0.0.1:9180/apisix/admin/routes/1"; -X PUT \ - -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -H "X-API-KEY: ${admin_key}" \ -d '{ "uri": "/post", "plugins": { "ai-aws-content-moderation": { "comprehend": { - "access_key_id": "'"$ACCESS_KEY_ID"'", - "secret_access_key": "'"$SECRET_ACCESS_KEY"'", + "access_key_id": "'"$AWS_ACCESS_KEY"'", + "secret_access_key": "'"$AWS_SECRET_ACCESS_KEY"'", "region": "us-east-1" }, "moderation_categories": { - "PROFANITY": 0.5 + "PROFANITY": 0.1 } }, "ai-proxy": { + "provider": "openai", "auth": { "header": { - "api-key": "'"$OPENAI_KEY"'" + "Authorization": "Bearer '"$OPENAI_API_KEY"'" } }, - "model": { - "provider": "openai", - "name": "gpt-4", - "options": { - "max_tokens": 512, - "temperature": 1.0 - } - } - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "httpbin.org:80": 1 + "model": "gpt-4" } } }' ``` -这里使用 `ai-proxy` 插件是因为它简化了对 LLM 的访问。不过，您也可以在上游配置中配置 LLM。 +</TabItem> +<TabItem value="adc" label="ADC"> + +创建一个配置了 `ai-aws-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由： + +```yaml title="adc.yaml" +services: + - name: aws-moderation-service + routes: + - name: aws-moderation-route + uris: + - /post + methods: + - POST + plugins: + ai-aws-content-moderation: + comprehend: + access_key_id: "${AWS_ACCESS_KEY}" + secret_access_key: "${AWS_SECRET_ACCESS_KEY}" + region: us-east-1 + moderation_categories: + PROFANITY: 0.1 + ai-proxy: + provider: openai + auth: + header: + Authorization: "Bearer ${OPENAI_API_KEY}" + options: + model: gpt-4 +``` -现在发送一个请求： +将配置同步到网关： ```shell -curl http://127.0.0.1:9080/post -i -XPOST -H 'Content-Type: application/json' -d '{ - "messages": [ - { - "role": "user", - "content": "<very profane message here>" - } - ] -}' +adc sync -f adc.yaml ``` -然后请求将被阻止，并返回如下错误： +</TabItem> +<TabItem value="ingress" label="Ingress Controller"> -```text -HTTP/1.1 400 Bad Request -Date: Thu, 03 Oct 2024 11:53:15 GMT -Content-Type: text/plain; charset=utf-8 -Transfer-Encoding: chunked -Connection: keep-alive -Server: APISIX/3.10.0 +<Tabs groupId="k8s-api"> +<TabItem value="gateway-api" label="Gateway API"> -request body exceeds PROFANITY threshold +创建一个配置了 `ai-aws-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由： + +```yaml title="ai-aws-moderation-ic.yaml" +apiVersion: apisix.apache.org/v1alpha1 +kind: PluginConfig +metadata: + namespace: aic + name: ai-aws-moderation-plugin-config +spec: + plugins: + - name: ai-aws-content-moderation + config: + comprehend: + access_key_id: "your-aws-access-key-id" + secret_access_key: "your-aws-secret-access-key" + region: us-east-1 + moderation_categories: + PROFANITY: 0.1 + - name: ai-proxy + config: + provider: openai + auth: + header: + Authorization: "Bearer your-api-key" + options: + model: gpt-4 +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + namespace: aic + name: aws-moderation-route +spec: + parentRefs: + - name: apisix + rules: + - matches: + - path: + type: Exact + value: /post + method: POST + filters: + - type: ExtensionRef + extensionRef: + group: apisix.apache.org + kind: PluginConfig + name: ai-aws-moderation-plugin-config ``` -发送一个在请求体中包含合规内容的请求： +</TabItem> +<TabItem value="ingress" label="APISIX Ingress Controller"> + +创建一个配置了 `ai-aws-content-moderation` 和 [`ai-proxy`](./ai-proxy.md) 插件的路由： + +```yaml title="ai-aws-moderation-ic.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + namespace: aic + name: aws-moderation-route +spec: + ingressClassName: apisix + http: + - name: aws-moderation-route + match: + paths: + - /post + methods: + - POST + plugins: + - name: ai-aws-content-moderation + enable: true + config: + comprehend: + access_key_id: "your-aws-access-key-id" + secret_access_key: "your-aws-secret-access-key" + region: us-east-1 + moderation_categories: + PROFANITY: 0.1 + - name: ai-proxy + enable: true + config: + provider: openai + auth: + header: + Authorization: "Bearer your-api-key" + options: + model: gpt-4 +``` + +</TabItem> +</Tabs> + +将配置应用到集群： ```shell -curl http://127.0.0.1:9080/post -i -XPOST -H 'Content-Type: application/json' -d '{ - "messages": [ - { - "role": "system", - "content": "You are a mathematician" - }, - { "role": "user", "content": "What is 1+1?" } - ] -}' +kubectl apply -f ai-aws-moderation-ic.yaml +``` + +</TabItem> +</Tabs> + +向路由发送一个 POST 请求，请求体中包含系统提示和一个带有轻度亵渎词汇的用户问题： + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + { "role": "system", "content": "You are a mathematician" }, + { "role": "user", "content": "Stupid, what is 1+1?" } + ] + }' ``` -此请求将正常代理到配置的 LLM。 +您应该收到 `HTTP/1.1 400 Bad Request` 响应，并看到以下消息： ```text -HTTP/1.1 200 OK -Date: Thu, 03 Oct 2024 11:53:00 GMT -Content-Type: text/plain; charset=utf-8 -Transfer-Encoding: chunked -Connection: keep-alive -Server: APISIX/3.10.0 +request body exceeds PROFANITY threshold +``` + +向路由发送另一个包含正常问题的请求： + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + { "role": "system", "content": "You are a mathematician" }, + { "role": "user", "content": "What is 1+1?" } + ] + }' +``` -{"choices":[{"finish_reason":"stop","index":0,"message":{"content":"1+1 equals 2.","role":"assistant"}}],"created":1727956380,"id":"chatcmpl-AEEg8Pe5BAW5Sw3C1gdwXnuyulIkY","model":"gpt-4o-2024-05-13","object":"chat.completion","system_fingerprint":"fp_67802d9a6d","usage":{"completion_tokens":7,"prompt_tokens":23,"total_tokens":30}} +您应该收到 `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" + } + ], + ... +} ``` -您还可以配置其他审核类别的过滤器，如下所示： +### 审核整体毒性 + +以下示例演示如何使用该插件审核提示中的整体毒性水平，以及审核单独的类别。亵渎阈值设置为 `1`（允许高度亵渎），而整体毒性阈值设置为较低的值（`0.2`）。 + +<Tabs groupId="api"> +<TabItem value="admin-api" label="Admin API"> + +使用 [`ai-proxy`](./ai-proxy.md) 插件创建一个到 LLM 聊天补全端点的路由，并在 `ai-aws-content-moderation` 中配置允许的亵渎级别和整体毒性级别： ```shell curl "http://127.0.0.1:9180/apisix/admin/routes/1"; -X PUT \ - -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -H "X-API-KEY: ${admin_key}" \ -d '{ "uri": "/post", "plugins": { "ai-aws-content-moderation": { "comprehend": { - "access_key_id": "'"$ACCESS_KEY_ID"'", - "secret_access_key": "'"$SECRET_ACCESS_KEY"'", + "access_key_id": "'"$AWS_ACCESS_KEY"'", + "secret_access_key": "'"$AWS_SECRET_ACCESS_KEY"'", "region": "us-east-1" }, "moderation_categories": { - "PROFANITY": 0.5, - "HARASSMENT_OR_ABUSE": 0.7, - "SEXUAL": 0.2 - } + "PROFANITY": 1 + }, + "moderation_threshold": 0.2 }, "ai-proxy": { + "provider": "openai", "auth": { "header": { - "api-key": "'"$OPENAI_KEY"'" + "Authorization": "Bearer '"$OPENAI_API_KEY"'" } }, - "model": { - "provider": "openai", - "name": "gpt-4", - "options": { - "max_tokens": 512, - "temperature": 1.0 - } - } - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "httpbin.org:80": 1 + "model": "gpt-4" Review Comment: 同样的问题：这里的 Admin API 示例设置了 `ai-proxy.model`，但文档约定应为 `ai-proxy.options.model`。请将模型配置移动到 `options` 下，确保示例可用且与其他文档一致。 ```suggestion "options": { "model": "gpt-4" } ``` ########## docs/zh/latest/plugins/ai-aws-content-moderation.md: ########## @@ -29,221 +29,532 @@ description: 本文档包含有关 Apache APISIX ai-aws-content-moderation 插 # --> -## 描述 +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ai-aws-content-moderation"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -`ai-aws-content-moderation` 插件处理请求体以检查毒性内容，如果超过配置的阈值则拒绝请求。 +## 描述 -**_此插件只能在代理请求到 LLM 的路由中使用。_** +`ai-aws-content-moderation` 插件集成了 [AWS Comprehend](https://aws.amazon.com/comprehend/)，用于在代理请求到 LLM 时检查请求体中的有害内容，例如亵渎、仇恨言论、侮辱、骚扰、暴力等，如果评估结果超过配置的阈值则拒绝请求。 -**_目前，该插件仅支持与 [AWS Comprehend](https://aws.amazon.com/comprehend/) 的集成进行内容审核。欢迎提交 PR 以引入对其他服务提供商的支持。_** +此插件只能在代理请求到 LLM 的路由中使用。 ## 插件属性 -| **字段** | **必选项** | **类型** | **描述** | -| ---------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| comprehend.access_key_id | 是 | String | AWS 访问密钥 ID | -| comprehend.secret_access_key | 是 | String | AWS 秘密访问密钥 | -| comprehend.region | 是 | String | AWS 区域 | -| comprehend.endpoint | 否 | String | AWS Comprehend 服务端点。必须匹配模式 `^https?://` | -| comprehend.ssl_verify | 否 | String | 启用 SSL 证书验证 | -| moderation_categories | 否 | Object | 审核类别及其分数的键值对。在每个对中，键应该是 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；值应该在 0 和 1 之间（包含） | -| moderation_threshold | 否 | Number | 内容有害、冒犯或不当的程度。较高的值表示允许更多毒性内容。范围：0 - 1。默认值：0.5 | +| **字段** | **必选项** | **类型** | **描述** | +| --- | --- | --- | --- | +| `comprehend` | True | object | [AWS Comprehend](https://aws.amazon.com/comprehend/) 配置。 | +| `comprehend.access_key_id` | True | string | AWS 访问密钥 ID。 | +| `comprehend.secret_access_key` | True | string | AWS 秘密访问密钥。 | +| `comprehend.region` | True | string | AWS 区域。 | +| `comprehend.endpoint` | False | string | AWS Comprehend 服务端点。必须匹配模式 `^https?://`。 | +| `comprehend.ssl_verify` | False | boolean | 如果为 true，则启用 TLS 证书验证。默认值：`true`。 | +| `moderation_categories` | False | object | 审核类别及其对应阈值的键值对。在每个键值对中，键应为 `PROFANITY`、`HATE_SPEECH`、`INSULT`、`HARASSMENT_OR_ABUSE`、`SEXUAL` 或 `VIOLENCE_OR_THREAT` 之一；阈值应在 0 到 1 之间（包含）。 | +| `moderation_threshold` | False | number | 整体毒性阈值。值越高，允许的有害内容越多。此选项与 `moderation_categories` 中的单独类别阈值不同。例如，如果 `moderation_categories` 中设置了 `PROFANITY` 阈值为 `0.5`，而请求的 `PROFANITY` 分数为 `0.1`，则请求不会超过类别阈值。但如果请求的其他类别（如 `SEXUAL` 或 `VIOLENCE_OR_THREAT`）超过了 `moderation_threshold`，则请求将被拒绝。默认值：`0.5`。范围：0 - 1。 | ## 使用示例 -首先初始化这些 shell 变量： +以下示例使用 OpenAI 作为上游服务提供商。 + +开始之前，请创建一个 [OpenAI 账户](https://openai.com) 并获取 [API 密钥](https://openai.com/blog/openai-api)。如果您使用其他 LLM 提供商，请参阅该提供商的文档获取 API 密钥。 + +此外，创建 [AWS IAM 用户访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) 以便 APISIX 访问 [AWS Comprehend](https://aws.amazon.com/comprehend/)。 + +您可以选择将这些密钥保存到环境变量中： + +```shell +export OPENAI_API_KEY=your-openai-api-key +export AWS_ACCESS_KEY=your-aws-access-key-id +export AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key +``` + +### 审核亵渎内容 + +以下示例演示如何使用该插件审核提示中的亵渎程度。亵渎阈值设置为较低的值（`0.1`），以仅允许较低程度的亵渎。 + +:::note + +您可以使用以下命令从 `config.yaml` 中获取 `admin_key` 并保存到环境变量中： ```shell -ADMIN_API_KEY=edd1c9f034335f136f87ad84b625c8f1 -ACCESS_KEY_ID=aws-comprehend-access-key-id-here -SECRET_ACCESS_KEY=aws-comprehend-secret-access-key-here -OPENAI_KEY=open-ai-key-here +admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') ``` -创建一个带有 `ai-aws-content-moderation` 和 `ai-proxy` 插件的路由： +::: + +<Tabs groupId="api"> +<TabItem value="admin-api" label="Admin API"> + +使用 [`ai-proxy`](./ai-proxy.md) 插件创建一个到 LLM 聊天补全端点的路由，并在 `ai-aws-content-moderation` 中配置允许的亵渎级别： ```shell curl "http://127.0.0.1:9180/apisix/admin/routes/1"; -X PUT \ - -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -H "X-API-KEY: ${admin_key}" \ -d '{ "uri": "/post", "plugins": { "ai-aws-content-moderation": { "comprehend": { - "access_key_id": "'"$ACCESS_KEY_ID"'", - "secret_access_key": "'"$SECRET_ACCESS_KEY"'", + "access_key_id": "'"$AWS_ACCESS_KEY"'", + "secret_access_key": "'"$AWS_SECRET_ACCESS_KEY"'", "region": "us-east-1" }, "moderation_categories": { - "PROFANITY": 0.5 + "PROFANITY": 0.1 } }, "ai-proxy": { + "provider": "openai", "auth": { "header": { - "api-key": "'"$OPENAI_KEY"'" + "Authorization": "Bearer '"$OPENAI_API_KEY"'" } }, - "model": { - "provider": "openai", - "name": "gpt-4", - "options": { - "max_tokens": 512, - "temperature": 1.0 - } - } - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "httpbin.org:80": 1 + "model": "gpt-4" Review Comment: 在 Admin API 示例中，`ai-proxy` 使用了顶层字段 `model`。但根据仓库中 `ai-proxy` 文档/示例的配置方式，模型应配置在 `ai-proxy.options.model` 下。建议调整为 `options.model`，避免读者复制后配置不生效。 ```suggestion "options": { "model": "gpt-4" } ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
