本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在應用程式中使用 ApplyGuardrail API 防護機制用於為您的生成式 AI 應用程式實作保護措施，這些應用程式會針對您的使用案例進行自訂，並與負責的 AI 政策保持一致。防護機制可讓您設定拒絕的主題、篩選有害內容，以及移除敏感資訊。 您可以使用 `ApplyGuardrail` API，使用預先設定的 Amazon Bedrock 防護機制來評估任何文字，而無需調用基礎模型。 `ApplyGuardrail` API 的功能包括： + **內容驗證** – 您可以將任何文字輸入或輸出傳送至 `ApplyGuardrail` API，以與定義的主題迴避規則、內容篩選條件、PII 偵測器和單字區塊清單進行比較。您可以獨立評估使用者輸入和 FM 產生的輸出。 + **彈性部署** – 您可以在應用程式流程中的任意位置整合 `ApplyGuardrail` API，以在處理或提供結果給使用者之前驗證資料。例如，如果您使用的是 RAG 應用程式，您現在可以在執行擷取之前評估使用者輸入，而不是等到產生最終回應。 + **與基礎模型分離** – `ApplyGuardrail` API 與基礎模型分離。您現在可以使用防護機制，而無需叫用基礎模型。您可以使用評估結果來設計生成式 AI 應用程式的體驗。 **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` 操作中設定相同的行為，方法是將追蹤設定為已啟用的完整選項。 **注意** 完整的輸出範圍不適用於敏感資訊篩選條件中的單字篩選條件或 regex。它實則適用於所有其他篩選政策，包括具有可偵測個人身分識別資訊 (PII) 之篩選條件的敏感資訊。