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.
# Créez une application RAG à l'aide des bases de connaissances Amazon Bedrock
De nombreuses entreprises accumulent de grands référentiels de documents sur leurs partages de fichiers NFS et SMB : manuels de produits, documents de politique, contrats, rapports de recherche, spécifications techniques et contenu généré par les utilisateurs.
Avec un point d'accès Amazon S3 connecté au volume FSx for ONTAP, les bases de connaissances Amazon Bedrock ingèrent le contenu directement depuis le volume. Foundation-model les réponses sont basées sur les documents dans lesquels vos équipes les enregistrent via NFS ou SMB. Le contenu mis à jour par les rédacteurs sur le partage est accessible à la base de connaissances lors de la prochaine synchronisation.
Dans ce didacticiel, vous téléchargerez un petit ensemble d'exemples de PDF sur votre volume FSx for ONTAP via un point d'accès Amazon S3, vous créerez une base de connaissances Amazon Bedrock pointant vers le point d'accès, vous ingérerez les documents et vous poserez une question via l'API. `RetrieveAndGenerate`
**Note**
Ce didacticiel prend environ **35 à 45 minutes**. Les ressources que vous Services AWS utilisez sont facturées pour les ressources que vous créez. Si vous effectuez rapidement toutes les étapes, y compris la section **Nettoyage**, le coût prévu est inférieur à **1$** dans l'est des États-Unis (Virginie du Nord) Région AWS. Cette estimation n'inclut pas les frais permanents pour le volume FSx for ONTAP lui-même.
## Conditions préalables
Avant de commencer, assurez-vous de disposer des éléments suivants :
+ Un volume FSx for ONTAP associé à un point d'accès Amazon S3. Le point d'accès doit avoir une origine de réseau **Internet** pour que le service Amazon Bedrock puisse y accéder. Pour obtenir des instructions sur la création d'un point d'accès, consultez[Création d’un point d’accès](fsxn-creating-access-points.md).
+ L'accès au modèle est activé pour un modèle d'intégration pris en charge par les bases de connaissances Amazon Bedrock et au moins un modèle de génération de texte (par exemple,`amazon.nova-lite-v1:0`) dans Région AWS lequel vous allez créer la base de connaissances. Ce didacticiel utilise `amazon.titan-embed-text-v2:0` (1024 dimensions) comme modèle d'intégration ; les modèles Cohere Embed sont également pris en charge. Si vous choisissez un autre modèle d'intégration, ajustez la dimension de l'indice vectoriel à l'étape 2 pour qu'elle corresponde à la dimension de sortie du modèle. L'accès aux modèles est activé dans la console Amazon Bedrock sous **Accès aux modèles**. Pour plus d'informations, consultez la section [Access Amazon Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) dans le guide de l'*utilisateur Amazon Bedrock*.
+ AWS CLI version 2 installée et configurée avec des informations d'identification permettant de créer des rôles IAM, des ressources Amazon S3 Vectors et des bases de connaissances Amazon Bedrock.
## Étape 1 : télécharger des exemples de documents vers le point d'accès
Téléchargez quelques PDF publics à utiliser comme exemple de corpus, puis chargez-les sur votre point d'accès à l'aide de l'alias du point d'accès Amazon S3.
1. Créez un répertoire local et téléchargez des exemples de fichiers PDF.
```
$ mkdir -p ~/kb-pdfs && cd ~/kb-pdfs
curl -sSL -o aws-overview.pdf https://d1.awsstatic.com/whitepapers/aws-overview.pdf
curl -sSL -o wellarchitected-framework.pdf https://docs.aws.amazon.com/pdfs/wellarchitected/latest/framework/wellarchitected-framework.pdf
curl -sSL -o s3-userguide.pdf https://docs.aws.amazon.com/pdfs/AmazonS3/latest/userguide/s3-userguide.pdf
```
1. Téléchargez chaque fichier sur le point d'accès. {{access-point-alias}}Remplacez-le par l'alias de votre point d'accès (par exemple,`my-kb-ap-a1b2c3d4e5f6g7h8i9j0kl1mnop2uuse1a-ext-s3alias`). Vous pouvez trouver l'alias dans la console Amazon FSx sous **Points d'accès Amazon S3 attachés** à votre volume, ou en exécutant. `aws fsx describe-s3-access-point-attachments`
```
$ for f in *.pdf; do
aws s3 cp "$f" "s3://{{access-point-alias}}/$f"
done
```
1. Vérifiez que les fichiers ont atterri sur le volume.
```
$ aws s3 ls s3://{{access-point-alias}}/
```
**Note**
Les bases de connaissances Amazon Bedrock imposent une taille de fichier maximale de 50 Mo par document. Les fichiers de plus de 50 Mo sont ignorés lors de l'ingestion.
## Étape 2 : Création d'un magasin de vecteurs
La base de connaissances stocke les intégrations de documents dans un magasin vectoriel. Les bases de connaissances Amazon Bedrock prennent en charge plusieurs magasins vectoriels ; ce didacticiel utilise les vecteurs Amazon S3 par défaut, car il est optimisé en termes de coûts pour les charges de travail RAG et nécessite une configuration minimale. Amazon OpenSearch Serverless est également pris en charge ; consultez la section pliable à la fin de cette étape pour obtenir ces instructions.
### Pour créer le magasin vectoriel à l'aide de la console
Si vous utilisez la console pour créer la base de connaissances[Étape 4 : Création de la base de connaissances et de la source de données](#tutorial-bedrock-kb-create-kb), choisissez **Création rapide d'un nouveau magasin vectoriel** à l'étape **Base de données vectorielle**, puis sélectionnez **Amazon S3 Vectors** (recommandé) ou **Amazon OpenSearch Serverless**. Amazon Bedrock crée automatiquement le magasin vectoriel et toutes les configurations requises. Passez directement à [Étape 3 : créer un rôle IAM pour la base de connaissances](#tutorial-bedrock-kb-iam-role).
### Pour créer un magasin vectoriel Amazon S3 Vectors à l'aide du AWS CLI
1. Créez un compartiment vectoriel Amazon S3. Les noms de compartiments vectoriels suivent les mêmes règles d'unicité globale que les compartiments Amazon S3 standard. Ce didacticiel utilise `fsxn-kb-vectors` ; remplacez par un nom unique.
```
$ aws s3vectors create-vector-bucket --vector-bucket-name fsxn-kb-vectors
```
1. Créez un index vectoriel dans le compartiment. La dimension d'index doit correspondre à la dimension de sortie du modèle d'intégration ; Titan Text Embeddings v2 affiche 1024 dimensions. Le `nonFilterableMetadataKeys` paramètre indique que les champs de métadonnées Bedrock ne sont pas filtrables, ce qui les empêche de dépasser la limite de 2 Ko de métadonnées filtrables par vecteur.
```
$ aws s3vectors create-index --vector-bucket-name fsxn-kb-vectors \
--index-name bedrock-kb-index \
--dimension 1024 --distance-metric cosine --data-type float32 \
--metadata-configuration '{"nonFilterableMetadataKeys":["AMAZON_BEDROCK_METADATA","AMAZON_BEDROCK_TEXT"]}'
```
Notez le `indexArn` dans la réponse ; vous l'utilisez dans[Étape 4 : Création de la base de connaissances et de la source de données](#tutorial-bedrock-kb-create-kb).
### Alternative : créez un magasin vectoriel OpenSearch Service Serverless à l'aide du AWS CLI
Si vous préférez OpenSearch Service Serverless (pour des requêtes par seconde plus élevées, des fonctionnalités de recherche avancées ou une familiarité opérationnelle existante), suivez les étapes ci-dessous au lieu de la procédure Amazon S3 Vectors ci-dessus.
1. Créez des politiques de chiffrement et de sécurité réseau pour la collection.
```
$ aws opensearchserverless create-security-policy --name kb-enc --type encryption \
--policy '{"Rules":[{"ResourceType":"collection","Resource":["collection/fsxn-kb"]}],"AWSOwnedKey":true}'
aws opensearchserverless create-security-policy --name kb-net --type network \
--policy '[{"Rules":[{"ResourceType":"collection","Resource":["collection/fsxn-kb"]},{"ResourceType":"dashboard","Resource":["collection/fsxn-kb"]}],"AllowFromPublic":true}]'
```
1. Créez une politique d'accès aux données qui accorde au rôle de base de connaissances et à votre utilisateur actuel l'autorisation de lire et d'écrire la collection. Remplacez {{account-id}} et {{current-user}} par vos valeurs.
```
$ aws opensearchserverless create-access-policy --name kb-data --type data --policy '[{
"Rules":[
{"ResourceType":"index","Resource":["index/fsxn-kb/*"],"Permission":["aoss:*"]},
{"ResourceType":"collection","Resource":["collection/fsxn-kb"],"Permission":["aoss:*"]}
],
"Principal":[
"arn:aws:iam::{{account-id}}:role/fsxn-kb-role",
"arn:aws:iam::{{account-id}}:user/{{current-user}}"
]
}]'
```
1. Créez la collection et attendez qu'elle le devienne`ACTIVE`.
```
$ aws opensearchserverless create-collection --name fsxn-kb --type VECTORSEARCH
aws opensearchserverless batch-get-collection --names fsxn-kb \
--query 'collectionDetails[0].{status:status,endpoint:collectionEndpoint}'
```
1. Créez l'index vectoriel de la collection à l'aide d'un script Python avec des requêtes signées. L'index doit utiliser la dimension 1024 (pour Titan Text Embeddings v2) et les noms de champs attendus par Amazon Bedrock Knowledge Bases. Pour le script complet et les étapes de configuration suivantes, consultez la section [Conditions préalables à l'utilisation de OpenSearch Service Serverless](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-setup-oss.html) dans le guide de l'utilisateur d'*Amazon Bedrock*. Utilisez l'ARN de la collection et le nom d'index obtenus à l'étape 4 avec un type `storage-configuration` of`OPENSEARCH_SERVERLESS`.
## Étape 3 : créer un rôle IAM pour la base de connaissances
La base de connaissances a besoin d'un rôle IAM qu'elle peut assumer pour invoquer le modèle d'intégration, lire des objets via le point d'accès Amazon S3 et accéder au magasin vectoriel. La politique présentée ci-dessous autorise l'accès à un magasin vectoriel Amazon S3 Vectors. Si vous utilisez plutôt OpenSearch Service Serverless, remplacez l'`S3Vectors`instruction par une instruction qui accorde l'ARN `aoss:APIAccessAll` de la collection.
### Pour créer le rôle à l'aide de la console
Lorsque vous créez la base de connaissances à l'aide de la console Amazon Bedrock dans[Étape 4 : Création de la base de connaissances et de la source de données](#tutorial-bedrock-kb-create-kb), choisissez **Create and use a new service role**. Amazon Bedrock crée un rôle doté de la confiance et des autorisations requises, limité à votre base de connaissances, à votre modèle d'intégration, à votre magasin vectoriel et à votre source de données. Passez directement à [Étape 4 : Création de la base de connaissances et de la source de données](#tutorial-bedrock-kb-create-kb).
### Pour créer le rôle à l'aide du AWS CLI
1. Enregistrez la politique de confiance suivante sous le nom`kb-trust-policy.json`. Cela permet à Amazon Bedrock d'assumer le rôle. {{account-id}}Remplacez-le par votre Compte AWS identifiant.
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "bedrock.amazonaws.com"},
"Action": "sts:AssumeRole",
"Condition": {"StringEquals": {"aws:SourceAccount": "{{account-id}}"}}
}]
}
```
1. Enregistrez la politique d'autorisation suivante sous le nom`kb-permissions.json`. Il donne accès au modèle d'intégration, au point d'accès Amazon S3 et au magasin vectoriel. Remplacez les espaces réservés par vos valeurs.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "FoundationModel",
"Effect": "Allow",
"Action": ["bedrock:InvokeModel"],
"Resource": ["arn:aws:bedrock:{{region}}::foundation-model/amazon.titan-embed-text-v2:0"]
},
{
"Sid": "S3AccessPoint",
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:{{region}}:{{account-id}}:accesspoint/{{access-point-name}}",
"arn:aws:s3:{{region}}:{{account-id}}:accesspoint/{{access-point-name}}/object/*"
]
},
{
"Sid": "S3Vectors",
"Effect": "Allow",
"Action": [
"s3vectors:GetIndex",
"s3vectors:PutVectors",
"s3vectors:GetVectors",
"s3vectors:ListVectors",
"s3vectors:DeleteVectors",
"s3vectors:QueryVectors"
],
"Resource": [
"arn:aws:s3vectors:{{region}}:{{account-id}}:bucket/fsxn-kb-vectors",
"arn:aws:s3vectors:{{region}}:{{account-id}}:bucket/fsxn-kb-vectors/index/*"
]
}
]
}
```
1. Créez le rôle et joignez la politique d'autorisation.
```
$ aws iam create-role --role-name fsxn-kb-role \
--assume-role-policy-document file://kb-trust-policy.json
aws iam put-role-policy --role-name fsxn-kb-role --policy-name kb-access \
--policy-document file://kb-permissions.json
```
## Étape 4 : Création de la base de connaissances et de la source de données
La source de données pointe vers l'alias de votre point d'accès Amazon S3. Les bases de connaissances Amazon Bedrock acceptent l'alias du point d'accès à la place du nom du bucket.
### Pour créer la base de connaissances à l'aide de la console
1. Ouvrez la console Amazon Bedrock à [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/)l'adresse.
1. Dans le volet de navigation de gauche, choisissez **Bases de connaissances**, puis choisissez **Créer une base de connaissances**.
1. Sous **Détails de la base de connaissances**, entrez un nom (par exemple`fsxn-kb`) et une description.
1. Sous **Autorisations IAM**, choisissez **Créer et utiliser un nouveau rôle de service**.
1. Pour **Source de données**, choisissez **Amazon S3**, puis **Next**.
1. Entrez le nom de la source de données (par exemple,`fsxn-s3ap-source`).
1. Pour l'**URI S3**, entrez `s3://` suivi de l'alias de votre point d'accès, par exemple`s3://my-kb-ap-a1b2c3d4e5f6g7h8i9j0kl1mnop2uuse1a-ext-s3alias`. La console ne fait pas la distinction entre un nom de compartiment et un alias de point d'accès dans ce champ ; l'alias du point d'accès est accepté tel quel.
1. Choisissez **Suivant**.
1. Sous le **modèle Embeddings**, choisissez **Titan Text** Embeddings v2.
1. Sous **Base de données vectorielle**, choisissez **Création rapide d'un nouveau magasin de vecteurs**, puis sélectionnez **Amazon S3 Vectors**. Choisissez **Suivant**.
1. Passez en revue la configuration et choisissez **Créer une base de connaissances**. La création de la base de connaissances peut prendre plusieurs minutes.
### Pour créer la base de connaissances à l'aide du AWS CLI
1. Créez la base de connaissances. Remplacez les espaces réservés par vos valeurs. `indexArn`Il s'agit de l'ARN de l'index vectoriel Amazon S3 que vous avez créé à l'étape 2.
```
$ aws bedrock-agent create-knowledge-base --name fsxn-kb \
--role-arn arn:aws:iam::{{account-id}}:role/fsxn-kb-role \
--knowledge-base-configuration '{
"type":"VECTOR",
"vectorKnowledgeBaseConfiguration":{
"embeddingModelArn":"arn:aws:bedrock:{{region}}::foundation-model/amazon.titan-embed-text-v2:0"
}
}' \
--storage-configuration '{
"type":"S3_VECTORS",
"s3VectorsConfiguration":{
"indexArn":"{{index-arn}}"
}
}'
```
Notez le `knowledgeBaseId` dans la réponse.
1. Créez la source de données. Transmettez l'alias du point d'accès Amazon S3 comme nom du compartiment dans le `bucketArn` champ, à l'aide du formulaire`arn:aws:s3:::{{access-point-alias}}`.
```
$ aws bedrock-agent create-data-source \
--knowledge-base-id {{knowledge-base-id}} \
--name fsxn-s3ap-source \
--data-source-configuration '{
"type":"S3",
"s3Configuration":{"bucketArn":"arn:aws:s3:::{{access-point-alias}}"}
}'
```
Notez le `dataSourceId` dans la réponse.
## Étape 5 : Ingérer les documents
Exécutez une tâche d'ingestion pour parcourir les documents via le point d'accès, générer des intégrations et les indexer dans le magasin vectoriel.
### Pour exécuter l'ingestion à l'aide de la console
1. Dans la console Amazon Bedrock, ouvrez votre base de connaissances.
1. Dans la section **Source de données**, sélectionnez votre source de données, puis choisissez **Synchroniser**.
1. Attendez que l'**état de synchronisation** indique **Prêt**.
### Pour exécuter l'ingestion à l'aide du AWS CLI
1. Commencez le travail d'ingestion.
```
$ aws bedrock-agent start-ingestion-job \
--knowledge-base-id {{knowledge-base-id}} \
--data-source-id {{data-source-id}}
```
Notez le `ingestionJobId` dans la réponse.
1. Interrogez le travail jusqu'à ce qu'il soit terminé.
```
$ aws bedrock-agent get-ingestion-job \
--knowledge-base-id {{knowledge-base-id}} \
--data-source-id {{data-source-id}} \
--ingestion-job-id {{ingestion-job-id}}
```
Le `status` champ passe de `IN_PROGRESS` à`COMPLETE`. Le `statistics` champ indique le nombre de documents numérisés et indexés.
## Étape 6 : interroger la base de connaissances
Posez à la base de connaissances une question basée sur les documents ingérés. La réponse inclut des citations qui font référence aux documents sources via l'alias du point d'accès Amazon S3.
### Pour effectuer une requête à l'aide de la console
1. Dans la console Amazon Bedrock, ouvrez votre base de connaissances.
1. Choisissez **Tester la base de connaissances**.
1. Sous **Générer des réponses**, sélectionnez un modèle de génération de texte (par exemple, **Nova Lite**).
1. Entrez une question telle que `What are the pillars of the AWS Well-Architected Framework?` et choisissez **Exécuter**. La réponse s'affiche avec des références de citation qui renvoient aux documents sources dans le point d'accès Amazon S3.
### Pour effectuer une requête à l'aide du AWS CLI
Utilisez la commande `retrieve-and-generate`. Remplacez les espaces réservés par vos valeurs. `modelArn`Il doit faire référence à un profil d'inférence pour un modèle de génération de texte auquel vous avez accès.
```
$ aws bedrock-agent-runtime retrieve-and-generate \
--input '{"text":"What are the pillars of the AWS Well-Architected Framework?"}' \
--retrieve-and-generate-configuration '{
"type":"KNOWLEDGE_BASE",
"knowledgeBaseConfiguration":{
"knowledgeBaseId":"{{knowledge-base-id}}",
"modelArn":"arn:aws:bedrock:{{region}}:{{account-id}}:inference-profile/us.amazon.nova-lite-v1:0"
}
}'
```
La réponse contient la réponse générée `output.text` et une liste de citations dans le `citations` tableau. Chaque citation inclut un `s3Location.uri` champ qui pointe vers le document source via l'alias du point d'accès, dans le formulaire`s3://{{access-point-alias}}/{{file.pdf}}`.
## Résolution des problèmes
Les fichiers de rapports de tâches d'ingestion ont été ignorés
Les bases de connaissances Amazon Bedrock imposent une taille de fichier maximale de 50 Mo par document. Les fichiers de plus de 50 Mo sont répertoriés `failureReasons` et ignorés. Divisez ou compressez des documents volumineux avant de les télécharger.
`ValidationException`: modèle marqué comme Legacy
Le modèle de génération de texte que vous avez spécifié est obsolète pour votre compte. Choisissez un profil d'inférence actif, tel que `us.amazon.nova-lite-v1:0` ou un autre modèle actuellement pris en charge. Exécutez `aws bedrock list-inference-profiles` pour répertorier les profils disponibles.
`AccessDeniedException`pendant l'ingestion
Vérifiez que le rôle IAM de la base de connaissances possède `s3:GetObject` et se `s3:ListBucket` trouve sur l'ARN du point d'accès (et non sur le volume sous-jacent) et que le point d'accès provient d'un réseau Internet afin que le service Amazon Bedrock puisse y accéder. Si vous avez choisi l'alternative OpenSearch Service Serverless à l'étape 2, vérifiez également que la politique d'accès aux données indique le rôle comme principal.
La tâche d'ingestion réussit mais les requêtes ne renvoient aucun passage pertinent
Vérifiez que l'index vectoriel a été créé avec `dimension: 1024` (pour Titan Text Embeddings v2) et que les noms de champs dans le mappage d'index correspondent aux noms de champs configurés dans la base de connaissances.
## Nettoyage
Pour éviter des frais permanents, supprimez les ressources que vous avez créées :
+ Base de connaissances et source de données Amazon Bedrock
+ Index vectoriel et compartiment vectoriel Amazon S3 (ou collection OpenSearch Service Serverless, si vous avez utilisé l'alternative à l'étape 2)
+ Rôle IAM et politique en ligne
+ Objets téléchargés vers le point d'accès (s'ils ne sont plus nécessaires)
```
$ aws bedrock-agent delete-data-source --knowledge-base-id {{knowledge-base-id}} --data-source-id {{data-source-id}}
aws bedrock-agent delete-knowledge-base --knowledge-base-id {{knowledge-base-id}}
aws s3vectors delete-index --vector-bucket-name fsxn-kb-vectors --index-name bedrock-kb-index
aws s3vectors delete-vector-bucket --vector-bucket-name fsxn-kb-vectors
aws iam delete-role-policy --role-name fsxn-kb-role --policy-name kb-access
aws iam delete-role --role-name fsxn-kb-role
```
### Alternative : Nettoyer les ressources OpenSearch du service sans serveur
Si vous avez choisi l'alternative OpenSearch Service Serverless à l'étape 2, remplacez les `s3vectors` commandes ci-dessus par les suivantes. Les collections Idle OpenSearch Service Serverless sont OCU-hour facturées, alors supprimez-les rapidement lorsque vous aurez terminé le didacticiel.
```
$ # Get the collection ID (required by delete-collection; the name is not accepted)
COLLECTION_ID=$(aws opensearchserverless batch-get-collection --names fsxn-kb \
--query 'collectionDetails[0].id' --output text)
# Delete the collection, then the policies
aws opensearchserverless delete-collection --id "$COLLECTION_ID"
aws opensearchserverless delete-access-policy --name kb-data --type data
aws opensearchserverless delete-security-policy --name kb-net --type network
aws opensearchserverless delete-security-policy --name kb-enc --type encryption
```