Implémentation de la détection de sujets avec Amazon Bedrock Guardrail

La détection de sujet (topic detection) est une capacité fondamentale en traitement du langage naturel (natural language processing) avec des applications étendues dans la gestion de contenu, les systèmes de recommandation et les fonctionnalités de recherche. Amazon Bedrock Guardrail offre une solution puissante pour implémenter la détection de sujet avec une vitesse de traitement impressionnante, ce qui le rend idéal pour les applications nécessitant une analyse de texte efficace à grande échelle.

Ce guide vous accompagnera dans le processus de configuration et d'implémentation de la détection de sujet à l'aide d'Amazon Bedrock Guardrail. Assurez-vous également de consulter notre guide sur l'Implémentation de la Détection de Sujet avec OpenAI.

Le Jeu de Données (Dataset)

Notre implémentation a été testée sur un jeu de données diversifié comprenant 2 926 échantillons de texte répartis dans 14 catégories thématiques distinctes :

• Santé et Médecine (235 échantillons)
• Éducation (216 échantillons)
• Technologie (209 échantillons)
• Politique (207 échantillons)
• Alimentation et Cuisine (207 échantillons)
• Psychologie et Développement Personnel (206 échantillons)
• Environnement et Climat (206 échantillons)
• Divertissement (204 échantillons)
• Affaires et Entrepreneuriat (204 échantillons)
• Voyage et Tourisme (203 échantillons)
• Science et Espace (202 échantillons)
• Sports (201 échantillons)
• Histoire (200 échantillons)
• Finance et Économie (185 échantillons)

Exemples de Textes du Jeu de Données

Le tableau ci-dessous fournit un exemple représentatif de chaque catégorie de sujet :

Configuration d'Amazon Bedrock Guardrail

Vous pouvez configurer Amazon Bedrock Guardrail pour la détection de sujet en utilisant soit l'interface web AWS, soit programmatiquement via le SDK AWS. Nous allons explorer les deux approches.

Approche 1 : Utilisation de l'Interface Web AWS

L'interface web AWS fournit une manière conviviale de créer et configurer des garde-fous (guardrails) sans écrire de code.

Étape 1 : Créer un Nouveau Guardrail

Commencez par naviguer vers la console Amazon Bedrock et sélectionnez "Guardrails" dans le menu. Cliquez sur "Create guardrail" pour démarrer le processus de configuration.

Dans l'écran de configuration initiale, fournissez un nom pour votre guardrail (par ex., "Topic-Detection") et une description facultative. Ce sera la base de votre système de détection de sujet.

Étape 2 : Configurer les Sujets Refusés (Denied Topics)

Après avoir créé le guardrail, naviguez vers la section "Add denied topics". Ici, vous définirez les sujets que vous souhaitez que le système détecte.

Pour chaque sujet que vous souhaitez détecter :

1. Entrez le nom du sujet (par ex., "Sports")
2. Fournissez une définition claire qui aide le système à comprendre quel contenu relève de ce sujet
3. Ajoutez des phrases d'exemple qui représentent ce sujet (par ex., "Les Lakers ont remporté le championnat NBA après un match palpitant.")

Répétez ce processus pour chacun de vos sujets cibles. Dans notre benchmark, nous avons configuré les 14 catégories de sujets comme des "sujets refusés" pour exploiter les capacités de détection de sujet de Bedrock.

Étape 3 : Configurer l'Ancrage Contextuel (Contextual Grounding)

La dernière étape critique consiste à configurer la vérification d'ancrage contextuel, qui détermine avec quelle rigueur le système évalue la pertinence du sujet.

1. Naviguez vers "Add contextual grounding check"
2. Activez la vérification de pertinence (relevance check)
3. Définissez le seuil de score de pertinence (relevance score threshold) - c'est crucial pour équilibrer la précision (accuracy) et le rappel (recall)
   • Dans notre benchmark, nous avons utilisé un seuil de 0,7
   • Des valeurs plus basses (proches de 0) détecteront moins de sujets
   • Des valeurs plus élevées (proches de 0,99) seront plus sévères mais pourraient manquer certains contenus pertinents

Ce paramètre de seuil a un impact direct sur le taux de précision de votre système de détection de sujet. Ajuster cette valeur vous permet de trouver l'équilibre optimal entre précision et rappel pour votre cas d'utilisation spécifique.

Approche 2 : Utilisation du SDK AWS (Création Programmatique)

Pour la création automatisée ou programmatique de guardrails, en particulier lorsque vous traitez plusieurs sujets, vous pouvez utiliser le SDK AWS. Cette approche est particulièrement utile pour :

• Créer des guardrails dans le cadre de pipelines CI/CD
• Maintenir des configurations de guardrail cohérentes entre les environnements
• Gérer efficacement un grand nombre de sujets

Voici comment créer un guardrail programmatiquement en utilisant Python et le SDK AWS :

Étape 1 : Configurer Votre Environnement

Tout d'abord, installez les dépendances requises :

Copied!
1pip install boto3 pandas python-dotenv
2

Créez un fichier .env pour stocker en toute sécurité vos informations d'identification AWS :

Copied!
1AWS_REGION=votre-region-aws
2AWS_ACCESS_KEY=votre-cle-acces
3AWS_SECRET_KEY=votre-cle-secrete
4

Étape 2 : Préparer Vos Données de Sujets

Vous aurez besoin d'un jeu de données avec des étiquettes de sujets et des descriptions. Dans notre exemple, nous utilisons deux fichiers CSV :

• topic_detection.csv : Contient des échantillons de texte avec leurs étiquettes de sujet
• topics_descriptions.csv : Contient les noms des sujets et leurs descriptions

Le fichier de descriptions des sujets doit comporter des colonnes pour "Topic" et "Description", où les descriptions sont limitées à 200 caractères.

Étape 3 : Créer le Guardrail à l'aide du SDK AWS

Voici le code Python pour créer un guardrail programmatiquement, avec des commentaires détaillés expliquant chaque étape :

La première étape consiste à se connecter au service Amazon Bedrock :

Copied!
1import boto3
2import pandas as pd
3from dotenv import load_dotenv
4import os
5
6# Load environment variables from .env file for secure credential management
7load_dotenv()
8
9# Retrieve AWS credentials and region from environment variables
10AWS_REGION = os.getenv("AWS_REGION")
11AWS_SECRET_KEY = os.getenv("AWS_SECRET_KEY")
12AWS_ACCESS_KEY = os.getenv("AWS_ACCESS_KEY")
13
14# Initialize the Bedrock client with your AWS credentials
15# Note: This is different from the bedrock-runtime client used for inference
16client = boto3.client(
17	service_name="bedrock",  # Use the bedrock service for creating guardrails
18	region_name=AWS_REGION,
19	aws_secret_access_key=AWS_SECRET_KEY,
20	aws_access_key_id=AWS_ACCESS_KEY,
21)
22
23

Ensuite, nous chargeons le jeu de données contenant les échantillons de texte et leurs étiquettes de sujet. Ce jeu de données sera utilisé pour extraire les sujets uniques et les textes d'exemple qui seront ensuite utilisés pour définir les sujets à bloquer.

Copied!
1df = pd.read_csv(filepath_or_buffer="./data/topic_detection.csv")
2topics = list(df["label"].unique())  # Extract all unique topic labels
3
4# Load the dataset containing topic descriptions
5# This file should have a "Topic" column and a "Description" column
6df_desc = pd.read_csv(
7	filepath_or_buffer="./data/topics_descriptions.csv", delimiter=";"
8)
9
10# Get the formatted topic names from the descriptions file
11# These should be properly formatted for the guardrail (no spaces, special characters)
12formatted_topics = list(df_desc["Topic"].unique())
13topics_config = list()  # Initialize empty list to store topic configurations
14
15# Create a configuration dictionary for each topic
16# This maps each original topic label to its formatted name and description
17for topic, form_topic in zip(topics, formatted_topics):
18	# Create the configuration dictionary for this topic
19	config = {
20    	"name": form_topic,  # The formatted topic name (e.g., "HealthAndMedicine")
21    	"definition": df_desc[df_desc["Topic"] == form_topic]["Description"].values[0],  # Get the topic description
22    	"examples": [
23        	# Include a sample text for this topic - helps the guardrail understand the topic
24        	df[df["label"] == topic].sample(n=1, random_state=27)["text"].values[0]
25    	],
26    	"type": "DENY",  # Set type to "DENY" for topic detection purposes
27	}
28	topics_config.append(config)  # Add this topic's config to our list
29
30

Après avoir créé la configuration du guardrail, nous allons créer le guardrail en utilisant le code suivant :

Copied!
1# Create the guardrail with all configured topics
2create_response = client.create_guardrail(
3	name="Topic-Detection",  # Name of the guardrail
4	description="Detecting Topics",  # Description of the guardrail's purpose
5    
6	# Configure the topic policy with our list of topic configurations
7	topicPolicyConfig={"topicsConfig": topics_config},
8    
9	# Configure the contextual grounding settings
10	contextualGroundingPolicyConfig={
11    	"filtersConfig": [
12        	# Set the GROUNDING threshold to 0.7 - controls how strictly topics are matched
13        	{"type": "GROUNDING", "threshold": 0.7},
14        	# Set the RELEVANCE threshold to 0.7 - controls how relevant content must be
15        	{"type": "RELEVANCE", "threshold": 0.7},
16    	]
17	},
18    
19	# Messages to display when topics are detected
20	blockedInputMessaging="Topic Detected",  # Message for detected topics in input
21	blockedOutputsMessaging="Topic Detected",  # Message for detected topics in output
22)
23
24

Composants Clés de l'Approche SDK

1. Configuration des Sujets :

• Chaque sujet nécessite un nom, une définition, des exemples et un type ("DENY" pour la détection de sujet).

2. Configuration de l'Ancrage Contextuel :

• Nous définissons les seuils GROUNDING et RELEVANCE à 0,7, ce qui correspond à notre configuration via l'interface web.

3. Messagerie de Blocage :

• Nous définissons des messages simples à afficher lorsque des sujets sont détectés.

Avantages de l'Approche SDK :

• Automatisation : Créer des guardrails dans le cadre de workflows automatisés
• Contrôle de Version : Stocker les configurations de guardrail dans votre dépôt de code
• Configuration en Masse : Configurer efficacement plusieurs sujets à la fois
• Reproductibilité : Recréer facilement le même guardrail dans différents environnements

Après avoir créé le guardrail en utilisant l'une ou l'autre approche, vous recevrez un ID de guardrail dont vous aurez besoin pour la phase d'implémentation.

Implémentation de l'API Bedrock Guardrail

Une fois votre guardrail configuré, vous pouvez l'implémenter dans votre application Python. Voici un guide étape par étape :

Étape 1 : Configurer Votre Environnement

Tout d'abord, installez les dépendances requises :

Copied!
1pip install boto3 pandas tqdm python-dotenv
2

Créez un fichier .env pour stocker en toute sécurité vos informations d'identification AWS et la configuration du guardrail :

Copied!
1GUARDRAIL_ID=votre-id-guardrail
2GUARDRAIL_VERSION=votre-version-guardrail
3AWS_REGION=votre-region-aws
4AWS_ACCESS_KEY_ID=votre-cle-acces
5AWS_SECRET_ACCESS_KEY=votre-cle-secrete
6

Étape 2 : Implémenter la Fonction de Détection de Sujet

Voici le code Python pour implémenter la détection de sujet à l'aide d'Amazon Bedrock Guardrail :

Copied!
1from tqdm import tqdm
2import time
3from typing import Any
4import os
5import boto3
6import pandas as pd
7from dotenv import load_dotenv
8
9# Load environment variables from .env file
10load_dotenv()
11
12# Configuration parameters for AWS Bedrock
13GUARDRAIL_ID = os.getenv("GUARDRAIL_ID")  # The ID of your configured guardrail
14GUARDRAIL_VERSION = os.getenv("GUARDRAIL_VERSION")  # The version of your guardrail
15AWS_REGION = os.getenv("AWS_REGION")  # Your AWS region
16AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")  # Your AWS access key
17AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")  # Your AWS secret key
18
19# Initialize the Bedrock runtime client
20bedrock_runtime = boto3.client("bedrock-runtime", region_name=AWS_REGION)
21
22
23
24
25
26def topic_detection_bedrock(text: str) -> Any:
27	# Format the input text for the guardrail API
28	content = [{"text": {"text": text}}]
29    
30	# Measure execution time
31	start = time.time()
32    
33	# Call the Bedrock Guardrail API
34	response = bedrock_runtime.apply_guardrail(
35    	guardrailIdentifier=GUARDRAIL_ID,
36    	guardrailVersion=GUARDRAIL_VERSION,
37    	source="INPUT",  # Analyze the input text
38    	content=content,
39	)
40    
41	end = time.time()
42	execution_time = end - start
43    
44	# Process the response based on the guardrail's action
45	if response["action"] == "GUARDRAIL_INTERVENED":
46    	# Extract detected topics from the response
47    	topics = list()
48    	for topic in response["assessments"][0]["topicPolicy"]["topics"]:
49        	topics.append(topic["name"])
50        	print(topic["name"], execution_time)
51   	 
52    	# Return either a list of topics or a single topic
53    	if len(topics) > 1:
54        	return topics, execution_time
55    	else:
56        	return topics[0], execution_time
57	else:
58    	# If no topics were detected
59    	print(response["action"], execution_time)
60    	return response["action"], execution_time
61
62

Comprendre la Réponse de l'API

La réponse de l'API Bedrock Guardrail contient des informations précieuses sur les sujets détectés. Voici comment l'interpréter :

Lorsqu'un sujet est détecté, la réponse aura :

• action défini sur "GUARDRAIL_INTERVENED"
• assessments contenant un objet topicPolicy avec les topics détectés

Chaque sujet dans la réponse comprend :

• name : Le nom du sujet détecté
• confidence : Un score de confiance pour la détection

Si aucun sujet n'est détecté, l'action sera différente (généralement "ALLOW").

Étape 3 : Traiter Plusieurs Échantillons de Texte

Pour traiter un jeu de données d'échantillons de texte, vous pouvez utiliser le code suivant :

Copied!
1def main():
2	# Initialize lists to store results
3	topic_detected = list()
4	execution_time = list()
5    
6	# Load the dataset
7	df = pd.read_csv(filepath_or_buffer="data/topic_detection.csv")
8    
9	# Process each text sample with a progress bar
10	for _, row in tqdm(
11    	df.iterrows(), total=len(df), desc="Analyzing topics with bedrock guardrail"
12	):
13    	text = row["text"]
14    	topic, exec_time = topic_detection_bedrock(text=text)
15    	topic_detected.append(topic)
16    	execution_time.append(exec_time)
17    
18	# Add results as new columns to the dataframe
19	df["execution_time"] = execution_time
20	df["topic_detected"] = topic_detected
21    
22	# Save the results to a CSV file
23	df.to_csv(path_or_buf="data/bedrock_topic_detection.csv", index_label=False)
24
25if __name__ == "__main__":
26	main()
27
28

Performance d'Amazon Bedrock Guardrail pour la Détection de Sujet

Maintenant que nous avons couvert l'implémentation, examinons les caractéristiques de performance d'Amazon Bedrock Guardrail pour la détection de sujet sur la base de notre étude de benchmark.

Vitesse et Efficacité

Amazon Bedrock Guardrail démontre une efficacité de traitement impressionnante pour les tâches de détection de sujet :

• Temps de Traitement Moyen : 0,357 secondes par échantillon de texte
• Performance Cohérente : Variance minimale du temps de traitement selon les différentes catégories de sujets

Cette vitesse rend Bedrock Guardrail particulièrement bien adapté aux applications qui doivent traiter de grands volumes de texte en temps réel ou quasi réel.

Précision et Capacités de Détection

Nos tests ont révélé qu'avec la valeur de seuil par défaut de 0,7, Bedrock Guardrail atteint une précision approximative de 58 % avec un taux de faux positifs modéré. Cette configuration traite les échantillons de texte en une moyenne de 0,357 secondes, trouvant un équilibre raisonnable entre précision et vitesse.

Utilisation des Ressources

Bedrock Guardrail est conçu pour être efficace en termes de ressources de calcul :

• Utilisation de la Mémoire : Minimale par rapport à l'exécution de grands modèles de langage localement
• Mise à l'échelle (Scaling) : Gère l'augmentation de la charge avec élégance grâce à l'infrastructure AWS
• Rentabilité (Cost Efficiency) : Modèle de tarification basé sur le paiement à l'utilisation (pay-as-you-go) en fonction des appels API

Observations Clés

Notre benchmark a révélé plusieurs caractéristiques importantes de la détection de sujet par Bedrock Guardrail :

1. Impact de la Définition des Sujets : La qualité et la spécificité des définitions de sujets influencent significativement la précision de la détection

2. Diversité des Exemples : Inclure des exemples variés pour chaque sujet améliore la détection à travers différents styles d'écriture

3. Réglage du Seuil : Trouver la valeur de seuil optimale est crucial pour équilibrer la précision et les faux positifs

4. Cohérence du Traitement : La performance reste stable même avec des échantillons de texte plus longs

Ces observations soulignent l'importance d'une configuration et d'un réglage appropriés lors de l'implémentation de Bedrock Guardrail pour la détection de sujet.

Optimisation de Votre Système de Détection de Sujet

Pour améliorer la précision de votre système de détection de sujet Bedrock Guardrail, envisagez ces stratégies d'optimisation :

1. Affiner les Définitions de Sujets

Fournissez des définitions complètes pour chaque sujet qui le distinguent clairement des autres sujets. Incluez les concepts clés, la terminologie et les caractéristiques qui définissent le sujet.

2. Ajouter des Phrases d'Exemple Variées

Incluez une variété de phrases d'exemple qui représentent différents aspects de chaque sujet. Plus vos exemples sont diversifiés et représentatifs, mieux le système comprendra la portée du sujet.

3. Expérimenter avec les Seuils de Pertinence

Le seuil de pertinence dans la vérification d'ancrage contextuel a un impact significatif sur la précision de la détection. Expérimentez avec différentes valeurs pour trouver l'équilibre optimal :

• Seuil plus bas (par ex., 0,5) : Détecte moins de sujets.
• Seuil plus élevé (par ex., 0,8) : Le Guardrail bloque sévèrement presque tous les prompts.

4. Combiner avec le Pré-traitement (Pre-processing)

Envisagez d'implémenter des étapes de pré-traitement de texte avant d'envoyer le contenu à Bedrock :

• Normalisation du texte (minuscules, suppression des caractères spéciaux)
• Extraction de mots-clés pour mettre en évidence les termes importants
• Reconnaissance d'entités pour identifier les sujets clés

Cas d'Utilisation pour la Détection de Sujet avec Amazon Bedrock Guardrail

La détection de sujet d'Amazon Bedrock Guardrail est particulièrement bien adaptée pour :

1. Traitement de Contenu à Grand Volume : Applications qui doivent traiter rapidement de grands volumes de texte

2. Modération de Contenu en Temps Réel : Systèmes qui filtrent le contenu en fonction du sujet

3. Catégorisation de Contenu : Organisation automatique de documents, articles ou publications

4. Classification des Requêtes Utilisateur : Acheminer les demandes des utilisateurs vers les bases de connaissances ou systèmes de réponse appropriés

5. Systèmes de Recommandation de Contenu : Identifier les sujets de contenu pour correspondre aux intérêts des utilisateurs

Conclusion

Amazon Bedrock Guardrail offre une solution puissante, configurable et efficace pour implémenter la détection de sujet dans vos applications. Avec un temps de traitement moyen de seulement 0,357 secondes par échantillon de texte et la capacité de traiter environ 10 000 échantillons par heure, c'est un excellent choix pour les applications où la vitesse et l'évolutivité (scalability) sont des exigences critiques.

La précision de 58 % atteinte avec la configuration par défaut (seuil de 0,7) fournit une base solide, qui peut être encore améliorée grâce à un réglage minutieux des définitions de sujets, de la diversité des exemples et des paramètres de seuil. La nature configurable de Bedrock Guardrail vous permet d'ajuster l'équilibre entre précision et rappel en fonction des exigences spécifiques de votre cas d'utilisation.

En configurant soigneusement votre guardrail avec des sujets bien définis, des phrases d'exemple représentatives et des seuils de pertinence optimisés, vous pouvez construire un système de détection de sujet qui équilibre précision et performance pour répondre à vos exigences spécifiques. L'intégration transparente avec l'écosystème AWS le rend particulièrement attractif pour les organisations exploitant déjà les services AWS.

Au fur et à mesure que vous implémentez et affinez votre système de détection de sujet, rappelez-vous que la configuration optimale dépendra de votre cas d'utilisation unique, des types de contenu et des priorités de performance. Expérimentez avec différents paramètres pour trouver l'approche qui fonctionne le mieux pour votre application.