本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
在您的应用程序中使用 ApplyGuardrail API
防护机制用于为您的生成式人工智能应用程序实现保护措施，这些保护措施是针对您的应用场景定制的，并且符合您的负责任的人工智能策略的要求。防护机制让您能够配置拒绝的主题、筛除有害内容和删除敏感信息。
您可以通过预先配置的 Amazon Bedrock 防护机制，使用 ApplyGuardrail API 来评估任何文本，而无需调用基础模型。
ApplyGuardrailAPI 的功能包括：
-
内容验证 — 您可以将任何文本输入或输出发送到 ApplyGuardrail API，以将其与您定义的话题回避规则、内容过滤器、PII 检测器和单词块列表进行比较。您可以分别评估用户输入和 FM 生成的输出。
-
灵活部署-您可以将 ApplyGuardrail API 集成到应用程序流程中的任何位置，以便在处理或向用户提供结果之前验证数据。例如，如果您使用的是 RAG 应用程序，现在可以在执行检索之前评估用户输入，而不是等到最终的响应生成时再进行评估。
-
与@@ 基础模型分离 — ApplyGuardrail API 与基础模型分离。现在，您无需调用基础模型即可使用防护机制。您可以使用评估结果来设计生成式人工智能应用程序中的体验。
调 ApplyGuardrail 用您的申请流程
请求允许客户传递所有应该使用其定义的防护机制进行保护的内容。INPUT当要评估的内容来自用户时，应将源字段设置为（通常是 LLM 的输入提示）。应将源设置为OUTPUT何时应强制执行模型输出护栏（通常是 LLM 响应）。
使用时ApplyGuardrail，请指定要使用的护栏的guardrailIdentifierguardrailVersion
- 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操作仅在响应中返回检测到的内容。您可以指定带有FULL值的outputScope字段以返回完整输出。在这种情况下，响应还将包括未检测到的条目，用于增强调试。
通过将 trace 设置为 “已启用完整” 选项，可以在Invoke和Converse操作中配置同样的行为。
完整的输出范围不适用于敏感信息过滤器中的单词过滤器或正则表达式。它适用于所有其他过滤策略，包括带有可检测个人身份信息 (PII) 的过滤器的敏感信息。
