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. # Cas d’utilisation des barrières de protection Amazon Bedrock Cas d’utilisation des barrières de protection Après avoir créé une barrière de protection, vous pouvez l’appliquer aux fonctionnalités suivantes : + [Inférence de modèle](inference.md) : appliquez une barrière de protection aux invites soumises et aux réponses générées lors de l’exécution de l’inférence sur un modèle. + [Agents](agents.md) : associez une barrière de protection à un agent pour l’appliquer aux invites envoyées à l’agent et aux réponses renvoyées par celui-ci. + [Base de connaissances](knowledge-base.md) : appliquez une barrière de protection lorsque vous interrogez une base de connaissances et que des réponses sont générées à partir de celle-ci. + [Flux](flows.md) : ajoutez une barrière de protection à un nœud d’invite ou à un nœud de base de connaissances dans un flux pour l’appliquer aux entrées et aux sorties de ces nœuds. Le tableau suivant explique comment inclure un garde-corps pour chacune de ces fonctionnalités à l'aide de l'API Amazon Bedrock AWS Management Console ou de l'API Amazon Bedrock. **** | Cas d’utilisation | Console | API | | --- | --- | --- | | Inférence de modèle | Sélectionnez la barrière de protection lorsque vous [utilisez un terrain de jeu](playgrounds.md). | Spécifiez dans l'en-tête d'une [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)demande [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)ou ou incluez dans le guardrailConfig champ du corps d'une [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) ou d'une [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)demande. | | Association à un agent | Lorsque vous [créez ou mettez à jour](agents-build-modify.md) l’agent, spécifiez-la dans la section Détails de la barrière de protection du créateur d’agents. | Incluez un champ guardrailConfiguration dans le corps d’une demande [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html) ou [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html). | | Utilisation lors de l’interrogation d’une base de connaissances | Suivez les étapes décrites dans la section [Barrières de protection](kb-test-config.md#kb-test-config-guardrails) des configurations des requêtes. Ajoutez une barrière de protection lorsque vous définissez Configurations. | Incluez un champ guardrailConfiguration dans le corps d’une demande [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html). | | Inclure dans un nœud d’invite dans un flux | Lorsque vous [créez](flows-create.md) ou [mettez à jour](flows-modify.md) un flux, sélectionnez le nœud d’invite et spécifiez la barrière de protection dans la section Configurer. | Lorsque vous définissez le nœud d'invite dans le nodes champ d'une [UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html)demande [CreateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html)ou, incluez un guardrailConfiguration champ dans le [PromptFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PromptFlowNodeConfiguration.html). | | Inclure dans un nœud de base de connaissances dans un flux | Lorsque vous [créez](flows-create.md) ou [mettez à jour](flows-modify.md) un flux, sélectionnez le nœud de la base de connaissances et spécifiez la barrière de protection dans la section Configurer. | Lorsque vous définissez le nœud de base de connaissances dans le nodes champ d'une [UpdateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateFlow.html)demande [CreateFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateFlow.html)ou, incluez un guardrailConfiguration champ dans le [KnowledgeBaseFlowNodeConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_KnowledgeBaseFlowNodeConfiguration.html). | Cette section traite de l’utilisation d’une barrière de protection avec l’inférence de modèle et l’API Amazon Bedrock. Vous pouvez utiliser les opérations d'inférence de base ([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)et [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)) et l'ConverseAPI ([Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) et [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)). Avec les deux ensembles d’opérations, vous pouvez utiliser une barrière de protection avec l’inférence de modèle synchrone et en streaming. Vous pouvez également évaluer de manière sélective les entrées utilisateur et configurer le comportement de réponse en streaming. **Topics** + [ # Utilisez votre barrière de protection avec des opérations d’inférence pour évaluer les entrées des utilisateurs ](guardrails-input-tagging-base-inference.md) + [ # Utilisez l' ApplyGuardrail API dans votre application ](guardrails-use-independent-api.md) # Utilisez votre barrière de protection avec des opérations d’inférence pour évaluer les entrées des utilisateurs Utilisation avec des opérations d’inférence Vous pouvez utiliser des glissières de sécurité pour les opérations d'inférence de base [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)et [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)(streaming). Cette section explique comment évaluer de manière sélective les entrées utilisateur et comment configurer le comportement de réponse au streaming. Notez que pour les applications conversationnelles, vous pouvez obtenir les mêmes résultats avec l’[API Converse](guardrails-use-converse-api.md). Par exemple, le code qui appelle les opérations d’inférence de base, consultez [Soumettez une seule invite avec InvokeModel](inference-invoke.md). Pour plus d’informations sur l’utilisation d’une barrière de protection avec les opérations d’inférence de base, suivez les étapes décrites dans l’onglet API de [Test de votre barrière de protection](guardrails-test.md). **Topics** + [ # Application de balises aux entrées utilisateur pour filtrer le contenu ](guardrails-tagging.md) + [ # Configuration du comportement des réponses en streaming pour filtrer le contenu ](guardrails-streaming.md) + [ # Intégration d’une barrière de protection à l’API Converse ](guardrails-use-converse-api.md) # Application de balises aux entrées utilisateur pour filtrer le contenu Application de balises aux entrées utilisateur Les balises d’entrée vous permettent de marquer du contenu spécifique dans le texte d’entrée que vous souhaitez traiter avec des barrières de protection. Cela est utile lorsque vous souhaitez appliquer des barrières de protection à certaines parties de l’entrée, tout en laissant d’autres parties non traitées. Par exemple, l’invite d’entrée dans les applications RAG peut contenir des invites système, des résultats de recherche provenant de sources de documentation fiables et des requêtes d’utilisateurs. Comme les invites système sont fournies par le développeur et que les résultats de recherche proviennent de sources fiables, il se peut que vous n’ayez besoin de l’évaluation des barrières de protection que pour les requêtes des utilisateurs. Dans un autre exemple, l’invite d’entrée dans les applications conversationnelles peut contenir des instructions système, l’historique des conversations et les entrées utilisateur actuelles. Les invites système sont des instructions spécifiques aux développeurs, et l’historique des conversations contient l’historique des entrées utilisateur et des réponses du modèle qui ont peut-être déjà été évalués par les barrières de protection. Dans un tel scénario, vous souhaiterez peut-être évaluer uniquement les entrées utilisateur actuelles. En utilisant des balises d’entrée, vous pouvez mieux contrôler quelles parties de l’invite d’entrée doivent être traitées et évaluées par les barrières de protection, en veillant à ce que vos dispositifs de protection soient personnalisés pour vos cas d’utilisation. Cela contribue également à améliorer les performances et à réduire les coûts, car vous avez la possibilité d’évaluer une section relativement courte et pertinente de l’entrée, plutôt que l’intégralité de l’invite d’entrée. **Contenu des balises pour les barrières de protection** Pour baliser le contenu à traiter par les barrières de protection, utilisez la balise XML qui est une combinaison d’un préfixe réservé et d’un `tagSuffix` personnalisé. Par exemple : ``` { "text": """ You are a helpful assistant. Here is some information about my account: - There are 10,543 objects in an S3 bucket. - There are no active EC2 instances. Based on the above, answer the following question: Question: How many objects do I have in my S3 bucket? ... Here are other user queries: How do I download files from my S3 bucket? """, "amazon-bedrock-guardrailConfig": { "tagSuffix": "xyz" } } ``` Dans l’exemple précédent, le contenu *« How many objects do I have in my S3 bucket? »* et *« How do I download files from my S3 bucket? »* est balisé pour un traitement par les barrières de protection à l’aide de la balise ``. Notez que le préfixe `amazon-bedrock-guardrails-guardContent` est réservé par les barrières de protection. **Suffixe de balise** Le suffixe de balise (`xyz` dans l’exemple précédent) est une valeur dynamique que vous devez fournir dans le champ `tagSuffix` dans `amazon-bedrock-guardrailConfig` pour utiliser le balisage d’entrée. Il est recommandé d’utiliser une nouvelle chaîne aléatoire comme `tagSuffix` pour chaque demande. Cela permet d’atténuer les potentielles attaques par injection d’invite en rendant imprévisible la structure des balises. Une balise statique peut entraîner la fermeture de la balise XML par un utilisateur malveillant et l’ajout de contenu malveillant après fermeture de la balise, ce qui entraîne une *attaque par injection*. Vous êtes limité aux caractères alphanumériques d’une longueur comprise entre 1 et 20 caractères inclus. Avec le suffixe d'exemple`xyz`, vous devez inclure tout le contenu à protéger à l'aide des balises XML avec votre suffixe :. `` *your content* `` Nous vous recommandons d’utiliser un identifiant unique dynamique pour chaque demande en tant que suffixe de balise. **Balises multiples** Vous pouvez utiliser la même structure de balises plusieurs fois dans le texte d’entrée pour marquer différentes parties du contenu en vue du traitement par les barrières de protection. L’imbrication de balises n’est pas autorisée. **Contenu non balisé** Le contenu situé en dehors des balises d’entrée n’est pas traité par les barrières de protection. Cela vous permet d’inclure des instructions, des exemples de conversations, des bases de connaissances ou tout autre contenu que vous jugez sûr et que vous ne souhaitez pas traiter avec les barrières de protection. S’il n’existe aucune balise dans l’invite d’entrée, l’invite complète est traitée par les barrières de protection. La seule exception concerne les filtres [Détection des attaques d’invites avec les barrières de protection Amazon Bedrock](guardrails-prompt-attack.md), qui nécessitent la présence de balises d’entrée. # Configuration du comportement des réponses en streaming pour filtrer le contenu Réponses en streaming L'[InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)API renvoie les données dans un format de streaming. Cela vous permet d’accéder aux réponses par fragments sans attendre le résultat complet. Lorsque vous utilisez des barrières de protection avec une réponse en streaming, il existe deux modes de fonctionnement : synchrone et asynchrone. **Mode synchrone** Dans le mode synchrone par défaut, les barrières de protection mettent en mémoire tampon et appliquent les politiques configurées à un ou plusieurs fragments de réponse avant que la réponse ne soit renvoyée à l’utilisateur. Le mode de traitement synchrone introduit une certaine latence dans les fragments de réponse, car cela signifie que la réponse est retardée jusqu’à la fin de l’analyse des barrières de protection. Cependant, il offre une meilleure précision, car chaque fragment de réponse est analysé par les barrières de protection avant d’être envoyé à l’utilisateur. **Mode asynchrone** En mode asynchrone, les barrières de protection envoient les fragments de réponse à l’utilisateur dès qu’ils sont disponibles, tout en appliquant de manière asynchrone les politiques configurées en arrière-plan. L’avantage est que les fragments de réponse sont fournis immédiatement, sans impact sur le temps de latence, mais ils peuvent contenir du contenu inapproprié jusqu’à ce que l’analyse des barrières de protection soit terminée. Dès qu’un contenu inapproprié est identifié, les fragments suivants sont bloqués par les barrières de protection. **Avertissement** Les barrières de protection Amazon Bedrock ne prennent pas en charge le masquage d’informations sensibles en mode asynchrone. **Activation du mode asynchrone** Pour activer le mode asynchrone, vous devez inclure le paramètre `streamProcessingMode` dans l’objet `amazon-bedrock-guardrailConfig` de votre demande `InvokeModelWithResponseStream` : ``` { "amazon-bedrock-guardrailConfig": { "streamProcessingMode": "ASYNCHRONOUS" } } ``` En comprenant les compromis entre les modes synchrone et asynchrone, vous pouvez choisir le mode approprié en fonction des exigences de votre application en matière de latence et de précision de la modération de contenu. # Intégration d’une barrière de protection à l’API Converse Intégration d’une barrière de protection à l’API Converse Vous pouvez utiliser une barrière de protection pour protéger les applications conversationnelles que vous créez avec l’API Converse. Par exemple, si vous créez une application de chat avec l’API Converse, vous pouvez utiliser une barrière de protection pour bloquer le contenu inapproprié saisi par l’utilisateur et celui généré par le modèle. Pour plus d’informations sur l’API Converse, consultez [Mener une conversation avec les opérations d’API Converse](conversation-inference.md). **Topics** + [ ## Appel de l’API Converse avec des barrières de protection ](#guardrails-use-converse-api-call) + [ ## Traitement de la réponse lors de l’utilisation de l’API Converse ](#guardrails-use-converse-api-response) + [ ## Exemple de code pour l’utilisation de l’API Converse avec des barrières de protection ](#converse-api-guardrail-example) ## Appel de l’API Converse avec des barrières de protection Pour utiliser un garde-corps, vous devez inclure les informations de configuration du garde-corps dans les appels aux [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) ou [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(pour les réponses en streaming) dans les opérations. Vous pouvez éventuellement sélectionner un contenu spécifique dans le message que vous souhaitez faire évaluer par la barrière de protection. Pour plus d’informations sur les modèles que vous pouvez utiliser avec les barrières de protection et l’API Converse, consultez [Modèles et fonctionnalités des modèles pris en charge](conversation-inference-supported-models-features.md). **Topics** + [ ### Configuration d’une barrière de protection fonctionnant avec l’API Converse ](#guardrails-use-converse-api-call-configure) + [ ### Évaluation du contenu spécifique d’un message uniquement ](#guardrails-use-converse-api-call-message) + [ ### Protection d’une invite système envoyée à l’API Converse ](#guardrails-use-converse-api-call-message-system-guard) + [ ### Message et comportement de la barrière de protection d’une invite système ](#guardrails-use-converse-api-call-message-system-message-guard) ### Configuration d’une barrière de protection fonctionnant avec l’API Converse Vous spécifiez les informations de configuration de la barrière de protection dans le paramètre d’entrée `guardrailConfig`. La configuration inclut l’ID et la version de 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 qu’elle a bloqué. Avec l'`Converse`opération, `guardrailConfig` c'est un [GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConfiguration.html)objet, comme indiqué dans l'exemple suivant. ``` { "guardrailIdentifier": "Guardrail ID", "guardrailVersion": "Guardrail version", "trace": "enabled" } ``` Si vous utilisez`ConverseStream`, vous transmettez un [GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html)objet. Vous pouvez éventuellement utiliser le champ `streamProcessingMode` pour spécifier que vous souhaitez que le modèle termine l’évaluation par la barrière de protection avant de renvoyer les fragments de réponse en streaming. Vous pouvez également faire en sorte que le modèle réponde de manière asynchrone pendant que la barrière de protection poursuit son évaluation en arrière-plan. Pour de plus amples informations, veuillez consulter [Configuration du comportement des réponses en streaming pour filtrer le contenu](guardrails-streaming.md). ### Évaluation du contenu spécifique d’un message uniquement Lorsque vous transmettez un [message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) à un modèle, votre barrière de protection en évalue le contenu. Vous pouvez également évaluer des parties spécifiques d'un message en utilisant le champ `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)). **Astuce** L'utilisation du `guardContent` champ est similaire à l'utilisation de balises de saisie avec [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)et [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html). Pour de plus amples informations, veuillez consulter [Application de balises aux entrées utilisateur pour filtrer le contenu](guardrails-tagging.md). Par exemple, la barrière de protection suivante évalue uniquement le contenu du champ `guardContent` et non le reste du message. Ceci est utile pour que la barrière de protection évalue uniquement le message le plus récent d’une conversation, comme illustré dans l’exemple suivant. ``` [ { "role": "user", "content": [ { "text": "Create a playlist of 2 pop songs." } ] }, { "role": "assistant", "content": [ { "text": "Sure! Here are two pop songs:\n1. \"Bad Habits\" by Ed Sheeran\n2. \"All Of The Lights\" by Kanye West\n\nWould you like to add any more songs to this playlist?" } ] }, { "role": "user", "content": [ { "guardContent": { "text": { "text": "Create a playlist of 2 heavy metal songs." } } } ] } ] ``` Un autre cas d’utilisation de `guardContent` consiste à fournir un contexte supplémentaire pour un message sans que votre barrière de protection ne l’évalue. Dans l’exemple suivant, la barrière de protection évalue `"Create a playlist of heavy metal songs"` et ignore uniquement `"Only answer with a list of songs"`. ``` messages = [ { "role": "user", "content": [ { "text": "Only answer with a list of songs." }, { "guardContent": { "text": { "text": "Create a playlist of heavy metal songs." } } } ] } ] ``` Si le contenu ne figure pas dans un bloc `guardContent`, cela ne signifie pas nécessairement qu’il ne sera pas évalué. Ce comportement dépend des stratégies de filtrage utilisées par la barrière de protection. L’exemple suivant montre deux blocs `guardContent` avec des [contrôles d’ancrage contextuel](guardrails-contextual-grounding-check.md) (basés sur les champs `qualifiers`). Les contrôles d’ancrage contextuel dans la barrière de protection évaluent uniquement le contenu de ces blocs. Toutefois, si la barrière de protection comporte également un [filtre de mots](guardrails-content-filters.md) qui bloque le mot « background », le texte « Some additional background information. » sera toujours évalué, même s’il ne figure pas dans un bloc `guardContent`. ``` [{ "role": "user", "content": [{ "guardContent": { "text": { "text": "London is the capital of UK. Tokyo is the capital of Japan.", "qualifiers": ["grounding_source"] } } }, { "text": "Some additional background information." }, { "guardContent": { "text": { "text": "What is the capital of Japan?", "qualifiers": ["query"] } } } ] }] ``` ### Protection d’une invite système envoyée à l’API Converse Vous pouvez utiliser des barrières de protection avec les invites système que vous envoyez à l’API Converse. Pour protéger une invite système, spécifiez le champ `guardContent` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) dans l'invite système que vous transmettez à l'API, comme indiqué dans l'exemple suivant. ``` [ { "guardContent": { "text": { "text": "Only respond with Welsh heavy metal songs." } } } ] ``` Si vous ne renseignez pas le champ `guardContent`, la barrière de protection n’évalue pas le message d’invite système. ### Message et comportement de la barrière de protection d’une invite système La façon dont la barrière de protection évalue comment le champ `guardContent` se comporte diffère entre les invites système et les messages que vous transmettez dans le message. | | L’invite système comporte un bloc de barrière de protection | L’invite système ne comporte pas de bloc de barrière de protection | | --- | --- | --- | | **Les messages ont un bloc de barrière de protection** | Système : la barrière de protection examine le contenu du bloc de barrière de protection Messages : la barrière de protection examine le contenu du bloc de barrière de protection | Système : la barrière de protection n’examine rien Messages : la barrière de protection examine le contenu du bloc de barrière de protection | | **Les messages n’ont pas de bloc de barrière de protection** | Système : la barrière de protection examine le contenu du bloc de barrière de protection Messages : la barrière de protection examine tout | Système : la barrière de protection n’examine rien Messages : la barrière de protection examine tout | ## Traitement de la réponse lors de l’utilisation de l’API Converse Lorsque vous appelez l’opération Converse, la barrière de protection évalue le message que vous envoyez. Si la barrière de protection détecte du contenu bloqué, voici ce qui se passe. + Le champ `stopReason` dans la réponse est défini sur `guardrail_intervened`. + Si vous avez activé le suivi, celui-ci est disponible dans le champ `trace` ([ConverseTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseTrace.html)). Avec`ConverseStream`, la trace se trouve dans les métadonnées ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)) renvoyées par l'opération. + Le texte du contenu bloqué que vous avez configuré dans le garde-corps est renvoyé dans le champ `output` ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)). Avec `ConverseStream`, le texte de contenu bloqué se trouve dans le message diffusé. La réponse partielle suivante montre le texte du contenu bloqué et la trace de l’évaluation de la barrière de protection. La barrière de protection a bloqué le terme « *heavy metal* » dans le message. ``` { "output": { "message": { "role": "assistant", "content": [ { "text": "Sorry, I can't answer questions about heavy metal music." } ] } }, "stopReason": "guardrail_intervened", "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 }, "metrics": { "latencyMs": 721 }, "trace": { "guardrail": { "inputAssessment": { "3o06191495ze": { "topicPolicy": { "topics": [ { "name": "Heavy metal", "type": "DENY", "action": "BLOCKED" } ] }, "invocationMetrics": { "guardrailProcessingLatency": 240, "usage": { "topicPolicyUnits": 1, "contentPolicyUnits": 0, "wordPolicyUnits": 0, "sensitiveInformationPolicyUnits": 0, "sensitiveInformationPolicyFreeUnits": 0, "contextualGroundingPolicyUnits": 0 }, "guardrailCoverage": { "textCharacters": { "guarded": 39, "total": 72 } } } } } } } } ``` ## Exemple de code pour l’utilisation de l’API Converse avec des barrières de protection Cet exemple montre comment protéger une conversation à l’aide des opérations `Converse` et `ConverseStream`. L’exemple illustre comment empêcher un modèle de créer une liste de lecture contenant des chansons du genre heavy metal. **Pour protéger une conversation** 1. Créez une barrière de protection en suivant les instructions fournies dans [Création d’une barrière de protection](guardrails-components.md). + **Nom** : entrez *Heavy metal*. + **Définition du sujet** : entrez *Avoid mentioning songs that are from the heavy metal genre of music.* + **Ajout d’exemples d’expressions** : entrez *Create a playlist of heavy metal songs.* À l’étape 9, entrez le texte suivant : + **Message affiché pour les invites bloquées** : entrez *Sorry, I can’t answer questions about heavy metal music.* + **Message affiché pour les réponses bloquées** : entrez *Sorry, the model generated an answer that mentioned heavy metal music.* Vous pouvez configurer d’autres options de barrière de protection, mais cela n’est pas requis dans cet exemple. 1. Créez une version de la barrière de protection en suivant les instructions fournies dans [Création d’une version de barrière de protection](guardrails-versions-create.md). 1. Dans les exemples de code suivants ([Converse](#converse-api-guardrail-example-converse) et [ConverseStream](#converse-api-guardrail-example-converse-stream)), définissez les variables suivantes : + `guardrail_id` : ID de la barrière de protection que vous avez créée à l’étape 1. + `guardrail_version` : version de la barrière de protection que vous avez créée à l’étape 2. + `text` : utilisez `Create a playlist of heavy metal songs.` 1. Exécutez les exemples de code. La sortie doit afficher l’évaluation de la barrière de protection et le message de sortie `Text: Sorry, I can't answer questions about heavy metal music.` L’évaluation des entrées réalisée par la barrière de protection montre que le modèle a détecté le terme *heavy metal* dans le message d’entrée. 1. (Facultatif) Vérifiez que la barrière de protection bloque le texte inapproprié généré par le modèle en remplaçant la valeur de `text` par *List all genres of rock music*. Réexécutez les exemples. Vous devriez voir une évaluation de la sortie dans la réponse. ------ #### [ Converse ] Le code suivant utilise votre barrière de protection lors de l’opération `Converse`. ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to use a guardrail with the Converse API. """ import logging import json import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def generate_conversation(bedrock_client, model_id, messages, guardrail_config): """ Sends a message to a model. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. messages JSON): The message to send to the model. guardrail_config : Configuration for the guardrail. Returns: response (JSON): The conversation that the model generated. """ logger.info("Generating message with model %s", model_id) # Send the message. response = bedrock_client.converse( modelId=model_id, messages=messages, guardrailConfig=guardrail_config ) return response def main(): """ Entrypoint for example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") # The model to use. model_id="meta.llama3-8b-instruct-v1:0" # The ID and version of the guardrail. guardrail_id = "Your guardrail ID" guardrail_version = "DRAFT" # Configuration for the guardrail. guardrail_config = { "guardrailIdentifier": guardrail_id, "guardrailVersion": guardrail_version, "trace": "enabled" } text = "Create a playlist of 2 heavy metal songs." context_text = "Only answer with a list of songs." # The message for the model and the content that you want the guardrail to assess. messages = [ { "role": "user", "content": [ { "text": context_text, }, { "guardContent": { "text": { "text": text } } } ] } ] try: print(json.dumps(messages, indent=4)) bedrock_client = boto3.client(service_name='bedrock-runtime') response = generate_conversation( bedrock_client, model_id, messages, guardrail_config) output_message = response['output']['message'] if response['stopReason'] == "guardrail_intervened": trace = response['trace'] print("Guardrail trace:") print(json.dumps(trace['guardrail'], indent=4)) for content in output_message['content']: print(f"Text: {content['text']}") except ClientError as err: message = err.response['Error']['Message'] logger.error("A client error occurred: %s", message) print(f"A client error occured: {message}") else: print( f"Finished generating text with model {model_id}.") if __name__ == "__main__": main() ``` ------ #### [ ConverseStream ] Le code suivant utilise votre barrière de protection lors de l’opération `ConverseStream`. ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to use a guardrail with the ConverseStream operation. """ import logging import json import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def stream_conversation(bedrock_client, model_id, messages, guardrail_config): """ Sends messages to a model and streams the response. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. messages (JSON) : The messages to send. guardrail_config : Configuration for the guardrail. Returns: Nothing. """ logger.info("Streaming messages with model %s", model_id) response = bedrock_client.converse_stream( modelId=model_id, messages=messages, guardrailConfig=guardrail_config ) stream = response.get('stream') if stream: for event in stream: if 'messageStart' in event: print(f"\nRole: {event['messageStart']['role']}") if 'contentBlockDelta' in event: print(event['contentBlockDelta']['delta']['text'], end="") if 'messageStop' in event: print(f"\nStop reason: {event['messageStop']['stopReason']}") if 'metadata' in event: metadata = event['metadata'] if 'trace' in metadata: print("\nAssessment") print(json.dumps(metadata['trace'], indent=4)) def main(): """ Entrypoint for streaming message API response example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") # The model to use. model_id = "amazon.titan-text-express-v1" # The ID and version of the guardrail. guardrail_id = "Change to your guardrail ID" guardrail_version = "DRAFT" # Configuration for the guardrail. guardrail_config = { "guardrailIdentifier": guardrail_id, "guardrailVersion": guardrail_version, "trace": "enabled", "streamProcessingMode" : "sync" } text = "Create a playlist of heavy metal songs." # The message for the model and the content that you want the guardrail to assess. messages = [ { "role": "user", "content": [ { "text": text, }, { "guardContent": { "text": { "text": text } } } ] } ] try: bedrock_client = boto3.client(service_name='bedrock-runtime') stream_conversation(bedrock_client, model_id, messages, guardrail_config) except ClientError as err: message = err.response['Error']['Message'] logger.error("A client error occurred: %s", message) print("A client error occured: " + format(message)) else: print( f"Finished streaming messages with model {model_id}.") if __name__ == "__main__": main() ``` ------ # Utilisez l' ApplyGuardrail API dans votre application 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 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. **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).