# Alibaba Cloud AI Guardrails

Alibaba Cloud AI Guardrails keep the moderation policy in the [AI Guardrails console](https://www.aliyun.com/product/content-moderation/guardrail), and AISIX applies the policy's decision to gateway traffic through the `MultiModalGuard` API. Requests can be checked before they reach the upstream model, and responses can be checked before they reach callers. Every call also appears in the AI Guardrails console's own records, so you can audit decisions on the Alibaba Cloud side.

This is a different Alibaba Cloud product from [Alibaba Cloud Content Moderation](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/alibaba-cloud-ai.md) (`aliyun_text_moderation`, the `TextModerationPlus` API): it is activated and billed separately, its detection and blocking policies are configured in its own console, and only its calls appear in that console. Use this guardrail when you manage policy in the AI Guardrails console or need its composite checks — content compliance, prompt-attack detection, and sensitive-data handling in one call.

In this guide, you will create an Alibaba Cloud AI Guardrails resource, send one allowed request, and observe blocking and sensitive-data masking driven by the console policy.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before starting, prepare the following:

* Review [Guardrail Behavior](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/behavior.md) for hook points, enforcement modes, and remote failure handling.

* One of these configuration paths:

  <!-- -->

  * AISIX Enterprise or AISIX Cloud with an environment, an attached gateway, and a write-scoped admin token. For AISIX Enterprise, follow the [AISIX Enterprise getting-started guide](https://docs.api7.ai/ai-gateway/getting-started/aisix-cloud-quickstart.md). To request AISIX Cloud access, [contact API7](https://api7.ai/contact).
  * An open-source AISIX gateway that loads a declarative [`resources.yaml`](https://docs.api7.ai/ai-gateway/reference/resources-file.md) file.

* A working model alias and caller API key that can send Chat Completions requests.

* The Alibaba Cloud AI Guardrails service activated on your account (commodity `lvwang_guardrail_public_cn`, pay-as-you-go). Without it every call fails with business code `408` naming the commodity.

* An Alibaba Cloud AccessKey allowed to call the `MultiModalGuard` API action (RAM permission `yundun-greenweb:MultiModalGuard`).

* Detection and blocking policies enabled in the AI Guardrails console. The console policy — not AISIX — decides the outcome: a check module set to block returns `block`, one set to desensitize returns `mask`, and one set only to observe returns `watch` (which AISIX releases). A module that is not enabled does not run at all — for example, sensitive-data masking requires enabling the sensitive-data check with a desensitize action; until then those requests return `pass` with no `sensitiveData` result.

* `curl`. The control-plane path also uses `jq`.

## Create an Alibaba Cloud AI Guardrail[​](#create-an-alibaba-cloud-ai-guardrail "Direct link to Create an Alibaba Cloud AI Guardrail")

The example below checks both requests and responses with the `pro` service tier. Choose one configuration path, then use the shared verification procedure.

Export the gateway and provider values used by both paths:

```
# AISIX_PROXY has no trailing slash or endpoint path.

# The local quickstarts use http://127.0.0.1:3000.

export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

export AISIX_MODEL="gpt-4o-mini"

export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ALIBABA_CLOUD_ACCESS_KEY_ID"

export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ALIBABA_CLOUD_ACCESS_KEY_SECRET"
```

### AISIX Enterprise or AISIX Cloud[​](#aisix-enterprise-or-aisix-cloud "Direct link to AISIX Enterprise or AISIX Cloud")

Export the control-plane connection details:

```
# AISIX_CP includes /api and has no trailing slash.

# The local AISIX Enterprise quickstart uses http://localhost:8080/api.

export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"

export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

export ENV_ID="YOUR_ENVIRONMENT_ID"
```

Create an Alibaba Cloud AI Guardrails resource in the environment and capture its ID:

```
export GUARDRAIL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "aliyun-ai-guard",

    "enabled": false,

    "hook_point": "both",

    "fail_open": false,

    "kind": "aliyun_ai_guardrail",

    "config": {

      "region": "cn-shanghai",

      "access_key_id": "'"${ALIBABA_CLOUD_ACCESS_KEY_ID}"'",

      "access_key_secret": "'"${ALIBABA_CLOUD_ACCESS_KEY_SECRET}"'",

      "output_fail_open": false,

      "service_level": "pro",

      "timeout_ms": 3000

    }

  }' | jq -r '.guardrail.id')
```

❶ `both` checks caller requests and model responses. See [Guardrail Hook Point](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/behavior.md#guardrail-hook-point).

❷ `fail_open: false` blocks the request if Alibaba Cloud AI Guardrails fails or times out. This is the default.

❸ `output_fail_open: false` blocks unscanned model output during an Alibaba Cloud outage. This is the default.

❹ `service_level` selects the API tier: `pro` (the default) calls `query_security_check_pro` and `response_security_check_pro`; `basic` calls `query_security_check` and `response_security_check`. It must match the tier activated on your account.

❺ `timeout_ms` bounds each call to the Alibaba Cloud API end to end, from sending the request through reading the full response body, but not the whole check. Content longer than one call accepts is checked in several calls, one per chunk, and there is no overall deadline, so the total time is roughly the number of chunks multiplied by the per-call time. See [Content Size Limit](#content-size-limit).

AISIX derives the endpoint from `region` (`green-cip.<region>.aliyuncs.com`). Set `endpoint` in `config` to a full URL only when you need to override that host.

There is no local risk threshold to configure. The AI Guardrails console computes an overall suggestion from your configured policies, and AISIX follows it.

Attach the guardrail to the environment so it applies to all traffic:

```
curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID/attachments" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "scope_type": "env"

  }'
```

The `env` scope omits `scope_id` and covers every request in the environment. To narrow enforcement, set `scope_type` to `model`, `api_key`, or `team` and pass the resource ID as `scope_id`.

Enable the guardrail after its attachment exists:

```
curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{"enabled": true}'
```

The enabled configuration projects to attached gateways automatically.

### AISIX OSS[​](#aisix-oss "Direct link to AISIX OSS")

Add the guardrail to the resources file that already defines the example model and caller API key. The example reads credentials from `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET`. A running quickstart container does not inherit these variables from later host exports.

resources.yaml (Alibaba AI guardrail)

```
guardrails:

  - id: 2a42a7e0-2d70-4ddf-a3a7-03b781072f2a

    name: aliyun-ai-guard

    enabled: true

    hook_point: both

    fail_open: false

    kind: aliyun_ai_guardrail

    region: cn-shanghai

    access_key_id: ${ALIBABA_CLOUD_ACCESS_KEY_ID}

    access_key_secret: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET}

    output_fail_open: false

    service_level: pro

    timeout_ms: 3000



guardrail_attachments:

  - id: 11950c68-477a-4cc6-92fc-9f55e938f998

    guardrail_id: 2a42a7e0-2d70-4ddf-a3a7-03b781072f2a

    scope_type: env

    priority: 100
```

The provider fields sit directly on the guardrail entry rather than under `config`. AISIX derives the endpoint from `region`; set `endpoint` only when the gateway should use another full URL.

A guardrail applies only where an attachment puts it: add a `guardrail_attachments` entry naming it, or it loads and inspects no traffic. Apply the change by validating the complete file before reloading or recreating the gateway. If you are extending the open-source quickstart, follow [Reload a Resources File](https://docs.api7.ai/ai-gateway/deployment/configuration-propagation.md#reload-a-resources-file) to recreate the container only after validation succeeds and pass the additional credential variables.

## How AISIX Applies the Suggestion[​](#how-aisix-applies-the-suggestion "Direct link to How AISIX Applies the Suggestion")

Each `MultiModalGuard` response carries a suggestion computed by your console policy across every detection dimension (content compliance, prompt attack, sensitive data, and others). AISIX maps it to a gateway decision:

| Suggestion | AISIX behavior                                                                                                                                                                    |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pass`     | The request or response continues unchanged.                                                                                                                                      |
| `watch`    | The content continues unchanged; the detection detail is recorded in the gateway log.                                                                                             |
| `block`    | AISIX rejects with `422 content_filter` (or records a would-block in monitor mode).                                                                                               |
| `mask`     | AISIX rewrites the content when the request path and streaming mode support replacement. Otherwise, it blocks the content. See [Sensitive-Data Masking](#sensitive-data-masking). |

## Verify the Guardrail[​](#verify-the-guardrail "Direct link to Verify the Guardrail")

Control-plane projection is asynchronous. If the first request does not reflect the guardrail, wait for the gateway to apply the latest revision and retry. See [Resource Projection](https://docs.api7.ai/ai-gateway/cloud/resource-projection.md) for convergence checks.

Send a benign request through AISIX:

```
curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \

  -H "Authorization: Bearer ${AISIX_API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "model": "'"${AISIX_MODEL}"'",

    "messages": [

      {

        "role": "user",

        "content": "What is the capital of France?"

      }

    ]

  }'
```

A successful response starts with `HTTP/1.1 200 OK` and returns an OpenAI-compatible chat-completions body.

For a repeatable check, use content that your console policy is configured to block — a prompt-attack probe when the prompt-attack policy is on, or content the compliance policy rejects. Then send it:

```
curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \

  -H "Authorization: Bearer ${AISIX_API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "model": "'"${AISIX_MODEL}"'",

    "messages": [

      {

        "role": "user",

        "content": "YOUR_POLICY_VIOLATING_TEXT"

      }

    ]

  }'
```

A blocked response starts with `HTTP/1.1 422 Unprocessable Entity` and includes an OpenAI-compatible error:

```
{

  "error": {

    "message": "request blocked by content policy (guardrail 'aliyun-ai-guard')",

    "type": "content_filter"

  }

}
```

The call also appears in the AI Guardrails console's records, where the same decision shows its per-dimension detail.

## Sensitive-Data Masking[​](#sensitive-data-masking "Direct link to Sensitive-Data Masking")

When the console's sensitive-data policy is set to desensitize, Alibaba Cloud returns content with the sensitive spans replaced. AISIX writes that rewrite back into the request or response:

* On the input hook, the upstream model receives the desensitized prompt.
* On the output hook, the caller receives the desensitized response.

Masking a streamed response requires the whole response to be held back. Set `stream_processing_mode: "buffer_full"` on guardrails that should mask streamed output. In AISIX Enterprise and AISIX Cloud, add the field inside `config`; in the open-source resources file, add it directly to the guardrail entry.

In the default `window` mode, AISIX releases scanned windows incrementally and cannot rewrite content that is already on the wire. A `mask` suggestion arriving mid-stream is treated as `block`, so unmasked content is never released. Non-streaming requests and responses mask in both modes.

If Alibaba Cloud suggests `mask` but returns no desensitized text, AISIX blocks the request rather than releasing content the policy wanted masked.

## Content Size Limit[​](#content-size-limit "Direct link to Content Size Limit")

AISIX sends at most 2,000 characters to `MultiModalGuard` in one call, and it never truncates content to fit. For non-streaming requests and responses, AISIX joins the extracted text, splits it without loss into chunks of at most 2,000 characters, and checks every chunk. Each chunk is its own `MultiModalGuard` call. The calls run one after another, the number of chunks is not capped, and the check stops at the first chunk that blocks or fails. Latency and the number of Alibaba Cloud calls therefore grow linearly with content size, and Alibaba Cloud bills each call. When content spread across several messages needs masking, AISIX checks each message again so the desensitized text lines up with the original messages, which adds calls.

For streamed responses in `window` mode, AISIX divides content into overlapping windows of no more than 2,000 characters and checks each window separately.

Clients that resend the whole conversation on every call make every request pay for the full history. To reduce that load, set `input_messages: latest_turn` on the guardrail: the input check then reads only the latest turn instead of the whole conversation history. See [Choose the Input Message Window](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/behavior.md#choose-the-input-message-window).

## Streaming Output[​](#streaming-output "Direct link to Streaming Output")

Streamed responses are checked incrementally using the shared streaming controls described in [Guardrail Behavior](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/behavior.md#streaming-output). Each window of one response is sent with the same `sessionId` and `chatId`, so Alibaba Cloud groups the windows into one conversation record in its console.

## Trace a Decision to Alibaba Cloud[​](#trace-a-decision-to-alibaba-cloud "Direct link to Trace a Decision to Alibaba Cloud")

Every AISIX response carries an `x-aisix-request-id` header. Search the gateway log for it; the moderation decision logs on the same line as Alibaba Cloud's own `RequestId`. The decision is logged at `info` level, below the gateway's default `warn`, so it is written only with `log_level: "info"`. When you need `aliyun_request_id`, raise the level first: the level is read at startup, and a block handled at `warn` does not write this line. See [Collect Access Logs](https://docs.api7.ai/ai-gateway/observability/access-logs-and-request-correlation.md#collect-access-logs).

The line looks like this:

```
INFO request{request_id=12179fb5-5c3c-4a2a-a411-d73746379cc6}: aisix_guardrails::aliyun_ai_guardrail:

aliyun AI guardrail blocked content row=aliyun-ai-guard service="query_security_check_pro"

aliyun_request_id=019F6EF3-6F9A-5A25-9EED-256CB0E26448 aliyun_code=200 aliyun_suggestion=block

aliyun_dimensions=promptAttack:high/block,contentModeration:none/pass aliyun_labels=prompt_injection
```

| Field               | Meaning                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request_id`        | The gateway request ID, equal to the caller's `x-aisix-request-id`.                                                                                                |
| `aliyun_request_id` | Alibaba Cloud's own `RequestId` for the call. Use it to find the record in the AI Guardrails console or in an Alibaba Cloud support ticket.                        |
| `aliyun_suggestion` | The overall suggestion AISIX acted on.                                                                                                                             |
| `aliyun_dimensions` | Every detection dimension that ran, as `type:level/suggestion`. Most dimensions grade `none`/`low`/`medium`/`high`; the sensitive-data dimension grades `S0`–`S3`. |
| `aliyun_labels`     | The categories that detected something. Clean scans are omitted.                                                                                                   |

Requests that pass log the same fields at `debug` level. These lines carry category labels and never the matched text. See [What the Gateway Records](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/overview.md#what-the-gateway-records) for the other text that can carry it.

## Troubleshoot Configuration Errors[​](#troubleshoot-configuration-errors "Direct link to Troubleshoot Configuration Errors")

With `fail_open: false`, a guardrail that cannot get a decision blocks the request, so a configuration error reaches the caller as the same `422 content_filter` as a policy hit. The log tells them apart at `error` level:

| Log signal                                                       | Cause                                                                                                                                                                          |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| business code `408`, message naming `lvwang_guardrail_public_cn` | The AI Guardrails service is not activated on the account, or `service_level` names a tier the account has not activated. Activate the commodity in the Alibaba Cloud console. |
| `aliyun_code=SignatureDoesNotMatch`                              | The `access_key_secret` is wrong.                                                                                                                                              |
| `aliyun_code=InvalidAccessKeyId.NotFound`                        | The `access_key_id` is wrong, or the key is disabled.                                                                                                                          |
| auth/permission error naming the RAM policy                      | The RAM user lacks `yundun-greenweb:MultiModalGuard`.                                                                                                                          |

As with the Content Moderation guardrail, AISIX logs the error code but never the error body, which on a signature error quotes the entire signed request — including the caller's prompt — back at the sender.

## Choose Between the Two Alibaba Cloud Guardrails[​](#choose-between-the-two-alibaba-cloud-guardrails "Direct link to Choose Between the Two Alibaba Cloud Guardrails")

|                       | `aliyun_ai_guardrail` (this page)                                      | [`aliyun_text_moderation`](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/alibaba-cloud-ai.md) |
| --------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Alibaba Cloud product | AI Guardrails (`MultiModalGuard`)                                      | Content Moderation (`TextModerationPlus`)                                                                   |
| Where policy lives    | AI Guardrails console policies                                         | AISIX-side `risk_level_threshold` over returned risk levels                                                 |
| Checks                | Composite: content compliance, prompt attack, sensitive data, and more | Risk-level content moderation                                                                               |
| Actions               | Block, and sensitive-data masking                                      | Block                                                                                                       |
| Console call records  | Yes, in the AI Guardrails console                                      | No AI Guardrails records (Content Moderation product)                                                       |
| Activation            | `lvwang_guardrail_public_cn` commodity                                 | Content Moderation enhanced-edition APIs                                                                    |

## Next Steps[​](#next-steps "Direct link to Next Steps")

You have now configured Alibaba Cloud AI Guardrails and verified its policy-driven decisions. Use these guides to tune behavior or compare the related service:

* [Guardrail Behavior](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/behavior.md): adjust hook points, enforcement mode, streaming output, or remote failure handling.
* [Alibaba Cloud Content Moderation](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/alibaba-cloud-ai.md): the TextModerationPlus guardrail with AISIX-side risk thresholds.
* [Choosing a Guardrail Provider](https://docs.api7.ai/ai-gateway/traffic-controls/guardrails/overview.md): compare Alibaba Cloud AI Guardrails with other built-in and remote options.
