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. # Intégrez des contrôles de raisonnement automatisés dans votre application Après avoir déployé votre politique de raisonnement automatisé dans un garde-corps (voir[Déploiement de votre politique de raisonnement automatisé dans votre application](deploy-automated-reasoning-policy.md)), vous pouvez l'utiliser lors de l'exécution pour valider les réponses LLM et agir en fonction des commentaires. Cette page explique comment appeler l'API de validation, interpréter les résultats par programmation et implémenter des modèles d'intégration courants tels que la réécriture de réponses non valides et la pose de questions de clarification. Les contrôles de raisonnement automatisés fonctionnent uniquement en *mode détection* : ils renvoient des résultats et des commentaires au lieu de bloquer le contenu. Votre application est chargée de décider quoi faire avec les résultats : envoyer la réponse, la réécrire, demander des éclaircissements ou revenir au comportement par défaut. ## Présentation de l’intégration Au moment de l'exécution, l'intégration suit le flux suivant : ``` User question ──► LLM generates response ──► ApplyGuardrail validates response │ ┌─────────┴─────────┐ │ │ VALID Not VALID │ │ ▼ ▼ Serve response Inspect findings to user │ ┌────────┴────────┐ │ │ OTHER FINDING TRANSLATION_ TYPES AMBIGUOUS / SATISFIABLE │ │ ▼ ▼ Rewrite using Ask user for AR feedback clarification │ │ ▼ ▼ Validate again Validate with clarified input ``` Les résultats du raisonnement automatisé sont renvoyés via n'importe quelle API compatible avec une configuration Amazon Bedrock Guardrails : + `ApplyGuardrail`— API de validation autonome. Utilisez-le lorsque vous souhaitez valider le contenu indépendamment de l'invocation du LLM. Il s'agit de l'approche recommandée pour les contrôles de raisonnement automatisés, car elle vous permet de contrôler totalement le contenu qui est validé et à quel moment. + `Converse`et `InvokeModel` — Invocation du LLM APIs avec configuration de garde-corps. Les résultats du raisonnement automatique sont renvoyés dans le `trace` champ de la réponse. + `InvokeAgent`et `RetrieveAndGenerate` — Agent et base de connaissances APIs avec configuration de garde-corps. Cette page se concentre sur l'`ApplyGuardrail`API car elle offre la plus grande flexibilité pour implémenter les modèles de réécriture et de clarification décrits ci-dessous. Pour plus d'informations sur l'utilisation de garde-corps avec l'autre APIs, voir [Utiliser un](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use.html) garde-corps. ## Exemple de chatbot de réécriture open source Pour une implémentation complète, dans le style de production, des modèles décrits sur cette page, consultez le chatbot de [réécriture sur le raisonnement automatisé](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot). GitHub Cet exemple d'application illustre : + Boucle de réécriture itérative dans laquelle les réponses non valides sont automatiquement corrigées en fonction des commentaires de la réalité augmentée. + Questions de suivi lorsque le LLM a besoin d'un contexte supplémentaire de la part de l'utilisateur pour être réécrit avec précision. + Un mécanisme de temporisation qui reprend automatiquement le traitement lorsque les utilisateurs ne répondent pas aux questions de clarification. + Injection du contexte politique dans les invites du LLM afin que le LLM puisse référencer l'ensemble des règles de politique lors de la réécriture. + Enregistrement d'audit JSON de chaque itération de validation à des fins de conformité et de débogage. L'exemple utilise un Python/Flask backend avec une interface React et communique avec Amazon Bedrock pour l'inférence LLM et Amazon Bedrock Guardrails pour la validation via l'API. `ApplyGuardrail` **Note** L'exemple d'application inclut le contenu de la politique directement dans les invites de génération de LLM pour prendre en charge toute politique de raisonnement automatisé sans nécessiter le téléchargement de documents. Dans un déploiement de production, vous utiliserez généralement du contenu RAG ou alimenterez le LLM avec le document original en langage naturel au lieu du code source de la politique de raisonnement automatisé. ## Appel ApplyGuardrail avec contrôles de raisonnement automatisés Utilisez l'`ApplyGuardrail`API pour valider le contenu par rapport à votre garde-fou. L'API accepte un ou plusieurs blocs de contenu et renvoie une évaluation qui inclut les résultats du raisonnement automatisé. ### Structure de la demande `guardrailIdentifier` (obligatoire) L'ID ou ARN du garde-corps. Utilisez le garde-corps auquel est attachée votre politique de raisonnement automatisé. `guardrailVersion` (obligatoire) Le numéro de version du garde-corps (par exemple,`1`). N'utilisez pas `DRAFT` une version numérotée pour les charges de travail de production. `source` (obligatoire) Défini sur `OUTPUT` lors de la validation des réponses LLM. Défini sur `INPUT` lors de la validation des instructions de l'utilisateur. Pour les contrôles de raisonnement automatisés, vous validez généralement la sortie LLM. `content` (obligatoire) Un tableau de blocs de contenu à valider. Chaque bloc contient un `text` champ avec le contenu à vérifier. Vous pouvez transmettre la question de l'utilisateur et la réponse LLM sous forme de blocs de contenu distincts ou les combiner en un seul bloc. ### Exemple : valider une réponse LLM à l'aide du AWS CLI ``` aws bedrock-runtime apply-guardrail \ --guardrail-identifier "your-guardrail-id" \ --guardrail-version "1" \ --source OUTPUT \ --content '[ { "text": { "text": "User: Am I eligible for parental leave if I have been working here for 2 years full-time?\nAssistant: Yes, you are eligible for parental leave." } } ]' ``` ### Exemple : valider une réponse LLM à l'aide de Python (boto3) ``` import boto3 import json bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-east-1") response = bedrock_runtime.apply_guardrail( guardrailIdentifier="your-guardrail-id", guardrailVersion="1", source="OUTPUT", content=[ { "text": { "text": ( "User: Am I eligible for parental leave if I have been " "working here for 2 years full-time?\n" "Assistant: Yes, you are eligible for parental leave." ) } } ], ) # The AR findings are in the assessments for assessment in response.get("assessments", []): ar_assessment = assessment.get("automatedReasoningPolicy", {}) findings = ar_assessment.get("findings", []) for finding in findings: # Each finding is a union — exactly one key is present # Possible keys: valid, invalid, satisfiable, impossible, # translationAmbiguous, tooComplex, noTranslations print(json.dumps(finding, indent=2, default=str)) ``` ### Structure de réponse La `ApplyGuardrail` réponse inclut un `assessments` tableau. Chaque évaluation contient un `automatedReasoningPolicy` objet associé à un `findings` tableau. Chaque résultat est un type d'union ; exactement l'une des clés suivantes est présente : + `valid` + `invalid` + `satisfiable` + `impossible` + `translationAmbiguous` + `tooComplex` + `noTranslations` Pour une description détaillée de chaque type de recherche et de ses champs, voir[Constatations et résultats de validation](automated-reasoning-checks-concepts.md#ar-concept-findings). ## Interpréter les résultats de la réalité augmentée lors de Pour agir sur les résultats du raisonnement automatisé de manière programmatique, votre application doit extraire le type de recherche, les détails de la traduction et les règles sous-jacentes ou contradictoires. Les sections suivantes expliquent comment analyser chaque partie d'un résultat. ### Déterminer le type de recherche Chaque résultat est une union : une seule clé est présente. Vérifiez quelle clé existe pour déterminer le type de recherche : ``` def get_finding_type(finding): """Return the finding type and its data from an AR finding union.""" for finding_type in [ "valid", "invalid", "satisfiable", "impossible", "translationAmbiguous", "tooComplex", "noTranslations" ]: if finding_type in finding: return finding_type, finding[finding_type] return None, None ``` ### Lire la traduction La plupart des types de recherche incluent un `translation` objet qui montre comment les contrôles de raisonnement automatisés ont traduit l'entrée en langage naturel en logique formelle. La traduction contient : + `premises`— Les conditions extraites de l'entrée (par exemple,`isFullTime = true`,`tenureMonths = 24`). + `claims`— Les assertions à valider (par exemple,`eligibleForParentalLeave = true`). + `untranslatedPremises`— Parties de l'entrée qui n'ont pas pu être mappées aux variables de politique. Ces pièces ne sont pas validées. + `untranslatedClaims`— Réclamations qui n'ont pas pu être mappées aux variables de politique. Vérifiez `untranslatedPremises` et `untranslatedClaims` comprenez l'étendue de la validation. Un `VALID` résultat ne couvre que les demandes traduites ; le contenu non traduit n'est pas vérifié. ### Lisez les règles complémentaires ou contradictoires Selon le type de recherche, la recherche inclut des règles expliquant le résultat : + `valid`les résultats incluent `supportingRules` : les règles de politique qui prouvent que les affirmations sont correctes. + `invalid`les résultats incluent `contradictingRules` : les règles de politique violées par les réclamations. + `satisfiable`les résultats incluent à la fois a `claimsTrueScenario` et a`claimsFalseScenario`, indiquant les conditions dans lesquelles les affirmations sont vraies et fausses. Ces règles et scénarios sont les entrées clés du modèle de réécriture décrit dans[Réécrivez les réponses non valides à l'aide des commentaires AR](#rewrite-invalid-responses). ### Déterminer le résultat global Une seule demande de validation peut renvoyer plusieurs résultats. Pour déterminer le résultat global, triez les résultats par gravité et sélectionnez le pire. L'ordre de gravité du pire au meilleur est :`TRANSLATION_AMBIGUOUS`,`IMPOSSIBLE`,`INVALID`,`SATISFIABLE`,`VALID`. ``` SEVERITY_ORDER = { "tooComplex": 0, "translationAmbiguous": 0, "impossible": 1, "invalid": 2, "satisfiable": 3, "valid": 4, "noTranslations": 5, } def get_aggregate_result(findings): """Return the worst finding type from a list of findings.""" worst = None worst_severity = float("inf") for finding in findings: finding_type, _ = get_finding_type(finding) severity = SEVERITY_ORDER.get(finding_type, 0) if severity < worst_severity: worst_severity = severity worst = finding_type return worst ``` ## Gérez les résultats de validation dans votre application Utilisez le résultat agrégé pour décider de la prochaine action de votre application. Le tableau suivant récapitule les actions recommandées pour chaque type de résultat. | Résultat | Ce que cela signifie | Action recommandée | | --- | --- | --- | | valid | Il est mathématiquement prouvé que la réponse est correcte compte tenu des prémisses et de vos règles de politique. | Envoyez la réponse à l'utilisateur. Enregistrez les résultats à des fins d'audit (voir[Créez une piste d'audit](#build-audit-trail)). | | invalid | La réponse contredit les règles de votre politique. Le contradictingRules champ identifie les règles qui ont été violées. | Réécrivez la réponse en utilisant le feedback AR (voir[Réécrivez les réponses non valides à l'aide des commentaires AR](#rewrite-invalid-responses)). Si la réécriture échoue après plusieurs tentatives, bloquez la réponse et renvoyez un message de secours. | | satisfiable | La réponse est correcte dans certaines conditions, mais pas dans toutes. Ce n'est pas faux, mais il est incomplet : il ne mentionne pas toutes les exigences. | Réécrivez la réponse pour inclure les conditions manquantes. Utilisez le claimsFalseScenario pour identifier ce qui manque. Vous pouvez également laisser votre LLM poser des questions de clarification à l'utilisateur. | | impossible | Les prémisses sont contradictoires ou la politique contient des règles contradictoires. | Demandez à l'utilisateur de clarifier sa saisie (voir[Posez des questions de clarification](#ask-clarifying-questions)). Si le problème persiste, cela peut indiquer un problème de politique. Consultez le rapport de qualité. | | translationAmbiguous | L'entrée comporte plusieurs interprétations valides. Les modèles de traduction n'étaient pas d'accord sur la manière de mapper le langage naturel aux variables politiques. | Demandez des éclaircissements à l'utilisateur pour lever l'ambiguïté. Utilisez les differenceScenarios champs options et pour générer des questions de clarification ciblées. | | tooComplex | L'entrée dépasse les limites de traitement pour l'analyse logique. | Simplifiez la saisie en la divisant en parties plus petites ou renvoyez un message de secours expliquant que la réponse n'a pas pu être vérifiée. | | noTranslations | L'entrée n'est pas pertinente pour le domaine de votre politique. Aucune variable de politique n'a pu être mappée. | Le contenu est hors sujet pour cette politique. Diffusez la réponse sans validation AR ou utilisez d'autres composants de protection (tels que des politiques thématiques) pour gérer le contenu hors sujet. | ## Réécrivez les réponses non valides à l'aide des commentaires AR Le modèle d'intégration le plus puissant pour les contrôles de raisonnement automatisés est la *boucle de réécriture* : lorsqu'une réponse est `invalid` ou`satisfiable`, votre application crée une invite qui inclut la réponse d'origine, les résultats spécifiques et les règles de politique, puis demande au LLM de réécrire la réponse pour qu'elle soit cohérente avec la politique. La réponse réécrite est à nouveau validée et la boucle continue jusqu'à ce que la réponse soit atteinte `valid` ou qu'un nombre maximal d'itérations soit atteint. ### Réécriture du flux de boucle ``` LLM generates initial response │ ▼ Validate with ApplyGuardrail ◄──────────────────┐ │ │ ▼ │ ┌─────┴─────┐ │ │ │ │ VALID Not VALID │ │ │ │ ▼ ▼ │ Done Construct rewriting prompt │ with findings + rules │ │ │ ▼ │ LLM rewrites response │ │ │ ▼ │ Max iterations? ──── No ────────────────┘ │ Yes │ ▼ Return best response with warning ``` ### Construire l'invite de réécriture L'invite de réécriture doit inclure trois informations issues des résultats de l'AR : 1. La réponse d'origine dont la validation a échoué. 1. La constatation spécifique, y compris les prémisses traduites, les allégations et les règles contradictoires ou justificatives. 1. Une instruction pour réécrire la réponse afin qu'elle soit conforme aux règles de politique. **Exemple de modèle d'invite de réécriture :** ``` The following response was checked against our policy and found to be {finding_type}. Original response: {original_response} The validation found the following issue: - Premises (what was understood from the input): {premises} - Claims (what was asserted): {claims} - Contradicting rules: {contradicting_rules} Please rewrite the response so that it is consistent with the policy document. Keep the same helpful tone and answer the user's question accurately based on the rules. If you cannot provide an accurate answer without more information, explain what additional information is needed. ``` **Astuce** Incluez toujours le contenu RAG (Retrieval Augmented Generation) dans vos demandes de réécriture ou dans les règles de politique afin que le LLM dispose de tout le contexte dont il a besoin lors de la réécriture. Le modèle d'invite de réécriture fournit les détails de recherche spécifiques, tandis que l'invite du système fournit le contexte politique plus large. Cette approche à double contexte est illustrée dans l'exemple de chatbot de [réécriture open source](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/responsible_ai/automated-reasoning-rewriting-chatbot). ### Meilleures pratiques en matière de réécriture + **Définissez un nombre maximal d'itérations.** La boucle de réécriture doit avoir une limite stricte (généralement 2 à 5 itérations) pour éviter les boucles infinies. Si la réponse n'est toujours pas atteinte `valid` après le nombre maximal d'itérations, renvoyez la meilleure réponse avec un avertissement ou revenez à un message par défaut. + **Traitez les résultats par ordre de priorité.** Lorsque plusieurs résultats sont renvoyés, traitez d'abord le résultat le plus grave. L'ordre de sévérité est le `translationAmbiguous` suivant :`impossible`,`invalid`,`satisfiable`,,`valid`. + **Incluez le contexte de la politique dans l'invite du système.** Le LLM doit accéder au document source ou à l'intégralité des règles de politique pour pouvoir réécrire avec précision. Vous pouvez utiliser une [base de connaissances](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) pour inclure vos documents dans la demande de génération ou utiliser l'`ExportAutomatedReasoningPolicyVersion`API pour récupérer la définition de la politique et la mettre en forme pour le LLM. + **Enregistrez chaque itération.** Enregistrez la réponse initiale, les résultats, l'invite de réécriture et la réponse réécrite pour chaque itération. Cette piste d'audit est précieuse pour le débogage et la conformité (voir[Créez une piste d'audit](#build-audit-trail)). ## Posez des questions de clarification Lorsque le raisonnement automatisé vérifie le retour ou les `impossible` résultats `translationAmbiguous``satisfiable`, le LLM peut ne pas disposer de suffisamment d'informations pour réécrire la réponse avec précision. Dans ces cas, votre application peut demander des éclaircissements à l'utilisateur, puis intégrer les réponses lors de la prochaine tentative de validation. ### Quand demander des éclaircissements + **`translationAmbiguous`**— L'entrée comporte plusieurs interprétations valides. Le `options` terrain montre les interprétations concurrentes, et le `differenceScenarios` champ montre en quoi elles diffèrent dans la pratique. Utilisez-les pour générer des questions ciblées sur l'ambiguïté spécifique. + **`satisfiable`**— La réponse est correcte dans certaines conditions, mais pas dans toutes. `claimsFalseScenario`Indique les conditions dans lesquelles la réponse serait incorrecte. Demandez à l'utilisateur quelles sont ces conditions spécifiques. + **`impossible`**— L'entrée contient des déclarations contradictoires. Demandez à l'utilisateur de clarifier la contradiction. + Échec de la **réécriture — Si le LLM ne parvient** pas à réécrire la réponse `valid` après plusieurs tentatives, il peut avoir besoin d'un contexte supplémentaire de la part de l'utilisateur. Demandez au LLM de générer des questions de clarification en fonction des résultats. ### Schéma de clarification Le flux de clarification fonctionne comme suit : 1. Extrayez les variables ambiguës ou les conditions manquantes des résultats de l'AR. 1. Générez des questions de clarification, soit par programmation à partir des champs de recherche, soit en demandant au LLM de formuler des questions en fonction des résultats. 1. Présentez les questions à l'utilisateur et collectez des réponses. 1. Incorporez les réponses au contexte et générez une nouvelle réponse. 1. Validez la nouvelle réponse avec`ApplyGuardrail`. **Exemple : générer des questions de clarification à partir d'une constatation `satisfiable`** ``` def generate_clarifying_questions(finding_data, user_question): """Ask the LLM to generate clarifying questions from a SATISFIABLE finding.""" claims_true = json.dumps( finding_data.get("claimsTrueScenario", {}), indent=2, default=str ) claims_false = json.dumps( finding_data.get("claimsFalseScenario", {}), indent=2, default=str ) prompt = ( f"A user asked: {user_question}\n\n" f"The answer is correct when these conditions hold:\n{claims_true}\n\n" f"But incorrect when these conditions hold:\n{claims_false}\n\n" f"Generate 1-3 short, specific questions to ask the user to determine " f"which conditions apply to their situation. Format each question on " f"its own line." ) return generate_response(prompt, "You are a helpful assistant.") ``` ## Créez une piste d'audit Les résultats du raisonnement automatisé fournissent une preuve de validité mathématiquement vérifiable. Pour les secteurs réglementés et les scénarios de conformité, cette preuve est un facteur de différenciation clé : vous pouvez démontrer qu'une réponse de l'IA a été vérifiée par rapport à des règles politiques spécifiques avec des affectations de variables spécifiques, et pas simplement selon des modèles ou évaluée de manière probabiliste. Pour créer une piste d'audit efficace, enregistrez les informations suivantes pour chaque demande de validation : + **Horodatage et numéro de demande.** Date à laquelle la validation a eu lieu et identifiant unique de la demande. + **Contenu d'entrée.** La question de l'utilisateur et la réponse LLM qui ont été validées. + **Type de recherche et détails.** Le résultat de la validation (`valid`,`invalid`, etc.), les prémisses et revendications traduites, ainsi que les règles justificatives ou contradictoires. + **Mesures prises.** Ce que votre application a fait avec le résultat : elle a envoyé la réponse, l'a réécrite, a demandé des éclaircissements ou l'a bloquée. + **Réécrire l'histoire.** Si la réponse a été réécrite, enregistrez chaque itération : la réponse d'origine, l'invite de réécriture, la réponse réécrite et le résultat de validation pour chaque itération. + **Version de la politique.** La version du garde-corps et la version de la politique utilisées pour la validation. Cela vous permet de reproduire le résultat de la validation ultérieurement. **Exemple : structure d'entrée du journal d'audit** ``` { "timestamp": "2025-07-21T14:30:00Z", "request_id": "req-abc123", "guardrail_id": "your-guardrail-id", "guardrail_version": "1", "user_question": "Am I eligible for parental leave?", "llm_response": "Yes, you are eligible for parental leave.", "validation_result": "valid", "findings": [ { "type": "valid", "premises": "isFullTime = true, tenureMonths = 24", "claims": "eligibleForParentalLeave = true", "supporting_rules": ["A1B2C3D4E5F6"] } ], "action_taken": "served_response", "rewrite_iterations": 0 } ``` **Astuce** Stockez les journaux d'audit dans un magasin durable et inviolable tel qu'Amazon CloudWatch Logs ou Amazon S3 avec le verrouillage des objets activé. Pour les scénarios de conformité, pensez à utiliser Lake pour interroger les journaux d'audit de votre organisation.