本文档介绍了调用AI安全护栏多模态实时审核接口的方法。
步骤一:开通服务
前往AI安全护栏产品开通服务页面,开通AI安全护栏产品服务。
步骤二:为RAM用户授权
在接入SDK或者API之前,您需要为RAM用户授权。您可以为阿里云账号和RAM用户创建一个访问密钥(AccessKey)。在调用阿里云API时您需要使用AccessKey完成身份验证。获取方式,请参见获取AccessKey。
操作步骤
使用阿里云账号登录RAM控制台。
创建RAM用户。
具体操作,请参见创建RAM用户。
向RAM用户授权系统策略权限:
AliyunYundunGreenWebFullAccess。具体操作,请参见管理RAM用户的权限。
完成以上配置后,您可以使用RAM用户调用内容安全API。
步骤三:安装并接入SDK
AI安全护栏产品服务SDK请参考多模态SDK参考
API说明
使用说明
您可以调用该接口创建文本内容检测任务。
业务接口:MultiModalGuard
支持的地域及接入地址:
地域 | 外网接入地址 | 内网接入地址 |
华东2(上海) | https://green-cip.cn-shanghai.aliyuncs.com | https://green-cip-vpc.cn-shanghai.aliyuncs.com |
华北2(北京) | https://green-cip.cn-beijing.aliyuncs.com | https://green-cip-vpc.cn-beijing.aliyuncs.com |
华东1(杭州) | https://green-cip.cn-hangzhou.aliyuncs.com | https://green-cip-vpc.cn-hangzhou.aliyuncs.com |
华南1(深圳) | https://green-cip.cn-shenzhen.aliyuncs.com | https://green-cip-vpc.cn-shenzhen.aliyuncs.com |
西南1(成都) | https://green-cip.cn-chengdu.aliyuncs.com | 暂无 |
中国香港 | https://green-cip.cn-hongkong.aliyuncs.com | 暂无 |
华东 1 金融云(杭州) | https://green-cip.cn-hangzhou-finance.aliyuncs.com | 暂无 |
华东 2 金融云(上海) | https://green-cip.cn-shanghai-finance-1.aliyuncs.com | 暂无 |
深圳金融云 | https://green-cip.cn-shenzhen-finance-1.aliyuncs.com | 暂无 |
新加坡 | green-cip.ap-southeast-1.aliyuncs.com | green-cip-vpc.ap-southeast-1.aliyuncs.com |
德国(法兰克福) | https://green-cip.eu-central-1.aliyuncs.com | https://green-cip-vpc.eu-central-1.aliyuncs.com |
计费信息:该接口为收费接口。仅对HTTP状态码为200的请求进行计量计费,产生其他错误码时不会计费。关于计费方式,请参见开通与计费概述部分。
图片要求:
图片支持以下格式:PNG、JPG、JPEG、BMP、WEBP、TIFF、SVG、AVIF、HEIF(该格式最长边需小于 8192 px)、GIF(取第一帧)、ICO(取最后一图)。
图片大小限制在 20 MB 以内,高或者宽不能超过 30,000 px,且总像素不能超过 2.5 亿 px。像素建议大于 200*200(px),像素过低会影响内容安全检测算法的效果。
图片下载时间限制为 3 秒内,如果下载时间超过 3 秒,返回下载超时。
QPS限制:本接口的单用户QPS限制为50次/秒(含有文件模态时,默认限制为10次/秒)。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。
请求参数
名称 | 类型 | 是否必须 | 示例值 | 描述 |
Service | String | 是 | query_security_check_pro |
重要 query_security_check_pro 与response_security_check_pro 已正式上线,其在内容合规防护维度上对检出标签进行了细粒度划分,标签总数较前一版本显著增加。
|
ServiceParameters | JSONString | 是 | 审核服务需要的参数集。JSON字符串格式,关于每个字符串的描述,请参见ServiceParameters。 |
表 1. ServiceParameters
名称 | 类型 | 是否必须 | 示例值 | 描述 |
content | String | 至少传入一项内容 | 文本检测内容 | 审核的文本内容 重要 最大支持单次2000字符输入 |
imageUrls | JSONArray | http://xxxx123 | 当前只支持一张图片 重要 | |
fileUrls | JSONArray | http://xxxx456 | 当前只支持一个文件 重要 文件大小不超过10M | |
chatId | String | 否(如选用流式审核,必须传入该字段) | ABC123 | 用于唯一标识一轮“用户输入 + 大模型输出”的交互记录。 |
sessionId | String | 否 | 14**** | 会话ID,标记本次请求内容属于同一个会话窗口中的多轮对话内容。 |
done | Boolean | 否(如选用流式审核,建议要传该字段) | true |
|
dataId | String | 否 | img123****** | 用于唯一标识检测内容 |
accountId | String | 否 | 13**** | 账户ID,标识一个账户的唯一ID。上下文审核功能需单独申请开通,如需开启请联系您的商务经理或提交工单申请。未开通时,accountId 仅用作账号标识,不会累积同一账号跨请求的上下文。需要完整审核的内容应放在单次请求中发送,将同一段内容分多次请求发送可能无法检出风险。 |
ip | String | 否 | 192.168.1.*** | 账号ID的IP地址 |
referer | String | 否 | www.aliyun.com | referer请求头,用于防盗链等场景。长度不超过256个字符。 |
referenceContent | String | 否 | 上下文内容 | 用于和待检测内容进行对比,检测模型幻觉的上下文内容。 重要 模型幻觉检测依赖该参数:如果您启用了模型幻觉检测能力,但未实际传入该内容,会导致幻觉检测能力无法生效。此时接口不会返回错误,而是正常返回检测结果(Code 200),但返回结果的 Detail 中不会出现 Type 为 modelHallucination 的检测项。如需自检幻觉检测是否生效,请参见本文示例章节中的「未检出幻觉(对照)」示例。 |
accountId、sessionId 和 chatId 都用于标识请求归属,但作用范围不同,下表说明三者的用途和使用场景。
参数 | 用途 | 使用场景 |
accountId | 标识同一账户发起的多次请求 | 账号级标识;如需按账号累积上下文进行审核,需单独申请开通上下文审核功能 |
sessionId | 标记本次请求内容属于同一个大模型输出的流式响应内容 | 需要按会话维度串联多个切片内容送审时传入 |
chatId | 唯一标识一轮“用户输入 + 大模型输出”的交互记录 | 选用流式审核时必须传入 |
返回参数
名称 | 类型 | 示例值 | 描述 |
Code | Integer | 200 | 状态码。更多信息,请参见Code说明。 |
Data | JSONObject | {"Result":[...]} | 审核结果数据,具体请参见Data。 |
Message | String | OK | 请求消息的响应消息。 |
RequestId | String | AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE**** | 请求ID。 |
表 2. Data
名称 | 类型 | 示例值 | 描述 |
Detail | JSONArray | 检测的内容合规风险标签、置信分等结果,具体请参见Detail。 | |
Suggestion | String | Pass | 审核建议
说明
|
表 3. Detail
名称 | 类型 | 示例值 | 描述 |
Suggestion | String | pass | 审核建议
说明
|
Type | String | contentSecurity | 防护维度
|
Level | String | high |
说明 高风险内容建议直接处置;中风险内容建议人工复查;低风险内容建议在高召回需求时再做处理,日常建议和未检测到风险做相同处理。风险分值可以在登录AI安全护栏产品控制台配置。
|
Result | JSONArray | 检测的内容合规风险标签、置信分等结果,具体请参见Result。 |
表 4. Result
名称 | 类型 | 示例值 | 描述 |
Description | String | 疑似政治实体 | 对Labal字段的说明。 重要 该字段为Label字段的解释说明,可能会变更调整,实际处理结果时建议处理Label字段,不要基于该字段进行结果处置。 |
Confidence | Float | 81.22 | 置信分值,0到100分,保留到小数点后2位。部分标签无置信分。 |
Label | String | political_xxx | 文字内容检测运算后返回的标签,可能会检出多个标签和分值。 |
Level | String | high |
说明 高风险内容建议直接处置;中风险内容建议人工复查;低风险内容建议在高召回需求时再做处理,日常建议和未检测到风险做相同处理。风险分值可以在登录AI安全护栏产品控制台配置。
|
Ext | JSONObject | 部分防护维度会返回相应的扩展信息,具体请参见Ext。 |
表 5. Ext
名称 | 类型 | 示例值 | 描述 |
Riskwords | String | AA,BB,CC | 适用防护维度: contentModeration 内容合规检测
|
CustomizedHit | JSONArray | [{"LibName":"...","Keywords":"..."}] | 适用防护维度: contentModeration 内容合规检测
|
SensitiveData | JSONArray | ["6201112223455"] | 适用防护维度: sensitiveData 敏感内容检测 检出敏感样本 |
Desensitization | String | ...【手机号码】是我的联系方式... | 适用防护维度: sensitiveData 敏感内容检测 脱敏后的内容 |
FileUrl | String | https://sase-public-server-files.oss-cn-hangzhou.aliyuncs.com/saas-XXX | 适用防护维度: waterMark 数字水印标识 含水印文件下载链接 |
OutFileSize | String | 152357 | 适用防护维度: waterMark 数字水印标识 文件大小 |
FileUrlExp | String | 1754135551 | 适用防护维度: waterMark 数字水印标识 含水印文件下载链接失效时间 |
Filename | String | B7VKehJ4gZR.png | 适用防护维度: waterMark 数字水印标识 文件名称 |
OutFileHashMd5 | String | 8b96ff73e8d8060016bb41b16d337871 | 适用防护维度: waterMark 数字水印标识 文件MD5标识 |
表 6. CustomizedHit
名称 | 类型 | 示例值 | 描述 |
LibName | String | 自定义库1 | 自定义库名称 |
Keywords | String | 自定义词1,自定义词2 | 自定义词,多个词用逗号分隔。 |
示例
请求示例
{
"Service": "XXX",
"ServiceParameters": {
"content": "这款保温杯支持IP67级防水,可以在水下使用。",
"chatId": "ABC123",
"dataId": "img123******",
"accountId":"abc",
"sessionId":"abc",
"imageUrls": ["http://xxxx"], # 当前只支持一张图片
"fileUrls": ["http://xxxx"], # 当前只支持一个文件
"referer": "http://www.aliyun.com",
"referenceContent": "产品名称:智能保温杯。材质:316不锈钢。保温时长:12小时。容量:500ml。包装清单:保温杯×1、说明书×1。"
}
}正确用法:将需要审核的完整内容放在单次请求中发送。同一段内容分多次请求发送时,各次请求相互独立送审,可能无法检出风险。如需按账号累积上下文进行审核,请先申请开通上下文审核功能。
返回示例:
检测query_security_check_pro,命中系统策略:
{
"Code": 200,
"RequestId": "AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****",
"Message": "OK",
"Data": {
"Suggestion": "block",
"Detail": [
{
"Suggestion": "block",
"Type": "maliciousUrl",
"Level": "high",
"Result": [
{
"Description": "信息盗取",
"Label": "Info Stealer",
"Level": "high"
}
]
},
{
"Suggestion": "mask",
"Type": "sensitiveData",
"Level": "S2",
"Result": [
{
"Ext": {
"Desensitization": "...【手机号码】是我的联系方式...",
"SensitiveData": [
"136********"
]
},
"Description": "手机号(中国内地)",
"Label": "1814",
"Level": "S2"
},
{
"Ext": {
"SensitiveData": [
"**市"
]
},
"Description": "城市(中国内地)",
"Label": "1739",
"Level": "S0"
}
]
},
{
"Suggestion": "block",
"Type": "promptAttack",
"Level": "high",
"Result": [
{
"Description": "拒绝抑制越狱",
"Confidence": 100,
"Label": "Refusal Supression Jailbreak",
"Level": "high"
}
]
},
{
"Suggestion": "block",
"Type": "customLabel",
"Level": "high",
"Result": [
{
"Description": "命中自定义标签",
"Label": "***业务风险表达",
"Level": "high"
}
]
},
{
"Suggestion": "block",
"Type": "contentModeration",
"Level": "high",
"Result": [
{
"Ext": {
"RiskWords": "某政治实体名称",
"Advice": [
{
"answer": "test",
"hitLabel": "political_entity",
"hitLibName": "pornographic_adult-0827"
}
]
},
"Description": "疑似政治实体",
"Confidence": 100,
"Label": "political_entity",
"Level": "high"
},
{
"Ext": {
"CustomizedHit": [
{
"LibName": "需加黑拦截",
"KeyWords": "词a,词b,词c"
}
]
},
"Description": "命中自定义库",
"Confidence": 100,
"Label": "customized",
"Level": "high"
}
]
},
{
"Result": [
{
"Description": "内在幻觉",
"Confidence": 95,
"Label": "Intrinsic Hallucination",
"Level": "medium"
}
],
"Type": "modelHallucination",
"Suggestion": "block",
"Level": "medium"
}
]
}
}检测img_response_security_check,命中系统策略:
{
"Code": 200,
"Data": {
"Detail": [
{
"Level": "none",
"Result": [
{
"Confidence": 0.0,
"Description": "未检测出风险",
"Ext": {
"FileUrl": "https://sase-public-server-files.oss-cn-hangzhou.aliyuncs.com/saas-XXX",
"OutFileSize": 527918,
"FileUrlExp": "1754200240",
"Filename": "wJGz6kmZ1Ce.jpg",
"OutFileHashMd5": "02f5129f606027c7a87b84377ec98f8e"
},
"Label": "nonLabel",
"Level": "none"
}
],
"Suggestion": "pass",
"Type": "waterMark"
},
{
"Level": "high",
"Result": [
{
"Confidence": 90,
"Description": "违反广告法-极限词",
"Label": "ad_Compliance_WordLimit_Tii",
"Level": "high"
}
],
"Suggestion": "block",
"Type": "contentModeration"
}
],
"Suggestion": "block"
},
"Msg": "OK"
}检测text_img_security_check,命中系统策略:
{
"Code": 200,
"Data": {
"Detail": [
{
"Ext": {},
"Level": "high",
"Result": [
{
"Confidence": 98.34,
"Description": "女性乳沟",
"Label": "sexual_Cleavage",
"Level": "high"
}
],
"Suggestion": "block",
"Type": "contentModeration"
}
],
"Suggestion": "block"
},
"Msg": "OK"
}检测file_security_sync_check,命中系统策略:
{
"Code": 200,
"Data": {
"Detail": [
{
"Ext": {},
"Level": "high",
"Result": [
{
"Confidence": 100,
"Description": "网站后门",
"Label": "WebShell",
"Level": "high"
}
],
"Suggestion": "block",
"Type": "maliciousFile"
},
{
"Ext": {
"PageSum": 1
},
"Level": "none",
"Result": [
{
"Description": "未检测出风险",
"Label": "nonLabel",
"Level": "none"
}
],
"Suggestion": "pass",
"Type": "contentModeration"
}
],
"Suggestion": "block"
},
"Msg": "OK"
}检测text_file_sec_sync_check,命中系统策略:
{
"Code": 200,
"Data": {
"Detail": [
{
"Ext": {
"PageSum": 4
},
"Level": "none",
"Result": [
{
"Description": "未检测出风险",
"Label": "nonLabel",
"Level": "none"
}
],
"Suggestion": "pass",
"Type": "contentModeration"
}
],
"Suggestion": "pass"
},
"Msg": "OK"
}模型幻觉检测示例
模型幻觉(公测中)检测通过将大模型生成的内容与 referenceContent 传入的参考内容进行对比,识别模型输出中虚假或不准确的信息。以下示例覆盖三类典型幻觉场景和一个未检出对照场景,每个示例包含场景描述、输入内容(待检测内容 + referenceContent)、检测结果和结果解释,您可以复制示例内容自检接入效果。使用前提:已在防护配置中为该 Service 开启模型幻觉维度,并在请求的 ServiceParameters 中传入 referenceContent。
场景一:编造参考内容中不存在的信息
场景描述:参考内容中未提及防水能力,模型输出虚构了「IP67 级防水」,属于编造不存在的信息。
输入内容:
{
"Service": "query_security_check_pro",
"ServiceParameters": {
"content": "这款保温杯支持IP67级防水,可以在水下使用。",
"referenceContent": "产品名称:智能保温杯。材质:316不锈钢。保温时长:12小时。容量:500ml。包装清单:保温杯×1、说明书×1。"
}
}检测结果:
{
"Code": 200,
"Message": "OK",
"RequestId": "AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****",
"Data": {
"Suggestion": "block",
"Detail": [
{
"Type": "modelHallucination",
"Suggestion": "block",
"Level": "medium",
"Result": [
{
"Description": "内在幻觉",
"Confidence": 95,
"Label": "Intrinsic Hallucination",
"Level": "medium"
}
]
}
]
}
}结果解释:待检测内容中的「IP67 级防水」在参考内容中没有依据,被判定为模型幻觉。返回结果 Detail 中出现 Type 为 modelHallucination 的检测项,Label 为 Intrinsic Hallucination(内在幻觉),Confidence 为幻觉判定置信分,审核建议为阻断(block)。
场景二:虚构与参考内容矛盾的信息
场景描述:参考内容明确支持 7 天无理由退货,模型输出却声称「不支持退货」,属于虚构与参考内容相矛盾的信息。
输入内容:
{
"Service": "query_security_check_pro",
"ServiceParameters": {
"content": "该商品不支持退货,下单后无法退款。",
"referenceContent": "售后服务:本商品支持7天无理由退货,退货运费由买家自理。"
}
}检测结果:
{
"Code": 200,
"Message": "OK",
"RequestId": "AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****",
"Data": {
"Suggestion": "block",
"Detail": [
{
"Type": "modelHallucination",
"Suggestion": "block",
"Level": "medium",
"Result": [
{
"Description": "内在幻觉",
"Confidence": 95,
"Label": "Intrinsic Hallucination",
"Level": "medium"
}
]
}
]
}
}结果解释:待检测内容与参考内容中的退货政策直接矛盾,被判定为模型幻觉(Intrinsic Hallucination,内在幻觉),审核建议为阻断(block)。
未检出幻觉(对照)
场景描述:模型输出与参考内容一致,未检出幻觉。此时返回结果正常(Code 200),但 Detail 中不出现 Type 为 modelHallucination 的检测项。
输入内容:
{
"Service": "query_security_check_pro",
"ServiceParameters": {
"content": "这款保温杯的保温时长为12小时,容量是500ml。",
"referenceContent": "产品名称:智能保温杯。材质:316不锈钢。保温时长:12小时。容量:500ml。包装清单:保温杯×1、说明书×1。"
}
}检测结果:
{
"Code": 200,
"Message": "OK",
"RequestId": "AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****",
"Data": {
"Suggestion": "pass",
"Detail": []
}
}结果解释:待检测内容忠实于参考内容,未判定为幻觉,因此 Detail 中没有 modelHallucination 检测项。这也是开启模型幻觉维度但未传入 referenceContent 时的返回表现——接口不报错,但不返回幻觉检测结果,请先检查请求中是否传入了 referenceContent。
检测结果中的
Label、Description、Confidence等字段取值以接口实际返回为准。模型幻觉检测能力当前处于公测阶段。
Code说明
Code | 状态代码 | 说明 |
200 | OK | 原因:请求处理成功。 |
400 | BAD_REQUEST | 原因:请求有误,通常是请求参数不正确导致。 |
408 | PERMISSION_DENY | 原因:请求被拒绝授权校验,可能是账号未授权、账号欠费、账号未开通、账号被禁等。 |
500 | GENERAL_ERROR | 原因:服务端临时出错。 |
581 | TIMEOUT | 原因:请求超时。 |
588 | EXCEED_QUOTA | 原因:请求频率超出配额。本接口的单用户 QPS 限制为 50 次/秒(含有文件模态时,默认限制为 10 次/秒)。 |
已开启模型幻觉维度,但返回结果中没有模型幻觉检测项,如何排查?
模型幻觉(公测中)维度在返回结果中不生效时不会返回错误码:接口正常返回(Code 200),但 Detail 中不出现 Type 为 modelHallucination 的检测项。遇到该情况时,请按以下顺序排查:
确认请求的
ServiceParameters中传入了referenceContent参数。模型幻觉检测依赖该参数与待检测内容进行对比,未传入时不会返回幻觉检测结果。参数说明及可自检的调用示例,请参见本文「请求参数」与「示例」章节。确认该 Service 为文本类服务(如 AI 输入内容安全检测、AI 生成内容安全检测)。模型幻觉维度仅文本类 Service 支持,图片、文件、视频、音频类服务不支持该维度。
登录AI安全护栏产品控制台,在防护配置 > 模型防护中选择对应 Service,进入配置管理 > 防护维度,确认模型幻觉卡片处于开启状态。
在模型幻觉卡片的配置管理中检查幻觉检测程度:该项用于调节模型幻觉检测拦截的分数,当模型返回分数超过设置数值时,才会判断为模型幻觉。取值范围 60~100,默认 60。若本次内容的判定分未达到设置的拦截分数,则不会返回幻觉检测结果。
若以上各项均已确认但仍未返回幻觉检测结果,请提交工单并附上 RequestId。