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. # Utilisez l' ApplyGuardrail API 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 données saisies par l'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. **Topics** + [Appelez ApplyGuardrail votre flux de candidature](#guardrails-use-independent-api-call) + [Spécifiez le garde-corps à utiliser avec ApplyGuardrail](#guardrails-use-indepedent-api-call-configure) + [Exemples de cas d'utilisation de ApplyGuardrail](#guardrails-use-independent-api-call-message) + [Renvoie la sortie complète en ApplyGuardrail réponse](#guardrails-use-return-full-assessment) ## Appelez ApplyGuardrail votre flux de candidature 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écifiez le garde-corps à utiliser avec 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 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" } ] } } ] } ``` ------ ## Renvoie la sortie complète en ApplyGuardrail réponse 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'[ApplyGuardrail](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html)opération 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).