Alibaba Cloud AI Guardrails

Alibaba Cloud AI Guardrails keep the moderation policy in the AI Guardrails console, 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 (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

Before starting, prepare the following:

• Review Guardrail Behavior for hook points, enforcement modes, and remote failure handling.
• A self-hosted AISIX gateway with the admin and proxy listeners available.
• The admin key from the gateway config.yaml.
• 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.

Create an Alibaba Cloud AI Guardrail

Create an Alibaba Cloud AI Guardrails resource in AISIX:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aliyun-ai-guard",
    "enabled": true,
    "hook_point": "both",
    "fail_open": false,
    "output_fail_open": false,
    "kind": "aliyun_ai_guardrail",
    "region": "cn-shanghai",
    "access_key_id": "YOUR_ALIBABA_CLOUD_ACCESS_KEY_ID",
    "access_key_secret": "YOUR_ALIBABA_CLOUD_ACCESS_KEY_SECRET",
    "service_level": "pro",
    "timeout_ms": 3000
  }'

❶ both checks caller requests and model responses. See Guardrail Hook Point.

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

❸ 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 how long AISIX waits for the guardrail decision.

AISIX derives the endpoint from region (green-cip.<region>.aliyuncs.com). Set endpoint 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.

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 with the desensitized text Alibaba Cloud returns, then lets it continue. See Sensitive-Data Masking.

Verify the Guardrail

Send a benign request through AISIX:

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "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 "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "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

When the console's sensitive-data policy is set to desensitize, Alibaba Cloud returns the content with the sensitive spans replaced, and 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, so set stream_processing_mode: "buffer_full" on guardrails that should mask streamed output. stream_processing_mode is a field on the guardrail resource itself — include it in the create request above or update the resource later. 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.

Streaming Output

Streamed responses are checked incrementally using the shared streaming controls described in Guardrail Behavior. Each window of one response is sent with the same sessionId and chatId, so Alibaba Cloud stitches the pieces into one conversation record in its console — the windows of one streamed response appear together rather than as unrelated calls.

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:

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. The matched text itself is never logged — only category labels — so gateway logs cannot leak caller content.

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

	aliyun_ai_guardrail (this page)	aliyun_text_moderation
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

• Guardrail Behavior: adjust hook points, enforcement mode, streaming output, or remote failure handling.
• Alibaba Cloud Content Moderation: the TextModerationPlus guardrail with AISIX-side risk thresholds.
• Choosing a Guardrail Provider: compare Alibaba Cloud AI Guardrails with other built-in and remote options.