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.
# Guide d'intégration
L'ensemble de la solution est conçu pour être facilement extensible. La couche d'orchestration de cette solution est construite à l'aide [LangChain](https://www.langchain.com/)de. Vous pouvez ajouter à cette solution n'importe quel fournisseur de modèles, base de connaissances ou type de mémoire de conversation pris en charge par LangChain (ou par un tiers fournissant des LangChain connecteurs pour ces composants).
## Extension prise en charge LLMs
Pour ajouter un autre fournisseur de modèles, tel qu'un fournisseur LLM personnalisé, vous devez mettre à jour les trois composants suivants de la solution :
1. Créez une nouvelle pile `TextUseCase` CDK, qui déploie l'application de chat configurée avec votre fournisseur LLM personnalisé :
1. Clonez le [GitHub référentiel](https://github.com/aws-solutions/generative-ai-application-builder-on-aws) de cette solution et configurez votre environnement de génération en suivant les instructions fournies dans le [fichier README.md.](https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/README.md)
1. Copiez (ou créez-en un nouveau), collez-le dans le même répertoire et renommez-le en`custom-chat-stack.ts`. `source/infrastructure/lib/bedrock-chat-stack.ts`
1. Renommez la classe du fichier en une classe appropriée, telle que`CustomLLMChat`.
1. Vous pouvez choisir d'ajouter un secret Secrets Manager à cette pile, qui stocke vos informations d'identification pour votre LLM personnalisé. Vous pouvez récupérer ces informations d'identification lors de l'invocation du modèle dans la couche Lambda du chat décrite dans le paragraphe suivant.
1. Créez et attachez une couche Lambda contenant la bibliothèque Python du fournisseur de modèles à ajouter. Pour une application de chat utilisant Amazon Bedrock, la bibliothèque `langchain-aws` Python contient les connecteurs personnalisés situés au-dessus LangChain du package pour se connecter aux fournisseurs de modèles AWS (Amazon Bedrock et SageMaker AI), aux bases de connaissances (Amazon Kendra et Amazon Bedrock Knowledge Bases) et aux types de mémoire (tels que DynamoDB). De même, les autres fournisseurs de modèles disposent de leurs propres connecteurs. Cette couche vous permet d'associer la bibliothèque Python de ce fournisseur de modèles afin que vous puissiez utiliser ces connecteurs dans la couche Lambda du chat, qui invoque le LLM (étape 3). Dans cette solution, un bundler d'actifs personnalisé est utilisé pour créer des couches Lambda, qui sont attachées à l'aide des aspects CDK. Pour créer une nouvelle couche pour la bibliothèque de fournisseurs de modèles personnalisés, procédez comme suit :
1. Accédez à la `LambdaAspects` classe dans le `source/infrastructure/lib/utils/lambda-aspects.ts` fichier.
1. Suivez les instructions pour étendre les fonctionnalités de la classe d'aspects Lambda fournie dans le fichier (par exemple en ajoutant la `getOrCreateLangchainLayer` méthode). Pour utiliser cette nouvelle méthode (par exemple,`getOrCreateCustomLLMLayer`), mettez également à jour l'`LLM_LIBRARY_LAYER_TYPES`énumération dans le `source/infrastructure/lib/utils/constants.ts` fichier.
1. Étendez la fonction `chat` Lambda pour implémenter un générateur, un client et un gestionnaire pour le nouveau fournisseur.
`source/lambda/chat`Il contient les LangChain connexions pour les différentes classes LLMs ainsi que les classes de support pour les créer LLMs. Ces classes de support suivent les modèles de conception orientés Builder et Object pour créer le LLM.
Chaque gestionnaire (par exemple`bedrock_handler.py`) crée d'abord un *client*, vérifie les variables d'environnement requises dans l'environnement, puis appelle une `get_model` méthode pour obtenir la classe LangChain LLM. La méthode generate est ensuite appelée pour invoquer le LLM et obtenir sa réponse. LangChain prend actuellement en charge la fonctionnalité de streaming pour Amazon Bedrock, mais pas l' SageMaker IA. Sur la base d'une fonctionnalité de streaming ou non, le WebSocket gestionnaire approprié (`WebsocketStreamingCallbackHandler`ou`WebsocketHandler`) est appelé pour renvoyer la réponse à la WebSocket connexion à l'aide de la `post_to_connection` méthode.
Le `clients/builder` dossier contient les classes qui aident à créer un générateur LLM à l'aide du modèle Builder. Tout d'abord, a `use_case_config` est extrait d'un magasin de configurations DynamoDB, qui contient les informations relatives au type de base de connaissances, de mémoire de conversation et de modèle à construire. Il contient également les détails pertinents du modèle, tels que les paramètres du modèle et les instructions. Le générateur aide ensuite à suivre les étapes de création d'une base de connaissances, de création d'une mémoire de conversation pour maintenir le contexte de conversation pour le LLM, de définition des LangChain rappels appropriés pour les cas de streaming et de non-streaming, et de création d'un modèle LLM basé sur les configurations de modèle fournies. La configuration DynamoDB est stockée au moment de la création des cas d'utilisation lorsque vous déployez un cas d'utilisation à partir du tableau de bord de déploiement (ou lorsqu'il est fourni par les utilisateurs dans le cadre de déploiements de pile de cas d'utilisation autonomes sans le tableau de bord de déploiement).
Le `clients/factories` sous-dossier permet de définir la mémoire de conversation et la classe de base de connaissances appropriées, en fonction de la configuration LLM. Cela permet une extension facile à toute autre base de connaissances ou à tout autre type de mémoire que vous souhaitez que votre implémentation prenne en charge.
Le `shared` sous-dossier contient des implémentations spécifiques de la base de connaissances et de la mémoire de conversation qui sont instanciées dans les usines par le constructeur. Il contient également des récupérateurs de la base de connaissances Amazon Kendra et Amazon Bedrock appelés pour récupérer des documents relatifs LangChain aux cas d'utilisation du RAG, ainsi que des rappels, utilisés par le modèle LLM. LangChain
Les LangChain implémentations utilisent le langage LangChain d'expression (LCEL) pour composer ensemble des chaînes de conversation. `RunnableWithMessageHistory`La classe est utilisée pour conserver l'historique des conversations avec des chaînes LCEL personnalisées, permettant des fonctionnalités telles que le renvoi de documents sources et l'utilisation de la question reformulée (ou désambiguïsée) envoyée à la base de connaissances pour être également envoyée au LLM.
Pour créer votre propre implémentation d'un fournisseur personnalisé, vous pouvez :
1. Copiez le `bedrock_handler.py` fichier et créez votre gestionnaire personnalisé (par exemple,`custom_handler.py`), qui crée votre client personnalisé (par exemple,`CustomProviderClient`) (spécifié à l'étape suivante).
1. Copiez `bedrock_client.py` dans le dossier des clients. Renommez-le en `custom_provider_client.py` (ou renommez-le en votre nom de fournisseur de modèles spécifique, par exemple`CustomProvider`). Nommez la classe qu'elle contient de manière appropriée, par exemple `CustomProviderClient` qui hérite`LLMChatClient`.
Vous pouvez utiliser les méthodes fournies par `LLMChatClient` ou écrire vos propres implémentations pour les remplacer.
La `get_model` méthode crée un `CustomProviderBuilder` (voir l'étape suivante) et appelle la `construct_chat_model` méthode qui construit le modèle de chat à l'aide des étapes du générateur. Cette méthode agit en tant que *directeur* dans le modèle de générateur.
1. Copiez-le `clients/builders/bedrock_builder.py` et renommez-le en `custom_provider_builder.py` ainsi `CustomProviderBuilder` que la classe qu'il contient en héritant LLMBuilder ()`llm_builder.py`. Vous pouvez utiliser les méthodes fournies par LLMBuilder ou écrire vos propres implémentations pour les remplacer. Les étapes du générateur sont appelées en séquence dans la `construct_chat_model` méthode du client, telles que `set_model_defaults``set_knowledge_base`, et`set_conversation_memory`.
La `set_llm_model` méthode créerait le modèle LLM réel en utilisant toutes les valeurs définies à l'aide des méthodes appelées auparavant. Plus précisément, vous pouvez créer un LLM RAG (`CustomProviderRetrievalLLM`) ou non RAG (`CustomProviderLLM`), sur la base de `rag_enabled variable` ce qui est extrait de la configuration LLM dans DynamoDB.
Cette configuration est récupérée dans la `retrieve_use_case_config` méthode de la `LLMChatClient` classe.
1. Implémentez votre `CustomProviderRetrievalLLM` implémentation `CustomProviderLLM` ou son implémentation dans le `llm_models` sous-dossier selon que vous avez besoin d'un cas d'utilisation RAG ou non. La plupart des fonctionnalités permettant d'implémenter ces modèles sont fournies dans leurs `RetrievalLLM` classes `BaseLangChainModel` et respectivement, pour les cas d'utilisation autres que RAG et RAG.
Vous pouvez copier le `llm_models/bedrock.py` fichier et apporter les modifications nécessaires pour appeler le LangChain modèle qui fait référence à votre fournisseur personnalisé. Par exemple, Amazon Bedrock utilise une `ChatBedrock` classe pour créer un modèle de chat en utilisant LangChain.
*La méthode generate génère la réponse LLM à l'aide des chaînes LangChain LCEL.*
Vous pouvez également utiliser `get_clean_model_params` cette méthode pour nettoyer les paramètres du modèle conformément LangChain aux exigences de votre modèle.
## Extension des outils Strands pris en charge
La solution vous permet de créer et de déployer des serveurs MCP, des agents d'intelligence artificielle et des flux de travail multi-agents. Dans le cadre de l'expérience Agent Builder, vous pouvez associer des serveurs MCP pour offrir à vos agents des fonctionnalités supplémentaires. Outre les serveurs MCP, vous pouvez tirer parti des outils intégrés fournis par [Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/) (le framework sous-jacent utilisé par la solution).
Prête à l'emploi, la solution est préconfigurée avec les outils Strands suivants :
+ Heure actuelle (activée par défaut)
+ Calculatrice (activée par défaut)
+ Environnement
**Sélection du serveur et des outils MCP dans l'assistant Agent Builder affichant les outils Strands intégrés**
![\[torons intégrés, outils\]](http://docs.aws.amazon.com/fr_fr/solutions/latest/generative-ai-application-builder-on-aws/images/builtin-strands-tools.png)
Pour étendre à vos agents des outils Strands supplémentaires, suivez le processus en quatre étapes décrit dans cette section.
### Étape 1 : Trouvez l'outil Strands
Parcourez les [outils Strands disponibles](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/#available-tools) pour identifier l'outil que vous souhaitez utiliser. Chaque outil possède des capacités et des exigences de configuration spécifiques.
Par exemple, pour ajouter les fonctionnalités de récupération de la base de connaissances Amazon Bedrock, vous devez utiliser l'outil de [récupération](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py).
### Étape 2 : mise à jour du paramètre SSM
Pour rendre un outil disponible dans l'interface utilisateur de déploiement d'Agent Builder, mettez à jour le paramètre AWS Systems Manager Parameter Store qui définit les outils Strands pris en charge.
1. Accédez au AWS Systems Manager Parameter Store dans votre compte AWS.
1. Localisez le paramètre : `/gaab//strands-tools`
1. Ajoutez la configuration de votre outil à la fin de la liste existante à l'aide de la structure JSON suivante :
```
{
"name": "Bedrock KB Retrieve",
"description": "Retrieve information from Bedrock Knowledge Base",
"value": "retrieve",
"category": "AI",
"isDefault": false
}
```
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.html)
### Étape 3 : Configuration des variables d'environnement
De nombreux outils Strands nécessitent des variables d'environnement pour la configuration. Vous pouvez définir ces variables de deux manières :
**Option 1 : Configuration directe sur AgentCore Runtime**
Mettez à jour l'agent déployé directement sur Amazon Bedrock AgentCore Runtime avec les variables d'environnement requises.
**Option 2 : paramètres du modèle dans l'assistant de déploiement**
Ajoutez des variables d'environnement lors de l'étape de sélection du modèle dans l'assistant Agent Builder à l'aide de la section Paramètres du modèle. Les variables d'environnement qui suivent la convention de dénomination `ENV__` seront automatiquement chargées au moment de l'exécution dans l'environnement d'exécution de l'agent en tant que``.
Par exemple :
+ `ENV_RETRIEVE_KNOWLEDGE_BASE_ID`devient `KNOWLEDGE_BASE_ID`
+ `ENV_RETRIEVE_MIN_SCORE`devient `MIN_SCORE`
**Section des paramètres avancés du modèle montrant la configuration ENV\$1RETRIEVE\$1KNOWLEDGE\$1BASE\$1ID**
![\[paramètres du modèle env vars\]](http://docs.aws.amazon.com/fr_fr/solutions/latest/generative-ai-application-builder-on-aws/images/model-parameters-env-vars.png)
Reportez-vous à la documentation ou au code source de l'outil spécifique pour identifier les variables d'environnement requises. Pour l'outil de récupération, vous trouverez les options de configuration dans le [code source](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py#L293).
### Étape 4 : Ajouter des autorisations IAM
Ajoutez manuellement les autorisations IAM nécessaires à votre rôle AgentCore d'exécution Runtime pour permettre à l'agent d'utiliser l'outil.
Par exemple, pour utiliser l'outil de récupération avec les bases de connaissances Amazon Bedrock :
1. Accédez à la console IAM dans votre compte AWS.
1. Localisez le rôle AgentCore d'exécution Runtime pour votre agent.
1. Ajoutez l'autorisation suivante :
```
{
"Effect": "Allow",
"Action": "bedrock:Retrieve",
"Resource": "arn:aws:bedrock:region:account-id:knowledge-base/knowledge-base-id"
}
```
**Console IAM affichant la StrandsRetrieveTool KBAccess politique associée au rôle d' AgentCore exécution Runtime**
![\[mise à jour du rôle d'exécution de l'agent IAM\]](http://docs.aws.amazon.com/fr_fr/solutions/latest/generative-ai-application-builder-on-aws/images/agent-execution-role-update-IAM.png)
Les autorisations spécifiques requises varient en fonction de l'outil. Consultez la documentation de l'outil et la documentation du service AWS pour déterminer les autorisations IAM appropriées.
### Étape 5 : tester l'agent
Une fois les étapes de configuration terminées, testez votre agent pour vérifier que l'outil fonctionne correctement. Vous devriez voir les appels d'outils dans les journaux d'exécution et les réponses de l'agent.
**L'agent a utilisé avec succès l'outil de récupération pour répondre à une question sur les skate parks**
![\[exemple d'outil de récupération de brins\]](http://docs.aws.amazon.com/fr_fr/solutions/latest/generative-ai-application-builder-on-aws/images/strands-retrieve-tool-example.png)
**Note**
Pour une liste complète des outils Strands disponibles et de leurs fonctionnalités, reportez-vous à la [documentation des outils communautaires Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/).
## Élargir les bases de connaissances et les types de mémoires de conversation pris en charge
Pour ajouter vos implémentations de mémoire de conversation ou de base de connaissances, ajoutez les implémentations requises dans le `shared` dossier, puis modifiez les usines et les énumérations appropriées pour créer une instance de ces classes.
Lorsque vous fournissez la configuration LLM, qui est stockée dans le magasin de paramètres, la mémoire de conversation et la base de connaissances appropriées sont créées pour votre LLM. Par exemple, lorsque le `ConversationMemoryType` est spécifié en tant que DynamoDB, une instance `DynamoDBChatMessageHistory` de (disponible `shared_components/memory/ddb_enhanced_message_history.py` à l'intérieur) est créée. Lorsque le `KnowledgeBaseType` est spécifié comme Amazon Kendra, une instance de `KendraKnowledgeBase` (disponible à l'intérieur`shared_components/knowledge/kendra_knowledge_base.py`) est créée.
## Création et déploiement des modifications du code
Créez le programme à l'aide de la `npm run build` commande. Une fois les erreurs résolues, `cdk synth` lancez-vous pour générer les fichiers modèles et tous les actifs Lambda.
1. Vous pouvez utiliser le `0/stage-assets.sh` script pour transférer manuellement tous les actifs générés vers le bucket intermédiaire de votre compte.
1. Utilisez la commande suivante pour déployer ou mettre à jour la plateforme :
```
cdk deploy DeploymentPlatformStack --parameters AdminUserEmail='admin-email@amazon.com'
```
Tous CloudFormation les paramètres AWS supplémentaires doivent également être fournis avec le **AdminUserEmail**paramètre.