Utilisation de l’API ApplyGuardrail dans votre application - Amazon Bedrock
Appel de l’API ApplyGuardrail dans votre flux d’applicationsSpécification de la barrière de protection à utiliser avec l’API ApplyGuardrailExemples de cas d’utilisation de l’API ApplyGuardrailRenvoi de la sortie complète dans la réponse ApplyGuardrail

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation de l’API ApplyGuardrail dans votre application

Les barrières de protection sont utilisées afin d’implémenter des dispositifs de protection pour vos applications d’IA générative, qui sont personnalisés en fonction de vos cas d’utilisation et conformes à vos politiques en matière d’IA responsable. Elles vous permettent de configurer les sujets refusés, de filtrer les contenus préjudiciables et de supprimer les informations sensibles.

Vous pouvez utiliser l’API ApplyGuardrail pour évaluer n’importe quel texte à l’aide de vos barrières de protection Amazon Bedrock préconfigurées, sans avoir à invoquer les modèles de fondation.

Les fonctionnalités de l’API ApplyGuardrail incluent :

  • Validation du contenu : vous pouvez envoyer n’importe quelle entrée ou sortie de texte à l’API ApplyGuardrail pour la comparer aux règles d’évitement des sujets, aux filtres de contenu, aux détecteurs de données d’identification personnelle et aux listes de blocage de mots que vous avez définis. Vous pouvez évaluer indépendamment les entrées utilisateur et les sorties générées par le modèle de fondation.

  • Déploiement flexible : vous pouvez intégrer l’API ApplyGuardrail n’importe où dans votre flux d’applications pour valider les données avant de les traiter ou de communiquer les résultats à l’utilisateur. Par exemple, si vous utilisez une application RAG, vous pouvez désormais évaluer les entrées utilisateur avant d’effectuer la récupération, au lieu d’attendre la génération de la réponse finale.

  • Découplée des modèles de fondation : l’API ApplyGuardrail est découplée des modèles de fondation. Vous pouvez désormais utiliser les barrières de protection sans invoquer les modèles de fondation. Vous pouvez utiliser les résultats d’évaluation pour concevoir l’expérience de votre application d’IA générative.

Appel de l’API ApplyGuardrail dans votre flux d’applications

La demande permet au client de transmettre le contenu qui doit être protégé à l’aide des barrières de protection qu’il a définies. Le champ source doit être défini sur INPUT lorsque le contenu à évaluer provient d’un utilisateur (généralement l’invite d’entrée du LLM). La source doit être définie sur OUTPUT quand les barrières de protection des sorties du modèle doivent être appliqués (généralement la réponse du LLM).

Spécification de la barrière de protection à utiliser avec l’API ApplyGuardrail

Lors de l’utilisation d’ApplyGuardrail, vous spécifiez guardrailIdentifier et guardrailVersion pour la barrière de protection que vous souhaitez utiliser. Vous pouvez également activer le traçage de la barrière de protection, qui fournit des informations sur le contenu bloqué par celle-ci.

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"
            }
        }
    ]
}

Exemples de cas d’utilisation de l’API ApplyGuardrail

Les résultats de la demande ApplyGuardrail dépendent de l’action entreprise par la barrière de protection sur le contenu transmis.

  • Si une barrière de protection est intervenue là où le contenu est uniquement masqué, le contenu exact est renvoyé avec le masquage appliqué.

  • Si le barrière de protection est intervenue et a bloqué le contenu de la demande, le champ de sortie sera un seul texte, qui est le message prédéfini basé sur la configuration de la barrière de protection.

  • Si aucune action de barrière de protection n’a été effectuée sur le contenu de la demande, le tableau des sorties est vide.

Guardrails takes no action

Exemple de demande

{
    "source": "OUTPUT",
    "content": [
        "text": {
            "text": "Hi, my name is Zaid. Which car brand is reliable?"
        }
    ]
}

Exemple de réponse

{
    "usage": {
        "topicPolicyUnitsProcessed": 1,
        "contentPolicyUnitsProcessed": 1,
        "wordPolicyUnitsProcessed": 0,
        "sensitiveInformationPolicyFreeUnits": 0
    },
    "action": "NONE",
    "outputs": [],
    "assessments": [{}]
}
Guardrails blocks content

Exemple de réponse

{
    "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

Exemple de réponse

Les barrières de protection interviennent en masquant le nom 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

Exemple d’entrée

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

Exemple de sortie (contenu des blocs)

{
    "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"
                    }
                ]
            }
        }
    ]
}

Renvoi de la sortie complète dans la réponse ApplyGuardrail

Le contenu est considéré comme détecté s’il enfreint les configurations de votre barrière de protection. Par exemple, un ancrage contextuel est considéré comme détecté si le score d’ancrage ou de pertinence est inférieur au seuil correspondant.

Par défaut, l’opération ApplyGuardrail renvoie uniquement le contenu détecté dans une réponse. Vous pouvez spécifier le champ outputScope avec la valeur FULL pour renvoyer la sortie complète. Dans ce cas, la réponse inclut également des entrées non détectées pour un meilleur débogage.

Vous pouvez configurer ce même comportement dans les opérations Invoke et Converse en réglant la trace sur l’option complète activée.

Note

L’étendue de sortie complète ne s’applique pas aux filtres de mots ni aux expressions régulières dans les filtres d’informations sensibles. Elle s’applique à toutes les autres politiques de filtrage, y compris les informations sensibles avec des filtres capables de détecter les données d’identification personnelle (PII).