Skip to main content
API7.ai Logo

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.
  • One of these configuration paths:
    • AISIX Cloud with an environment, an attached gateway, and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • An open-source AISIX gateway that loads a declarative resources.yaml 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 AISIX Cloud path also uses jq.

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 Cloud​

Export the control-plane connection details:

# AISIX_CP includes /api and has no trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_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.

❷ 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 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.

Open-Source AISIX Gateway​

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
guardrails:
  - 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

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.

Every enabled guardrail in the resources file applies to every request handled by that gateway. 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 to recreate the container only after validation succeeds and pass the additional credential variables.

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:

SuggestionAISIX behavior
passThe request or response continues unchanged.
watchThe content continues unchanged; the detection detail is recorded in the gateway log.
blockAISIX rejects with 422 content_filter (or records a would-block in monitor mode).
maskAISIX rewrites the content when the request path and streaming mode support replacement. Otherwise, it blocks the content. See Sensitive-Data Masking.

Verify the Guardrail​

AISIX Cloud 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 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​

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 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​

AISIX sends at most 2,000 characters to MultiModalGuard in one call. For non-streaming requests and responses, AISIX joins the extracted text and sends the first 2,000 characters for the decision. For streamed responses in window mode, AISIX divides content into overlapping windows of no more than 2,000 characters and checks each window separately.

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 groups the windows into one conversation record in its console.

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
FieldMeaning
request_idThe gateway request ID, equal to the caller's x-aisix-request-id.
aliyun_request_idAlibaba 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_suggestionThe overall suggestion AISIX acted on.
aliyun_dimensionsEvery detection dimension that ran, as type:level/suggestion. Most dimensions grade none/low/medium/high; the sensitive-data dimension grades S0–S3.
aliyun_labelsThe 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 signalCause
business code 408, message naming lvwang_guardrail_public_cnThe 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=SignatureDoesNotMatchThe access_key_secret is wrong.
aliyun_code=InvalidAccessKeyId.NotFoundThe access_key_id is wrong, or the key is disabled.
auth/permission error naming the RAM policyThe 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 productAI Guardrails (MultiModalGuard)Content Moderation (TextModerationPlus)
Where policy livesAI Guardrails console policiesAISIX-side risk_level_threshold over returned risk levels
ChecksComposite: content compliance, prompt attack, sensitive data, and moreRisk-level content moderation
ActionsBlock, and sensitive-data maskingBlock
Console call recordsYes, in the AI Guardrails consoleNo AI Guardrails records (Content Moderation product)
Activationlvwang_guardrail_public_cn commodityContent Moderation enhanced-edition APIs

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: