# 政策中的護欄
<a name="policy-guardrails-in-policies"></a>

本節說明如何在政策中定義 Bedrock 護欄。Bedrock Guardrails 提供可設定的保護措施，可在請求和回應上執行，以確保 AI 應用程式的安全。您目前可以在政策中定義提示攻擊、內容篩選條件和敏感資訊防護機制。每個護欄都必須設定一個類別，且閾值必須介於 0 到 1 之間。

當護欄評估內容時，它會傳回介於 0 到 1 之間的可信度分數，指出評估內容呈現已定義屬性的可信度程度 （例如 `PROMPT_INJECTION`)。

## 護欄區域可用性
<a name="guardrails-regional-availability"></a>

下表顯示哪些 AWS 區域支援政策中的護欄：


|  | 美國東部 (維吉尼亞北部) | 美國東部 (俄亥俄) | 美國西部 (奧勒岡) | 歐洲 (法蘭克福) | 歐洲 (愛爾蘭) | 歐洲 (倫敦) | 歐洲 (巴黎) | 歐洲 (斯德哥爾摩) | 亞太地區 (孟買) | 亞太地區 (新加坡) | 亞太地區 (雪梨) | 亞太地區 (東京) | 亞太地區 (首爾) | 加拿大 (中部) | 南美洲 (聖保羅) |  AWS GovCloud （美國西部） | 
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | 
| 護欄支援 | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 

## 開始之前
<a name="policy-guardrails-before-you-begin"></a>

開始之前，您需要正確設定 IAM 角色。

### 許可
<a name="policy-guardrails-permissions"></a>

在與政策引擎相關聯的閘道上設定的 AgentCore Gateway 執行角色，必須具有 Bedrock AgentCore 操作和 Bedrock Guardrails 的許可。需要 `bedrock:InvokeGuardrailChecks`許可，因為政策資料平面會使用衍生自閘道執行角色的 FAS （正向存取工作階段） 登入資料，代表您呼叫 Bedrock Guardrails API。

```
{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeGuardrailChecks",
      "Resource": "*"
    }
  ]
}
```

### 支援的護欄
<a name="supported-guardrails"></a>


| 保護名稱 | 實體類型 | 保護類別 | 
| --- | --- | --- | 
| 內容篩選條件 |  `ContentFilter`  |  `VIOLENCE`, `HATE`, `SEXUAL`, `MISCONDUCT`, `INSULTS`  | 
| 提示攻擊偵測 |  `PromptAttack`  |  `JAILBREAK`, `PROMPT_INJECTION`, `PROMPT_LEAKAGE`  | 
| 敏感資訊 |  `SensitiveInformation`  |  `CREDIT_DEBIT_CARD_NUMBER`、`US_SOCIAL_SECURITY_NUMBER`、`EMAIL`、`PHONE`、`ADDRESS`、`AWS_ACCESS_KEY`、、`AWS_SECRET_KEY`、`PASSWORD``IP_ADDRESS`、`USERNAME`、、 `NAME`和超過 [20](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html) 個  | 

## 在政策中定義護欄
<a name="defining-guardrails-in-policies"></a>

若要在政策中定義護欄，您可以將政策撰寫為程式碼，或以自然語言描述政策。與您可能已建立的任何現有政策類似，您需要使用條件 (`permit`) 指定效果 （例如 `when guardrails`)。在這種情況下，您需要提供您要啟用的特定護欄防護、要使用的防護類別、您希望護欄防護措施評估的內容，以及可信度分數閾值。

 **護欄定義範例** 

```
suppressOutput (principal, action == AgentCore::Action::"<TARGET_NAME>_<METHOD>:<URI>", resource == AgentCore::Gateway::"<GATEWAY_ARN>")
when guardrails {
    BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"]
    .confidenceScore
    .greaterThan(decimal("0.2"))
};
```

### 指定護欄防護
<a name="specifying-a-guardrail-safeguard"></a>

若要選擇特定的保護實體類型，請使用 BedrockGuardrails 命名空間：


| 保護 | 護欄函數名稱 | 
| --- | --- | 
| 內容篩選條件 |  `BedrockGuardrails::ContentFilter`  | 
| 提示攻擊 |  `BedrockGuardrails::PromptAttack`  | 
| 敏感資訊 |  `BedrockGuardrails::SensitiveInformation`  | 

### 選取保護類別
<a name="selecting-a-safeguard-category"></a>

選取指定防護的類別 （請參閱 [支援的護欄](#supported-guardrails))。

例如， `BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])`

### 對護欄的影響
<a name="effects-for-guardrails"></a>

若要建立用於授權請求的護欄，請使用 `permit`和 `forbid`效果。這些會持續控管請求授權。

```
forbid (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource) when guardrails {
  BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.prompt])["PROMPT_INJECTION"].confidenceScore.greaterThan(decimal("0.6"))
};
```

若要建立護欄以用於隱藏工具、代理程式或模型的輸出，請使用 `suppressOutput`效果。 `suppressOutput` 是對動作傳回的資料運作的新效果。授權動作完成後，它會針對護欄評估輸出，並在違反護欄時隱藏輸出。

```
suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource) when guardrails {
  BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text])["US_SOCIAL_SECURITY_NUMBER"]
    .confidenceScore
    .greaterThan(decimal("0.5"))
};
```

### 將內容傳遞至護欄
<a name="passing-context-to-your-guardrail"></a>

在政策中定義護欄時，您必須指定資料路徑 （例如 `context.input.message`)，以識別要從動作承載擷取的值。護欄會評估擷取的值。您可以根據您的請求或回應結構描述指定資料的一或多個路徑。

例如， `[context.input.message, context.input.systemPrompt]`

### 護欄的閾值
<a name="thresholds-for-guardrails"></a>

透過內容篩選條件和提示攻擊偵測，護欄會傳回可信度分數，這是範圍 【0， 1】 中的數值，其中 0 是低可信度，1 是高可信度。分數代表護欄偵測到違規的可信度。目前的可能分數為離散值 {0、0.2、0.4、0.6、0.8 和 1.0}。

若要設定閾值，您需要提供十進位值給比較運算子 （例如 `greaterThan(decimal("0.4"))`)。

 **分數比較運算子** 

您可以將下列比較運算子套用至任何 `confidenceScore`、 `maxConfidenceScore()`或 `minConfidenceScore()`：


| 運算子 | Usage | 
| --- | --- | 
|  `.greaterThan(decimal("X.X"))`  | 分數 > 閾值 | 
|  `.greaterThanOrEqual(decimal("X.X"))`  | 分數 ≥ 閾值 | 
|  `.lessThan(decimal("X.X"))`  | 分數 < 閾值 | 
|  `.lessThanOrEqual(decimal("X.X"))`  | 分數 ≤ 閾值 | 

您可以使用政策中的彙總來擷取和比較護欄傳回的分數：

 **彙總** 


| 聚合 | 說明 | 範例 | 
| --- | --- | --- | 
|  `[<category>].confidenceScore`  | 存取特定類別的可信度分數 ([十進位](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `["HATE"].confidenceScore`  | 
|  `maxConfidenceScore()`  | 所有掃描類別的最大可信度 ([小數](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `.maxConfidenceScore()`  | 
|  `minConfidenceScore()`  | 所有掃描類別的最低可信度 ([小數](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `.minConfidenceScore()`  | 
|  `count()`  | 偵測到的問題清單數量 ([長](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-long)) |  `.count()`  | 

#### 如何選擇閾值
<a name="how-to-choose-a-threshold"></a>

如果您在提示撰寫服務時未指定閾值，AgentCore 會設定預設值。如果您撰寫政策時沒有撰寫服務的協助，您必須提供閾值。

以下預設值經過校正，可為大多數工作負載提供廣泛的涵蓋範圍和可接受的精確度：


| 保護 | 預設閾值 | 
| --- | --- | 
| 內容篩選條件 | 0.2 | 
| 提示攻擊偵測 | 0.4 | 
| 敏感資訊 | 0.2 | 

##### 選擇自訂閾值
<a name="_choosing_a_custom_threshold"></a>

如果預設閾值不符合您的需求，您可以使用下列其中一種方法來判斷工作負載的最佳閾值。

 **選項 1：針對黃金測試集進行評估** 

當您有一組具有明確預期結果的精選測試輸入時，請使用此方法。

1. 建立政策並將政策引擎模式設定為 LOG\_ONLY。

1. 透過政策引擎連接的閘道執行您的測試集。

1. 檢閱每個評估的日誌。每個日誌項目都包含評估的內容，以及護欄傳回的可信度分數。

1. 對於每個結果，標記護欄是否應該標記內容或未執行任何動作 （分別為 true 和 false)。

1. 使用這些標籤，結合日誌中可用的可信度分數，在多個閾值建立混淆矩陣。比較每個閾值的精確度和召回率，以選取符合您容錯能力與漏偵測值的值。

 **選項 2：針對生產流量進行評估** 

如果您沒有預先建置的測試集，並且想要使用實際流量模式進行校正，請使用此方法。

1. 建立政策並將政策引擎模式設定為 LOG\_ONLY。

1. 允許政策引擎評估生產流量。每個日誌項目都包含評估的內容，以及護欄傳回的可信度分數。

1. 使用 LLM-as-a-judge 將每個記錄的結果標記為 true （護欄應標記內容） 或 false （護欄不應標記內容）。

1. 使用這些標籤，在多個閾值建立混淆矩陣。比較每個閾值的精確度和召回率，以選取符合您容錯能力與漏偵測值的值。

### 政策中的測試護欄
<a name="_test_guardrails_in_policy"></a>

AgentCore 提供多個機制來測試護欄政策，然後再對生產流量強制執行它們。您可以在政策引擎層級、個別政策層級或兩者控制強制執行，以逐步驗證護欄行為。如需詳細資訊[，請參閱測試政策](policy-test-a-policy.md)。

## 護欄如何與 政策搭配使用
<a name="how-guardrails-works-with-policy"></a>

護欄政策可以套用至任何閘道目標。護欄執行於：\* **MCP 目標** — `POST /mcp`(JSON-RPC`tools/call`) \* **HTTP 執行期目標** — `POST /<target>/invocations` \* **HTTP 推論目標** — `POST /inference` 

當呼叫到達您的閘道時，政策評估者會執行下列動作：

1.  **符合範圍** — 識別適用於此請求的護欄政策

1.  **擷取內容** — 從請求內文中提取 `dataPath`（例如 `context.input.message`) 指定的欄位

1.  **呼叫 Bedrock InvokeGuardrailChecks API** — 評估內容並將傳回的可信度分數注入政策評估內容

1.  **使用護欄分數評估政策** — 比較傳回的可信度分數與政策中定義的閾值

1.  **傳回決策 **- `DENY` `ALLOW`或使用政策註釋傳回至閘道

注意：護欄是非確定性的。相同的輸入可能會導致不同的輸出。不過，政策是確定性的，相同的輸入一律會產生相同的輸出。

## 政策中護欄的限制
<a name="guardrails-in-policy-limitations"></a>
+  **不支援 regex 或模式比對** — 護欄使用 ML 評分，而不是規則表達式
+  **您無法將標準 Cedar 政策與護欄混合** — `when guardrails {…​}`取代 `when {…​}` 
+  **`when guardrails {…​}` 區塊中需要護欄** — 護欄區塊必須至少在 中定義一個護欄