阿里云AI安全护栏对接使用完全指南：从开通到生产级集成

apphuang2026年06月25日 13:54:155

一、AI安全护栏：大模型时代的"智能过滤系统"

随着生成式AI和AI Agent的爆发式增长，AI应用的用户量级与流量规模呈指数级上升。如何在技术创新和安全合规之间取得平衡，成为全行业关注的重要命题。阿里云AI安全护栏（AI Guardrails）正是为应对这一挑战而生的产品——它就像一套部署在AI系统输入输出端的"智能过滤系统"，在不打扰用户体验的前提下，默默守护每一次AI交互的安全。

AI安全护栏面向预训练大模型、AI服务和AI Agent等不同的业务形态，提供全链路防护体系。其核心能力覆盖内容合规检测、敏感内容检测、提示词攻击检测、恶意URL检测、模型幻觉检测等多个维度。无论是检测用户输入中的违规内容，还是拦截针对大模型的注入式攻击，亦或是扫描模型输出中的敏感信息，AI安全护栏都能提供精准的风险检测与主动防御能力。

本文将按照从准备工作到生产级集成的完整路径，详细讲解AI安全护栏的对接使用方法。全文涵盖开通服务、权限配置、SDK接入、API调用、控制台高级配置、第三方产品集成以及性能优化等全流程内容，并附有完整的代码示例。

需要先登录阿里云控制台，点击：阿里云控制台

二、准备工作：开通服务与权限配置

2.1 开通AI安全护栏服务

对接AI安全护栏的第一步是开通产品服务。访问AI安全护栏产品开通服务页面，按照提示完成开通操作。开通后默认采用按量后付费的计费方式，按照实际用量结算当日费用，不调用服务不收费。接口接入使用后系统会按使用量自动出账，无需手动操作。

2.2 RAM用户授权与AccessKey管理

在接入SDK或API之前，必须完成RAM用户的授权配置。您需要为阿里云账号或RAM用户创建一个访问密钥（AccessKey），在调用API时使用AccessKey完成身份验证。

具体操作步骤如下：

使用阿里云账号登录RAM控制台
创建RAM用户（如果尚未创建）
向RAM用户授予系统策略权限：AliyunYundunGreenWebFullAccess
为RAM用户创建AccessKey，获取AccessKey ID和AccessKey Secret

完成以上配置后，即可使用RAM用户调用内容安全API。强烈建议在生产环境中使用RAM子账号而非主账号进行API调用，以遵循最小权限原则，降低密钥泄露的风险。

2.3 服务关联角色授权

首次登录AI安全护栏控制台时，还需要完成服务关联角色的授权——即允许AI安全护栏访问相关云资源。系统会自动提示授权操作，按照指引完成即可。这一授权是使用云防火墙、日志投递等扩展功能的前提。

三、SDK接入：快速集成到您的代码中

3.1 支持的地域与接入地址

AI安全护栏目前支持多个地域的接入，每个地域都提供外网和内网两种接入地址：

华东2（上海）：外网 green-cip.cn-shanghai.aliyuncs.com，内网 green-cip-vpc.cn-shanghai.aliyuncs.com
华北2（北京）：外网 green-cip.cn-beijing.aliyuncs.com，内网 green-cip-vpc.cn-beijing.aliyuncs.com
华东1（杭州）：外网 green-cip.cn-hangzhou.aliyuncs.com，内网 green-cip-vpc.cn-hangzhou.aliyuncs.com
华南1（深圳）：外网 green-cip.cn-shenzhen.aliyuncs.com，内网 green-cip-vpc.cn-shenzhen.aliyuncs.com
新加坡：外网 green-cip.ap-southeast-1.aliyuncs.com，内网 green-cip-vpc.ap-southeast-1.aliyuncs.com
德国（法兰克福）：外网 green-cip.eu-central-1.aliyuncs.com，内网 green-cip-vpc.eu-central-1.aliyuncs.com

如果您的业务部署在阿里云ECS上，建议使用内网地址进行调用，可以显著降低网络延迟并节省外网流量费用。

3.2 Java SDK接入

AI安全护栏支持Java 1.8及以上版本。在Maven工程的pom.xml中添加以下依赖：

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>green20220302</artifactId>
    <version>1.0.0</version>
</dependency>

SDK源码可参考GitHub仓库：aliyun/alibabacloud-java-sdk/tree/master/green-20220302。

以下是Java SDK调用文本审核的完整示例：

import com.aliyun.green20220302.Client;
import com.aliyun.green20220302.models.TextModerationPlusRequest;
import com.aliyun.green20220302.models.TextModerationPlusResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class TextModerationExample {
    public static void main(String[] args) throws Exception {
        // 1. 配置客户端
        Config config = new Config()
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
            .setRegionId("cn-shanghai")
            .setEndpoint("green-cip.cn-shanghai.aliyuncs.com");
        
        Client client = new Client(config);
        
        // 2. 构建请求参数
        TextModerationPlusRequest request = new TextModerationPlusRequest();
        // Service参数：AI输入内容安全检测 或 AI生成内容安全检测
        request.setService("query_security_check_intl");
        
        // ServiceParameters为JSON字符串
        String serviceParams = "{\"content\":\"待审核的文本内容\",\"chatId\":\"会话唯一标识\"}";
        request.setServiceParameters(serviceParams);
        
        // 3. 发起调用
        RuntimeOptions runtime = new RuntimeOptions();
        TextModerationPlusResponse response = client.textModerationPlusWithOptions(request, runtime);
        
        // 4. 处理返回结果
        System.out.println("请求ID: " + response.getBody().getRequestId());
        System.out.println("检测结果: " + response.getBody().getData());
    }
}

3.3 Python SDK接入

Python SDK的安装与使用同样简洁。首先通过pip安装依赖：

pip install alibabacloud-green20220302

Python调用示例：

import os
from alibabacloud_green20220302.client import Client
from alibabacloud_green20220302.models import TextModerationPlusRequest
from alibabacloud_teaopenapi.models import Config
from alibabacloud_teautil.models import RuntimeOptions

# 1. 配置客户端
config = Config(
    access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    region_id='cn-shanghai',
    endpoint='green-cip.cn-shanghai.aliyuncs.com'
)
client = Client(config)

# 2. 构建请求
request = TextModerationPlusRequest()
request.service = 'query_security_check_intl'
request.service_parameters = '{"content":"待审核的文本内容","chatId":"会话唯一标识"}'

# 3. 发起调用
runtime = RuntimeOptions()
try:
    response = client.text_moderation_plus_with_options(request, runtime)
    print(f"请求ID: {response.body.request_id}")
    print(f"检测结果: {response.body.data}")
except Exception as e:
    print(f"调用异常: {e}")

阿里云SDK通过读取环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 来创建默认的访问凭证。建议在生产环境中使用环境变量方式管理密钥，避免将AccessKey硬编码在代码中。

四、API调用详解：核心接口与参数

4.1 核心接口：TextModerationPlus

AI安全护栏的核心业务接口是 TextModerationPlus，用于创建文本内容检测任务。该接口支持两种主要的检测服务：

AI输入内容安全检测（query_security_check_intl）：检测用户输入给大模型的文本内容
AI生成内容安全检测（response_security_check_intl）：检测大模型生成的文本内容

业务接口的单用户QPS限制为50次/秒，超过限制API调用会被限流。如果您的业务有更高的并发需求，可以提交工单申请提升QPS配额。

4.2 请求参数详解

调用 TextModerationPlus 接口时需要传入以下核心参数：

参数名称	类型	是否必须	描述
Service	String	是	检测服务类型，可选 query_security_check_intl 或 response_security_check_intl
ServiceParameters	JSONString	是	审核服务需要的参数集，包含 content、chatId 等字段

ServiceParameters 中主要包含以下字段：

content（必填）：待审核的文本内容，最大支持单次2000字符
chatId（可选）：用于唯一标识一轮"用户输入+大模型输出"的交互记录，便于追溯和关联分析

4.3 返回参数与结果处理

API调用成功后会返回检测结果，包含风险标签、置信度分数、建议动作等信息。返回结果中的关键字段包括：

Suggestion：建议动作，取值包括 pass（放行）、block（拦截）
RiskLevel：风险等级，取值包括 low（低风险）、medium（中风险）、high（高风险）
Labels：命中的风险标签列表，如色情、涉政、暴恐等

对于中高风险内容建议直接拦截，低风险内容可以发出警告或进行人工复核。业务方可以根据自身的合规要求，灵活配置不同风险等级对应的处置策略。

计费方面，该接口仅对HTTP状态码为200的请求进行计量计费，产生其他错误码时不会计费。

五、多模态检测：一次API调用覆盖全类型内容

AI安全护栏的设计目标是"简单、高效、无门槛"，为此提供了All In One API的调用模式。通过多模态检测接口，只需调用一个API，就能同时满足文本、图片、文件、音频、视频等多模态内容的交叉检测。

无论是内容合规检测、提示词攻击拦截还是恶意文件扫描，都可以在一次API调用中全部完成。对于同时涉及多种内容类型的AI应用场景（如图文混合的输入、包含附件的对话等），多模态检测接口可以显著简化集成复杂度，避免为每种内容类型分别对接不同的检测服务。

多模态同步检测接口支持内容合规检测、敏感内容检测、提示词攻击检测、恶意文件检测、恶意URL检测等全方位检测能力。具体的API调用方式与文本检测类似，只需在 ServiceParameters 中传入对应的多模态内容参数即可。

六、控制台配置：精细化防护策略管理

6.1 检测项配置与防护维度

AI安全护栏控制台提供了完整的检测项配置能力，用于管理检测服务和防护维度。在控制台左侧导航栏选择"检测项配置"，可以查看当前可用的Service列表。主要包括以下Service：

AI输入内容安全检测（query_security_check_intl）：检测用户输入给大模型的文本内容
AI生成内容安全检测（response_security_check_intl）：检测大模型生成的文本内容
Agent日志内容检测（agent_log_guard_ec）：检测Agent作业记录中的文本内容
AIGC输入图片安全检测（img_query_guard_ec）：检测用户输入的图片内容
AIGC输出图片安全检测（img_response_guard_ec）：检测大模型生成的图片内容

每个Service都支持多个防护维度，以卡片形式展示在Service管理页面中。文本类Service主要支持以下防护维度：

内容合规：检测色情、暴力、政治等不良内容，默认启用
敏感内容检测：检测可能泄露的个人信息或企业敏感性数据，需单独计费
提示词攻击检测：检测旨在绕过⼤模型安全限制的恶意提示词，需单独计费
恶意URL（公测中）：扫描大模型内容中的恶意链接
模型幻觉（公测中）：检测大模型产生的虚假或不准确信息

您可以通过卡片上的开关随时启用或关闭对应的防护功能。配置变更后大约需要2至5分钟生效并应用于生产环境。

6.2 自定义检测Agent

AI安全护栏支持用户配置和管理自定义检测Agent，该功能基于大语言模型，通过灵活自定义的交互内容来快速实现业务自定义检测类别的检测和过滤。

启用步骤：

在控制台左侧导航栏选择对应的Service（如AI输入内容安全检测）
单击操作列的"管理"进入检测项配置页面
若自定义检测Agent未开启，可在此页面一键开启（该功能单独收费）

配置大模型：

Qwen3Guard-Gen-4B：基于Qwen3构建的生成式安全审核模型，内置支持9类风险标签和3级风险分级，支持119种语言及方言。目前仅支持新加坡节点。审核response时，content字段应以"query<|interval|>response"格式拼接
Qwen3_Plus：千问3系列Plus模型，效果、速度、成本均衡，适合对效果要求较高但对耗时有一定容忍度的复杂场景
Qwen3_Flash：千问3系列Flash模型，速度快、成本低，适合简单任务

配置自定义提示词：

选择预设场景模板或自定义标签模板
配置检测标签（待检测的具体类别名称，一般为名词短语）和检测描述（检测标准和规则，必要时可枚举示例）
配置多个检测标签即让大模型进行多分类任务，需用准确精简的语言描述清楚每项检测任务

配置示例：

检测标签：站外引流
检测描述：通过直接引导或隐晦暗示（含变体、隐喻等）将用户引导至站外其他平台或渠道的行为
检测标签：对xx品牌恶意差评
检测描述：针对xx品牌的无依据恶意拉踩、不实负面差评，或针对品牌创始人的虚假诋毁

自定义部分的提示词字符长度（所有检测标签与检测提示词的总字符长度）与计量相关，每3000字符计量一次（不满3000按3000计算）。

6.3 词库管理与代答库配置

词库管理用于定制私有化的审核规则。您可以创建词库，设置有风险的违规关键词或在检测前需要过滤掉的关键词。

词库创建规则：

支持多个关键词采用"与或非"逻辑组合，如"微信&兼职"表示只有同时出现两个词时才命中（&表示与，~表示非）
每个关键词以换行分隔，单个词不超过50字
最多1000行，如需批量添加请使用上传文件导入
同一账号下总共支持添加10万个词，最多可创建20个词库

词库黑名单：命中词库中任一关键词后，API返回参数中 labels 会返回 C_customized（用户库命中）。词库白名单：命中关键词后先忽略再检测，即对这些关键词不进行审核。

代答库管理支持根据风险标签自定义配置代答内容。当检测到特定风险内容时，系统可以用预设的代答内容替换原始输出，既保证了安全合规，又维持了用户体验的连贯性。单个标签最多支持配置三个代答库。

七、产品集成：与阿里云生态无缝联动

AI安全护栏与阿里云的多个基础设施产品深度结合，支持在多种产品中一键开启调用，满足不同业务场景的防护需求。

7.1 与Web应用防火墙（WAF）集成

在WAF 3.0中，可以通过AI应用防护功能建立防护规则，有效拦截恶意提示词攻击并实时管控用户输入及模型生成内容中的违法违规信息。具体配置路径为：登录WAF控制台 → 选择防护模板 → 在请求检测模板与响应检测模板中选取AI安全护栏已存在的检测项Service → 完成配置。

WAF还支持分片配置，即设置请求分片大小与响应分片大小，该参数决定了单次发送至AI安全护栏进行风险检测的文本长度。分片大小直接影响性能与成本的权衡：增大分片大小可减少AI安全护栏的调用次数从而降低成本，但相应地用户端接收完整响应的延迟也会增加。

分片计算示例：若客户端发送500字节内容且分片大小设为300字节，系统将按每300字节一组进行切分，共触发2次AI安全护栏检测。系统已内置防切分机制，可确保风险文本的语义完整性不受分区处理的影响。

7.2 与阿里云百炼集成

在阿里云百炼平台中，可以通过开启安全护栏功能，在配置发布时自动检测发布内容的安全合规性。用户可以配置安全策略检测敏感内容及合规问题，如隐私信息泄露风险、恶意脚本注入风险、不合规内容发布风险等。

7.3 与AI网关集成

在AI网关中，可以在Model API的详情页面开启AI安全护栏防护。通过网关层面的集成，可以实现对所有经过网关的AI API请求进行统一的安全检测，无需在每个后端服务中单独集成SDK。

7.4 与AgentScope集成

AI安全护栏提供了AgentScope插件，通过调用AI安全护栏服务，实现对AgentScope中大模型和工具调用的输入输出的实时安全防护。

AgentScope集成支持以下检测点：

pre_reply / on_reply：Agent回复前，检测用户输入，违规直接阻断了
post_print / on_reasoning：流式chunk输出时，进行流式增量检测
post_reasoning：LLM推理完成后，进行最终检测并支持违规内容替换
toolkit middleware / on_acting：工具执行前，检测工具输入参数，阻止危险工具调用

拦截策略根据护栏服务返回的 Suggestion 和 RiskLevel 字段决策：中高风险直接拦截，低风险发出警告，安全内容正常通过。

八、流式检测与性能优化

8.1 流式检测方案

对于大模型流式生成内容的场景，AI安全护栏提供了专门的流式检测方案。客户应用在接收到用户Prompt后调用大模型进行推理并流式生成文本内容，为确保内容安全，生成的文本需经护栏系统检测且确认无风险后方可对用户透出。

流式内容检测通常采用切片机制，累计一定字符后触发审核。具体有两种模式：

阈值模式：每累积到指定字符数（默认300）后送检一次
滑动窗口模式：每累积X个字符后将最近的N个字符审核一次

这种设计既可以保留上下文信息，也可以极大降低等待时间，做到客户无感的安全防护。

8.2 性能与成本权衡

在使用AI安全护栏时，需要在性能与成本之间做出合理的权衡：

分片大小：增大分片大小可减少调用次数从而降低成本，但会增加延迟
检测频率：流式场景下适当增加累积阈值可减少调用次数，但可能延迟风险内容的发现
并发控制：注意单用户QPS限制为50次/秒，合理规划请求量避免限流

建议根据业务的实际延迟要求和成本预算，通过控制台或API参数灵活调整这些配置项。

九、常见问题解答

问1：AI安全护栏支持哪些内容类型的检测？

答：AI安全护栏支持文本、图片、文件、音频、视频等多模态内容的检测。通过多模态API接口，一次调用即可完成全类型内容的交叉检测。

问2：调用AI安全护栏API时如何计费？

答：默认采用按量后付费方式，按照实际用量结算当日费用，不调用不收费。仅对HTTP状态码为200的请求进行计量计费。敏感内容检测、提示词攻击检测、自定义检测Agent等部分功能需单独计费。

问3：AI安全护栏的QPS限制是多少？能否提升？

答：TextModerationPlus接口的单用户QPS限制为50次/秒。如果业务有更高并发需求，可以提交工单申请提升QPS配额。

问4：自定义检测Agent中可选哪些大模型？

答：目前可选Qwen3Guard-Gen-4B（生成式安全审核模型，支持119种语言）、Qwen3_Plus（效果速度成本均衡）和Qwen3_Flash（速度快成本低）。

问5：AI安全护栏可以与哪些阿里云产品集成？

答：AI安全护栏支持与WAF、阿里云百炼、AI网关、AgentScope等多个产品集成。同时支持API、SDK等多种接入方式。

问6：如何配置自定义词库？

答：在AI安全护栏控制台的词库管理页面创建词库，支持关键词逻辑组合（&表示与、~表示非）。词库可设置为黑名单（命中即返回违规）或白名单（命中即忽略）。