Règle SanitizeUserPrompt

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Présentation

La règle SanitizeUserPrompt protège les applications d'IA contre les contenus nuisibles en assainissant les requêtes utilisateur envoyées aux modèles d'IA générative. La règle utilise Model Armor pour évaluer les requêtes utilisateur et détecter les contenus nuisibles, ce qui permet de protéger de manière native les charges de travail d'IA à l'aide d'Apigee. Model Armor est un service Google Cloud qui propose des mesures de sécurité et de protection de l'IA pour atténuer les risques associés aux grands modèles de langage (LLM).

Cette règle est utilisée conjointement avec la règle SanitizeModelResponse.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Avant de commencer

Avant d'utiliser la règle SanitizeUserPrompt, vous devez effectuer les tâches suivantes :

• Créez un modèle Model Armor. Vous devez effectuer cette étape avant de créer une règle SanitizeUserPrompt.
• Définissez le point de terminaison de l'API pour le service Model Armor.
• Créez une règle SanitizeModelResponse. Vous devez effectuer cette tâche avant de déployer la règle SanitizeUserPrompt.

Rôles requis

Pour obtenir les autorisations nécessaires pour appliquer et utiliser la règle SanitizeUserPrompt, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le compte de service que vous utilisez pour déployer les proxys Apigee :

• Utilisateur Model Armor (roles/modelarmor.user)
• Lecteur Model Armor (roles/modelarmor.viewer)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer les API

Enable the Model Armor API.

Enable the API

Élément <SanitizeUserPrompt>

Définit une règle SanitizeUserPrompt.

Valeur par défaut	Consultez l'onglet Règles par défaut ci-dessous.
Obligatoire ?	Obligatoire
Type	Objet complexe
Élément parent	ND
Éléments enfants	<DisplayName> <IgnoreUnresolvedVariables> <TemplateName> <UserPromptSource>

L'élément <SanitizeUserPrompt> utilise la syntaxe suivante :

Syntaxe

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

Règle par défaut

L'exemple suivant montre les paramètres par défaut lorsque vous ajoutez une règle SanitizeUserPrompt à votre flux de requête dans l'interface utilisateur d'Apigee :

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

Lorsque vous insérez une nouvelle règle SanitizeUserPrompt à l'aide de l'interface utilisateur d'Apigee, le modèle contient des bouchons pour toutes les opérations possibles. Vous trouverez ci-dessous des informations sur les éléments requis.

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
name	ND	Obligatoire	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError	faux	Facultatif	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi : Les règles d'erreur sont déclenchées UNIQUEMENT en cas d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel
enabled	true	Facultatif	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async	faux	Obsolète	Cet attribut est obsolète.

Le tableau suivant fournit une description détaillée des éléments enfants de <SanitizeUserPrompt> :

Élément enfant	Obligatoire ?	Description
<DisplayName>	Facultatif	Nom de la règle.
<IgnoreUnresolvedVariables>	Facultatif	Spécifie si le traitement s'arrête si la variable utilisée pour le nom du modèle ou la charge utile Model Armor n'est pas résolue.
<ModelArmor>	Obligatoire	Contient les informations requises pour spécifier le modèle Model Armor.
<UserPromptSource>	Facultatif	Emplacement de la charge utile pour le texte de l'invite utilisateur à extraire. Seules les valeurs de texte de chaîne sont acceptées. Ce champ accepte la syntaxe des modèles de messages Apigee, y compris l'utilisation de variables ou de fonctions JSONPath. Exemple : {jsonpath('$.input.prompt.text',request.content,false)}

Exemple

Cette section fournit un exemple utilisant <SanitizeUserPrompt>.

Cet exemple utilise toutes les valeurs par défaut pour la détection de modèles et l'extraction de requêtes :

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
</SanitizeUserPrompt>

Référence d'élément enfant

Cette section décrit les éléments enfants de <SanitizeUserPrompt>.

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut	N/A
Obligatoire ?	Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type	Chaîne
Élément parent	<PolicyElement>
Éléments enfants	Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Exemple

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<IgnoreUnresolvedVariables>

Détermine si le traitement s'arrête lorsqu'une variable n'est pas résolue. Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement.

Valeur par défaut	Faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<SanitizeUserPrompt>
Éléments enfants	Aucun

<ModelArmor>

Contient les informations requises pour spécifier le modèle Model Armor.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Chaîne
Élément parent
Éléments enfants	<TemplateName>

L'élément <ModelArmor> utilise la syntaxe suivante :

Syntaxe

<ModelArmor>
  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
</ModelArmor>

Exemple

Cet exemple utilise des variables de flux Apigee pour renseigner les informations requises.

<ModelArmor>
  <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName>
</ModelArmor>

Le tableau suivant fournit une description détaillée des éléments enfants de <ModelArmor>.

Élément enfant	Obligatoire ?	Description
<TemplateName>	Obligatoire	Chaîne Modèle Model Armor utilisé pour assainir la requête utilisateur. Cette valeur peut être modélisée à l'aide des variables de flux Apigee suivantes : projects/{organization.name}/locations/{system.region.name}/templates/{id}

<UserPromptSource>

Emplacement de la charge utile pour le texte de l'invite utilisateur à extraire. Ce champ est compatible avec la syntaxe des modèles de messages Apigee, y compris l'utilisation de variables ou de fonctions JSONPath. Exemple :

{jsonpath('$.input.prompt.text',request.content,false)}

Valeur par défaut	{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	<SanitizeUserPrompt>
Éléments enfants	Aucun

Variables de flux

Les variables de flux peuvent être utilisées pour configurer le comportement d'exécution dynamique des règles et des flux en fonction des en-têtes HTTP, du contenu des messages ou du contexte disponible dans le flux. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables de flux.

La règle peut définir ces variables en lecture seule lors de l'exécution.

Nom de la variable	Description
SanitizeUserPrompt.POLICY_NAME.templateUsed	Indique le modèle d'armure utilisé. Par exemple : projects/myproject/locations/us-west1/templates/mytemplate
SanitizeUserPrompt.POLICY_NAME.userPrompt	Spécifie le contenu de la requête utilisé pour l'appel à Model Armor afin d'assainir le contenu.
SanitizeUserPrompt.POLICY_NAME.modelResponse	Spécifie le contenu de la réponse du LLM utilisé pour l'appel à Model Armor afin de nettoyer le contenu.
SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor	Spécifie la réponse JSON de Model Armor.
SanitizeUserPrompt.POLICY_NAME.filterMatchState	Indique si le filtre a été mis en correspondance. Les valeurs valides sont MATCH_FOUND et NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.invocationResult	Champ indiquant le résultat de l'invocation, quel que soit l'état de la correspondance. Elle peut se caractériser de la manière suivante : SUCCÈS : tous les filtres ont été exécutés avec succès. PARTIEL : certains filtres ont été ignorés ou n'ont pas pu être exécutés. ÉCHEC : Tous les filtres ont été ignorés ou leur exécution a échoué.
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState	Résultat de l'exécution du filtre d'IA responsable. Les valeurs valides sont EXECUTION_SUCCESS et EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState	État de correspondance du filtre d'IA responsable. Les valeurs valides sont MATCH_FOUND et NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState	État d'exécution des résultats d'inspection du filtre SDP. Les valeurs valides sont EXECUTION_SUCCESS et EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState	État de correspondance du résultat de l'inspection du filtre SDP. Les valeurs valides sont MATCH_FOUND et NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	État d'exécution des résultats d'identification du filtre SDP. Les valeurs valides sont EXECUTION_SUCCESS et EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	État de correspondance des résultats d'identification du filtre SDP. Les valeurs valides sont MATCH_FOUND et NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState	État d'exécution des résultats du filtre d'injection de requêtes et de jailbreaking. Les valeurs valides sont EXECUTION_SUCCESS et EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState	État de correspondance des résultats du filtre d'injection de requêtes et de jailbreaking. Les valeurs valides sont MATCH_FOUND et NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState	État d'exécution du filtre CSAM. Les valeurs valides sont EXECUTION_SUCCESS et EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState	État de correspondance du filtre CSAM. Les valeurs valides sont MATCH_FOUND et NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState	État d'exécution du filtre d'URI malveillant. Les valeurs valides sont EXECUTION_SUCCESS et EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState	État de correspondance du filtre d'URI malveillant. Les valeurs valides sont MATCH_FOUND et NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode	Code d'erreur personnalisé remplacé, le cas échéant, dans la réponse Model Armor.
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage	Code d'erreur personnalisé remplacé, le cas échéant, dans la réponse Model Armor.
SanitizeUserPrompt.POLICY_NAME.csamFilterMatched/code>	Valeur booléenne indiquant si le filtre CSAM a trouvé une correspondance.
SanitizeUserPrompt.POLICY_NAME.maliciousURIs	Liste ajoutée des URI malveillants détectés par le filtre d'URI malveillants.
SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected	Valeur booléenne indiquant si le filtre d'URI malveillant a trouvé une correspondance.
SanitizeUserPrompt.POLICY_NAME.matchesFound	Valeur booléenne indiquant si l'un des filtres correspond.
SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected	Valeur booléenne indiquant si le filtre d'injection d'invite a trouvé une correspondance.
SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence	Niveau de confiance de la détection d'injection de requêtes.
SanitizeUserPrompt.POLICY_NAME.raiMatchesFound	Valeur booléenne indiquant si le filtre d'IA responsable a trouvé une correspondance.
SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor	Valeur booléenne indiquant si une requête a été envoyée à Model Armor.
SanitizeUserPrompt.POLICY_NAME.sanitizeOperation	Spécifie l'opération effectuée par la règle. Les valeurs autorisées sont SANITIZE_USER_PROMPT et SANITIZE_MODEL_RESPONSE.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Apigee spécifiques à la règle SanitizeUserPrompt. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur	État HTTP	Cause
steps.sanitize.user.prompt.response.FilterMatched	400	Cette erreur se produit si la requête utilisateur ne passe pas le contrôle du modèle Model Armor.
steps.sanitize.user.prompt.SanitizationResponseParsingFailed	500	Cette erreur se produit si la réponse Model Armor ne peut pas être analysée.
steps.sanitize.user.prompt.FailedToExtractUserPrompt	500	Cette erreur se produit si l'extraction automatique de l'invite utilisateur pour la valeur par défaut a échoué.
steps.sanitize.user.prompt.InternalError	500	Cette erreur se produit en cas d'erreur interne du serveur.
steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed	500	Cette erreur se produit si le nom du modèle ne peut pas être résolu.
steps.sanitize.modelarmor.AuthenticationFailure	500	Cette erreur se produit si le compte de service n'est pas autorisé à appeler l'API Model Armor.
steps.sanitize.modelarmor.ModelArmorAPIFailed	500	Cette erreur se produit si l'API Model Armor génère une erreur.
steps.sanitize.modelarmor.ModelArmorCalloutError	500	Cette erreur se produit si l'appel d'API Model Armor échoue.
steps.sanitize.modelarmor.ServiceUnavailable	500	Cette erreur se produit si le service Model Armor n'est pas disponible.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur	Cause
The ModelArmor/TemplateName element is required.	Se produit si l'élément <TemplateName> dans <ModelArmor> est absent.
The TemplateName element value is required.	Se produit si la valeur <TemplateName> est vide.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Lieu	Exemple
fault.name="FAULT_NAME"	FAULT_NAME est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name Matches "UnresolvedVariable"
SanitizeUserPrompt.POLICY_NAME.failed	POLICY_NAME est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	SanitizeUserPrompt.sanitize-prompt.failed = true

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

{
  "fault": {
    "faultstring": "SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizeuserprompt.UnresolvedVariable"
    }
  }
}

Exemple de règle de défaillance

<FaultRule name="SanitizeUserPrompt Faults">
    <Step>
        <Name>SUP-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizeuserprompt.failed = true)</Condition>
</FaultRule>

Code et messages d'erreur du modèle Model Armor

Le modèle Model Armor permet de remplacer les codes et messages d'erreur générés par les requêtes d'API de la règle SanitizeUserPrompt. Si l'utilisateur définit les remplacements, les codes et messages d'erreur Model Armor rempliront les variables de flux.

Par exemple, une réponse avec des codes et des messages d'erreur Model Armor peut ressembler à ce qui suit :

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "filterResults": {...},
    "sanitizationMetadata": {
      "errorCode": "890",
      "errorMessage": "get out"
      },
    "invocationResult": "SUCCESS"
  }
}

Schémas

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.