# 添加AI护栏规则 #### 功能介绍 添加AI护栏规则 #### URI POST /v1/{project_id}/aiguard/{policy_id}/llmrules 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 项目ID，用于标识请求所属的项目 **约束限制：** 字符串类型，32位UUID **取值范围：** 只能由英文字母、数字组成，长度为1\~64个字符 **默认取值：** 不涉及 | | policy_id | 是 | String | **参数解释：** 策略ID，用于标识AI护栏策略 **约束限制：** 字符串类型，32位UUID **取值范围：** 只能由英文字母、数字组成，长度为1\~64个字符 **默认取值：** 不涉及 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释：** 用户Token，用于验证请求的合法性。通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值) **约束限制：** 字符串类型，长度1\~16384个字符 **取值范围：** 只能由英文字母、数字及"-"、"_"组成 **默认取值：** 不涉及 | | Content-Type | 是 | String | **参数解释：** 内容类型，用于指定请求体的媒体类型 **约束限制：** 固定值application/json **取值范围：** application/json **默认取值：** application/json | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释：** 规则名称，用于标识AI护栏规则。 **约束限制：** 字符串类型，必填，长度1-255字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | detect_opts | 是 | Array of [DetectOpt] objects | **参数解释：** 检测选项配置列表，用于配置AI护栏规则的检测选项。 **约束限制：** 数组类型，必填，最多10个元素。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | action | 是 | [AiGuardRuleAction] object | **参数解释：** 防护动作，用于指定AI护栏规则的防护动作。 **约束限制：** 对象类型，必填。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | detect_labels | 是 | [DetectLabels] object | **参数解释：** 检测标签配置，用于配置AI护栏规则的检测标签。 **约束限制：** 对象类型，必填。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | description | 否 | String | **参数解释：** 规则描述，用于补充说明规则的用途或备注信息。 **约束限制：** 字符串类型，非必填，最大长度1024字符。 **取值范围：** 长度0\~1024的字符串。 **默认取值：** 不涉及。 | | not_supported_language_action | 否 | String | **参数解释：** 不支持语言的防护动作，支持pass和block。 **约束限制：** 字符串类型，必填。 **取值范围：** pass、block。 **默认取值：** 不涉及。 | | detect_target | 否 | String | **参数解释：** 检测目标，当detect_type=image时生效，ocr代表图片中提取的文本，content代表图片语义。 **约束限制：** 字符串类型，非必填，当detect_type=image时生效。 **取值范围：** ocr、content。 **默认取值：** 不涉及。 | | custom_answers_id | 否 | String | **参数解释：** 自定义代答库ID，当action.category=block时有效。 **约束限制：** 字符串类型，非必填，当action.category=block时有效。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | abuse_config | 否 | [AbuseConfig] object | **参数解释：** 算力滥用配置，当detect_opts包含type=abuse且enable=true时必填。 **约束限制：** 对象类型，当detect_opts包含type=abuse且enable=true时该字段必填。 **取值范围：** 对象类型，包含scope和threshold字段。 **默认取值：** 不涉及。 | | topic_config | 否 | [TopicConfig] object | **参数解释：** 话题控制配置，当detect_opts包含type=topic_detect且enable=true时必填。 **约束限制：** 对象类型，非必填，当detect_opts包含type=topic_detect且enable=true时必填。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表4DetectOpt | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 否 | String | **参数解释：** 检测类型，用于标识检测的类型。 **约束限制：** 字符串类型，必填。 **取值范围：** lexicon(词库检测)、compliance(合规检测)、inject(注入检测)、immunity_lexicon(豁免词库)、supported_language(语言检测)、pii(敏感词检测)、abuse(算力滥用检测)、topic_detect(话题检测)。当detect_target=image时，immunity_lexicon(豁免词库)不生效。 **默认取值：** 不涉及。 | | enable | 否 | Boolean | **参数解释：** 是否启用该检测类型，用于标识检测类型的启用状态。 **约束限制：** 布尔类型，必填。 **取值范围：** true(启用)、false(禁用)。 **默认取值：** 不涉及。 | 表5AiGuardRuleAction | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | category | 否 | String | **参数解释：** 动作分类，用于标识防护动作的类型。 **约束限制：** 字符串类型，必填。 **取值范围：** log(仅记录)、block(拦截)、desensitize(脱敏)。 **默认取值：** 不涉及。 | 表6DetectLabels | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | compliance_labels | 否 | Array of strings | **参数解释：** 合规检测标签列表，用于配置合规检测标签。 **约束限制：** 数组类型，非必填。 **取值范围：** 字符串数组，最多10个元素。 **默认取值：** 不涉及。 | | inject_labels | 否 | Array of strings | **参数解释：** 注入检测标签列表，用于配置注入检测标签。 **约束限制：** 数组类型，非必填。 **取值范围：** 字符串数组，最多10个元素。 **默认取值：** 不涉及。 | | immunity_lexicon_labels | 否 | Array of strings | **参数解释：** 豁免词库标签列表，用于配置豁免词库标签。 **约束限制：** 数组类型，非必填。 **取值范围：** 字符串数组，最多10个元素。 **默认取值：** 不涉及。 | | lexicon_labels | 否 | Array of strings | **参数解释：** 自定义词库检测标签列表，用于配置自定义词库检测标签。 **约束限制：** 数组类型，非必填。 **取值范围：** 字符串数组，最多10个元素。 **默认取值：** 不涉及。 | | lexicon_internal_labels | 否 | Array of strings | **参数解释：** 内置词库检测标签列表，用于配置内置词库检测标签。 **约束限制：** 数组类型，非必填。 **取值范围：** 字符串数组，最多10个元素。 **默认取值：** 不涉及。 | | supported_language_labels | 否 | Array of strings | **参数解释：** 支持检测语言标签列表，用于配置支持的语言检测标签。 **约束限制：** 数组类型，非必填。 **取值范围：** 字符串数组，最多100个元素。 **默认取值：** 不涉及。 | | pii_labels | 否 | Array of strings | **参数解释：** 敏感词标签列表，用于配置敏感词检测标签。 **约束限制：** 数组类型，非必填。 **取值范围：** 字符串数组，最多100个元素。 **默认取值：** 不涉及。 | 表7AbuseConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | scope | 否 | [AbuseScope] object | **参数解释：** 请求统计范围，用于指定算力滥用的统计范围。 **约束限制：** 对象类型，必填。 **取值范围：** 对象类型，包含type和user_identifier字段。 **默认取值：** 不涉及。 | | threshold | 否 | [AbuseThreshold] object | **参数解释：** 触发阈值配置，用于指定算力滥用的触发阈值。 **约束限制：** 对象类型，必填。 **取值范围：** 对象类型，包含time_window_seconds和conditions字段。 **默认取值：** 不涉及。 | 表8AbuseScope | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 否 | String | **参数解释：** 统计范围类型，用于指定算力滥用的统计方式。 **约束限制：** 字符串类型，必填。 **取值范围：** all_users：统计所有用户的合并用量；single_user：按单个用户统计用量。 **默认取值：** 不涉及。 | | user_identifier | 否 | String | **参数解释：** 用户标识字段名，当type=single_user时必填，指定用户标识字段名。 **约束限制：** 字符串类型，当type=single_user时必填。 **取值范围：** 字符串类型，如user_id、app_id、ip等，长度1\~64字符。 **默认取值：** 不涉及。 | 表9AbuseThreshold | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | time_window_seconds | 否 | Integer | **参数解释：** 统计时间窗口（秒），用于指定阈值统计的时间范围。 **约束限制：** 整数类型，必填。 **取值范围：** 1\~86400的整数，如60/300/3600。 **默认取值：** 不涉及。 | | conditions | 否 | Array of [AbuseCondition] objects | **参数解释：** 阈值条件列表，用于指定触发阈值的条件。 **约束限制：** 数组类型，当前版本必须恰好1个条件。 **取值范围：** 数组类型，每个元素为AbuseCondition对象。 **默认取值：** 不涉及。 | 表10AbuseCondition | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | dimension | 否 | String | **参数解释：** 算力消耗统计维度，用于指定统计的维度。 **约束限制：** 字符串类型，必填。 **取值范围：** input：仅统计模型输入；output：仅统计模型输出；input_output：统计输入+输出的合并。 **默认取值：** 不涉及。 | | metric | 否 | String | **参数解释：** 阈值指标类型，用于指定阈值的衡量方式。 **约束限制：** 字符串类型，必填。 **取值范围：** call_count：调用次数；char_count：字符数。 **默认取值：** 不涉及。 | | value | 否 | Long | **参数解释：** 阈值数值，用于指定触发阈值的具体数值。 **约束限制：** 整数类型，必填，必须大于0。当metric=call_count时上限为1,000,000，当metric=char_count时上限为1,000,000,000,000。 **取值范围：** metric=call_count时：1\~1,000,000；metric=char_count时：1\~1,000,000,000,000。 **默认取值：** 不涉及。 | 表11TopicConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | topic_name | 是 | String | **参数解释：** 话题名称。 **约束限制：** 必填，字符串类型，最大长度20个字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | topic_description | 是 | String | **参数解释：** 话题描述。 **约束限制：** 必填，字符串类型，最大长度500个字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | sensitive_words | 否 | Array of strings | **参数解释：** 敏感词列表。 **约束限制：** 非必填，数组类型，最多100个元素，每个元素最大长度20个字符。 **取值范围：** 数组元素为字符串类型。 **默认取值：** 不涉及。 | | black_samples | 否 | Array of strings | **参数解释：** 黑样本列表。 **约束限制：** 非必填，数组类型，最多10个元素，每个元素最大长度100个字符。 **取值范围：** 数组元素为字符串类型。 **默认取值：** 不涉及。 | | white_samples | 否 | Array of strings | **参数解释：** 白样本列表。 **约束限制：** 非必填，数组类型，最多10个元素，每个元素最大长度100个字符。 **取值范围：** 数组元素为字符串类型。 **默认取值：** 不涉及。 | | scope | 是 | String | **参数解释：** 检测作用域。 **约束限制：** 必填，字符串类型，取值为request、response或request_response。 **取值范围：** request、response、request_response。 **默认取值：** 不涉及。 | | block_response | 否 | String | **参数解释：** 拦截回包内容，仅外层action.category=block时有意义，非block落库归一化为null。 **约束限制：** 非必填，字符串类型，最大长度2048个字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | custom_llm_id | 否 | String | **参数解释：** 关联的自定义大模型ID。 **约束限制：** 非必填，字符串类型。传入时校验自定义大模型是否存在。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 规则ID，用于唯一标识规则 **取值范围：** 字符串类型，长度1-64字符 | | name | String | **参数解释：** 规则名称，用于标识规则的名称 **取值范围：** 字符串类型，长度1-255字符 | | policy_id | String | **参数解释：** 策略ID，用于标识规则所属的策略 **取值范围：** 字符串类型，32位UUID | | status | String | **参数解释：** 规则状态，用于标识规则的启用状态 **取值范围：** enable(启用)、disable(禁用) | | detect_opts | Array of [DetectOpt] objects | **参数解释：** 检测选项配置列表，用于配置AI护栏规则的检测选项 **取值范围：** 数组类型，每个元素为DetectOpt对象 | | action | [AiGuardRuleAction] object | **参数解释：** 防护动作，用于指定AI护栏规则的防护动作 **取值范围：** 对象类型，包含category字段 | | detect_labels | [DetectLabels] object | **参数解释：** 检测标签配置，用于配置AI护栏规则的检测标签 **取值范围：** 对象类型，包含多个标签列表 | | create_time | Long | **参数解释：** 创建时间，用于标识规则的创建时间 **取值范围：** 毫秒时间戳，大于0的整数 | | update_time | Long | **参数解释：** 更新时间，用于标识规则的最后更新时间 **取值范围：** 毫秒时间戳，大于0的整数 | | detect_labels_info | [DetectLabelsInfo] object | **参数解释：** 检测标签详情，用于返回检测标签的详细信息 **取值范围：** 对象类型，DetectLabelsInfo对象 | | abuse_config | [AbuseConfig] object | **参数解释：** 算力滥用配置，仅当detect_opts包含type=abuse且enable=true时返回。 **取值范围：** 对象类型，包含scope和threshold字段。 | | detect_type | String | **参数解释：** 检测类别。text: 文本检测, image: 图片检测，为null时代表文字 **取值范围：** text、image | | detect_target | String | **参数解释：** 检测目标，detect_type=image时有效。ocr代表图片中提取的文本，content代表图片语义 **取值范围：** ocr、content | | not_supported_language_action | String | **参数解释：** 不支持语言的检测防护动作，detect_opts为supported_language有效。pass: 放行, block: 拦截。 **取值范围：** pass、block | | source | String | **参数解释：** 规则来源，system代表系统，custom代表用户创建 **取值范围：** system、custom | | source_id | String | **参数解释：** 当source=system时，source_id为默认模板规则的Id **取值范围：** 字符串类型，8位字符 | | description | String | **参数解释：** 规则描述，最大长度1024 **取值范围：** 字符串类型，长度0-1024字符 | | custom_answers_id | String | **参数解释：** 自定义代答库ID，当action.category=block时有效。 **取值范围：** 不涉及。 | | custom_answers_name | String | **参数解释：** 自定义代答库名称，当action.category=block时有效，与custom_answers_id对应。 **取值范围：** 不涉及。 | | topic_config | [TopicConfig] object | **参数解释：** 话题控制配置，仅当detect_opts包含type=topic_detect且enable=true时返回。 **取值范围：** 不涉及。 | 表13DetectOpt | 参数 | 参数类型 | 描述 | |:---|:---|:---| | type | String | **参数解释：** 检测类型，用于标识检测的类型。 **取值范围：** lexicon(词库检测)、compliance(合规检测)、inject(注入检测)、immunity_lexicon(豁免词库)、supported_language(语言检测)、pii(敏感词检测)、abuse(算力滥用检测)、topic_detect(话题检测)。当detect_target=image时，immunity_lexicon(豁免词库)不生效。 | | enable | Boolean | **参数解释：** 是否启用该检测类型，用于标识检测类型的启用状态。 **取值范围：** true(启用)、false(禁用)。 | 表14AiGuardRuleAction | 参数 | 参数类型 | 描述 | |:---|:---|:---| | category | String | **参数解释：** 动作分类，用于标识防护动作的类型。 **取值范围：** log(仅记录)、block(拦截)、desensitize(脱敏)。 | 表15DetectLabels | 参数 | 参数类型 | 描述 | |:---|:---|:---| | compliance_labels | Array of strings | **参数解释：** 合规检测标签列表，用于配置合规检测标签。 **取值范围：** 字符串数组，最多10个元素。 | | inject_labels | Array of strings | **参数解释：** 注入检测标签列表，用于配置注入检测标签。 **取值范围：** 字符串数组，最多10个元素。 | | immunity_lexicon_labels | Array of strings | **参数解释：** 豁免词库标签列表，用于配置豁免词库标签。 **取值范围：** 字符串数组，最多10个元素。 | | lexicon_labels | Array of strings | **参数解释：** 自定义词库检测标签列表，用于配置自定义词库检测标签。 **取值范围：** 字符串数组，最多10个元素。 | | lexicon_internal_labels | Array of strings | **参数解释：** 内置词库检测标签列表，用于配置内置词库检测标签。 **取值范围：** 字符串数组，最多10个元素。 | | supported_language_labels | Array of strings | **参数解释：** 支持检测语言标签列表，用于配置支持的语言检测标签。 **取值范围：** 字符串数组，最多100个元素。 | | pii_labels | Array of strings | **参数解释：** 敏感词标签列表，用于配置敏感词检测标签。 **取值范围：** 字符串数组，最多100个元素。 | 表16DetectLabelsInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | compliance_labels_info | Array of [LabelInfo] objects | **参数解释：** 合规检测标签详情列表 **取值范围：** 数组类型，最多100个元素 | | inject_labels_info | Array of [LabelInfo] objects | **参数解释：** 注入检测标签详情列表 **取值范围：** 数组类型，最多100个元素 | | immunity_lexicon_labels_info | Array of [LabelInfo] objects | **参数解释：** 豁免词库标签详情列表 **取值范围：** 数组类型，最多100个元素 | | lexicon_labels_info | Array of [LabelInfo] objects | **参数解释：** 自定义词库检测标签详情列表 **取值范围：** 数组类型，最多100个元素 | | lexicon_internal_labels_info | Array of [LabelInfo] objects | **参数解释：** 内置词库检测标签详情列表 **取值范围：** 数组类型，最多100个元素 | | supported_language_labels | Array of [LabelInfo] objects | **参数解释：** 语言检测标签信息列表 **取值范围：** 数组类型，最多100个元素 | | pii_labels_info | Array of [LabelInfo] objects | **参数解释：** 敏感词的标签详情列表 **取值范围：** 数组类型，最多100个元素 | 表17LabelInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | label | String | **参数解释：** 检测标签，用于标识检测的标签 **取值范围：** 字符串类型，长度1-50字符 | | name | String | **参数解释：** 检测名称，用于标识检测的名称 **取值范围：** 字符串类型，长度0-256字符 | 表18AbuseConfig | 参数 | 参数类型 | 描述 | |:---|:---|:---| | scope | [AbuseScope] object | **参数解释：** 请求统计范围，用于指定算力滥用的统计范围。 **取值范围：** 对象类型，包含type和user_identifier字段。 | | threshold | [AbuseThreshold] object | **参数解释：** 触发阈值配置，用于指定算力滥用的触发阈值。 **取值范围：** 对象类型，包含time_window_seconds和conditions字段。 | 表19AbuseScope | 参数 | 参数类型 | 描述 | |:---|:---|:---| | type | String | **参数解释：** 统计范围类型，用于指定算力滥用的统计方式。 **取值范围：** all_users：统计所有用户的合并用量；single_user：按单个用户统计用量。 | | user_identifier | String | **参数解释：** 用户标识字段名，当type=single_user时必填，指定用户标识字段名。 **取值范围：** 字符串类型，如user_id、app_id、ip等，长度1\~64字符。 | 表20AbuseThreshold | 参数 | 参数类型 | 描述 | |:---|:---|:---| | time_window_seconds | Integer | **参数解释：** 统计时间窗口（秒），用于指定阈值统计的时间范围。 **取值范围：** 1\~86400的整数，如60/300/3600。 | | conditions | Array of [AbuseCondition] objects | **参数解释：** 阈值条件列表，用于指定触发阈值的条件。 **取值范围：** 数组类型，每个元素为AbuseCondition对象。 | 表21AbuseCondition | 参数 | 参数类型 | 描述 | |:---|:---|:---| | dimension | String | **参数解释：** 算力消耗统计维度，用于指定统计的维度。 **取值范围：** input：仅统计模型输入；output：仅统计模型输出；input_output：统计输入+输出的合并。 | | metric | String | **参数解释：** 阈值指标类型，用于指定阈值的衡量方式。 **取值范围：** call_count：调用次数；char_count：字符数。 | | value | Long | **参数解释：** 阈值数值，用于指定触发阈值的具体数值。 **取值范围：** metric=call_count时：1\~1,000,000；metric=char_count时：1\~1,000,000,000,000。 | 表22TopicConfig | 参数 | 参数类型 | 描述 | |:---|:---|:---| | topic_name | String | **参数解释：** 话题名称。 **取值范围：** 不涉及。 | | topic_description | String | **参数解释：** 话题描述。 **取值范围：** 不涉及。 | | sensitive_words | Array of strings | **参数解释：** 敏感词列表。 **取值范围：** 数组元素为字符串类型。 | | black_samples | Array of strings | **参数解释：** 黑样本列表。 **取值范围：** 数组元素为字符串类型。 | | white_samples | Array of strings | **参数解释：** 白样本列表。 **取值范围：** 数组元素为字符串类型。 | | scope | String | **参数解释：** 检测作用域。 **取值范围：** request、response、request_response。 | | block_response | String | **参数解释：** 拦截回包内容，仅外层action.category=block时有意义，非block落库归一化为null。 **取值范围：** 不涉及。 | | custom_llm_id | String | **参数解释：** 关联的自定义大模型ID。 **取值范围：** 不涉及。 | **状态码：400** 表23响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，用于标识错误类型 **取值范围：** 字符串类型，长度1\~64字符 | | error_msg | String | **参数解释：** 错误信息，用于描述错误详情 **取值范围：** 字符串类型，长度1\~2048字符 | **状态码：500** 表24响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，用于标识错误类型 **取值范围：** 字符串类型，长度1\~64字符 | | error_msg | String | **参数解释：** 错误信息，用于描述错误详情 **取值范围：** 字符串类型，长度1\~2048字符 | #### 请求示例 ``` { "name" : "llmtt20260209", "detect_opts" : [ { "type" : "immunity_lexicon", "enable" : true }, { "type" : "lexicon", "enable" : false }, { "type" : "compliance", "enable" : false }, { "type" : "inject", "enable" : false } ], "action" : { "category" : "log" }, "detect_labels" : { "compliance_labels" : [ "", "", "" ], "inject_labels" : [ "", "", "" ], "immunity_lexicon_labels" : [ "111", "", "" ], "lexicon_labels" : [ "", "", "" ] } } ``` #### 响应示例 **状态码：200** 操作成功 ``` { "id" : "b313fef51f874f0e89ec215b80effa9e", "name" : "llmtt20260209", "detect_opts" : [ { "type" : "immunity_lexicon", "enable" : true }, { "type" : "lexicon", "enable" : false }, { "type" : "compliance", "enable" : false }, { "type" : "inject", "enable" : false } ], "action" : { "category" : "log" }, "detect_labels" : { "compliance_labels" : [ "", "", "" ], "inject_labels" : [ "", "", "" ], "immunity_lexicon_labels" : [ "111", "", "" ], "lexicon_labels" : [ "", "", "" ] } } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 操作成功 | | 400 | 参数错误 | | 500 | 服务端内部错误 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-waf/ErrorCode.html)。