本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在您的应用程序中使用 ApplyGuardrail API
护栏用于为您的生成式人工智能应用程序实现保护措施，这些保护措施是针对您的应用场景定制的，并且符合您的负责任的人工智能策略的要求。护栏让您能够配置拒绝的主题、筛除有害内容和删除敏感信息。
您可以通过预先配置的 Amazon Bedrock 护栏，使用 `ApplyGuardrail` API 来评估任何文本，而无需调用基础模型。
`ApplyGuardrail` API 的功能包括：
+ **内容验证** – 您可以将任何文本输入或输出发送到 `ApplyGuardrail` API，以将其与您定义的主题规避规则、内容筛选条件、PII 检测器和单词阻止列表进行比较。您可以分别评估用户输入和 FM 生成的输出。
+ **灵活部署** – 您可以将 `ApplyGuardrail` API 集成到应用程序流中的任何位置，以便在处理数据或向用户提供结果之前验证数据。例如，如果您使用的是 RAG 应用程序，则现在可以在执行检索之前评估用户输入，而不必等到生成最终响应。
+ **与基础模型分离** – `ApplyGuardrail` API 与基础模型相分离。现在，您无需调用基础模型即可使用护栏。您可以使用评估结果来设计生成式人工智能应用程序中的体验。
**Topics**
+ [调 ApplyGuardrail 用您的申请流程](#guardrails-use-independent-api-call)
+ [指定要与之配合使用的护栏 ApplyGuardrail](#guardrails-use-indepedent-api-call-configure)
+ [的示例用例 ApplyGuardrail](#guardrails-use-independent-api-call-message)
+ [作为 ApplyGuardrail 响应，返回完整输出](#guardrails-use-return-full-assessment)
## 调 ApplyGuardrail 用您的申请流程
请求允许客户传递所有应该使用其定义的护栏进行保护的内容。当要评估的内容来自用户时（通常是对 LLM 的输入提示），应将源字段设置为 `INPUT`。在应该强制执行模型输出护栏时（通常是 LLM 响应），应将源设置为 `OUTPUT`。
## 指定要与之配合使用的护栏 ApplyGuardrail
使用 `ApplyGuardrail` 时，您需要指定要使用的护栏的 `{{guardrailIdentifier}}` 和 `{{guardrailVersion}}`。您还可以为护栏启用跟踪功能，该功能可以提供护栏阻止的内容的相关信息。
------
#### [ ApplyGuardrail API request ]
```
POST /guardrail/{{{guardrailIdentifier}}}/version/{{{guardrailVersion}}}/apply HTTP/1.1
{
"source": "INPUT" | "OUTPUT",
"content": [{
"text": {
"text": "string",
}
}, ]
}
```
------
#### [ ApplyGuardrail API response ]
```
{
"usage": {
"topicPolicyUnits": "integer",
"contentPolicyUnits": "integer",
"wordPolicyUnits": "integer",
"sensitiveInformationPolicyUnits": "integer",
"sensitiveInformationPolicyFreeUnits": "integer",
"contextualGroundingPolicyUnits": "integer"
},
"action": "GUARDRAIL_INTERVENED" | "NONE",
"output": [
// if guardrail intervened and output is masked we return request in same format
// with masking
// if guardrail intervened and blocked, output is a single text with canned message
// if guardrail did not intervene, output is empty array
{
"text": "string",
},
],
"assessments": [{
"topicPolicy": {
"topics": [{
"name": "string",
"type": "DENY",
"action": "BLOCKED",
}]
},
"contentPolicy": {
"filters": [{
"type": "INSULTS | HATE | SEXUAL | VIOLENCE | MISCONDUCT |PROMPT_ATTACK",
"confidence": "NONE" | "LOW" | "MEDIUM" | "HIGH",
"filterStrength": "NONE" | "LOW" | "MEDIUM" | "HIGH",
"action": "BLOCKED"
}]
},
"wordPolicy": {
"customWords": [{
"match": "string",
"action": "BLOCKED"
}],
"managedWordLists": [{
"match": "string",
"type": "PROFANITY",
"action": "BLOCKED"
}]
},
"sensitiveInformationPolicy": {
"piiEntities": [{
// for all types see: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GuardrailPiiEntityConfig.html#bedrock-Type-GuardrailPiiEntityConfig-type
"type": "ADDRESS" | "AGE" | ...,
"match": "string",
"action": "BLOCKED" | "ANONYMIZED"
}],
"regexes": [{
"name": "string",
"regex": "string",
"match": "string",
"action": "BLOCKED" | "ANONYMIZED"
}],
"contextualGroundingPolicy": {
"filters": [{
"type": "GROUNDING | RELEVANCE",
"threshold": "double",
"score": "double",
"action": "BLOCKED | NONE"
}]
},
"invocationMetrics": {
"guardrailProcessingLatency": "integer",
"usage": {
"topicPolicyUnits": "integer",
"contentPolicyUnits": "integer",
"wordPolicyUnits": "integer",
"sensitiveInformationPolicyUnits": "integer",
"sensitiveInformationPolicyFreeUnits": "integer",
"contextualGroundingPolicyUnits": "integer"
},
"guardrailCoverage": {
"textCharacters": {
"guarded":"integer",
"total": "integer"
}
}
}
},
"guardrailCoverage": {
"textCharacters": {
"guarded": "integer",
"total": "integer"
}
}
]
}
```
------
## 的示例用例 ApplyGuardrail
`ApplyGuardrail` 请求的输出取决于护栏对传递的内容采取的操作。
+ 如果护栏进行了干预并且仅掩蔽了部分内容，则系统会返回原始内容，其中包含被掩蔽的部分。
+ 如果护栏进行了干预并屏蔽了请求内容，则输出字段将是单个文本，这是基于护栏配置的固定消息。
+ 如果护栏未对请求内容采取任何操作，则输出数组为空。
------
#### [ Guardrails takes no action ]
**请求示例**
```
{
"source": "OUTPUT",
"content": [
"text": {
"text": "Hi, my name is Zaid. Which car brand is reliable?"
}
]
}
```
**响应示例**
```
{
"usage": {
"topicPolicyUnitsProcessed": 1,
"contentPolicyUnitsProcessed": 1,
"wordPolicyUnitsProcessed": 0,
"sensitiveInformationPolicyFreeUnits": 0
},
"action": "NONE",
"outputs": [],
"assessments": [{}]
}
```
------
#### [ Guardrails blocks content ]
**响应示例**
```
{
"usage": {
"topicPolicyUnitsProcessed": 1,
"contentPolicyUnitsProcessed": 1,
"wordPolicyUnitsProcessed": 0,
"sensitiveInformationPolicyFreeUnits": 0
},
"action": "GUARDRAIL_INTERVENED",
"outputs": [{
"text": "Configured guardrail canned message (i.e., can't respond)"
}],
"assessments": [{
"topicPolicy": {
"topics": [{
"name": "Cars",
"type": "DENY",
"action": "BLOCKED"
}]
},
"sensitiveInformationPolicy": {
"piiEntities": [{
"type": "NAME",
"match": "ZAID",
"action": "ANONYMIZED"
}],
"regexes": []
}
}]
}
```
------
#### [ Guardrails masks content ]
**响应示例**
护栏通过屏蔽名称 `ZAID` 进行干预。
```
{
"usage": {
"topicPolicyUnitsProcessed": 1,
"contentPolicyUnitsProcessed": 1,
"wordPolicyUnitsProcessed": 0,
"sensitiveInformationPolicyFreeUnits": 0
},
"action": "GUARDRAIL_INTERVENED",
"outputs": [{
"text": "Hi, my name is {NAME}. Which car brand is reliable?"
},
{
"text": "Hello {NAME}, ABC Cars are reliable ..."
}
],
"assessments": [{
"sensitiveInformationPolicy": {
"piiEntities": [{
"type": "NAME",
"match": "ZAID",
"action": "ANONYMIZED"
}],
"regexes": []
}
}]
}
```
------
#### [ AWS CLI example ]
**输入示例**
```
aws bedrock-runtime apply-guardrail \
--cli-input-json '{
"guardrailIdentifier": "someGuardrailId",
"guardrailVersion": "DRAFT",
"source": "INPUT",
"content": [
{
"text": {
"text": "How should I invest for my retirement? I want to be able to generate $5,000 a month"
}
}
]
}' \
--region us-east-1 \
--output json
```
**输出示例（块内容）**
```
{
"usage": {
"topicPolicyUnits": 1,
"contentPolicyUnits": 1,
"wordPolicyUnits": 1,
"sensitiveInformationPolicyUnits": 1,
"sensitiveInformationPolicyFreeUnits": 0
},
"action": "GUARDRAIL_INTERVENED",
"outputs": [
{
"text": "I apologize, but I am not able to provide fiduciary advice. ="
}
],
"assessments": [
{
"topicPolicy": {
"topics": [
{
"name": "Fiduciary Advice",
"type": "DENY",
"action": "BLOCKED"
}
]
}
}
]
}
```
------
## 作为 ApplyGuardrail 响应，返回完整输出
如果内容违反了护栏配置，则视为检测到了内容。例如，如果一致性或相关性分数小于相应的阈值，则认为已检测到上下文一致性问题。
默认情况下，该[ApplyGuardrail](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html)操作仅在响应中返回检测到的内容。您可以指定值为 `FULL` 的 `outputScope` 字段以返回完整输出。在这种情况下，响应还将包含未检测到的条目以增强调试效果。
您可以通过将跟踪设置为完全启用选项，在 `Invoke` 和 `Converse` 操作中配置相同的行为。
**注意**
完整输出范围不适用于敏感信息筛选条件中的单词筛选条件或正则表达式。它适用于所有其他筛选策略，包括带有可检测个人身份信息（PII）的筛选条件的敏感信息。